Asenkron GRPO

Bu eğitimci vllm, transformers>=5.2.0 ve kernels gerektirir (eğitim, FlashAttention'ı Hub üzerinden bu bileşen aracılığıyla yükler). Dağıtık eğitim için yalnızca FSDP2 desteklenir (DeepSpeed ZeRO desteklenmez).

Şu anda vllm ve transformers çelişkili bağımlılık kısıtlamalarına sahip. Bunu aşmak için önce vLLM'yi kurun, ardından transformers'ı zorla kurun ve son olarak transformers'ın kabul ettiği sürümü sabitleyen TRL'in ek paketi üzerinden kernels'i ekleyin:

Kopyalandı

pip install vllm
pip install 'transformers>=5.2.0' --no-deps
pip install 'trl[kernels]'

Genel Bakış

experimental.async_grpo.AsyncGRPOTrainer, aynı GRPO algoritmasını uygular ancak rollout üretimini eğitimden ayırır. Arka plan işçisi, eğitim döngüsünün bunları tüketirken bir vLLM sunucusundan sürekli olarak tamamlamaları akış olarak almasını sağlar; böylece üretim ve gradyan güncellemeleri sırayla değil, üst üste gerçekleşir. API, GRPOTrainer ile aynıdır — GRPO yönteminin kendisiyle ilgili tüm ayrıntılar için (avantaj hesaplama, KL tahmini, kayıp formülasyonu, ödül fonksiyonları vb.) GRPO Trainer belgelerine bakın. GRPOTrainer'daki tüm özellikler mevcut değildir; desteklenen parametreler için experimental.async_grpo.AsyncGRPOConfig'e başvurun.

Bu eğitimci Quentin Gallouédec ve Amine Dirhoussi tarafından katkı sağlanmıştır.

GRPOTrainer'dan farkı

Standart GRPOTrainer'da üretim ve eğitim ardışık olarak gerçekleşir: bir parti üretilir, kayıp hesaplanır, ağırlıklar güncellenir ve bu işlem tekrarlanır. Üretimin aynı GPU'larda çalıştığı vLLM colocate modu dahil olmak üzere, bir faz tamamlanmadan diğeri başlayamaz.

experimental.async_grpo.AsyncGRPOTrainer bu iki kaygıyı ayırır:

• Rollout worker (arka plan süreci) — vLLM sunucusuna istemler gönderir, tamamlamaları ödül fonksiyonlarıyla puanlar, avantajları hesaplar ve eğitime hazır örnekleri bir kuyruğa iter.
• Eğitim döngüsü (ana süreç) — kuyruktan örnekleri alır, kırpılmış vekil kaybı (clipped surrogate loss) hesaplar ve model ağırlıklarını günceller.

Rollout worker, trainer'dan türetilen ayrı bir süreçte çalıştığından ödül hesaplama, eğitim döngüsüyle GIL için asla yarışmaz. Bu durum, reward_funcs, tools ve environment_factory (ikincisi için OpenEnv kılavuzu'na bakın; bu kılavuz sözleşmeyi ve mevcut entegrasyonları kapsar) olarak iletebileceğiniz şeyler için iki sonuç doğurur:

Rollout worker'ı ayrı bir süreçte çalıştırdığımız için, ona iletilen her şey pickled edilir. Bu nedenle her ödül fonksiyonu, araç ve environment_factory (ve bunların kapattığı her şey) picklable olmalıdır: modül düzeyinde bir fonksiyon, functools.partial veya çağrılabilir sınıf örneği kullanın. Araçlar istisnadır: model, bir aracı adıyla çağırır, bu yüzden her araç __name__ altında kaydedilmeli ve modül düzeyinde bir fonksiyon olmalıdır. Lambda'lar ve kapanışlar (closures), trainer.train() sırasında TypeError fırlatır. Bu, ödül fonksiyonlarının süreç içi çağrıldığı ve kapanışların (closures) çalıştığı GRPOTrainer'dan bir farktır.

The rollout process also runs with CUDA_VISIBLE_DEVICES="", so it cannot use the GPU. A GPU-backed reward model (e.g. an AutoModelForSequenceClassification scorer) still loads without error but silently falls back to CPU (note that in GRPOTrainer, such a reward model shares the trainer’s GPUs). Keep reward functions CPU-side and lightweight (verifiers like accuracy_reward, format/length checks).

GPU ödül modeline gerçekten ihtiyacınız varsa, önerilen yaklaşım, modelin kendi çıkarım motorunun arkasında sunulmasıdır (vLLM, TGI, …) ve bunun ayrı GPU'larda yapılmasıdır; ardından hafif, picklable bir ödül fonksiyonu HTTP üzerinden bu modele çağrı yapar. Bu sayede ödül modeli kendi cihazında kalırken rollout süreci yalnızca CPU'da çalışır ve eğitimciden bağımsız olarak ölçeklenir.

Araçlar ve ortam yöntemleri senkron veya asenkron olabilir. Senkron araçlar, max_concurrent_rollouts boyutunda bir iş parçacığı havuzunda çalışır; bu sayede yavaş bir araç, diğer devam eden vLLM isteklerini asla engellemez. Tek bir asistan turu içinde, araç çağrıları modelin onları ürettiği sırada çalışır. Dolayısıyla en fazla max_concurrent_rollouts senkron araç aynı anda çalışır; bu nedenle paylaşılan durumu okuyan veya yazan bir aracın iş parçacığı güvenli (thread-safe) olması gerekir.

Her weight_sync_steps eğitim adımı sonrasında, güncellenmiş ağırlıklar NCCL üzerinden vLLM sunucusuna aktarılır; böylece sonraki üretimler en güncel politikayı yansıtır.

Üretim ve eğitim eşzamanlı olarak çalıştığı için, eğitim örnekleri modelin biraz daha eski bir sürümü tarafından üretilmiş olabilir. max_staleness parametresi, bir örneğin atılmadan önce kaç ağırlık güncellemesi geride kalabileceğini kontrol eder.

Eşzamanlılık

vLLM sunucusuna gönderilen eşzamanlı istek sayısı max_concurrent_rollouts ile sınırlandırılır. Varsayılan olarak max(max_staleness, 1) × per_device_train_batch_size × gradient_accumulation_steps × num_processes olarak otomatik ayarlanır — eğitimcinin örnekler bayatlamadan önce tüketebileceği maksimum örnek sayısı. Bundan fazlasını üretmek israftır çünkü fazla örnekler atılır.

max_concurrent_rollouts bir tavan değeridir, fiilen uçuşta olan istek sayısını belirtmez. İşçi, sunucunun /metrics uç noktasını birkaç saniyede bir sorgular ve bunun altında canlı bir sınır tutar (rollout/concurrency_cap): belirli bir eşzamanlılık seviyesinin ötesinde, KV önbelleği dolduğu, diziler önemsizleştirilip yeniden hesaplandığı ve önbelleğe alınmış öneklerin atılıp yeniden doldurulduğu için ek istekler vLLM’i yavaşlatır. Sınır, başlangıçta sunucudan açılışta okunan KV cache tokens / max_model_len değerine ayarlanır: tam uzunlukta sığabilecek kadar istek, böylece ilk adım sistemde aşırı yüklenmeye neden olamaz. Kullanım 0,6’nın altında kaldığı ve kuyrukta bekleyen bir şey olmadığı sürece, bir sınır miktarı kadar rollout tamamlanıp her seferinde sınır %25 oranında artar, tavan değere kadar. KV önbelleği kullanımı 0,8’i aştığında sınır %30 oranında düşürülür; çalışan hiçbir istek iptal edilmez, yalnızca havuz yeni sınırın altına inene kadar kabul durur ve o zamana kadar ek bir düşüş uygulanmaz. Sunucu /metrics uç noktasını açmıyorsa, sınır tavan değerde kalır.

Kontrol noktası ve devam: ignore_data_skip varsayılan olarak True'dir; temel Trainer'ın atla ve yeniden oynat döngüsü, canlı bir rollout kuyruğuna uygulanmaz. Bunun yerine, henüz eğitim görmemiş ilk istemin indeksi, her kontrol noktasıyla birlikte rollout_state.json dosyasına kaydedilir ve devam sırasında geri yüklenir; böylece işçi, örnekleri yeniden oynatmadan o isteme hızlıca ilerler. Bu, üreticinin değil eğitim konumudur: işçi, rollout kuyruğu derinliği kadar eğitimin önünde çalışır ve bu tamponlanan örnekler çalışmanın sona ermesiyle kaybolur; dolayısıyla üreticinin konumundan devam etmek, oluşturulmuş ancak eğitim görmemiş istimleri atlar. Akış veri kümeleri (IterableDataset) yeniden konumlandırılamaz; işçileri devam sırasında 0. istimden yeniden başlar. FSDP ile bf16=True (varsayılan) veya fp16=True kullanıldığında, ana ağırlıklar fp32 olsa bile model.safetensors bu veri türünde yazılır; bu nedenle itilen kontrol noktası, sunulan modelin boyutundadır, iki katı değil. fp32 ana ağırlar ve optimizör durumu yine de devam dosyalarına (pytorch_model_fsdp.bin, optimizer.bin) gider; devam sırasında okunan dosyalar bunlardır, bu yüzden devam etme işleminden etkilenmez. FSDP olmadan kontrol noktası aynı zamanda devam dosyasıdır, bu nedenle ana veri türünü korur.

Hızlı başlangıç

# train_async_grpo.py
from datasets import load_dataset
from trl.experimental.async_grpo import AsyncGRPOTrainer
from trl.rewards import accuracy_reward

dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

trainer = AsyncGRPOTrainer(
    model="Qwen/Qwen3-4B",
    reward_funcs=accuracy_reward,
    train_dataset=dataset,
)
trainer.train()

vLLM sunucusu ve eğitimci ayrı GPU'larda çalışmalıdır. GPU'larınızı bölmek için CUDA_VISIBLE_DEVICES kullanın. Örneğin, 2 GPU ile vLLM sunucusunu GPU 0'da, eğitimciyi ise GPU 1'de aşağıdaki gibi çalıştırabilirsiniz:

# Terminal 1: vLLM server on GPU 0 (dev mode + NCCL weight transfer are required)
CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen3-4B \
    --max-model-len 4096 \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --weight-transfer-config '{"backend":"nccl"}'

--max-model-len değerini, beklediğiniz maksimum toplam dizi uzunluğuna (istek + tamamlama) ayarlayın. Daha düşük bir değer, sunucudaki GPU bellek kullanımını azaltarak KV önbelleği için daha fazla bellek boşaltır ve verimliliği artırır. İyi bir başlangıç noktası, yapılandırmanızdaki istek uzunluğu ile max_completion_length değerinin toplamıdır.

# Terminal 2: training on GPU 1
CUDA_VISIBLE_DEVICES=1 accelerate launch train_async_grpo.py

AMD GPU'ları

Trainer, AMD GPU'lerde (ROCm) ek bir kurulum gerektirmeden çalışır: yukarıdaki komutlar olduğu gibi işe yarar. Eğitim, AMD GPU'lerde kernels-community/aiter-flash-attn dikkat çekirdeğini, NVIDIA Blackwell GPU'lerde kernels-community/flash-attn4 ve diğer NVIDIA GPU'lerde kernels-community/flash-attn3 kullanır; tümü kernels kütüphanesi tarafından Hub'dan indirilir. Dikkat logitlerini sınırlayan (attn_logit_softcapping) modeller, örneğin Gemma 2, AMD GPU'lerde veya NVIDIA Blackwell GPU'lerde desteklenmez.

Görüntü-dil modelleri

Görüntü-dil modelleri (Qwen3.5, Qwen3.6, Qwen3-VL, …) sadece metin veri kümelerinde eğitilebilir. Model kimliğini normalde olduğu gibi iletin; başka hiçbir değişiklik gerekmez:

CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen3.5-2B \
    --max-model-len 4096 \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --weight-transfer-config '{"backend":"nccl"}'

Görüntü kulesi dondurulmuştur. Sadece metin içeren bir veri seti asla görüntü jetonları üretmez, bu nedenle kule ileri geçiş tarafından asla kullanılmaz. Metin kulesinin dışındaki her şey (görüntü kulesi, çok modlu projeksiyoncu) için requires_grad=False değerine sahiptir: gradyan ve optimizör durumu almaz ve ağırlık senkronizasyonu onu tamamen atlar — sunucu, kontrol noktasından yüklediği değerleri korur. Kule yine de yüklendiği için ağırlıkları için GPU belleği maliyeti oluşturur.

Görseller henüz desteklenmiyor. Görsel içeren istemler, vLLM sunucusuna veya eğitim ileri geçişine iletilmez. Çok modlu eğitim, görsel ızgarasından 3B M-RoPE konumlarını oluşturmak için dolgu olmadan paketleme yoluna da ihtiyaç duyar; bu yol burada uygulanmamıştır.

Top-k ve top-p örneklemesi

Top-k ve top-p, örneklem dağılımını tüm sözlük yerine kısıtlı bir aday kümesi üzerinde yeniden normalize eder. Sunucunun log-olasılıkları bunu yansıtır (--logprobs-mode processed_logprobs), bu nedenle eğitimcinin de aynı küme üzerinde normalize etmesi gerekir; aksi halde tüm önem oranları yanlı olur: bir token’ın tüm sözlük altındaki olasılığı, aslında çekildiği aday kümesi altındaki olasılıktan daha düşüktür (DeepSeek-V3.2, bölüm 3.1). top_p < 1 veya top_k > 0 durumunda, işçi her örneklenen token için sunucudan aday kümesini ister ve eğitimci log-olasılıkları bu küme üzerinde yeniden normalize eder. Bunun için iki ek sunucu bayrağı gerekir ve vLLM aday kümesinin boyutunu bununla sınırladığı için top_k ayarlanmalıdır:

CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen3-4B \
    --max-model-len 4096 \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --weight-transfer-config '{"backend":"nccl"}' \
    --return-sampling-mask \
    --enable-scale-out

config = AsyncGRPOConfig(top_p=0.95, top_k=512)

--return-sampling-mask, vLLM'nin aday kümesini (vLLM 0.28 veya üzeri, V2 model runner'ında: sunucu bayrağı reddediyorsa VLLM_USE_V2_MODEL_RUNNER=1) kaydetmesini sağlar; --enable-scale-out, bu kümeyi döndüren token-in-token-out uç noktasını açığa çıkarır. İşçi, başlarken sunucuda her iki ayarı da kontrol eder. Eski bir vLLM bu kümeyi döndüremediğinden, eğitimci tüm sözlük üzerinde normalleştirmeye devam eder ve yanlı orana dair bir uyarı verir.

Puan ortalaması

Sunucunun log-olasılıkları eğitimcinin (trainer) log-olasılıklarıyla asla birebir eşleşmez: farklı çekirdekler (kernels), farklı bir hassasiyet, birkaç adım geride kalmış bir politika. Önem ağırlıkları (importance weights) tek başına bunu düzeltmez, çünkü örneklenen bir token'ın $\nabla_\theta \log \pi_\theta$ örnekleyici altında sıfıra ortalama olmaz, bu yüzden her güncelleme politikanın örnekleyiciye doğru çekilmesine de neden olur (Skor merkezleme). Varsayılan olarak eğitimci, her konumda bu beklentiyi çıkarır (score_centering=True), örnekleyicinin num_sampler_logprobs en olası token'ları üzerinde tahmin edilir ve örnekleyiciye göre önem oranı dışarıda kalan token'lar düşürülür [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max]. Bunun için worker, sunucudan üretilen her token'ın üst log-olasılıklarını ister ve bunları token başına serialize eder: büyük bir num_sampler_logprobs sunucuyu yavaşlatır ve onun --max-logprobs kabul ettiği sınırı belirler. score_centering=False sadece kırpılmış amaç fonksiyonuyla (clipped objective) eğitim yapar. sampling/masked_mean sınırların düşürdüğü token'ların oranıdır ve sampling/sampler_mass de üst token'larla kapsanan örnekleyicinin (sampler) olasılık kütlesidir.

En yüksek log-olasılıkların (log-probabilities) seri hale getirilmesi, vLLM API sunucusunda CPU işidir ve varsayılan tek API sunucusuyla num_sampler_logprobs=8 değeri, üretim (generation) verimliliğini yarıya indirir. vLLM 0.32 veya üzeri sürümlerde sunucuyu --api-server-count 8 bayrağıyla başlatın: tek bir H100 üzerinde 1,5B ile 7B parametreli modellerde ölçüldüğünde, en yüksek 8 log-olasılık bu durumda üretim verimliliğinin %3'ünden azına mal oluyor. vLLM 0.31'de aynı bayrak hâlâ %20 ile %40 arasında bir kayba yol açıyor; bu sorun vllm-project/vllm#58181 ile yamalandı.

LoRA

Tam model yerine bir LoRA adaptörü eğitmek için peft_config geçin:

from peft import LoraConfig

trainer = AsyncGRPOTrainer(
    model="Qwen/Qwen3-4B",
    reward_funcs=reward_len,
    train_dataset=dataset,
    peft_config=LoraConfig(r=32, lora_alpha=64, target_modules="all-linear"),
)

Her ağırlık senkronizasyonunda güncellenmiş politika sunucuya iletilmelidir. Varsayılan olarak eğitimci, adaptörü temel modele birleştirir ve tam birleşik ağırlıkları gönderir; bu, 7B'lik bir model için her senkronizasyonda yaklaşık 15 GB'dır. vLLM sunucusunu --enable-lora ile başlatırsanız, bunun yerine yalnızca adaptör gönderilir; r=32 için yaklaşık 160 MB'dır:

CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 vllm serve Qwen/Qwen3-4B \
    --max-model-len 4096 \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --weight-transfer-config '{"backend":"nccl"}' \
    --enable-lora \
    --max-lora-rank 32 \
    --max-loras 6

VLLM_ALLOW_RUNTIME_LORA_UPDATING=1, eğitimcinin her yeni adaptörü gönderdiği uç noktayı açığa çıkarır. --enable-lora kullanılsa bile --weight-transfer-config parametresini koruyun: eğitimci yalnızca başlangıçta bir senkronizasyon modu seçer ve bu noktada sunucu zaten çalışır durumdadır; birleşik senkronizasyon ise yedek çözümdür.

--max-lora-rank, 1, 8, 16, 32, 64, 128, 256, 320, 512 değerlerinden biri olmalıdır. Sunucunun sunabileceği en yüksek rankı belirler, sunacağı rankı değil; bu nedenle r=4 adaptörü 8 altında sorunsuz çalışır. --max-loras, en az max_staleness + 2 olmalıdır: eğitimci, eski bir politika altında başlayan bir rollout'un ortada politika değiştirmek yerine o politika altında tamamlanabilmesi için max_staleness + 1 adaptör sürümünü kayıtlı tutar ve her senkronizasyonda en eski sürümü boşaltmadan önce bir sonraki sürümü yükler. Eğitimci, başlangıçta her iki değeri de kontrol eder ve sunucuyu hangi değerlerle yeniden başlatacağınızı belirtir.

vLLM, adaptörleri ağ üzerinden değil diskten yüklediği için eğitimci, her sürümü <output_dir>/.vllm_lora/ altında yazar ve sunucuya yolu verir. Sunucu farklı bir makinede çalışıyorsa, bu dizinin her ikisinin de görebildiği bir dosya sisteminde bulunması gerekir.

<output_dir>/.vllm_lora/ bir sunum önbelleğidir, eğittiğiniz adaptörün saklandığı yer değildir. Yalnızca en son sürümleri barındırır ve her biri, güncellik penceresinden düştükten kısa süre sonra silinir. Adaptörünüzü koruyan şey checkpoint'lerdir, bu nedenle onları kapatmayın: save_strategy="no" ile saatler süren bir çalıştırma biter ve arkasında hiçbir şey bırakmaz. output_dir'ın sunucu tarafından okunabilir olması ve işin ömründen uzun süre var olması gerekir; bu nedenle, yavaş bir paylaşımlı dosya sisteminden senkronizasyonları uzak tutsa bile düğüm yerel geçici alanı işe yaramaz.

Adapter senkronizasyonu her zaman daha hızlı değildir. vLLM, birleşik ağırlıklar yerine bir LoRA adaptörü sunarken token başına yaklaşık 1.33–1.39x daha yavaş üretim yapar ve üretim genellikle RL'de duvar saati süresini belirleyen ana faktördür. Buna karşılık, her senkronizasyonda çok daha kısa bir duraklama ve senkronizasyon bant genişliğinin yaklaşık %1'i elde edilir. Üretim verimliliği darboğazınızsa, birleşik senkronizasyon genellikle hâlâ daha iyi bir seçimdir.

Rollout döngüsünü özelleştirme

Üretim, ödül, avantaj ve filtreleme işlemleri experimental.async_grpo.AsyncRolloutLoop içindeki rollout sürecinde çalışır. Bunlardan birini değiştirmek için döngünün bir alt sınıfını oluşturup ilgili adımın metodunu geçersiz kılın ve bu alt sınıfı bir trainer alt sınıfında loop_cls olarak ayarlayın. Trainer’ın yapıcısı değişmez.

