İşlerde Modelleri Eğitin

Bu sayfa, bir kütüphanenin betiğiyle veya kendi betiğinizle modelleri Jobs üzerinde ince ayar yapmayı ve eğitmeyi gösterir. Her örnek, tek bir A10G üzerinde dakikalar içinde tamamlanan kısa bir çalışmayla sınırlıdır ve yaklaşık 0,10 $ hesaplama maliyeti gerektirir. Job, Hugging Face’in makinelerinde çalıştığı için terminalinizi veya dizüstü bilgisayarınızı kapatsanız da işlem devam eder. Daha önce bir Job çalıştırmadıysanız, Hızlı Başlangıç CLI’nin kurulumunu, oturum açmayı ve bir Job’ın ihtiyaç duyduğu kredileri kapsar.

İlk çalışma

Bu komut, bir görüntü sınıflandırıcısını 2.000 Food-101 görüntüsü üzerinde ince ayar yapar ve yaklaşık üç dakika içinde Hub'daki ad alanınıza gönderir:

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

Transformers bölümü, tam çalışmayı ve diğer örnek betikleri kapsar.

Bir eğitim Job'unun nasıl oluşturulduğu

Yukarıdaki komutun beş parçası vardır ve bu sayfadaki her komutun aynı parçaları vardır.

