TRL documentation
Pelatihan dengan Jobs
Pelatihan dengan Jobs
Hugging Face Jobs menjalankan pelatihan Anda di GPU Hugging Face. Anda memilih perangkat keras untuk setiap run dan hanya membayar sesuai detik-detik eksekusinya. Dengan --push_to_hub, model yang telah dilatih akan diunggah ke Hub di akhir proses.
Pada panduan ini, Anda akan belajar cara:
- Jalankan skrip pelatihan TRL dengan satu perintah
- Ikuti sebuah run dan lihat kurva loss-nya
- Jalankan skrip Anda sendiri, dengan pengaturan perangkat kerasnya di file
- Simpan checkpoint dan lanjutkan eksekusi yang terputus
- Melatih di beberapa GPU
Untuk cara kerja Jobs secara umum, termasuk hardware dan harga, lihat dokumentasi Jobs.
Persyaratan
- Akun Hugging Face dengan saldo kredit positif. Pekerjaan bersifat bayar sesuai pemakaian: Anda hanya membayar untuk detik-detik yang digunakan.
- Masuk ke Hugging Face Hub (
hf auth login)
Jalankan pertama kali
Perintah ini melakukan fine-tuning pada Qwen2-0.5B-Instruct menggunakan dataset chat Capybara dengan skrip SFT TRL, kemudian mendorong model ke akun Anda:
hf jobs uv run \
--flavor a10g-small \
--timeout 30m \
--secrets HF_TOKEN \
-- \
https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py \
--model_name_or_path Qwen/Qwen2-0.5B-Instruct \
--dataset_name trl-lib/Capybara \
--max_steps 100 \
--output_dir Qwen2-0.5B-SFT \
--push_to_hubfrom huggingface_hub import run_uv_job
run_uv_job(
"https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py",
flavor="a10g-small",
timeout="30m",
secrets={"HF_TOKEN": "hf_..."},
script_args=[
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--max_steps", "100",
"--output_dir", "Qwen2-0.5B-SFT",
"--push_to_hub",
],
)Proses ini memakan waktu beberapa menit dan biayanya jauh di bawah $1 di a10g-small. Opsi sebelum -- adalah untuk Jobs: perangkat keras, batas waktu, dan token yang digunakan untuk mendorong model. --secrets HF_TOKEN mengirim token yang Anda gunakan untuk masuk. Di Python, berikan token itu sendiri. Argumen setelah URL skrip diteruskan ke skrip. hf jobs uv run menjalankan skrip Python dengan uv. sft.py mencantumkan dependensinya di header bagian atas file, sehingga Jobs menginstal TRL sebelum skrip dimulai. Job berhenti ketika skrip keluar, dan penagihan berhenti bersamanya.
--max_steps 100 membuat eksekusi pertama ini singkat. Hapus parameter ini untuk eksekusi penuh: tiga epoch, nilai bawaan skrip, membutuhkan beberapa jam di a10g-small, sehingga naikkan --timeout agar sesuai, misalnya --timeout 3h. Jobs menghentikan eksekusi ketika batas waktu tercapai, yang secara bawaan adalah 30 menit. GPU yang lebih besar seperti a100-large menyelesaikan proses lebih cepat. Lihat Hardware untuk varian dan harganya.
Ikuti jalannya
hf jobs uv run mengalirkan log dan menahan terminal Anda hingga eksekusi selesai. Ctrl+C hanya menghentikan aliran log: Job tetap berjalan. Tambahkan --detach untuk langsung mendapatkan ID Job, kemudian:
hf jobs logs -f <job_id> # stream the logs
hf jobs ps # list your running Jobs
hf jobs inspect <job_id> # status, and the error message if it failed
hf jobs cancel <job_id> # stop itLihat Manage Jobs untuk informasi lebih lanjut.
Untuk kurva loss, TRL mencatat ke Trackio. Tambahkan --env TRACKIO_SPACE_ID=<your-username>/trackio sebelum -- untuk memberi nama Space bagi dasbor, dan --report_to trackio setelah URL skrip. Trackio membuat Space dan bucket untuk metrik jika belum ada. Keduanya bersifat publik secara default. Tracker lain yang didukung Transformers juga berfungsi. Untuk Weights & Biases, tambahkan --with wandb --secrets WANDB_API_KEY sebelum -- dan --report_to wandb setelah URL skrip. --secrets WANDB_API_KEY membaca nilai dari WANDB_API_KEY di lingkungan lokal Anda. Lihat variabel lingkungan dan rahasia untuk cara lain meneruskannya.
Jalankan skrip Anda sendiri
Tulis kode pelatihan Anda dalam file Python (misalnya, train.py). Daftarkan dependensinya di bagian atas file, dalam header skrip, dengan cara yang sama seperti yang dilakukan oleh skrip TRL. Jobs akan menginstalnya sebelum skrip dimulai:
# /// script
# dependencies = [
# "trl",
# "peft",
# ]
# ///
from datasets import load_dataset
from peft import LoraConfig
from trl import SFTConfig, SFTTrainer
dataset = load_dataset("trl-lib/Capybara", split="train")
trainer = SFTTrainer(
model="Qwen/Qwen2.5-0.5B",
train_dataset=dataset,
peft_config=LoraConfig(),
args=SFTConfig(output_dir="Qwen2.5-0.5B-SFT", max_steps=100),
)
trainer.train()
trainer.push_to_hub()Lalu jalankan dengan CLI hf jobs atau API Python:
hf jobs uv run \
--flavor a10g-small \
--timeout 30m \
--secrets HF_TOKEN \
train.pyfrom huggingface_hub import run_uv_job
run_uv_job(
"train.py",
flavor="a10g-small",
timeout="30m",
secrets={"HF_TOKEN": "hf_..."},
)Untuk skrip tanpa header, daftarkan dependensi saat peluncuran dengan --with, satu per satu per paket: --with trl --with peft (dependencies=["trl", "peft"] di Python). Skrip juga dapat berupa URL, seperti tautan raw GitHub, Gist, atau file di repo Hub publik.
Pengaturan peluncuran juga dapat diletakkan di dalam skrip. Tabel [tool.hf-jobs] di header mengatur perangkat keras, batas waktu, dan rahasia:
# /// script
# dependencies = [
# "trl",
# "peft",
# ]
#
# [tool.hf-jobs]
# flavor = "a10g-small"
# timeout = "30m"
# secrets = ["HF_TOKEN"]
# ///hf jobs uv run train.py kemudian tidak memerlukan opsi, dan opsi yang Anda berikan tetap menimpa skrip. Skrip membawa semua yang dibutuhkan untuk dijalankan, sehingga Anda dapat membagikannya, atau kembali ke skrip tersebut nanti, tanpa perlu mengingat GPU dan timeout apa yang dibutuhkan. hf jobs uv run --dry-run train.py menampilkan pengaturan yang telah dipecahkan dan menandai nilai yang berasal dari skrip. Tabel ini hanya dibaca oleh CLI hf: run_uv_job() mengabaikannya. Lihat Mendefinisikan konfigurasi peluncuran di skrip.
Jalankan skrip TRL apa pun
Pola yang sama dijalankan oleh setiap skrip trainer TRL (SFT, DPO, GRPO, reward modeling, dan lainnya) serta contoh .py mandiri di Indeks Contoh. Masing-masing mendeklarasikan dependensinya di header skrip. Contoh yang membaca file lain di sebelahnya perlu folder-nya dimount ke dalam Job. Lihat Direktori lokal. Contoh yang hanya untuk notebook tidak dapat dikirim dengan cara ini. Argumen skripnya sama dengan saat Anda menjalankan skrip secara lokal.
Simpan checkpoint
Disk dari sebuah Job dihapus ketika Job berakhir, termasuk ketika mencapai batas waktu atau gagal. Untuk eksekusi jangka panjang, simpan checkpoint di luar Job agar tetap tersimpan setelah Job berakhir.
Cara termudah adalah dengan mendorong setiap checkpoint ke repo model output saat disimpan:
hf jobs uv run \
--flavor a10g-small \
--timeout 3h \
--secrets HF_TOKEN \
-- \
https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py \
--model_name_or_path Qwen/Qwen2-0.5B-Instruct \
--dataset_name trl-lib/Capybara \
--output_dir Qwen2-0.5B-SFT \
--push_to_hub \
--save_steps 500 \
--hub_strategy checkpointfrom huggingface_hub import run_uv_job
run_uv_job(
"https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py",
flavor="a10g-small",
timeout="3h",
secrets={"HF_TOKEN": "hf_..."},
script_args=[
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--output_dir", "Qwen2-0.5B-SFT",
"--push_to_hub",
"--save_steps", "500",
"--hub_strategy", "checkpoint",
],
)Dengan --hub_strategy checkpoint, checkpoint terbaru, termasuk state optimizer, disimpan di folder last-checkpoint dari repo. Untuk melanjutkan run yang terputus, mount repo ke Job baru dan resume dari folder tersebut: jalankan perintah yang sama dengan --volume hf://<your-username>/Qwen2-0.5B-SFT:/previous sebelum -- dan --resume_from_checkpoint /previous/last-checkpoint setelah URL script.
Untuk menyimpan beberapa checkpoint di luar repo model, tulislah ke Storage Bucket sebagai gantinya. Buat satu dengan hf buckets create <your-username>/checkpoints --private, mount ke dalam Job, dan arahkan --output_dir ke sana:
hf jobs uv run \
--flavor a10g-small \
--timeout 3h \
--secrets HF_TOKEN \
--volume hf://buckets/<your-username>/checkpoints:/checkpoints \
-- \
https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py \
--model_name_or_path Qwen/Qwen2-0.5B-Instruct \
--dataset_name trl-lib/Capybara \
--output_dir /checkpoints/Qwen2-0.5B-SFT \
--save_steps 500from huggingface_hub import Volume, run_uv_job
run_uv_job(
"https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py",
flavor="a10g-small",
timeout="3h",
secrets={"HF_TOKEN": "hf_..."},
volumes=[Volume(type="bucket", source="<your-username>/checkpoints", mount_path="/checkpoints")],
script_args=[
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--output_dir", "/checkpoints/Qwen2-0.5B-SFT",
"--save_steps", "500",
],
)Untuk melanjutkan eksekusi yang terputus, jalankan kembali perintah yang sama dengan --resume_from_checkpoint /checkpoints/Qwen2-0.5B-SFT/checkpoint-<step>. Lihat Menulis ke bucket saat berjalan untuk informasi lebih lanjut dan Volumes untuk opsi mount.
Setiap checkpoint menyimpan status model dan optimizer, dengan ukuran beberapa kali lipat dari model. Tambahkan
--save_total_limit 2untuk hanya menyimpan yang terbaru. Jika Anda juga meneruskan--push_to_hub, atur--hub_model_id, atau repo diberi nama sesuai bagian terakhir dari jalur output.
Beberapa GPU
Flavor dengan beberapa GPU mempersingkat waktu eksekusi. Untuk ini, gunakan hf jobs run, yang menjalankan perintah dalam image Docker alih-alih skrip, dengan image huggingface/trl, yang sudah memiliki TRL dan Accelerate terpasang. Kemudian mulai satu proses per GPU. Ini berfungsi untuk skrip TRL dan untuk kode pelatihan Anda sendiri.
Percepat skrip TRL
Jalankan SFT dari awal panduan ini, di empat GPU:
hf jobs run \
--flavor l4x4 \
--timeout 30m \
--secrets HF_TOKEN \
huggingface/trl \
-- \
trl sft --nproc_per_node 4 \
--model_name_or_path Qwen/Qwen2-0.5B-Instruct \
--dataset_name trl-lib/Capybara \
--max_steps 100 \
--output_dir Qwen2-0.5B-SFT \
--push_to_hubfrom huggingface_hub import run_job
run_job(
image="huggingface/trl",
command=[
"trl", "sft", "--nproc_per_node", "4",
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--max_steps", "100",
"--output_dir", "Qwen2-0.5B-SFT",
"--push_to_hub",
],
flavor="l4x4",
timeout="30m",
secrets={"HF_TOKEN": "hf_..."},
)trl CLI meneruskan --nproc_per_node ke torchrun. Atur nilainya ke jumlah GPU pada flavor, di sini empat L4. Setiap proses mengambil batch-nya sendiri, sehingga ukuran batch efektifnya empat kali lipat dari eksekusi single-GPU. Eksekusi ini memakan waktu beberapa menit. Tanpa --max_steps, tiga epoch penuh memakan waktu sekitar satu jam, jadi naikkan --timeout, misalnya menjadi 2h.
Skrip Anda sendiri
Anda tidak terbatas pada skrip TRL. Kode pelatihan yang berjalan dengan torchrun secara lokal akan berjalan dengan cara yang sama di Jobs, selama image memiliki paket yang dibutuhkan. Sebagai contoh, simpan skrip GRPO dengan fungsi reward Anda sendiri sebagai train_grpo.py di sebuah folder, lalu mount folder tersebut ke dalam Job. Jobs mengunggah folder ke bucket privat dan memount-nya hanya-baca:
hf jobs run \
--flavor l4x4 \
--timeout 30m \
--secrets HF_TOKEN \
--volume ./my-project:/code \
huggingface/trl \
-- \
torchrun --nproc_per_node 4 /code/train_grpo.pyfrom huggingface_hub import run_job, sync_job_volume
code = sync_job_volume("./my-project", "/code")
run_job(
image="huggingface/trl",
command=["torchrun", "--nproc_per_node", "4", "/code/train_grpo.py"],
flavor="l4x4",
timeout="30m",
secrets={"HF_TOKEN": "hf_..."},
volumes=[code],
)Skrip dijalankan dengan TRL yang sudah terpasang di dalam image, sehingga tidak memerlukan header skrip. GRPOTrainer secara default menghasilkan completions dengan transformers, sehingga ini berjalan dalam satu Job tanpa server vLLM. Untuk generasi yang lebih cepat, lihat vLLM Integration. Bagian berikutnya menjelaskan bagaimana hf jobs run menggunakan image tersebut.
Gambar Docker
Jobs menjalankan skrip Anda dengan uv, yang menginstal dependensi yang dideklarasikan di header # /// script ke dalam lingkungan baru. Oleh karena itu, TRL yang diimpor oleh skrip Anda berasal dari header tersebut, bukan dari image, dan contoh hf jobs uv run di atas sama sekali tidak memerlukan --image.
Gambar Docker dengan TRL yang sudah terpasang tersedia di huggingface/trl. Menyerahkannya ke hf jobs uv run memberikan job lapisan sistem dari gambar tersebut, seperti toolchain CUDA-nya, yang penting untuk dependensi yang dikompilasi terhadapnya:
hf jobs uv run \
--flavor a100-large \
--secrets HF_TOKEN \
--image huggingface/trl \
train.pyfrom huggingface_hub import run_uv_job
run_uv_job(
"train.py",
flavor="a100-large",
secrets={"HF_TOKEN": "hf_..."},
image="huggingface/trl",
)Untuk menjalankan TRL yang terpasang di dalam image, gunakan hf jobs run sebagai gantinya. Perintah ini menjalankan perintah di dalam image secara langsung, tanpa perlu header script untuk di-resolve, sehingga TRL milik image itulah yang akan dieksekusi. -- memisahkan perintah dari opsi Jobs, yang diperlukan setiap kali perintah itu sendiri mengambil opsi:
hf jobs run \
--flavor a100-large \
--secrets HF_TOKEN \
huggingface/trl \
-- \
trl sft --model_name_or_path Qwen/Qwen2-0.5B-Instruct --dataset_name trl-lib/Capybara --output_dir Qwen2-0.5B-SFTfrom huggingface_hub import run_job
run_job(
image="huggingface/trl",
command=[
"trl", "sft",
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--output_dir", "Qwen2-0.5B-SFT",
],
flavor="a100-large",
secrets={"HF_TOKEN": "hf_..."},
)Gambar dipublikasikan di bawah tiga jenis tag:
| Tag | Isi |
|---|---|
X.Y.Z | Rilis TRL dari versi tersebut, yang dibangun saat versi itu dirilis |
latest | Rilis terbaru |
dev | Cabang main, dibangun ulang setiap kali ada merge |
Gunakan dev untuk menjalankan versi pengembangan, yang berguna untuk mencoba perbaikan yang sudah masuk ke main tetapi belum dirilis:
hf jobs run \
--flavor a100-large \
--secrets HF_TOKEN \
huggingface/trl:dev \
-- \
trl sft --model_name_or_path Qwen/Qwen2-0.5B-Instruct --dataset_name trl-lib/Capybara --output_dir Qwen2-0.5B-SFTfrom huggingface_hub import run_job
run_job(
image="huggingface/trl:dev",
command=[
"trl", "sft",
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--output_dir", "Qwen2-0.5B-SFT",
],
flavor="a100-large",
secrets={"HF_TOKEN": "hf_..."},
)Tag hanya memilih apa yang diinstal dalam image, sehingga tag penting untuk hf jobs run. Dengan hf jobs uv run, versi berasal dari header skrip, dan tag tidak memengaruhi versi TRL yang diimpor.
Menggabungkan keduanya, sehingga uv menyelesaikan header skrip sementara beberapa impor masih berasal dari image, memerlukan flag tambahan. Lihat Reuse the image’s packages and add dependencies with UV untuk bentuk tersebut dan path yang diperlukan.
Jobs berjalan pada image Docker dari Hugging Face Spaces atau Docker Hub, sehingga Anda juga dapat menentukan image kustom apa pun:
hf jobs uv run \
--flavor a100-large \
--secrets HF_TOKEN \
--image <docker-image> \
train.pyfrom huggingface_hub import run_uv_job
run_uv_job(
"train.py",
flavor="a100-large",
secrets={"HF_TOKEN": "hf_..."},
image="<docker-image>",
)Update on GitHubWrapper TRL Jobs meluncurkan skrip TRL pada Jobs dengan konfigurasi preset untuk beberapa model, misalnya
trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybara.