Melatih Model pada Tugas

Halaman ini menunjukkan cara melakukan fine-tuning dan melatih model pada Jobs, menggunakan skrip dari sebuah library atau skrip Anda sendiri. Setiap contoh dibatasi pada eksekusi singkat yang selesai dalam hitungan menit di satu A10G, dengan biaya komputasi sekitar $0.10. Job berjalan di mesin Hugging Face, sehingga tetap berjalan meskipun Anda menutup terminal atau laptop Anda. Jika Anda belum pernah menjalankan Job sebelumnya, Quickstart membahas instalasi CLI, proses login, dan kredit yang dibutuhkan oleh sebuah Job.

Jalankan pertama kali

Perintah ini melakukan fine-tuning pada klasifikasi gambar menggunakan 2.000 gambar Food-101 dan mengirimkannya ke namespace Anda di Hub, dalam waktu sekitar tiga menit:

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/transformers/main/examples/pytorch/image-classification/run_image_classification.py \
  --model_name_or_path google/vit-base-patch16-224-in21k \
  --dataset_name ethz/food101 \
  --do_train --do_eval \
  --remove_unused_columns False \
  --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1 \
  --output_dir vit-food101 \
  --push_to_hub

Bagian Transformers membahas eksekusi penuh dan skrip contoh lainnya.

Bagaimana sebuah Job pelatihan disusun

Perintah di atas memiliki lima bagian, dan setiap perintah di halaman ini memiliki bagian yang sama.