• Ne çalışır. hf jobs uv run komutuyla başlatılan bir uv betiği: bağımlılıklarını üst kısımdaki bir yorum bloğunda (# /// script, PEP 723 biçimi) beyan eden ve uv’nin bunları taze bir ortama kurduğu bir Python betiği. TRL bölümünde bir örnek gösteriliyor. Veya hf jobs run komutuyla başlatılan bir kütüphane Docker görüntüsü: görüntüde zaten kurulu olan kütüphaneyi kullanır. Kütüphane pip ile kuruluyorsa bir uv betiğiyle başlayın. Kütüphane derlenmiş bağımlılıklarla birlikte bir görüntü sağlıyorsa veya belgeleri bunu söylüyorsa görüntüyü kullanın. Karşılaştırmalı değerlendirmeler için Docker görüntülerini kullanma bölümüne bakın.
• Bir token. İşler varsayılan olarak Hugging Face token'ı almaz. -s HF_TOKEN token'ınızı bir gizli değer olarak iletir, böylece çalıştırma modelini itebilir ve kısıtlı veya özel girdileri okuyabilir. Diğer gizli değerler de aynı şekilde iletilir, örneğin -s WANDB_API_KEY.
• Donanım ve süre. --flavor GPU'yu seçer. --timeout süreyi belirler; varsayılan değer 30 dakikadır. Zaman aşımına takılan bir çalıştırma durdurulur, bu nedenle --timeout değerini beklenen çalışma sürenizin üzerine ayarlayın. Donanım türü ve Zaman aşımı bölümlerine bakın.
• hf bayrakları ile betik arasında bir -- bulunmalıdır. -- öncesindeki bayraklar hf jobs içindir. Ardından betik yolu ve betiğin kendi argümanları gelir. Bu işaret yoksa, hf bayrağıyla aynı adı paylaşan bir betik argümanı, örneğin --timeout veya --token, hf tarafından alınır. Görüntü biçiminde, -- sonrasında gelen, konteynerde çalıştırılacak komuttur.
• Çıktının nereye gideceği. Aşağıdaki her kütüphane, tamamlanan modeli bir Hub deposuna gönderebilir ve her örnek bu seçeneği gösterir. Transformers ve TRL için depo, --output_dir adını alır. Bir çalıştırma, -v kullanarak birini konteynere bağlayarak, ilerledikçe bağlı bir bucket'a da yazabilir. Bitimden sonra bölümüne bakın.

Kendi eğitim kodunuz. Uygun olan en basit formu kullanın:

• Tek dosya. Bağımlılıklarını bir betik başlığında belirtin ve hf jobs uv run train.py komutunu çalıştırın. TRL bölümünde bir örnek gösterilmektedir.

• Yerel içe aktarmalara sahip bir proje klasörü, bir pyproject.toml veya yapılandırma dosyaları. hf jobs uv run yalnızca betik dosyasını yükler, bu nedenle klasörü bağlayın. Bağlama salt okunurdur, bu nedenle komut projeyi yazılabilir bir dizine kopyalar ve orada çalıştırır, tıpkı yerelde yapacağınız gibi:

  Kopyalandı

  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, bağımlılıkları pyproject.toml dosyasından veya betiğin başlığından yükler; yerel içe aktarmalar ve göreli yollar değiştirilmeden çalışır. Yerel dizinler bölümüne bakın.

• Sistem paketleri veya CUDA araç seti gerektiren kod. Bir kez görüntü oluşturun ve hf jobs run ile çalıştırın. Docker Space ile kendi görüntünüzü oluşturun başlıklı bölümü inceleyin.

Bir betik, TRL bölümünde gösterildiği gibi, betik başlığındaki [tool.hf-jobs] tablosunda kendi başlatma yapılandırmasını da taşıyabilir. Betikte başlatma yapılandırmasını tanımlama bölümüne bakın. Aynı komutlar Python'dan run_uv_job() ve run_job() olarak kullanılabilir; bunlar Yapılandırma bölümünde ele alınır.

Uzun bir çalıştırma öncesi kontroller

Kapakları çıkarmadan önce, birkaç kontrol israf edilen bir çalıştırmayı önler.

• Önce duman testi yapın. Bu sayfadaki örneklerde yapıldığı gibi, komutu küçük bir varyant üzerinde adım sınırıyla çalıştırın. Bu, bağımlılıkların kurulduğunu, verilerin yüklendiğini, modelin sığırdığını ve push işleminin çalıştığını kanıtlar. Ardından sınırı kaldırın ve tam çalıştırmayı başlatın.
• Veri sığışını kontrol edin. Her varyantın sabit bir disk alanı vardır ve bu alan Fiyatlandırma ve Faturalandırma sayfasındaki Ephemeral Storage sütununda listelenir. Ağırlıklar, veri seti ve kaydedilen checkpoint'ler bu alanı paylaşır. Disk için çok büyük olan bir veri seti, indirilmek yerine akış olarak işlenebilir veya bağlanabilir. Büyük Veri Setlerini İşleme bölümüne bakın.
• Çalışma süresini tahmin edin. Duman testinin son train_* metrikleri train_steps_per_second değerini içerir ve trainer başlarken toplam adım sayısını yazdırır. Birlikte, tam çalışmanın eğitim süresini verir. Job, bağımlılıkları yüklemek ve modeli indirmek için de zaman harcadığından, --timeout değerini bunun rahat üzerinde ayarlayın. Lezzye göre oranlar Pricing and Billing sayfasındadır.
• Çoklu GPU içeren bir varyantta, her GPU için bir süreç başlatın. x2, x4 veya x8 ile biten varyantlar, tek bir makinede birden fazla GPU sağlar. Başlatma yönteminizin bunları kullandığından emin olun. Transformers ve TRL, TRL bölümünde gösterildiği gibi accelerate launch gerektirir. Axolotl bunu kendi başına yapar. Sadece python train.py tek bir GPU kullanır ve Trainer, GPU başına bir süreçten daha yavaş olan DataParallel'e geri düşer.
• Tekrar çalıştıracaksanız sabitleyin. Bir betik URL'sini main yerine bir commit'e, bir görüntüyü ise latest yerine belirli bir etikete sabitleyin. Böylece bir yeniden çalıştırmada aynı yazılımı alırsınız. Aşağıdaki betik URL'leri main'i takip eder, bu nedenle birini yeniden çalıştırmadan önce commit'i sabitleyin.
• Zaman aşımı veya bir çökme durumunda çalışmanın kaybolmaması için uzun süreli çalışmaları bağlı bir kovaya kontrol noktası olarak kaydedin. Bitimden sonra bölümüne bakın.

Çalışırken

Hem hf jobs run hem de hf jobs uv run komutları, çalıştırma bitene kadar logları akış olarak gösterir ve terminalinizi açık tutar. Ctrl+C yalnızca log akışını durdurur. İş, tamamlanana veya hf jobs cancel <job_id> komutuyla durdurulana kadar çalışmaya devam eder.

Daha uzun çalıştırmalar için, Job ID'yi hemen geri almak üzere -d (ayır) parametresini iletin, ardından çalıştırmayı hf jobs logs -f <job_id> ile izleyin ve GPU'nun meşgul olduğunu hf jobs stats <job_id> ile doğrulayın. Ayırılmış bir çalıştırmadan sonra hf jobs wait <job_id>, Job sona erene kadar bekler ve başarısız olursa sıfır dışı bir kodla çıkar; bu, bir betiğin veya bir ajan döngüsünün ihtiyaç duyduğu davranıştır. Ayırılmamış bir çalıştırma zaten bunu yapar. Job Yönetimi bölümüne bakın.

İş günlükleri, kayıp değerlerini metin olarak yazdırır. Eğriler için, eğitimcileri trackio gibi bir deney izleyicisine yönlendirin ve Weights & Biases gibi barındırılan bir izleyici için anahtarını ikinci bir gizli değer olarak iletin.

Bitiminden sonra

Bir Job sona erdiğinde, ister tamamlansın ister başarısız olsun ya da zaman aşımına uğrasın, Job'un diski silinir. Saklamak istediğiniz her şey, bu noktadan önce konteynerden dışarı çıkarılmalıdır.

Modeli bir Hub deposuna gönderin. Bu sayfadaki her kütüphanenin bu amaçla bir seçeneği vardır: Transformers, TRL ve Diffusers için --push_to_hub, Unsloth betikleri için --output-repo, Axolotl YAML dosyasında hub_model_id. Çalışmanın sonunda kütüphane, ağırlıkları, tokenizer'ı ve temel modeli ile eğitim argümanlarını kaydeden oluşturulmuş bir model kartını yükler. Depo yoksa oluşturulur. Özel (private) hale getirmek için önce hf repos create <name> --private komutuyla oluşturun. İnce tanecikli bir jetonun, model deposuna yazma ve oluşturma erişimine sahip olması gerekir. Bu erişim olmadan çalışma sonuna kadar eğitim yapar ancak yükleme sırasında başarısız olur.

İlerledikçe bir kovaya yazın. Saatler süren bir çalıştırma için, mevcut bir Storage Bucket'ı okuma-yazma olarak bağlayın (hf buckets create ile bir tane oluşturun) ve kütüphanenin çıktı dizinini ona yönlendirin. Kontrol noktaları, kaydedildikleri anda kovaya yerleşir; bu sayede bir zaman aşımı veya çökme çalıştırmayı kaybettirmez ve sonraki Job onlardan devam edebilir. Aynı yol, model olmayan değerlendirme çıktıları, günlükler ve diğer her şey için de geçerlidir.

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

Transformers, TRL ve Diffusers betikleri --output_dir alır. Axolotl, YAML içinde output_dir alır. Ayrıca --push_to_hub geçirirseniz, --hub_model_id değerini de ayarlayın; aksi takdirde depo, çıktı yolunun son kısmıyla (run-01) adlandırılır. Yarıda kalan bir çalıştırmayı sürdürmek için aynı kovayı yeniden bağlayın ve kütüphanenin devam etme seçeneğini, örneğin Transformers Trainer için --resume_from_checkpoint gibi, geçirin. Bağlama seçenekleri için Volume bölümüne bakın.

Başarısız bir çalışmayı okuyun. Başarısız olan bir Job, günlüklerini korur: hf jobs logs <job_id> işlem bittikten sonra çalışır ve hf jobs inspect <job_id> son durumu ve hata mesajını verir. hf jobs logs -f, çalıştırma başarılı olsun ya da olmasın, günlük akışı sonlandığında döner; bu nedenle çalıştığını varsaymadan önce inspect komutunu kontrol edin.

Transformers

Transformers deposundaki örnek betikler, bağımlılıklarını betik başlığında belirtir; bu sayede GitHub URL'lerinden doğrudan Jobs üzerinde çalıştırılabilirler. URL'den sonraki argümanlar betiğe iletilir. İlk çalıştırma, image-classification betiğini kullanır.

Tam çalıştırma için o komuttan --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1 parametrelerini kaldırın: 75.000 Food-101 eğitim görüntüsü üzerinde üç epoch, a10g-small üzerinde yaklaşık bir saat sürer, bu lezzetin ücretine göre yaklaşık 1 $ tutar ve %90 doğruluğa ulaşır. Başlatmadan önce --timeout değerini 2h olarak artırın. --push_to_hub, modeli çıktı dizini adını kullanarak ad alanınız altında yükler. Metin sınıflandırma, özetleme, çeviri, token sınıflandırma, konuşma tanıma ve daha fazlası için betikler mevcuttur.

TRL

TRL, her eğitimci (SFT, DPO, GRPO ve diğerleri) için kendi bağımlılıklarını açıklayan, Transformers betikleri gibi URL'lerinden doğrudan Jobs üzerinde çalıştırılabilen hazır betiklere sahiptir. Bu komut, küçük bir modeli söyleşi veri seti üzerinde ince ayar yapar:

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

Bu işlem yaklaşık altı dakikada tamamlanır. Tam çalıştırma için --max_steps parametresini kaldırın: Capybara için üç epoch, yani betiğin varsayılanı, a10g-small üzerinde yaklaşık 2 saat 20 dakika sürer, bu nedenle --timeout değerini buna göre artırın. TRL’nin kendi belgeleri daha hızlı olan a100-large kullanır.

Kendi TRL betiğinizi yazma ve huggingface/trl görüntüsünü çalıştırma dahil olmak üzere tam rehber, TRL belgelerindeki Training with Jobs bölümündedir.

Birden fazla GPU için, accelerate içeren TRL görüntüsüne geçin ve her GPU için bir süreç başlatmasını sağlayın:

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

--max_steps olmadan, tam çalışma (Capybara için üç epoch, scriptin varsayılanı) iki A10G üzerinde yaklaşık 1 saat 35 dakika sürer.

Kendi TRL betiğinizi yazdığınızda, başlatma yapılandırması onunla birlikte taşınabilir. Başlıktaki [tool.hf-jobs] tablosu, türü, zaman aşımını ve gizli bilgileri belirler:

# /// 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 artık bayrak gerektirmez ve geçirdiğiniz bir bayrak yine de önceliklidir. Başlatma yapılandırmasını betikte tanımlama bölümüne bakın.

Unsloth

Unsloth, unsloth/jobs veri setinde her model ailesi için ayrı bir hazır çalıştırılabilir betik sunar. Bu betikler, başlıklarındaki komutla Unsloth’u kurar ve veri seti ile çıktı deposunu argüman olarak alır:

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

Bu işlem yaklaşık beş dakikada tamamlanır ve bir LoRA adaptörü gönderir. Tam bir epoch için --max-steps 50 ifadesini --num-epochs 1 ile değiştirin ve --timeout değerini artırın. Adım adım anlatım, Hugging Face blogundaki Fine-tune with Unsloth on Jobs başlıklı yazıdadır.

Axolotl

Axolotl, bir YAML yapılandırmasını alır ve kendi Docker görüntüsünden çalıştırılır; bu nedenle bu bölümde sabitlenmiş bir etiketle hf jobs run kullanılır ve yapılandırma -v ile yerel bir dizinden senkronize edilir. Axolotl örneklerinden bir yapılandırmayı ./configs/lora.yml olarak kaydedin ve komutun ardından gösterilen anahtarları ekleyin. Bu örnek, examples/phi/lora-3.5.yaml dosyasını kullanır; bu dosya, Phi-3.5-mini için bir LoRA ince ayarıdır ve başka bir değişiklik içermez. Görüntü zaten axolotl komutunu içerir.

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, yerel configs dizinini özel jobs-artifacts kovanaza (ilk kullanımda sizin için oluşturulur) yükler ve konteynerde salt okunur olarak bağlar; böylece diskteki YAML, çalışmanın kullandığı YAML olur. Çıktı YAML içinde ayarlanır. Bu anahtarlar, çalışmanın sonunda modeli iter ve max_steps bu deneme çalışmasını sınırlar:

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

Bu işlem yaklaşık yedi dakikada tamamlanır ve adaptörü hub_model_id adresine, özel bir depo olarak gönderir. Tam çalıştırma için max_steps parametresini kaldırın. Görsel etiketi biçimleri Axolotl’ın Docker kılavuzunda açıklanmıştır.

Daha fazla GPU için yalnızca flavor’ı değiştirin, başka bir şey yapmayın: a10g-largex4 üzerinde axolotl train, her GPU için bir süreç başlatır. DeepSpeed ve FSDP ise Axolotl’ın çoklu GPU kılavuzunda ele alınan YAML anahtarları meselesidir.

Daha fazla ayrıntı için Axolotl belgelerindeki Hugging Face İşleri kılavuzuna bakın.

Diffusers

Diffusers deposundaki DreamBooth LoRA betiklerinin çoğu, bağımlılıklarını betik başlığında belirtir; bu sayede Transformers betikleri gibi GitHub URL'lerinden doğrudan Jobs üzerinde çalışırlar. Bu komut, bir köpeğin beş fotoğrafında FLUX.2 [klein] 4B için bir LoRA eğitir:

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

Bu işlem yaklaşık beş dakikada tamamlanır ve LoRA'yı iter. Gerçek bir çalıştırma için --max_train_steps değerini artırın; FLUX.2 README dosyası 500 kullanır. O klasördeki diğer README dosyaları, kalan modelleri ve bellek seçeneklerini kapsar. Bir betiğin başındaki # /// script bloğunu kontrol edin: SDXL betiği gibi bu bloğu içermeyen betiklerin bağımlılıkları --with ile geçirilmelidir.

Daha ileriye

• Eğittiğiniz modeli bir değerlendirme çalışması veya demo için geçici bir uç noktanın arkasına almak için Model Sunma kullanın. Çıkarım Uç Noktaları ise sürekli açık kalan bir uç nokta çalıştırır.
• Gizli anahtarlar, ortam değişkenleri, hacimler ve bir betiğin kendi ayarını ve zaman aşımını taşımasına olanak tanıyan [tool.hf-jobs] tablosu için Yapılandırma.
• İşleri listelemek, denetlemek, hata ayıklamak ve iptal etmek için İşleri Yönet.
• Disk sığmayan verilerin akış ve bağlama işlemleri için Büyük Veri Setlerini İşleme.
• Zamanlayıcıda bir eğitim komutu çalıştırmak için İşleri Zamanla.
• Topluluk yazılarını, görsel-dil ince ayarını ve büyük veri kümelerini bir eğitim çalışmasına akış olarak aktarmayı içeren Örnekler & Eğiticiler.
• Kodlama ajanından Jobs kullanma: hf CLI becerisi, Claude Code, Codex ve Cursor'ın bu çalıştırmaları sizin adınıza başlatıp izlemesini sağlar.