Trainer özellikleri

Aşağıdaki her tarif, Trainer'ın belirli bir özelliğini gösterir: özel kayıp fonksiyonları, bellek verimli değerlendirme, checkpoint stratejileri ve daha fazlası.

Burada görmek istediğiniz bir özellik veya iş akışı varsa bir issue açın.

Özel kayıp fonksiyonu

Varsayılan kayıp fonksiyonunu değiştirmek için compute_loss_func parametresini Trainer sınıfına iletin. Bu fonksiyon, ileri geçişten sonra çalışır ve yalnızca kaybın çıktılardan nasıl hesaplanacağını tanımlar. İleri geçişin kendisini değiştirmek istiyorsanız bunun yerine compute_loss() metodunu alt sınıflandırın.

Özel kayıp fonksiyonunun aşağıdaki imzaya sahip olması gerekir:

import torch.nn.functional as F

def my_loss_fn(outputs, labels, num_items_in_batch):
    logits = outputs["logits"]
    loss = F.cross_entropy(logits, labels, reduction="sum")
    return loss / num_items_in_batch

• outputs, ham model çıktısıdır (outputs.logits biçimi (batch, seq_len, vocab_size) şeklindedir).
• labels, Trainer'in ileri geçişten önce girdi partisindeki token kimliklerini ayırarak elde ettiği değerdir.
• num_items_in_batch, birikmiş tam batch içindeki tahmin hedeflerinin sayısını ifade eder. Neden-sonuç LM modellerinde, etiket kaydırması her dizinin 0. konumunu hedef olmadan bıraktığı için kaydırılmış etiketler (labels[..., 1:]) sayılır. Ayrıntılar için Kayıp ölçekleme bölümüne bakın. Özel bir kayıp fonksiyonu sağlandığında Trainer otomatik kayıp normalizasyonunu atlar; bu nedenle fonksiyonunuz normalizasyonu doğrudan ele almalıdır.

trainer = Trainer(
    model=model,
    args=TrainingArguments(...),
    train_dataset=train_dataset,
    compute_loss_func=my_loss_fn,
)
trainer.train()

compute_loss() metodunu geçersiz kılmanın daha fazla örneği için alt sınıflandırma kılavuzuna bakın.

Başlangıçta değerlendirme

İlk eğitim adımından önce tam bir değerlendirme turu çalıştırmak için eval_on_start=True değerini ayarlayın. Eğitim öncesi değerlendirme, özellikle uzun süreli çalıştırmalarda değerlendirme hattındaki sorunları erken aşamada ortaya çıkarır.

eval_on_start, geçerli bir eval_strategy (örneğin "epoch") ve bir değerlendirme veri seti gerektirir.

from transformers import Trainer, TrainingArguments

trainer = Trainer(
    model=model,
    args=TrainingArguments(
        output_dir="out",
        eval_strategy="epoch",
        eval_on_start=True,
    ),
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    compute_metrics=compute_metrics,
)
trainer.train()

Tam bir eval zaman alır, bu nedenle en faydalı kullanım anları ilk çalıştırmalar veya compute_metrics değiştirildikten sonraki çalıştırmalardır.

Hafıza verimli değerlendirmeler

Değerlendirme sırasında Trainer, her batch üzerinde bir ileri geçiş çalıştırır ve logitleri GPU üzerinde tek bir tensöre birleştirir. Değerlendirme veri seti tamamen işlendikten sonra Trainer, birleştirilen logitleri CPU'ya taşır ve compute_metrics fonksiyonunu çağırır. Büyük modeller veya değerlendirme setleri için, biriken logitler GPU belleğini tüketebilir; çünkü aynı donanımda eğitim sorunsuz çalışır ve eğitim sırasında her seferinde yalnızca bir batch'in aktivasyonları tutulur.

eval_accumulation_steps

Biriken tahminleri her n batch'te bir GPU'dan CPU'ya taşıyın. Daha düşük değerler, daha sık CPU aktarımları pahasına GPU belleğini azaltır.

from transformers import Trainer, TrainingArguments

trainer = Trainer(
    model=model,
    args=TrainingArguments(
        output_dir="out",
        eval_strategy="epoch",
        eval_accumulation_steps=16,   # move predictions to CPU every 16 batches
    ),
    eval_dataset=eval_dataset,
    compute_metrics=compute_metrics,
)
trainer.train()