• Yang dijalankan. Bisa berupa skrip uv, yang diluncurkan dengan hf jobs uv run: sebuah skrip Python yang mendeklarasikan dependensinya dalam blok komentar di bagian atas (# /// script, format PEP 723), yang kemudian diinstal oleh uv ke lingkungan baru. Bagian TRL menunjukkan satu contohnya. Atau bisa berupa image Docker dari sebuah pustaka, yang diluncurkan dengan hf jobs run, yang menggunakan pustaka yang sudah terinstal di dalam image tersebut. Mulailah dengan skrip uv jika pustaka tersebut dapat diinstal dengan pip. Gunakan image jika pustaka tersebut menyediakannya dengan dependensi yang sudah dikompilasi, atau jika dokumentasinya menginstruksikan demikian. Lihat Menggunakan image Docker untuk memahami trade-off-nya.
• Sebuah token. Job tidak mendapatkan token Hugging Face secara default. -s HF_TOKEN meneruskan token Anda sebagai secret, sehingga run dapat mendorong modelnya dan membaca input yang gated atau privat. Secret lain dikirim dengan cara yang sama, misalnya -s WANDB_API_KEY.
• Perangkat keras dan waktu. --flavor memilih GPU. --timeout mengatur batas waktu, yang secara default 30 menit. Eksekusi yang mencapai batas waktu akan dihentikan, sehingga aturlah --timeout di atas perkiraan waktu eksekusi Anda. Lihat Flavor perangkat keras dan Batas waktu.
• Ada -- di antara flag hf dan skrip. Flag sebelum -- adalah untuk hf jobs. Setelahnya adalah path skrip dan argumen skrip itu sendiri. Tanpanya, argumen skrip yang memiliki nama sama dengan flag hf, seperti --timeout atau --token, akan diambil oleh hf. Dalam bentuk image, apa yang mengikuti -- adalah perintah yang akan dijalankan di dalam container.
• Ke mana output dikirim. Setiap pustaka di bawah ini dapat mendorong model yang sudah selesai ke repositori Hub, dan setiap contoh menunjukkan opsinya. Untuk Transformers dan TRL, repositori mengambil nama dari --output_dir. Sebuah run juga dapat menulis ke bucket yang terpasang saat proses berjalan, menggunakan -v untuk memasangnya ke dalam container. Lihat Setelah selesai.

Kode pelatihan Anda sendiri. Gunakan bentuk paling sederhana yang sesuai:

• Satu file. Deklarasikan dependensinya di header skrip dan jalankan hf jobs uv run train.py. Bagian TRL menunjukkan satu contohnya.

• Folder proyek dengan impor lokal, file pyproject.toml atau file konfigurasi. hf jobs uv run hanya mengunggah file skrip, jadi pasang (mount) folder tersebut. Mount bersifat read-only, sehingga perintah menyalin proyek ke direktori yang dapat ditulis dan menjalankannya di sana, seperti yang Anda lakukan secara lokal:

  Disalin

  hf jobs run --flavor a10g-small --timeout 30m -s HF_TOKEN \
    -v ./my-project:/code ghcr.io/astral-sh/uv:python3.12-bookworm -- \
    bash -c "cp -r /code /tmp/project && cd /tmp/project && uv run train.py --config configs/run.yaml"

  uv run menginstal dependensi dari pyproject.toml atau header skrip, dan impor lokal serta path relatif berfungsi tanpa perubahan. Lihat Local directories.

• Kode yang membutuhkan paket sistem atau toolkit CUDA. Bangun image sekali lalu jalankan dengan hf jobs run. Lihat Build your own image with a Docker Space.

Sebuah skrip juga dapat membawa konfigurasi peluncurannya sendiri dalam tabel [tool.hf-jobs] di header skrip, seperti yang ditunjukkan pada bagian TRL. Lihat Mendefinisikan konfigurasi peluncuran di skrip. Perintah yang sama tersedia dari Python sebagai run_uv_job() dan run_job(), yang dibahas dalam Konfigurasi.

Pemeriksaan sebelum eksekusi panjang

Sebelum Anda melepas cap, beberapa pemeriksaan dapat mencegah eksekusi yang sia-sia.

• Lakukan uji coba singkat terlebih dahulu. Jalankan perintah dengan batas langkah pada varian kecil, seperti contoh di halaman ini. Hal ini membuktikan bahwa dependensi terpasang, data dimuat, model muat, dan push berhasil. Kemudian, hapus batasnya dan luncurkan eksekusi penuh.
• Periksa apakah data muat. Setiap flavor memiliki disk tetap, yang tercantum di kolom Ephemeral Storage pada Pricing and Billing. Bobot, dataset, dan checkpoint yang disimpan berbagi disk tersebut. Dataset yang terlalu besar untuk disk dapat di-streaming atau dimount alih-alih diunduh. Lihat Process Large Datasets.
• Perkirakan waktu eksekusi. Metrik train_* akhir dari smoke test mencakup train_steps_per_second, dan trainer mencetak jumlah total langkah saat dimulai. Keduanya memberikan waktu pelatihan untuk seluruh eksekusi. Atur --timeout dengan nyaman di atasnya, karena Job juga menghabiskan waktu untuk menginstal dependensi dan mengunduh model. Tarif per flavor ada di Pricing and Billing.
• Pada varian multi-GPU, jalankan satu proses per GPU. Varian yang diakhiri dengan x2, x4 atau x8 menyediakan beberapa GPU dalam satu mesin. Pastikan cara Anda meluncurkan proses memanfaatkan GPU tersebut. Transformers dan TRL membutuhkan accelerate launch, seperti yang ditunjukkan pada bagian TRL. Axolotl melakukannya secara mandiri. Peluncuran biasa dengan python train.py hanya menggunakan satu GPU, dan Trainer akan kembali ke DataParallel, yang lebih lambat daripada satu proses per GPU.
• Pin jika Anda akan menjalankan ulang. Pin URL skrip ke commit alih-alih main, dan pin image ke tag tertentu alih-alih latest. Dengan demikian, eksekusi ulang akan menggunakan perangkat lunak yang sama. URL skrip di bawah ini mengikuti main, jadi pin commit sebelum Anda menjalankan ulang salah satunya.
• Simpan checkpoint untuk run yang panjang ke bucket yang terpasang, sehingga timeout atau crash tidak akan menghilangkan run tersebut. Lihat Setelah selesai.

Saat berjalan

Kedua hf jobs run dan hf jobs uv run mengalirkan log dan menahan terminal Anda hingga eksekusi selesai. Ctrl+C hanya menghentikan aliran log. Job tetap berjalan hingga selesai atau Anda menghentikannya dengan hf jobs cancel <job_id>.

Untuk eksekusi yang lebih lama, gunakan -d (detach) untuk langsung mendapatkan Job ID, lalu pantau jalannya dengan hf jobs logs -f <job_id> dan pastikan GPU sedang aktif dengan hf jobs stats <job_id>. Setelah eksekusi detached, hf jobs wait <job_id> akan memblokir hingga Job selesai dan keluar dengan status non-zero jika gagal, yang dibutuhkan oleh skrip atau loop agen. Eksekusi non-detached sudah melakukan hal ini. Lihat Manage Jobs.

Log pekerjaan mencetak nilai loss sebagai teks. Untuk kurva, arahkan trainer ke pelacak eksperimen seperti trackio dan, untuk pelacak yang dihosting seperti Weights & Biases, berikan kuncinya sebagai rahasia kedua.

Setelah selesai

Disk dari sebuah Job dibuang ketika Job berakhir, baik karena selesai, gagal, maupun habis waktu. Segala sesuatu yang ingin Anda simpan harus dikeluarkan dari container sebelum saat itu.

Push model ke repo Hub. Setiap library di halaman ini memiliki opsi untuk itu: --push_to_hub untuk Transformers, TRL dan Diffusers, --output-repo untuk skrip Unsloth, hub_model_id dalam YAML Axolotl. Di akhir run, library mengunggah weights, tokenizer, dan model card yang dihasilkan yang mencatat base model serta argumen training. Repo akan dibuat jika belum ada. Untuk membuatnya privat, buat terlebih dahulu dengan hf repos create <name> --private. Token fine-grained memerlukan akses write dan create ke repo model. Tanpa itu, run akan melatih hingga akhir lalu gagal saat upload.

Tulis ke bucket saat proses berjalan. Untuk run yang memakan waktu berjam-jam, mount Storage Bucket yang sudah ada dengan mode baca-tulis (buat satu dengan hf buckets create) dan arahkan direktori output pustaka ke sana. Checkpoint akan masuk ke bucket saat disimpan, sehingga timeout atau crash tidak akan menghilangkan run, dan Job berikutnya dapat melanjutkan dari checkpoint tersebut. Rute yang sama juga berlaku untuk output evaluasi, log, dan hal lain yang bukan model.

hf jobs uv run --flavor a10g-large --timeout 8h -s HF_TOKEN \
  -v hf://buckets/your-username/checkpoints:/ckpt -- \
  train.py --output_dir /ckpt/run-01

Skrip Transformers, TRL, dan Diffusers menerima --output_dir. Axolotl menerima output_dir di YAML. Jika Anda juga meneruskan --push_to_hub, tetapkan juga --hub_model_id, atau repositori akan dinamai berdasarkan bagian terakhir dari jalur output (run-01). Untuk melanjutkan eksekusi yang terputus, mount bucket yang sama lagi dan teruskan opsi resume dari pustakanya, seperti --resume_from_checkpoint untuk Trainer Transformers. Lihat Volumes untuk opsi mount.

Baca run yang gagal. Job yang gagal tetap menyimpan log-nya: hf jobs logs <job_id> tetap berfungsi setelah job berakhir, dan hf jobs inspect <job_id> memberikan status akhir serta pesan error. hf jobs logs -f akan berhenti ketika stream log berakhir, terlepas dari apakah run berhasil atau tidak, jadi periksa inspect sebelum mengasumsikan bahwa run berhasil.

Transformers

Skrip contoh di repositori Transformers menyatakan dependensinya di header skrip, sehingga dapat dijalankan di Jobs langsung dari URL GitHub-nya. Argumen setelah URL diteruskan ke skrip. Eksekusi pertama menggunakan skrip klasifikasi gambar.

Untuk eksekusi penuh, hilangkan --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1 dari perintah tersebut: tiga epoch pada 75.000 gambar pelatihan Food-101 memakan waktu sekitar satu jam di a10g-small, sekitar $1 pada tarif flavor tersebut, dan mencapai akurasi 90%. Naikkan --timeout menjadi 2h sebelum Anda meluncurkannya. --push_to_hub mengunggah model di bawah namespace Anda menggunakan nama direktori output. Skrip tersedia untuk klasifikasi teks, ringkasan, terjemahan, klasifikasi token, pengenalan ucapan, dan lainnya.

TRL

TRL memiliki skrip siap-jalan untuk setiap trainer (SFT, DPO, GRPO, dan lainnya), masing-masing mendeklarasikan dependensinya sendiri, sehingga dapat dijalankan di Jobs langsung dari URL-nya, seperti skrip Transformers. Perintah ini melakukan fine-tuning pada model kecil menggunakan dataset chat:

hf jobs uv run --flavor a10g-small --timeout 30m -s 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_hub

Ini selesai dalam waktu sekitar enam menit. Hapus --max_steps untuk eksekusi penuh: tiga epoch Capybara, nilai bawaan skrip, memakan waktu sekitar 2 jam 20 menit di a10g-small, jadi naikkan --timeout bersamanya. Dokumentasi TRL sendiri menggunakan a100-large, yang lebih cepat.

Panduan lengkap, termasuk menulis skrip TRL Anda sendiri dan menjalankan image huggingface/trl, adalah Training with Jobs di dokumentasi TRL.

Untuk beberapa GPU, beralih ke image TRL, yang menyertakan accelerate, dan biarkan memulai satu proses per GPU:

hf jobs run --flavor a10g-largex2 --timeout 30m -s HF_TOKEN huggingface/trl -- \
  accelerate launch --num_processes 2 -m trl.scripts.sft \
  --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

Tanpa --max_steps, eksekusi penuh (tiga epoch Capybara, nilai bawaan skrip) memakan waktu sekitar 1 jam 35 menit pada dua A10G.

Saat Anda menulis skrip TRL Anda sendiri, konfigurasi peluncuran dapat menyertainya. Tabel [tool.hf-jobs] di header mengatur flavor, timeout, dan secrets:

# /// script
# dependencies = ["trl"]
#
# [tool.hf-jobs]
# flavor  = "a10g-small"
# timeout = "1h"
# secrets = ["HF_TOKEN"]
# ///
from trl import SFTConfig, SFTTrainer
...

hf jobs uv run train.py kemudian tidak memerlukan flag, dan flag yang Anda berikan tetap menang. Lihat Mendefinisikan konfigurasi peluncuran di dalam skrip.

Unsloth

Unsloth menyediakan skrip siap jalan di dataset unsloth/jobs, satu untuk setiap keluarga model. Skrip tersebut menginstal Unsloth dari header skripnya dan mengambil dataset serta repo output sebagai argumen:

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://huggingface.co/datasets/unsloth/jobs/resolve/main/sft-lfm2.5.py \
  --dataset mlabonne/FineTome-100k \
  --max-steps 50 \
  --output-repo your-username/lfm-finetuned

Proses ini selesai dalam waktu sekitar lima menit dan mendorong adapter LoRA. Untuk satu epoch penuh, ganti --max-steps 50 dengan --num-epochs 1 dan tingkatkan --timeout. Panduan lengkapnya ada di Fine-tune with Unsloth on Jobs di blog Hugging Face.

Axolotl

Axolotl mengambil konfigurasi YAML dan dijalankan dari image Docker-nya sendiri, sehingga bagian ini menggunakan hf jobs run dengan tag yang dipatok dan menyinkronkan konfigurasi dari direktori lokal dengan -v. Simpan konfigurasi dari Axolotl examples sebagai ./configs/lora.yml dan tambahkan kunci yang ditunjukkan setelah perintah. Contoh ini menggunakan examples/phi/lora-3.5.yaml, yaitu fine-tune LoRA untuk Phi-3.5-mini, tanpa perubahan lain. Image tersebut sudah berisi perintah axolotl.

hf jobs run --flavor a10g-small --timeout 30m -s HF_TOKEN \
  -v ./configs:/configs \
  axolotlai/axolotl:0.19.0-py3.12-cu130-2.13.0 -- \
  axolotl train /configs/lora.yml

-v ./configs:/configs mengunggah direktori lokal configs ke bucket jobs-artifacts privat Anda (dibuatkan untuk Anda saat penggunaan pertama) dan memount-nya secara read-only di dalam container, sehingga YAML di disk Anda adalah YAML yang digunakan oleh run. Output diatur di YAML. Kunci-kunci ini mendorong model di akhir run, dan max_steps membatasi run percobaan ini:

hub_model_id: your-username/my-adapter
hub_strategy: end
max_steps: 20

Proses ini selesai dalam waktu sekitar tujuh menit dan mendorong adapter ke hub_model_id, sebagai repo privat. Hapus max_steps untuk eksekusi penuh. Format tag gambar dijelaskan dalam panduan Docker Axolotl.

Untuk lebih banyak GPU, ubah flavor dan tidak ada yang lain: pada a10g-largex4, axolotl train memulai satu proses per GPU secara otomatis. DeepSpeed dan FSDP kemudian menjadi soal kunci YAML, yang dibahas dalam panduan multi-GPU Axolotl.

Untuk detail lebih lanjut, lihat panduan Hugging Face Jobs di dokumentasi Axolotl.

Diffusers

Sebagian besar skrip DreamBooth LoRA di repositori Diffusers menyatakan dependensinya di header skrip, sehingga dapat dijalankan di Jobs langsung dari URL GitHub-nya, seperti skrip Transformers. Perintah ini melatih LoRA untuk FLUX.2 [klein] 4B menggunakan lima foto anjing:

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/diffusers/main/examples/dreambooth/train_dreambooth_lora_flux2_klein.py \
  --pretrained_model_name_or_path black-forest-labs/FLUX.2-klein-4B \
  --dataset_name diffusers/dog-example \
  --instance_prompt "a photo of sks dog" \
  --resolution 512 --mixed_precision bf16 --guidance_scale 1 \
  --gradient_checkpointing --cache_latents \
  --optimizer adamW --use_8bit_adam --learning_rate 1e-4 \
  --max_train_steps 20 --seed 0 \
  --output_dir /tmp/out \
  --push_to_hub --hub_model_id your-username/klein-dog-lora

Proses ini selesai dalam waktu sekitar lima menit dan mendorong LoRA. Naikkan --max_train_steps untuk eksekusi sungguhan; FLUX.2 README menggunakan 500. README lainnya di folder tersebut mencakup model yang tersisa beserta opsi memori mereka. Periksa bagian atas skrip untuk blok # /// script: skrip yang tidak memilikinya, seperti skrip SDXL, memerlukan dependensi yang diteruskan dengan --with.

Lebih lanjut

• Serve Models untuk menempatkan model yang Anda latih di belakang endpoint sementara, untuk menjalankan evaluasi atau demo. Inference Endpoints menjalankan endpoint yang tetap aktif.
• Konfigurasi untuk rahasia, variabel lingkungan, volume, dan tabel [tool.hf-jobs] yang memungkinkan skrip membawa konfigurasi dan batas waktu (timeout) miliknya sendiri.
• Kelola Job untuk membuat daftar, memeriksa, men-debug, dan membatalkan Job.
• Proses Dataset Besar untuk streaming dan mounting data yang tidak muat di disk.
• Jadwalkan Tugas untuk menjalankan perintah pelatihan berdasarkan timer.
• Contoh & Tutorial untuk tulisan komunitas, termasuk penyesuaian halus (fine-tuning) visi-bahasa dan streaming dataset besar ke dalam proses pelatihan.
• Gunakan Jobs dari agen coding: skill hf CLI memungkinkan Claude Code, Codex, dan Cursor untuk meluncurkan dan memantau run ini untuk Anda.