Örneğin, politikanın zaten çözdüğü istemleri örneklemeyi durduran bir müfredat, eşiği bir yapılandırma alt sınıfında tanımlanır:

from dataclasses import dataclass

import numpy as np

from trl.experimental.async_grpo import AsyncGRPOConfig, AsyncGRPOTrainer, AsyncRolloutLoop


@dataclass
class CurriculumConfig(AsyncGRPOConfig):
    pass_rate_cap: float = 0.9


class CurriculumRolloutLoop(AsyncRolloutLoop):
    def filter_prompt(self, row_index, row, epoch):
        return self.pass_rates.get(row_index, 0.0) < self.config.pass_rate_cap

    async def setup(self):
        self.pass_rates = {}

    def compute_advantages(self, group):
        scored = group.rewards[~np.isnan(group.rewards)]
        if len(scored):
            self.pass_rates[group.row_index] = float(np.mean(scored > 0))
        return super().compute_advantages(group)


class CurriculumTrainer(AsyncGRPOTrainer):
    loop_cls = CurriculumRolloutLoop

Ödüller, reward_funcs, get_reward tanımlayan ortamlar ve özel bir generate_one'ün experimental.async_grpo.Rollout üzerinde ayarladığı reward üzerinden toplanır: bir yargıçla puanlamak için asenkron bir ödül fonksiyonu iletin veya puanlamayı generate_one içinde yapın. compute_advantages, puanlanan ödüllerinin tümü eşit olduğu için daha sonra atılan gruplar dahil olmak üzere her grup için çalışır; atma işlemi avantajlara değil, ödüllere bakar. Döngü, türetilmiş bir süreçte oluşturulduğundan, alt sınıfı modül düzeyinde tanımlayın. İstemcileri, döngünün olay döngüsünde çalışan setup içinde oluşturun; bunun yerine __init__'i geçersiz kılmayın. filter_prompt tarafından reddedilen bir istem, atılan bir grup gibi o çağ için atlanır ve ona sayılır. Bir çağdaki tüm istemleri reddederse döngü bir hata fırlatır.

Tasarım felsefesi

Bu eğitimci bilinçli olarak minimal tutulmuş olup genel amaçlı bir çözüme dönüşmesi hedeflenmemektedir. Desteklenmeyen bir özelliğe ihtiyacınız varsa, depoyu klonlayıp eğitimciyi doğrudan ihtiyaçlarınıza göre uyarlamanızı öneririz. Yeni özellikler yalnızca anlamlı bir topluluk talebi olduğunda değerlendirilecektir.

Kaydedilen metrikler

Bir rollout, bir gradyan haline gelmeden önce birkaç aşamadan geçer. Önce bir prompttan nihai batch kompozisyonumuza kadar olan farklı aşamalara bir bakalım:

Dataset row = PROMPT (message list + reward kwargs)
 └─ GROUP                  (1 prompt, `num_generations` rollouts, 1 advantage baseline)
     └─ ROLLOUT            (1 conversation, keyed by `rollout_id`)
         ├─ TURN           (1 vLLM /v1/completions call + tool messages fed back)
         │   └─ TurnRecord (prompt_ids, output_ids, output_log_probs)
         └─ reconcile      (`_chain_to_sequences` classifies drift per turn: CLEAN/REALIGN/FORK)
             └─ SEQUENCE   (≥1 per rollout; new one per fork; dropped if no trained token)
                 └─ SAMPLE (Sequence + group advantage + reward + metrics)

════════════ Trainer process boundary: `rollout_buffer` (mp.Queue) ════════════

                 └─ SAMPLE (Pulled 1 at a time; dropped if staleness > `max_staleness`)
                     └─ ROW            (Planner inserts it into one of `dp` prefix tries, attention-cost-balanced)
                         └─ MICRO-BATCH (`dp` rows, one per rank)
                             └─ PACKED ROW (Collator lays each trie out: unique tokens, depth as `position_ids`)
                                 └─ FORWARD (`compute_loss`, bs=1, padding stripped, FA3 per trie segment)
                     └─ OPTIMIZER STEP (from `grad_accum` micro-batches)

Üstten alta okunduğunda:

• a group, num_generations kez üretilen tek bir prompt'tur. Avantaj taban çizgisi bu grubun içinde hesaplanır; bu nedenle puanlanan birim de gruptur.
• a rollout tek bir sohbettir. Her tur, tüm mesaj listesini yeniden belirteçlere ayırır (re-tokenize), bu nedenle turlar arasındaki sapma sonunda uzlaştırılmalıdır.
• reconciling, bir rollout'u birden fazla sequence'e fork edebilir; bu nedenle tek bir konuşma birden fazla eğitim örneği üretebilir.
• a örnek, bir dizi ile onun avantajı, ödülü ve metrikleridir. Bu, süreç sınırını geçen şeydir.
• sınırın ötesinde trainer, örnekleri rows (her DP rank için bir tane) olarak planlar, her satırı bir prefix trie içine katlayarak paylaşılan tokenlerin yalnızca bir kez iletilmesini sağlar ve grad_accum mikro-toplu işlemleri tek bir optimizer adımında biriktirir.