preprocess_logits_for_metrics

GPU üzerinde, her eval batch'inde, ileri geçişin hemen ardından ve logit birikiminden önce bir kez çağrılır. Dönen değer, eval_pred.predictions içindeki logitleri değiştirir. Hesaplamayı batch düzeyinde çalıştırmak, batch başına gerginlik boyutunu azaltır ve eval_accumulation_steps'e daha küçük bir gerginlik aktarılmasını sağlar.

import evaluate
from transformers import Trainer, TrainingArguments

metric = evaluate.load("accuracy")

def preprocess_logits_for_metrics(logits, labels):
    if isinstance(logits, tuple):
        logits = logits[0]
    return logits.argmax(dim=-1)

def compute_metrics(eval_preds):
    preds, labels = eval_preds
    labels = labels[:, 1:].reshape(-1)
    preds = preds[:, :-1].reshape(-1)
    return metric.compute(predictions=preds, references=labels)

trainer = Trainer(
    model=model,
    args=TrainingArguments(
        output_dir="out",
        eval_strategy="epoch",
        eval_accumulation_steps=16,
    ),
    eval_dataset=eval_dataset,
    compute_metrics=compute_metrics,
    preprocess_logits_for_metrics=preprocess_logits_for_metrics,
)
trainer.train()

Dataloader performansı

Varsayılan olarak Trainer, dataloader_num_workers=0 ile bir dataloader oluşturur. Veriler ana işlemde yüklenirken GPU boşta kalır; bu durum, batch'ler arasında düşük GPU kullanım oranı olarak kendini gösterir.

Hem dataloader_persistent_workers hem de dataloader_prefetch_factor için dataloader_num_workers > 0 gereklidir.

• dataloader_persistent_workers, her epoch arasında worker alt süreçlerini canlı tutarak baştan başlatma işlemini önler; bunun bedeli ise daha yüksek bellek kullanımıdır.
• dataloader_prefetch_factor, her worker'ın önceden hazırladığı batch sayısını kontrol eder. dataloader_prefetch_factor=2 ve num_workers=4 kullanıldığında, GPU mevcut batch üzerinde eğitim yaparken bellekte en fazla 8 batch bulunur.

from transformers import TrainingArguments

args = TrainingArguments(
    output_dir="out",
    dataloader_num_workers=4,            # spawn 4 worker subprocesses
    dataloader_persistent_workers=True,  # keep them alive between epochs
    dataloader_prefetch_factor=2,        # each worker preloads 2 batches ahead
)

Örnekleri uzunluğa göre grupla

Benzer uzunluklardaki örnekleri gruplayarak padding'i azaltmak için train_sampling_strategy="group_by_length" kullanın. Ön hesaplanmış uzunluklar sağlamadığınızda Trainer, her veri seti öğesindeki ilk model girdisinden bunları çıkarır. İşleyici tabanlı çok modlu veri setleri BatchFeature nesneleri döndürdüğünde de bu çalışır, çünkü bunlar eşleme benzeri özellik kapsayıcılarıdır.

from transformers import TrainingArguments

training_args = TrainingArguments(
    output_dir="qwen3-vl-finetuned",
    train_sampling_strategy="group_by_length",
)

Eğer bir Dataset'in önceden hesaplanmış bir uzunluk sütunu varsa, Trainer bu sütunu kullanır. Varsayılan sütun adı length'tir. Veri setiniz başka bir ad kullanıyorsa length_column_name parametresini ayarlayın. Bu strateji, bilinen uzunluğa sahip bir veri seti gerektirir ve IterableDataset için yok sayılır.

Toplu yeniden dengeleme örneklemesi

Değişken uzunluklu veri setlerinde, bir mikro-toplu (micro-batch) içindeki ve cihazlar arası dengesizlik, cihazların dolgu (padding) üzerinde zaman kaybetmesine ve gradyan senkronizasyonu adımlarında boşta kalmasına neden olur.

TrainingArguments içinde train_sampling_strategy="batch_rebalance" değerini ayarlayarak her iki etkiyi de azaltabilirsiniz. Her optimizasyon adımı için örnekleyici:

1. Toplu işlemin örneklerini uzunluğa göre sıralar.
2. Sıralanmış batch'i cihazlar arasında paylaştırır; böylece her mikro-batch'in dolgu token maliyeti dengelenir. Uzun örnekler içeren mikro-batch'ler daha az örnek alırken, kısa örnekler içeren mikro-batch'ler daha fazla örnek alır.

Bu, her mikro-toplam içindeki dolgu miktarını azaltır ve her cihaz bir mikro-toplamı yaklaşık aynı anda tamamlar; bu da senkronizasyon sırasında boşta kalma süresini azaltır ve tepe bellek kullanımını "group_by_length" değerinden daha düşük tutar. Bu strateji şu an için yalnızca veri paralel eğitimde desteklenmektedir (tensor paralelliği henüz desteklenmemektedir).

from transformers import Trainer, TrainingArguments

trainer = Trainer(
    model=model,
    args=TrainingArguments(
        output_dir="out",
        train_sampling_strategy="batch_rebalance",  # balance padding cost across devices
        per_device_train_batch_size=8,              # average samples per micro-batch
        length_column_name="length",                # optional: dataset column with precomputed lengths
    ),
    train_dataset=train_dataset,
)
trainer.train()

per_device_train_batch_size burada kesin bir adım başına örnek sayısı değil, bir ortalamadır: bazı mikro-partiler daha az, bazıları daha fazla örnek içerir, ancak adım başına eğitilen toplam örnek sayısı, normal dağıtık örneklem stratejisiyle aynı kalır.

Örnekleme birimi, partileri sıralamak ve dengelemek için her örneğin uzunluğuna ihtiyaç duyar. Varsayılan olarak Trainer, bu uzunlukları hesaplamak için eğitim başlangıcında tüm veri setini bir kez tarar. Bu taramayı atlamak için uzunlukları önceden hesaplayıp bir veri seti sütununa yazın (örneğin ön işleme sırasında) ve sütunun adını length_column_name olarak iletin (varsayılan "length").

NEFTune

NEFTune, ileri geçiş sırasında token gömme vektörlerine rastgele gürültü ekler. Gürültü, düzenleyici (regularization) olarak görev yapar ve talimatla ince ayar (instruction fine-tuning) performansını iyileştirebilir.

NEFTune'ü TrainingArguments içinde neftune_noise_alpha değerini ayarlayarak etkinleştirin. Tipik alfa değerleri 5 ile 15 arasında değişir.

from transformers import Trainer, TrainingArguments

trainer = Trainer(
    model=model,
    args=TrainingArguments(
        output_dir="out",
        num_train_epochs=3,
        neftune_noise_alpha=5,
    ),
    train_dataset=train_dataset,
)
trainer.train()

NEFTune yalnızca eğitimi etkiler ve eğitimden sonra orijinal gömme katmanı geri yüklenir.

Kayıt Tutma

Trainer'ın logging_strategy, logging_steps ve report_to ile günlük kayıtlarını ne zaman ve nereye yazacağını kontrol edin.

• logging_strategy="steps", her logging_steps() optimizör güncellemesinde kayıt tutar. Bunun yerine her epoch sonunda kayıt tutmak için "epoch" kullanın.
• report_to, Trackio gibi bir deney izleyicisine günlükleri iletir.

from transformers import Trainer, TrainingArguments

trainer = Trainer(
    model=model,
    args=TrainingArguments(
        output_dir="out",
        logging_strategy="steps",
        logging_steps=50,               # write a log entry every 50 optimizer updates
        report_to="trackio",            # stream to Trackio (or "wandb", "tensorboard", …)
        run_name="model-experiment-v1", # display name in the tracker
    ),
    train_dataset=train_dataset,
)
trainer.train()

Kontrol Noktası Oluşturma

Trainer, her save_steps() optimizör güncellemesinde bir kontrol noktası kaydeder ve bunların hepsini (veya en son ~TrainingArguments.save_total_limit tanesini) saklar.

save_strategy="best", bir metriğe göre yalnızca en iyi tek checkpoint'i saklar. Yeni bir checkpoint, izlenen metrik iyileştiğinde kaydedilir; bu da disk alanını korur ve eski checkpoint'lerin birikmesini önler.

from transformers import Trainer, TrainingArguments

trainer = Trainer(
    model=model,
    args=TrainingArguments(
        output_dir="out",
        eval_strategy="epoch",
        save_strategy="best",
        metric_for_best_model="perplexity",   # save when eval perplexity improves
        greater_is_better=False,              # lower perplexity is better
        load_best_model_at_end=True,          # load the best weights after training finishes
    ),
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    compute_metrics=compute_metrics,          # must return {"perplexity": ...}
)
trainer.train()

Eğitimi sürdür

Eğitim yarıda kaldıysa ve ilerlemeyi kaybetmeden kaldığınız yerden devam etmek istiyorsanız train() fonksiyonuna resume_from_checkpoint=True parametresini iletin. Eğitim, output_dir içindeki en son kontrol noktasından devam edecektir.

trainer.train(resume_from_checkpoint=True)

Belirli bir noktadan devam etmek için bir checkpoint yolu belirtin.

trainer.train(resume_from_checkpoint="out/checkpoint-1000")

Yeniden başlatıldığında, Trainer optimizör durumunu, zamanlayıcı durumunu ve RNG durumunu geri yükler.

Checkpoint'ten devam etmek, checkpoint dizininde optimizer ve scheduler durum dosyalarının bulunmasını gerektirir. Bu dosyalar eksikse (örneğin, save_only_model=True durumunda), optimizer baştan başlar.

JIT denetim noktası oluşturma

Periyodik checkpoint'leme (save_strategy="steps" veya "epoch") kullanıldığında, son kaydedilen checkpoint ile kesinti arasındaki eğitim ilerlemesini kaybedersiniz. Kueue gibi önemsenebilir iş yüklerine sahip paylaşımlı kümelerde işler herhangi bir anda sonlandırılabildiğinden, bu boşluk saatlerce boşa harcanan hesaplama gücü anlamına gelebilir.

JIT (Just-In-Time) checkpointing bu boşluğu kapatır. Trainer bir SIGTERM sinyali aldığında, eğitim kesildiği tam noktada bir checkpoint kaydeder; böylece ilerlemede en az kayıpla devam edersiniz. Periyodik checkpointing ile birlikte çalışır. Periyodik kayıtlar çökmelere ve donanım arızalarına karşı koruma sağlarken, JIT kayıtları preemption ve düzgün kapatmalara karşı koruma sağlar.

Bunu TrainingArguments içinde enable_jit_checkpoint=True olarak ayarlayarak etkinleştirin.

from transformers import TrainingArguments

training_args = TrainingArguments(
    output_dir="your-model",
    enable_jit_checkpoint=True,
)

SIGTERM sinyali alındığında Trainer, mevcut eğitim adımının tamamlanmasını bekler, bir checkpoint kaydeder ve eğitimi zarifçe durdurur. Kayıt işlemi başladığında bir sentinel dosyası (checkpoint-is-incomplete.txt) yazılır ve checkpoint tamamen yazıldığında bu dosya kaldırılır. Bir checkpoint dizininde bu dosya hâlâ bulunuyorsa, kayıt işlemi tamamlanmadan yarıda kesilmiştir. Trainer bunu otomatik olarak kontrol etmez, bu nedenle devam etmeden önce kendiniz kontrol edin.

JIT kontrol noktasından, diğer herhangi bir kontrol noktasından olduğu gibi aynı şekilde devam edin.

trainer.train(resume_from_checkpoint=True)

Orkestratörünüzü, kontrol noktasının tamamlanması için yeterli süreye izin verecek şekilde yapılandırmalısınız. Varsayılan Kubernetes düzgün kapatma süresi yalnızca 30 saniyedir ve bu, genellikle daha büyük modeller için yeterli değildir.

spec:
  template:
    spec:
      terminationGracePeriodSeconds: 300

#SBATCH --signal=TERM@300

Gerekli kibarlık süresini, en uzun olası eğitim adımı süresi ile kontrol noktası kaydetme süresinin toplamına, kontrol noktası işlemi başlamadan önceki 3 saniyelik kill_wait gecikmesini ekleyerek hesaplayın. Örneğin, bir eğitim adımı en fazla 2 dakika sürüyor ve bir kontrol noktası kaydetmek 2 dakika alıyorsa, en az 243 saniyelik bir kibarlık süresi belirleyin.