Buna göre metriklerimizi, hangi aşamanın (veya varlığın) hakkında olduklarına göre bölüyoruz:

Token metriklerinin belirsizliğini gidermek için bazı terimleri de tanımlayalım:

• oluşturulan jetonlar, modelin ürettiği jetonlardır (completions/*).
• forwarded jetonlar, forward geçişinin işlediği tüm jetonlardır: istem, varsa araç sonuçları ve üretilen jetonlar.
• trained tokenlar, completion_mask == 1 olan alt kümedir ve kayıp bu alt küme üzerinden hesaplanır. Örneğin, bir fork veya realign işlemi, zaten üretilmiş tokenları bağlama (context) olarak düşürebilir; bu nedenle trained ≠ generated.

Toplu işlem numaralarının nasıl oluşturulduğu

satır, tek bir DP rank'ın tek bir mikro-batch'te ileriye aktardığı şeydir: tek bir prefix forest'a paketlenmiş birkaç örnek, böylece paylaştıkları tokenlar yalnızca bir kez ileriye aktarılır — bkz. Tree packing. Planlayıcı, örneklerin hangi satıra yerleştirileceğini belirler (dikkat maliyetini dengeleyerek hiçbir rank'ın geride kalmamasını sağlar) ve paklemeyi bir veri toplayıcı (data collator) gerçekleştirir.

Tüm metriklerimizde “step” her zaman TAM bir optimizer adımını ifade eder, asla bir micro-batch değildir. gradient_accumulation_steps micro-batch bir adım oluşturur ve _per_step adlı her metrik, global_step, logging_steps ve Trainer sözlüğünün geri kalanıyla uyumlu şekilde optimizer başına adımı temsil eder. Bir metrik micro-batch başına ise bu açıkça belirtilir (batch/microbatches_per_step) ya da satır başına bir büyüklüktür (batch/row_*, batch/samples_per_row).

Dolayısıyla bir adım, sabit sayıda row-slots içerir:

row-slots per step = gradient_accumulation_steps x world_size

bu da parti metriklerinin birbirleriyle karşılaştırılabileceğiniz bir merdiven oluşturmasını sağlar:

sample                                     sample/forwarded_tokens_mean
  └─ packed into a ROW                     batch/samples_per_row, batch/row_tokens_mean
      └─ one row per DP rank               = one micro-batch
          └─ gradient_accumulation_steps micro-batches = one STEP
                                           batch/samples_per_step, batch/forwarded_tokens_per_step

Dolayısıyla batch/samples_per_step ≈ row-slots x batch/samples_per_row ve aynı mantık token'lar için de geçerlidir. İki taraf yalnızca adım içindeki mikro-partiler arasındaki değişkenliğe kadar eşleşir — adım başına metrikler toplamlar, satır başına olanlar ise ortalamalardır — bu nedenle tam bir eşleşme yerine yüzde birin kesri kadar bir sapma bekleyin.

batch/row_fill_frac, örnekler uzun olduğunda dikkat edilmesi gereken metriktir: 10k token'lık bir örnek, 32k bütçesini kötü bir şekilde doldurur (üçü sığar, dördü asla sığmaz, bu yüzden paketleyici genellikle ikisini alır ve satır ~%77 dolu kalır), oysa 1k token'lık örnekler onu neredeyse mükemmel bir şekilde doldurur. Bu bir hata değil, kuantizasyondur ve token_budget ayarlanabilir parametredir — her dizide dikkat (attention) O(L²) olduğundan, uzun dizilerden oluşan daha dolu bir satırın bellek maliyetinin doğrusal olarak artmadığını göz önünde bulundurmak gerekir.

Ağaç paketleme

Bir satır, bir prefix trie'dir, birleştirme değildir: birden fazla örnek tarafından paylaşılan bir token yalnızca bir kez iletilir ve dikkat mekanizması her örneğe yalnızca kendi geçmişini gösterir. Tek bir istemcinin (prompt) tüm rollout'ları bu istemciyi tekrarlar ve çok turlu bir rollout'un her turu sohbeti yeniden gönderir, bu da dekodlayıcının iş yükünü packing oranı (ham tokenlar ÷ iletilen tokenlar) kadar azaltır. Bu yalnızca bir yerleşim değişikliğidir: her eğitim tokenı kendi hedefini, avantajını ve eski log-olasılığını korur ve log-olasılığı, örneğin tek başına iletilmesiyle eşleşir.

Nerede gerçekleşir:

planner    TreeRow.add            the trie grows sample by sample; a sample is priced by its novel tokens
   │                              (TreeRow.fits), so `token_budget` bounds unique tokens, not raw ones
collator   TreeRow.pack           DFS layout: unique tokens, depth as position_ids, one loss term per
   │                              original trained token (token_index), and per segment its queries and
   │                              the K/V indices of its root-to-segment path, all built on CPU
attention  tree_attention         gather K/V along the paths, one FA3 varlen call, causal

Bir istemin iki dağıtımında nasıl çalıştığı:

1. Rollouts             r0:  p1 p2 p3 a1 a2
                        r1:  p1 p2 p3 b1 b2                      10 raw tokens

2. Trie (one per row)   S0 [p1 p2] ─┬─ S1 [p3 a1 a2]          nodes are keyed on (token, next token),
                                   └─ S2 [p3 b1 b2]          so the fork happens one token early and
                                                              every node predicts exactly one token;
                                                              chains without a fork become segments

3. Packed row           idx           0  1 | 2  3  4 | 5  6  7
   (DFS order)          input_ids    p1 p2 | p3 a1 a2 | p3 b1 b2  8 tokens: MLPs, norms and projections
                        position_ids  0  1 |  2  3  4 |  2  3  4  run once per unique token
                        segment      S0    | S1       | S2

4. Attention            seg   queries      K/V gathered            kv_index
   (one FA3 call)       S0    [p1 p2]      [p1 p2]                 0 1
                        S1    [p3 a1 a2]   [p1 p2 | p3 a1 a2]      0 1 2 3 4
                        S2    [p3 b1 b2]   [p1 p2 | p3 b1 b2]      0 1 5 6 7

                        FA3 aligns the causal mask bottom-right      K:  p1 p2 p3 a1 a2
                        when queries are fewer than keys, so a       Q: p3   ■  ■  ■  ·  ·
                        segment's queries see their ancestors and       a1   ■  ■  ■  ■  ·
                        their own causal past, and nothing else.        a2   ■  ■  ■  ■  ■

5. Loss                 p2 (idx 1) predicts p3 for both rollouts; token_index points every trained
                        token of every rollout at the position that predicts it

Birkaç sonuç:

• Ortak bir önek paylaşıldığında: bir istemin (prompt) rollout'ları ve istemler arasında ortak bir sistem istemi veya araç şeması. Planlayıcı, örneklemeyi, istemi zaten bulunan ve group_id'sini tutan satıra gönderir. Bu satır dolduğunda, örneklemeye bir sıra hâlâ boşsa veya en yüklü satırı artırmıyorsa başka bir satıra gider; bu durum mikro-topluğun (micro-batch) süresini belirler; aksi halde mikro-topluğun kapanması sağlanır.
• Paylaşılan hiçbir şey düz paketleme değildir: her örnek, yolu kendisi olan tek bir segmenttir; bu da sıradan, dolgu içermeyen FA3 varlen paketlemesidir.
• Sadece K/V kopyalanır: paylaşılan önek, her torun segmenti için bir kez toplanır; bu, paketlenmemiş eğitimin tuttuğuyla yaklaşık aynıdır ve GQA ile küçük kalır.
• Gated DeltaNet hibritleri desteklenir (Qwen3.5, Qwen3.6, Qwen3-Next, …): bunların konvolüsyonu her token’ın kendi öncüllerini okur ve parçalı delta kuralı her segmenti ebeveyninin son durumundan başlatır (trl/experimental/async_grpo/tree_gated_delta_rule.py). Bunun için, bu katmanların ağaç paketleme yamalarının değiştirdiği modül düzeyindeki fonksiyonları çağırdığı transformers>=5.15.0 sürümü gereklidir. Dikkat dışındaki başka herhangi bir katmana sahip modeller başlatma sırasında reddedilir.

Ne sağlar: hiçbir şey paylaşılmadığında, düz padding'siz paketleme hızında çalışır ve hızlanma, paketleme oranıyla yaklaşık olarak artar (Qwen3-0.6B/1.7B, H100 üzerinde 3.4 oranında yaklaşık 2.8–3x). Oran, paylaşılan önek × satır başına örnek sayısıdır, bu nedenle batch/samples_per_row birincil göstergedir: 1'e yakınsa hiçbir şey paylaşılamaz ve kaldıraç token_budget'tır.

Tüketim üzerinden değerlendirin, batch/trained_tokens_per_step / perf/fwd_bwd_s. Paketlenmiş bir mikro-toplu işlem daha fazla örnek içerdiğinden perf/fwd_bwd_s artar ve ileri yönlendirilen tokenlara bölünen perf/mfu_* düşer — bunların hiçbiri bir gerileme değildir. Satır başına daha fazla örnek, adım başına daha fazla rollout çekildiği anlamına da gelir, bu da üretim kısıtlı bir çalışmayı daha da öyle yapar.

Satırları uzatan veya azaltan her şey paylaşımı kaldırır. Önce fork_threshold_tokens değerini kontrol edin: bir tur, yeniden tokenizasyon kayması bu kadar token olduğunda ancak kendi satırına ayrılır ve ajan tabanlı kayma genellikle varsayılan 1024 değerine karşı onlarca token olduğundan hiçbir tur ayrılmaz ve bir sohbet, rank başına tek satıra çöker. rollout/fork_frac hangi rejimde olduğunuzu belirtir.

Rollout kuyruğu

Worker, puanlanmış örnekleri bir kuyruğa iter ve trainer ondan çeker. Bu tek kuyruğu dört metrik tanımlar ve farklı sorulara yanıt verir:

Son iki metrik (perf/rollout_wait_s ve rollout/backpressure_s) birbirinin aynasıdır ve asla aynı anda büyük olmaz! Bunları kuyruk boyutuyla birlikte okuyarak darboğazın hangi tarafta olduğunu anlarsınız:

• kuyruk neredeyse boş, perf/rollout_wait_s yüksek → üretim kısıtlı. Eğitmen aç kalıyor; rollout/generated_tok_s, rollout/concurrency ve rollout/score_queue_size değerlerine bakın.
• kuyruk neredeyse dolu, rollout/backpressure_s yüksek → trainer-bound. Üretim kısıtlanıyor ve çıktısı kuyrukta bekliyor, bu yüzden sample/staleness_mean değerinin yükseldiğini izleyin.
• her ikisi de sıfıra yakın → dengeli!

Tamamlamalar

Bir completion, rollout'un tüm turlarında sayılan, vLLM'in bir prompt için ürettiğidir.

Rollout'lar

Bir rollout, tek bir tam konuşmadır: oraya ulaşmak için yapılan her araç gidiş-dönüşü dahil olmak üzere, tamamlanana kadar üretilen bir istemdir. num_generations rollout aynı istemi paylaşır ve bir grup oluşturur.

Tüm rollout'ları aynı ödülü almış (veya bunlardan ikiden azı puanlanabilir olmuş) bir grup kuyruğa eklenmek yerine düşürülür: varsayılan avantajlarla her yerde sıfır avantaja sahiptir, bu nedenle bir ileri ve geri geçiş maliyeti oluşturur ve hiçbir şeyi değiştirmez. Batch etkilenmez, hâlâ tutulan gruplardan samples_per_step değerini doldurur, bu yüzden birçok grup düşürüldüğünde bir adım daha fazla üretim gerektirir. Düşürülen bir grup yine de bir epoch'a sayılır; epoch, prompt'lar üzerinde tek bir geçiş olarak kalır.

Araçlar

Yalnızca model araçları çalıştırdığında kaydedilir. tools/<name>/*, rewards/<func>/*'in ödül fonksiyonu başına tekrarlandığı gibi, araç adı başına tekrarlanır; çünkü başarısız olan tek bir araç, tümünün ortalamasında görünmez. Yerleşik araç döngüsü ve OpenEnv harness eğitimcisi (HarnessAsyncGRPOTrainer, bkz. harness'lerde eğitim) aynı adları kaydettiğinden, tek bir panoda her ikisi de okunabilir; path sütunu, her metriğin hangi bileşen tarafından üretildiğini belirtir.

Ortamlar

Yalnızca bir environment_factory ile kaydedilir. Her iki çağrı da işçinin araç iş parçacığı havuzunda (tool thread pool) çalıştığından, yavaş bir ortam yalnızca kendi rollout'unu geciktirir, uçuştaki diğerlerini değil.

Kuyruktan gelen örnekler

Her örnek bir RolloutSample'dır: bir gruptaki her nesil tamamlandıktan ve puanlandıktan sonra, _score_group içindeki işçi tarafından birleştirilen hizalanmış dizi, grup avantajı, ödül ve örnek başına metrikler. İşçi bunları rollout_buffer'a iter; aşağıdaki her şey, eğitim için bunları çekerken eğitimci tarafında ölçülür.

Ödüller ve politika dışılık

Partiler

Bir mikro-batch world_size satırdır (paketleme, düzleştirme ile 1 diziye indirger), bu nedenle her DP rank'ı için bir tane olur ve i rank'ı i satırını iletir. Bunların gradient_accumulation_steps adedi bir optimizör adımı oluşturur. Bir adım, toplamda gradient_accumulation_steps × world_size satırı kapsar. Aşağıdaki her _per_step metriği, tüm adım ve tüm rank'lar üzerinden bir toplamdır; batch/row_* olanlar ise satırlar üzerinden ortalama değerlerdir.

Performans

Throughput, eğitimcinin saniyede kaç token işlediğini ölçer. Model FLOPs Utilization (MFU), modelin ileri ve geri geçişleri için kullanılan eğitim cihazlarının teorik hesaplama kapasitesinin yüzdesini tahmin eder. Bu tahmin için kullanılan kapasite, donanıma ve eğitim hassasiyetine bağlıdır.

Throughput ve MFU iki zaman temelinde raporlanır:

• _fwd_bwd, ileri ve geri geçişler sırasında performansı ölçer.
• _wall_clock, optimizasyon güncellemelerini, ağırlık senkronizasyonunu ve rollout'lar için harcanan bekleme süresini de içeren tam optimizasyon adımındaki performansı ölçer.

Bu fark, hesaplama performansını bekleme ve koordinasyon maliyetinden ayırt etmeye yardımcı olur. Her iki MFU metriği de yalnızca eğitim cihazlarını açıklar: harici rollout veya öğretmen sunucularının hesaplama veya donanım kapasitesini içermezler. Duvar saati MFU, bu hizmetlerin kendi kullanım oranlarını değil, eğitimcinin bu hizmetleri beklemek için harcadığı süreyi yansıtır.

MFU, seçilen hassasiyette yerel eğitim cihazının tepe hesaplama kapasitesi bilindiğinde raporlanır. Aksi takdirde MFU atlanır; eğitim devam eder ve veri aktarımı ile zamanlama metrikleri kullanılabilir kalır.

AsyncGRPOConfig

AsyncGRPOTrainer

>>> from trl.experimental.async_grpo import AsyncGRPOTrainer
>>> from trl.rewards import accuracy_reward
>>> from datasets import load_dataset

>>> dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

>>> trainer = AsyncGRPOTrainer(
...     model="Qwen/Qwen2.5-0.5B-Instruct",
...     reward_funcs=accuracy_reward,
...     train_dataset=dataset,
... )
>>> trainer.train()

>>> class CurriculumTrainer(AsyncGRPOTrainer):
...     loop_cls = CurriculumRolloutLoop

AsyncRolloutLoop

Rollout

TurnRecord

RolloutGroup