TRL documentation

Pelatih GRPO Asinkron

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Pelatih GRPO Asinkron

model badge

Ikhtisar

AsyncGRPOTrainer mengimplementasikan algoritma GRPO yang sama tetapi memisahkan generasi rollout dari pelatihan. Worker latar belakang secara terus-menerus mengalirkan kelengkapan dari server vLLM sementara loop pelatihan mengonsumsinya, sehingga generasi dan pembaruan gradien tumpang tindih alih-alih bergantian.

Trainer ini disumbangkan oleh Amine Dirhoussi dan Quentin Gallouédec.

Mulai cepat

Contoh ini menunjukkan cara melatih model menggunakan metode Asynchronous GRPO. Kami melatih Qwen3.5 2B model dengan prompt dari DeepMath-103K dataset. Anda dapat melihat data dalam dataset di sini:

Berikut adalah skrip untuk melatih model. Trainer membutuhkan vLLM dan kernels, dan accuracy_reward membutuhkan math-verify, yang dapat Anda instal dengan pip install trl[vllm,kernels,math_verify].

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

if __name__ == "__main__":  # the rollout worker is a spawned process that re-imports this script
    dataset = load_dataset("trl-lib/DeepMath-103K", split="train")

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

Generation berjalan di server vLLM, pada GPU yang berbeda dari trainer. Mulai di GPU 0:

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

Lalu jalankan skrip pada GPU 1 menggunakan perintah berikut:

CUDA_VISIBLE_DEVICES=1 python train_async_grpo.py

Kompatibilitas dan batasan

Beberapa kombinasi argumen sengaja dibatasi dalam implementasi AsyncGRPOTrainer saat ini:

  • Generation selalu dijalankan pada server vLLM terpisah, yang dimulai dengan vllm serve. Tidak ada mode colocate.
  • Prompt dari dataset harus dalam format percakapan. Dengan environment_factory, dataset mungkin tidak memiliki kolom prompt, dan reset() menyediakannya.
  • Fungsi reward harus berupa callable Python. Model reward yang diberikan sebagai id model atau PreTrainedModel tidak didukung, lihat Menggunakan fungsi reward kustom.
  • Trainer membutuhkan transformers>=5.2.0.
  • Pelatihan terpecah (sharded) menggunakan FSDP2. DeepSpeed tidak didukung, dan demikian pula paralelisme konteks dan sekuens (cp_size > 1 atau sp_size > 1 di parallelism_config).
  • use_liger_kernel=True tidak didukung.
  • Adaptasi PEFT yang menargetkan lm_head tidak didukung.
  • Model dengan attention sink tidak didukung. Lapisan non-attention yang didukung hanyalah lapisan DeltaNet bergerbang dari model hibrida (Qwen3.5, Qwen3.6, Qwen3-Next, …), yang membutuhkan transformers>=5.15.0.
  • Gambar tidak didukung, lihat Melatih Model Bahasa Visual.

Training memuat kernel attention-nya dari Hub melalui pustaka kernels: kernels-community/aiter-flash-attn pada GPU AMD (ROCm), kernels-community/flash-attn4 pada GPU NVIDIA Blackwell, dan kernels-community/flash-attn3 pada GPU NVIDIA lainnya. Model yang membatasi logit attention-nya (attn_logit_softcapping), seperti Gemma 2, tidak didukung pada GPU AMD maupun GPU NVIDIA Blackwell.

Menggali lebih dalam metode Asynchronous GRPO

Di GRPOTrainer, proses generasi dan pelatihan bersifat berurutan: menghasilkan satu batch, menghitung loss, memperbarui bobot, lalu diulang. Bahkan dalam colocate mode, satu fase harus selesai sebelum fase lainnya dimulai. Di AsyncGRPOTrainer, worker rollout menghasilkan dan menilai kelengkapan (completions) dalam proses latar belakang, sementara loop pelatihan menghitung loss dan memperbarui model. Untuk memahami cara kerjanya, proses ini dapat dipecah menjadi tiga langkah utama: menghasilkan kelengkapan, menghitung advantage, dan menghitung loss. Tidak ada model referensi, sehingga tidak ada istilah divergensi KL (default GRPO, beta=0.0).

Membuat kelengkapan

Worker rollout mempertahankan hingga max_concurrent_rollouts permintaan yang sedang diproses ke server vLLM. Untuk setiap prompt, ia menghasilkan sekelompok G G komplemen (num_generations) dan, setelah seluruh kelompok selesai, memberikan skor dan menghitung keuntungannya. Sampel pelatihan yang dihasilkan masuk ke dalam antrean, yang diambil oleh loop pelatihan. Generasi hanya menunggu ketika berada max_staleness langkah di depan pelatihan (lihat Konkurensi), dan langkah pelatihan hanya menunggu ketika antrean kosong.

Setiap weight_sync_steps langkah pelatihan, trainer mengirimkan bobot terbarunya ke server vLLM melalui NCCL, sehingga kelengkapan berikutnya berasal dari kebijakan terbaru. Oleh karena itu, sebuah kelengkapan dapat berasal dari kebijakan yang beberapa langkah lebih tua daripada kebijakan yang sedang dilatih: sampel yang tertinggal lebih dari max_staleness pembaruan bobot saat ditarik oleh trainer akan dibuang.

Metrik dan bagian lain dari halaman ini menggunakan istilah berikut untuk tahapan yang dilalui oleh sebuah penyelesaian:

  • a grup adalah satu prompt dan G G rollout-nya. Advantage dihitung di dalamnya.
  • a rollout adalah satu percakapan lengkap yang dihasilkan untuk sebuah prompt, termasuk setiap pemanggilan tool. Ia terdiri dari satu atau lebih turns, masing-masing berupa satu permintaan vLLM.
  • a sample adalah data yang digunakan untuk menghitung loss: token-token dari sebuah rollout, beserta advantage-nya. Sebuah rollout multi-turn dapat menghasilkan lebih dari satu sample (lihat Multi-turn rollouts).
  • a row adalah apa yang diteruskan oleh satu proses dalam satu micro-batch: beberapa sampel yang dikemas bersama (lihat Tree packing). Satu micro-batch berisi satu baris per proses, dan gradient_accumulation_steps micro-batch membentuk satu step, yaitu langkah optimizer.

Jumlah token hadir dalam tiga jenis: token yang dihasilkan adalah token yang diproduksi oleh model, token yang diteruskan adalah setiap token dari sebuah sampel (termasuk prompt dan hasil tool), dan token yang dilatih adalah token yang menjadi dasar perhitungan loss.

Menghitung keuntungan

Untuk setiap G G komplemen dari sebuah grup, reward adalah jumlah dari reward dari setiap fungsi reward. Advantage dinormalisasi di dalam grup, seperti pada GRPO: A^i,t=ri−mean(r)std(r)\hat{A}_{i,t} = \frac{r_i - \text{mean}(\mathbf{r})}{\text{std}(\mathbf{r})}

Tidak ada opsi scale_rewards: advantage selalu diskalakan dengan deviasi standar grup. Completion yang semua fungsi reward-nya mengembalikan None tidak dimasukkan ke dalam mean dan deviasi standar grup, serta mendapatkan advantage nol.

Grup yang semua reward-nya sama akan dibuang: dengan default advantage, nilainya nol di mana-mana, sehingga melatihnya hanya akan menghabiskan satu forward dan backward pass tanpa menghasilkan perubahan apa pun. Proporsi grup seperti ini dicatat sebagai frac_zero_std_groups. Langkah diisi dari grup-grup yang dipertahankan, sehingga banyak grup yang dibuang berarti lebih banyak generasi per langkah. Grup yang dibuang tetap dihitung ke dalam epoch, yang tetap satu kali lintasan atas prompt.

Menghitung loss

Log-probabilities dari server vLLM tidak pernah persis sama dengan trainer: kernel yang berbeda, presisi yang berbeda, dan kebijakan yang beberapa langkah tertinggal (lihat Mengatasi Ketidakcocokan Pelatihan-Inferensi). Trainer menggunakan log-probabilities dari sampler sebagai kebijakan lama, sehingga satu rasio importance mencakup baik ketidakcocokan maupun keusangan: ri,t(θ)=πθ(oi,t∣q,oi,<t)πsampler(oi,t∣q,oi,<t). r_{i,t}(\theta) = \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\text{sampler}}(o_{i,t} \mid q, o_{i,< t})}.

Token yang rasionya berada di luar [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] akan dihapus dari loss. Untuk informasi lebih lanjut, lihat Masked Importance Sampling.

Secara default (score_centering=True), trainer menggunakan Score Centering. Bobot kepentingan saja tidak menghilangkan ketidakcocokan: skor ∇θlog⁡πθ \nabla_\theta \log \pi_\theta dari token yang disampel tidak rata-rata nol di bawah sampler μ \mu , sehingga setiap pembaruan juga menarik kebijakan menuju sampler. Score centering mengurangi ekspektasi tersebut di setiap posisi: ∇θL=−Eo∼μ[A^(f(rt)∇θlog⁡πθ(ot)−Ev∼μ[f(rv)∇θlog⁡πθ(v)])],rv=πθ(v)μ(v), \nabla_\theta \mathcal{L} = - \mathbb{E}_{o \sim \mu} \left[ \hat{A} \left( f(r_t) \nabla_\theta \log \pi_\theta(o_t) - \mathbb{E}_{v \sim \mu} \left[ f(r_v) \nabla_\theta \log \pi_\theta(v) \right] \right) \right], \quad r_v = \frac{\pi_\theta(v)}{\mu(v)},

di mana f(r)=r f(r) = r di dalam [Cmin⁡,Cmax⁡] [C_{\min}, C_{\max}] dan 0 0 di luar. Ekspektasi dalam diambil dari num_sampler_logprobs token paling mungkin pada setiap posisi, yang diminta oleh worker rollout dari server.

Dengan score_centering=False, trainer menggunakan tujuan pengganti terpotong (clipped surrogate objective) GRPO sebagai gantinya, dengan rasio yang sama yang dimasker: L(θ)=−1∑i∣oi∣∑i∑t=1∣oi∣1[Cmin⁡≤ri,t(θ)≤Cmax⁡]min⁡(ri,t(θ)A^i,t, clip(ri,t(θ),1−ϵlow,1+ϵhigh)A^i,t), \mathcal{L}(\theta) = - \frac{1}{\sum_{i} |o_i|} \sum_{i} \sum_{t=1}^{|o_i|} \mathbb{1}\left[ C_{\min} \le r_{i,t}(\theta) \le C_{\max} \right] \min \left( r_{i,t}(\theta) \hat{A}_{i,t}, \, \text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_{\text{low}}, 1 + \epsilon_{\text{high}} \right) \hat{A}_{i,t} \right),

di mana ϵlow \epsilon_{\text{low}} adalah epsilon dan ϵhigh \epsilon_{\text{high}} adalah epsilon_high.

Dalam kedua kasus, loss dinormalisasi oleh jumlah token yang dilatih dalam micro-batch, dihitung di semua proses, dan dirata-ratakan di atas gradient_accumulation_steps micro-batch dari satu step.

Metrik yang dicatat

Selama pelatihan, kami mencatat metrik berikut:

  • num_tokens: Total jumlah token yang diteruskan sejauh ini, termasuk prompt dan completion. Dengan tree packing, prefiks yang dibagikan oleh beberapa sampel hanya dihitung sekali.
  • completions/mean_length: Rata-rata panjang dari completion yang dihasilkan. Saat menggunakan tools, hanya token non-tool yang dihitung.
  • completions/min_length: Panjang minimum dari komposisi yang dihasilkan. Saat menggunakan tools, hanya token non-tool yang dihitung.
  • completions/max_length: Panjang maksimum dari komplitasi yang dihasilkan. Saat menggunakan tools, hanya token non-tool yang dihitung.
  • completions/mean_terminated_length: Rata-rata panjang dari kelengkapan yang dihasilkan yang diakhiri dengan EOS. Saat menggunakan alat, hanya token non-alat yang dihitung.
  • completions/min_terminated_length: Panjang minimum dari completion yang dihasilkan yang diakhiri dengan EOS. Saat menggunakan tools, hanya token non-tool yang dihitung.
  • completions/max_terminated_length: Panjang maksimum dari completion yang dihasilkan yang diakhiri dengan EOS. Saat menggunakan tools, hanya token non-tool yang dihitung.
  • completions/clipped_ratio: Rasio penyelesaian yang terpotong (clipped), di mana giliran terakhirnya tidak diakhiri dengan token EOS.
  • completions/duplicate_frac: Fraksi dari rollout yang mengulang rollout sebelumnya dari grup mereka secara token per token. Lihat Saturasi dan duplikat.
  • tools/call_frequency: Rata-rata jumlah pemanggilan alat per penyelesaian, di seluruh rollout, termasuk grup yang kemudian dibuang. Dicatat hanya ketika trainer memiliki alat.
  • tools/failure_frequency: Proporsi pemanggilan alat yang gagal (alat tidak ditemukan atau memicu pengecualian), dari seluruh pemanggilan alat, termasuk grup yang kemudian dibuang. Nilainya NaN pada jendela pencatatan log tanpa pemanggilan alat, di mana GRPO mencatat 0.0. Dicatat hanya ketika trainer memiliki alat.
  • rewards/{reward_func_name}/mean: Rata-rata reward dari fungsi reward tertentu, di atas setiap completion yang dinilai, termasuk grup-grup yang kemudian dibuang. Ketika sebuah environment memiliki reward melalui get_reward, {reward_func_name} adalah nama kelas dari environment tersebut.
  • rewards/{reward_func_name}/group_std: Standar deviasi dari reward yang dihasilkan oleh fungsi reward tertentu, dihitung di dalam setiap grup dan dirata-ratakan di atas sampel yang dilatih.
  • reward: Rata-rata keseluruhan reward setelah menjumlahkan reward di seluruh fungsi, di setiap penyelesaian yang dinilai, termasuk grup-grup yang kemudian dibuang. Ini adalah reward dari kebijakan, sehingga inilah yang perlu dipantau: reward_trained tidak memasukkan grup-grup yang reward-nya semuanya sama.
  • reward_group_std: Deviasi standar dari total reward di seluruh fungsi, dihitung di dalam setiap grup dan dirata-ratakan pada sampel yang dilatih. Nilai ini menjadi pembagi untuk advantage, berbeda dengan reward_std pada GRPO yang diambil dari seluruh batch.
  • reward_trained: Rata-rata reward dari sampel yang digunakan trainer untuk pelatihan. Metrik ini mengabaikan grup yang reward-nya semuanya sama dan sampel yang dibuang karena melebihi max_staleness.
  • reward_zero_std_groups: Rata-rata reward dari grup-grup yang reward-nya semuanya sama, yang dihapus: reward yang mereka capai. Lihat Saturasi dan duplikat untuk membacanya bersama frac_zero_std_groups dan reward.
  • frac_zero_std_groups: Proporsi grup dengan standar deviasi reward nol (semua jawaban benar atau salah), atau dengan kurang dari dua penyelesaian yang dapat dinilai. Grup-grup ini dihapus.
  • sampling/sampling_logp_difference/mean: Rata-rata selisih absolut antara log probabilitas yang dikembalikan oleh sampler (vLLM) dan yang dihitung ulang oleh model pelatihan, di atas token yang dilatih.
  • sampling/sampling_logp_difference/max: Selisih absolut terbesar dari jenis tersebut.
  • sampling/importance_sampling_ratio/min: Rasio importance sampling terkecil ri,t(θ) r_{i,t}(\theta) antara model dan sampler, di atas token yang dilatih, sebelum token di luar [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] dibuang.
  • sampling/importance_sampling_ratio/mean: Rata-rata rasio importance sampling tersebut.
  • sampling/importance_sampling_ratio/max: Rasio importance sampling terbesar.
  • sampling/masked_mean: Proporsi token yang dilatih yang dihapus dari loss karena rasio importance sampling-nya berada di luar [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max].
  • sampling/sampler_mass: Rata-rata massa probabilitas yang dicakup oleh num_sampler_logprobs token paling mungkin dari sampler. Dicatat hanya ketika score_centering=True.
  • entropy: Entropi rata-rata dari prediksi token di seluruh token yang dilatih.
  • aux_loss: kerugian bantu penyeimbangan beban dari model Mixture-of-Experts, sebelum dikalikan dengan router_aux_loss_coef dan ditambahkan ke kerugian. Dicatat hanya ketika model adalah model MoE dan router_aux_loss_coef tidak nol.
  • clip_ratio/region_mean: Rasio probabilitas token di mana tujuan GRPO dipangkas agar tetap berada di dalam trust region: clip(ri,t(θ),1−ϵlow,1+ϵhigh) \text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_\mathrm{low}, 1 + \epsilon_\mathrm{high} \right) . Dengan score_centering=True loss tidak dipangkas, sehingga clip_ratio/* metrik menghitung token di luar trust region.
  • clip_ratio/low_mean: Rata-rata rasio probabilitas token yang dipangkas pada batas bawah trust region: ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/low_min: Fraksi token terkecil per penyelesaian yang dipangkas pada batas bawah trust region: ri,t(θ)<1−ϵlowr_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}.
  • clip_ratio/high_mean: Rata-rata rasio probabilitas token yang dipangkas pada batas atas trust region: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.
  • clip_ratio/high_max: Fraksi token terbesar per penyelesaian yang dipangkas pada batas atas trust region: ri,t(θ)>1+ϵhighr_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}.

Metrik lainnya menjelaskan pipeline asinkron.

Metrik dicatat sekali per jendela pencatatan: semua yang tercatat sejak log sebelumnya, yang mencakup logging_steps langkah optimizer terakhir. Selama jendela tersebut:

  • Rata-rata yang diukur per rollout, sampel, atau panggilan, seperti reward, rollout/turns_mean, dan tools/latency_s, dirata-ratakan di atas semua rollout, sampel, atau panggilan dalam jendela tersebut. Laju seperti rollout/generated_tokens_per_s adalah total token dibagi dengan total detik.
  • Jika tidak, nama yang bagian terakhirnya mengandung kata count akan dijumlahkan: sample/dropped_stale_count adalah jumlah sampel yang dibuang sejak log terakhir, bukan sejak awal pelatihan.
  • Nama yang bagian terakhirnya mengandung kata max atau min, seperti sample/staleness_max atau completions/max_length, mempertahankan nilai terbesar atau terkecil.
  • Metrik lainnya adalah rata-rata dari nilai yang tercatat dalam jendela.

Unit:

  • _s: detik.
  • tokens_per_s: token per detik.
  • _frac: fraksi antara 0 dan 1.
  • _per_step: jumlah dalam satu langkah optimizer, dirata-ratakan atas langkah-langkah dalam jendela.

Metrik rollout

  • rollout/duration_s: Waktu nyata (wall time) dari satu rollout, mulai dari dispatch hingga loop rollout mengumpulkannya.
  • rollout/generated_tokens_per_s: Laju throughput generasi, dalam token yang dihasilkan per detik, sejak laporan sebelumnya.
  • rollout/concurrency: Jumlah rollout yang sedang berjalan ke server vLLM.
  • rollout/concurrency_cap: Batas saat ini untuk rollout yang sedang berjalan, yang mengikuti beban server. Lihat Konkurensi.
  • rollout/turns_mean, rollout/turns_max: Rata-rata dan jumlah maksimum giliran per rollout.
  • rollout/samples_per_rollout: Jumlah sampel pelatihan per rollout. Di atas 1.0, beberapa rollout di-fork; di bawah 1.0, beberapa tidak menghasilkan token yang dilatih. Lihat Multi-turn rollouts.
  • rollout/fork_frac: Fraksi transisi giliran yang prompt-nya tidak dimulai dengan token yang dipegang, sehingga giliran tersebut memulai sampel baru.
  • rollout/drift_tokens_mean, rollout/drift_tokens_max: Jumlah token yang ditahan dan dirender ulang oleh sebuah fork, dirata-ratakan atas transisi giliran (transisi yang tidak melakukan fork dihitung sebagai 0). Sampel baru berbagi token sebelum titik divergensi, sehingga ini adalah kontribusi tambahan dari setiap fork ke proses forward.
  • rollout/score_queue_size: Jumlah grup yang selesai dan menunggu untuk dinilai.
  • rollout/queue_size: Jumlah sampel yang dinilai dan menunggu di antrean rollout, diukur pada titik di mana trainer mengambilnya. Lihat Antrean rollout.
  • rollout/score_s: Waktu untuk menilai sebuah grup.
  • rollout/score_wait_s: Waktu yang dihabiskan oleh grup yang telah selesai sebelum diberi skor.
  • rollout/score_block_s: Waktu di mana generasi diblokir karena antrean penilaian penuh.
  • rollout/backpressure_s: Waktu yang dihabiskan oleh proses generasi untuk menunggu sebelum memulai rollout karena sudah max_staleness langkah di depan proses pelatihan, dirata-ratakan dari seluruh waktu tunggu dalam jendela pencatatan. Lihat Konkurensi.
  • rollout/vllm_retry_count: Jumlah permintaan vLLM yang diulang. Server yang bermasalah akan tampak seperti perlambatan yang tidak jelas penyebabnya.
  • rollout/vllm_kv_cache_usage_frac: Penggunaan KV cache vLLM (maksimum di antara engine), dirata-ratakan dari polling dalam jendela pencatatan.
  • rollout/vllm_running_requests: Jumlah permintaan yang sedang didekode oleh mesin server (vLLM’s num_requests_running, dijumlahkan di seluruh mesin). Selisih dengan rollout/concurrency adalah permintaan yang berada di proses API server, sedang membangun respons.
  • rollout/vllm_queued_requests: Jumlah permintaan yang telah diterima server tetapi belum dijadwalkan (num_requests_waiting dari vLLM, dijumlahkan di seluruh engine).
  • rollout/vllm_preemption_count: Jumlah permintaan yang dipreempt oleh server (num_preemptions_total dari vLLM, dijumlahkan di seluruh engine). Sinkronisasi bobot mereset cache server, yang mempreempt setiap permintaan yang sedang berjalan, sehingga ini bukan sinyal tekanan.

Metrik alat

  • tools/latency_s, tools/{tool_name}/latency_s: Waktu yang dihabiskan untuk mengeksekusi pemanggilan alat, untuk semua alat dan per alat.
  • tools/{tool_name}/call_count, tools/{tool_name}/failure_count: Jumlah panggilan dan panggilan yang gagal per tool.
  • tools/unknown_name_count: Jumlah pemanggilan ke alat yang tidak ada. Berbeda dengan alat yang dijalankan dan memicu pengecualian, ini adalah kesalahan kebijakan.
  • tools/parallel_calls_mean: Rata-rata jumlah pemanggilan alat dalam pesan asisten yang memanggil alat.
  • tools/loop_exhausted_frac: Proporsi rollout yang dipotong pada max_tool_calling_iterations saat masih memanggil tools, dari seluruh rollout, termasuk rollout tanpa panggilan dan grup yang kemudian dibuang. Dicatat hanya ketika trainer memiliki tools.

HarnessAsyncGRPOTrainer mencatat sebagian besar dari hal-hal ini dengan nama yang sama. Lihat Training on harnesses untuk perbedaannya.

Metrik lingkungan

  • env/reset_s: Waktu yang dihabiskan di reset() lingkungan sebelum rollout dimulai. Dicatat hanya ketika environment_factory disediakan.
  • env/reward_s: Waktu yang dihabiskan di get_reward() lingkungan setelah rollout berakhir. Dicatat hanya jika lingkungan mendefinisikan get_reward.

Metrik sampel

  • sample/forwarded_tokens_mean, sample/forwarded_tokens_max: Rata-rata dan jumlah maksimum token yang diteruskan per sampel.
  • sample/trained_tokens_mean: Rata-rata jumlah token terlatih per sampel.
  • sample/time_in_queue_s: Waktu yang dihabiskan sampel di antrean rollout sebelum dilatih.
  • sample/staleness_mean, sample/staleness_max: Jumlah pembaruan bobot antara kebijakan yang menghasilkan sampel dan kebijakan yang melatihnya. Metrik sampling/importance_sampling_ratio/* dan sampling/sampling_logp_difference/* menggabungkan keusangan ini dengan ketidakcocokan pelatihan-inferensi: rasio yang menyimpang dari 1.0 atau perbedaan log-probabilitas yang menyimpang dari 0.0 pada keusangan nol menunjukkan adanya ketidakcocokan, misalnya perbedaan dtype dengan server.
  • sample/dropped_stale_count: Jumlah sampel yang dibuang karena melebihi max_staleness.

Metrik batch

  • batch/forwarded_tokens_per_step, batch/trained_tokens_per_step: Jumlah token yang diteruskan dan dilatih per langkah, di semua proses.
  • batch/samples_per_step, batch/groups_per_step: Jumlah sampel dan jumlah grup berbeda per langkah. Keduanya berbeda berdasarkan jumlah sampel per grup.
  • batch/microbatches_per_step: Jumlah micro-batch per langkah.
  • batch/masked_token_frac: Proporsi token yang diteruskan yang tidak dilatih.
  • batch/samples_per_row, batch/row_tokens_mean, batch/row_tokens_max: Jumlah sampel per baris, serta rata-rata dan jumlah maksimum token yang diteruskan per baris.
  • batch/row_fill_frac: Proporsi token_budget yang digunakan oleh baris.
  • batch/row_imbalance: Rasio biaya perhatian baris termahal terhadap rata-ratanya. Proses dengan baris termahal akan menghentikan proses lainnya pada all-reduce gradien; 1.0 adalah keseimbangan sempurna.
  • batch/packing_ratio: Jumlah token sebelum packing per token yang diteruskan: faktor yang menentukan seberapa besar packing memperkecil forward, 1.0 ketika tidak ada yang dibagikan.
  • batch/pad_frac: Fraksi padding yang ditambahkan untuk menyamakan panjang baris. Ini hanya menimbulkan biaya transfer dan dihapus sebelum forward.
  • batch/dropped_oversize_count: Jumlah sampel yang dibuang karena melebihi token_budget.

Metrik kinerja

  • perf/step_s: Waktu nyata (wall time) dari satu langkah, termasuk optimizer, sinkronisasi bobot, dan waktu menunggu sampel.
  • perf/fwd_bwd_s, perf/fwd_s: Waktu yang dihabiskan pada langkah forward dan backward, serta hanya pada langkah forward.
  • perf/optimizer_s: Waktu yang dihabiskan pada langkah optimizer.
  • perf/rollout_wait_s: Waktu pelatihan menunggu karena antrean rollout kosong. Lihat Antrean rollout.
  • perf/weight_sync_s: Waktu sinkronisasi bobot, yang dipecah menjadi perf/weight_sync_pause_s (menunggu vLLM untuk dijeda), perf/weight_sync_barrier_s (menunggu proses lainnya) dan perf/weight_sync_transfer_s (mengirimkan bobot).
  • perf/fwd_bwd_forwarded_tokens_per_s, perf/wall_clock_forwarded_tokens_per_s: Jumlah token yang diteruskan per detik, baik pada jalur forward dan backward maupun pada seluruh langkah.
  • perf/wall_clock_trained_tokens_per_s: Jumlah token yang dilatih per detik, selama seluruh langkah.
  • perf/fwd_bwd_mfu, perf/wall_clock_mfu: Utilisasi FLOPs model pada perangkat pelatihan, baik untuk jalur forward dan backward maupun untuk seluruh langkah. Metrik ini tidak mencakup server vLLM. Dicatat hanya ketika puncak komputasi perangkat pelatihan pada presisi pelatihan diketahui, dan ketika estimasi FLOPs mendukung arsitektur model (seperti Llama, Qwen2, Qwen3, Qwen3-MoE, atau Qwen3-VL).

Kustomisasi

Mengonfigurasi server vLLM

Trainer menghasilkan dengan server vLLM, yang dijangkau di vllm_server_base_url (secara default http://localhost:8000):

VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --max-model-len 4096
  • VLLM_SERVER_DEV_MODE=1 dan --weight-transfer-config membuka endpoint yang digunakan trainer untuk mengirimkan bobotnya.
  • --logprobs-mode processed_logprobs membuat server mengembalikan log-probabilitas dari distribusi yang diambil, setelah penerapan temperature dan top-k/top-p, yang merupakan nilai yang dibandingkan oleh rasio kepentingan.
  • --api-server-count 8 mempertahankan log-probabilitas teratas agar permintaan centering skor dapat dilayani dengan murah (lihat peringatan di bawah).
  • --max-model-len adalah panjang total urutan maksimum (prompt dan completion) yang Anda perkirakan. Nilai yang lebih rendah mengurangi penggunaan memori GPU di server, sehingga membebaskan lebih banyak memori untuk KV cache dan meningkatkan throughput. Titik awal yang baik adalah panjang prompt ditambah max_completion_length dari config Anda. Dengan tools, setiap turn menambahkan hingga max_completion_length token ditambah hasil tool, jadi atur nilainya ke percakapan terpanjang yang Anda perkirakan. Jika prompt sebuah turn ditambah max_completion_length lebih panjang dari --max-model-len, server akan menolak permintaan tersebut dan eksekusi berhenti dengan error dari server. Dengan top_k atau top_p, server justru menghentikan turn tersebut saat mencapai --max-model-len, dan hanya menolak prompt yang sudah sepanjang itu. Nilai ini juga menjadi default untuk token_budget.

Pastikan server menggunakan GPU yang berbeda dari trainer, jika tidak Anda mungkin akan menemui error NCCL. Anda dapat menentukan GPU yang akan digunakan dengan variabel lingkungan CUDA_VISIBLE_DEVICES.

Serialisasi log-probabilitas teratas adalah pekerjaan CPU di server API vLLM, dan dengan satu server API default serta num_sampler_logprobs=8, throughput generasi berkurang setengahnya. Jalankan server dengan --api-server-count 8 pada vLLM 0.32 atau lebih baru: diukur pada satu H100 dengan model 1,5B hingga 7B, log-probabilitas teratas-8 kemudian hanya memakan biaya kurang dari 3% dari throughput generasi. Pada vLLM 0.31, flag yang sama masih menyisakan kerugian 20 hingga 40%, yang telah diperbaiki di hulu oleh vllm-project/vllm#58181.

Kesejajaran

Tiga batas menentukan berapa banyak rollout yang dijalankan secara bersamaan. Dua pertama beradaptasi secara otomatis; yang ketiga diatur oleh Anda.

Kedaluwarsa. max_staleness mengatur seberapa jauh langkah pelatihan yang boleh dijalankan oleh proses generasi di depan trainer. Worker melacak ini dalam satuan token, karena jumlah sampel dalam satu langkah berubah seiring panjang atau pendeknya hasil penyelesaian. Setelah setiap langkah, trainer menghitung jumlah token yang digunakan, dan membiarkan worker mempertahankan hingga max(max_staleness, 1) kali jumlah token tersebut dalam antrean atau sedang diproses. Sebelum langkah pertama, trainer mengasumsikan setiap baris penuh. Worker memulai grup rollout baru hanya selama berada di bawah batas tersebut. Pada awal proses, worker belum mengetahui berapa banyak token yang dihasilkan oleh satu rollout, sehingga memulai satu grup pada satu waktu hingga grup pertama selesai. Sampel yang pada akhirnya tetap lebih dari max_staleness langkah kedaluwarsa akan dibuang.

Memuat vLLM. Mengirim terlalu banyak permintaan ke vLLM sekaligus membuatnya lebih lambat: KV cache terisi penuh, dan vLLM harus jeda serta mengulang beberapa permintaan. Oleh karena itu, worker juga membatasi jumlah rollout yang berjalan secara bersamaan, yang dicatat sebagai rollout/concurrency_cap, dan memeriksa /metrics server setiap 5 detik untuk menyesuaikannya. Batas ini dimulai dari jumlah permintaan yang muat di KV cache pada panjang penuh (KV cache tokens / max_model_len), sehingga server tidak kelebihan beban di awal. Selama penggunaan KV-cache tetap di bawah 60% dan tidak ada permintaan yang menunggu, batasnya dinaikkan sebesar 25%, maksimal sekali per sejumlah cap rollout yang selesai. Ketika penggunaan melebihi 80%, batasnya diturunkan sebesar 30%: permintaan yang sedang berjalan tetap dilanjutkan, dan permintaan baru menunggu. Jika server tidak memiliki endpoint /metrics, batasnya adalah max_concurrent_rollouts.

Sumber daya. max_concurrent_rollouts (default 512) adalah batas atas jumlah rollout yang berjalan secara bersamaan. Ini adalah satu-satunya batas yang Anda atur sendiri, karena trainer tidak dapat melihat apa yang dapat ditangani oleh lingkungan dan tool Anda. Setiap rollout yang berjalan menggunakan satu lingkungan, dapat menjalankan panggilan tool sinkron pada thread pool dengan ukuran ini, dan menjaga koneksi terbuka ke server vLLM. Atur nilainya sesuai dengan yang dapat ditangani oleh komponen tersebut, misalnya jumlah sesi yang diterima oleh server lingkungan Anda:

from trl import AsyncGRPOConfig

training_args = AsyncGRPOConfig(
    ...,
    max_concurrent_rollouts=64,
)

Jika nilainya terlalu rendah, proses generasi akan melambat. Sebuah rollout mempertahankan slot-nya selama menjalankan alat atau menunggu di antara giliran, bukan hanya saat vLLM melakukan generasi, sehingga rollout yang memanggil banyak alat membutuhkan lebih banyak slot agar vLLM tetap sibuk. Jika nilainya jauh lebih tinggi dari nilai default, server vLLM dapat mulai memutus koneksi.

Metrik yang dicatat menunjukkan batas mana yang menahan proses generasi:

  • rollout/backpressure_s di atas nol: batas keusangan. Proses generasi berada di depan proses pelatihan, yang merupakan hal yang wajar ketika inferensi lebih cepat daripada pelatihan.
  • rollout/concurrency pada rollout/concurrency_cap, di bawah max_concurrent_rollouts: beban server vLLM.
  • rollout/concurrency pada max_concurrent_rollouts, dengan rollout/vllm_kv_cache_usage_frac rendah dan perf/rollout_wait_s tinggi: batas atas. Naikkan max_concurrent_rollouts jika lingkungan dan alat Anda mengizinkan.

Antrean rollout

Worker mendorong sampel yang telah diberi skor ke dalam antrean, dan trainer menarik darinya. Empat metrik menggambarkan antrean tersebut:

  • rollout/queue_size: berapa banyak sampel yang sedang menunggu.
  • sample/time_in_queue_s: berapa lama satu sampel menunggu sebelum dilatih, yaitu bagian waktu dari keusangan (staleness)-nya.
  • perf/rollout_wait_s: berapa lama pelatihan menunggu karena antrean kosong.
  • rollout/backpressure_s: berapa lama generasi menunggu karena berada max_staleness langkah di depan pelatihan.

Dua yang terakhir adalah cermin satu sama lain. Dibaca bersama dengan ukuran antrean, keduanya menunjukkan sisi mana yang menjadi bottleneck:

  • antrean hampir kosong, perf/rollout_wait_s tinggi: generation-bound. Trainer sedang kelaparan; periksa rollout/generated_tokens_per_s, rollout/concurrency dan rollout/score_queue_size.
  • antrean yang menyimpan sekitar max_staleness langkah token, rollout/backpressure_s tinggi: trainer-bound. Proses generasi tertahan, dan sample/staleness_mean berada di dekat batasnya.
  • keduanya tinggi: batas max_staleness itu sendiri terlalu ketat. Rollout yang sedang berjalan memenuhi batas tersebut sebelum sampelnya mencapai antrean, sehingga trainer menunggu sementara generasi ditahan. Naikkan max_staleness.
  • keduanya mendekati nol: seimbang.

Jenuh dan duplikat

Kebijakan belajar dari perbedaan antara rollout dari sebuah grup: setiap keuntungan dihitung terhadap imbalan rata-rata grup. Ketika setiap rollout dalam sebuah grup mendapatkan imbalan yang sama, semuanya mendapat keuntungan nol, sehingga grup tersebut dibuang (lihat Metriks yang dicatat) dan tidak mengajarkan apa pun kepada kebijakan. Seiring jalannya eksekusi menjadi jenuh, semakin banyak grup yang berakhir seperti ini, baik karena setiap rollout menyelesaikan prompt atau karena tidak ada yang berhasil. Empat metrik membedakan kasus-kasus ini, dan masing-masing menjawab pertanyaannya sendiri, sehingga Anda dapat membacanya langsung dari plot mereka:

metrikpertanyaan
frac_zero_std_groupsbagian dari kelompok yang tidak membawa sinyal
reward_zero_std_groupsdi mana kelompok-kelompok tersebut terjebak: reward rata-rata mereka. Dengan reward 0/1, ini adalah proporsi di mana setiap rollout berhasil, sehingga 0,9 berarti hampir semua di antaranya berhasil, dan 0,1 berarti hampir semua di antaranya gagal di setiap rollout
rewardseberapa baik kebijakan tersebut di setiap grup yang dinilai, termasuk yang dihapus
completions/duplicate_fracapakah sampling masih menghasilkan rollout yang berbeda untuk prompt yang sama

Baca tiga pertama secara bersamaan, dibandingkan dengan rentang reward Anda:

frac_zero_std_groupsreward_zero_std_groupsrewarddiagnosisapa yang harus dilakukan
rendahany (berisik di beberapa grup)anysehat: sebagian besar grup menghasilkan gradiennothing
mendakidi bagian atas rentangmendakijenuh di bagian atas: prompt telah menjadi terlalu mudah bagi kebijakan, yang merupakan cara sebuah run yang sukses biasanya berakhirhentikan eksekusi, atau beralih ke prompt yang lebih sulit
tinggidi bagian bawah rentangrendah dan datarterjebak di bagian bawah: prompt terlalu sulit, atau fungsi reward tidak pernah memberikan kreditPeriksa completions/clipped_ratio terlebih dahulu, karena completion yang terpotong sebelum jawabannya akan mendapat skor 0, lalu baca beberapa completion untuk memastikan bahwa fungsi reward dapat mem-parsenya
mendakiturunturunregression: grup yang sebelumnya lulus kini gagal bersamaperiksa completions/duplicate_frac dan entropy untuk melihat adanya kolaps
tinggidi tengahanycampuran: dengan reward 0/1, beberapa prompt terlalu mudah dan yang lain terlalu sulit. Dengan reward berbasis nilai parsial, grup juga bisa terjebak pada skor parsial yang samamembaca rollouts

completions/duplicate_frac adalah proporsi rollout yang mengulang rollout sebelumnya dari grupnya secara token per token, di seluruh giliran mereka. Rollout yang identik mendapatkan reward yang identik, sehingga duplikat juga mendorong frac_zero_std_groups naik.

completions/duplicate_fracdiagnosis
dekat 0, dengan baseline kecil pada tugas-tugas yang penyelesaiannya cukup pendek sehingga dapat diulang secara kebetulansehat: rollout dari sebuah grup disampel secara independen
melonjak menuju (num_generations - 1) / num_generationssampling tidak lagi acak: setiap grup kembali sebagai salinan dari satu rollout. Misalnya, temperature 0, atau mesin vLLM data-parallel yang mendekode teks yang sama karena mereka berbagi seed sampling (worker mengirim seed unik dengan setiap permintaan untuk mencegah hal ini)
naik perlahan, dengan entropy yang turuncollapse: kebijakan sedang konvergen ke satu jawaban per prompt

Metrik ini dicatat saat worker menilai sebuah grup, bukan saat sampelnya dilatih, sehingga metrik ini berjalan sedikit di depan proses pelatihan dan mencakup grup yang sampelnya kemudian dibuang karena melebihi max_staleness. Grup yang tidak memiliki rollout yang dapat dinilai, karena setiap fungsi reward mengembalikan None, akan dibuang dan dihitung dalam frac_zero_std_groups, tetapi karena grup tersebut tidak memiliki reward, reward_zero_std_groups tidak menyertakannya.

Packing pohon

Contoh-contoh dalam micro-batch dikemas menjadi satu baris per proses, tanpa padding. Sebuah baris adalah prefix trie, bukan konkatenasi: token yang dibagikan oleh beberapa contoh hanya diteruskan sekali, dan perhatian (attention) tetap menunjukkan setiap contoh hanya riwayatnya sendiri. Rollout dari sebuah grup semuanya mengulang prompt-nya, dan setiap giliran dari rollout multi-giliran mengulang percakapan sejauh ini, sehingga forward menyusut sesuai rasio pengemasan (batch/packing_ratio). Ini hanyalah perubahan tata letak: setiap token yang dilatih mempertahankan target, keuntungan (advantage), dan log-probabilitas lamanya masing-masing, dan log-probabilitasnya cocok dengan meneruskan contoh tersebut secara terpisah.

Pada dua rollout dari satu prompt, di mana p adalah prompt dan a, b adalah dua penyelesaian:

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

2. Trie             S0 [p1 p2] ─┬─ S1 [p3 a1 a2]       p3 is not shared: a position predicts
                                └─ S2 [p3 b1 b2]       one token, and p3 predicts a1 or b1

3. Packed row       index         0  1 |  2  3  4 |  5  6  7
   (depth-first)    input_ids    p1 p2 | p3 a1 a2 | p3 b1 b2    8 tokens: everything but attention
                    position_ids  0  1 |  2  3  4 |  2  3  4    runs on 8 instead of 10
                    segment      S0    | S1       | S2

4. Attention        segment   queries    keys and values: the segment's path in the trie
   (one call)       S0        p1 p2      p1 p2              index 0 1
                    S1        p3 a1 a2   p1 p2 p3 a1 a2     index 0 1 2 3 4
                    S2        p3 b1 b2   p1 p2 p3 b1 b2     index 0 1 5 6 7

5. Loss             r0: a1 a2 predicted at index 2 3   each trained token is predicted at the index
                    r1: b1 b2 predicted at index 5 6   of the token before it in its rollout

Beberapa konsekuensinya:

  • Prefix umum mana pun dibagikan: rollout dari sebuah prompt, dan antar prompt, prompt sistem atau skema tool yang sama. Sampel dikirim ke baris yang sudah memegang grupnya, di mana promptnya sudah ada. Ketika baris tersebut penuh, sampel dikirim ke baris lain jika masih ada proses dengan baris kosong, atau jika hal itu tidak meningkatkan baris yang paling terbebani, yang menentukan waktu micro-batch; jika tidak, micro-batch ditutup.
  • Tidak ada yang dibagikan adalah plain packing: setiap sampel kemudian menjadi segmen tersendiri, yang merupakan packing tanpa padding biasa.
  • Hanya K/V yang diduplikasi: prefiks bersama dikumpulkan sekali per segmen keturunan, yang kira-kira sama dengan yang dipegang oleh pelatihan terurai, dan kecil dengan grouped-query attention.
  • Hybrid Gated DeltaNet didukung (Qwen3.5, Qwen3.6, Qwen3-Next, …): konvolusinya membaca pendahulu dari setiap token, dan aturan delta chunked-nya memulai setiap segmen dari keadaan akhir induknya.

token_budget membatasi jumlah token pada satu baris, dengan menghitung token yang dibagikan hanya sekali. Secara default, nilainya adalah max_model_len dari server, sehingga tidak ada sampel yang dapat melampauinya. Jika tidak ada token yang dibagikan, tree packing berjalan dengan kecepatan sekitar sama dengan plain padding-free packing, dan percepatannya meningkat secara proporsional dengan rasio packing (sekitar 2,8 hingga 3x pada rasio 3,4 di Qwen3-0.6B dan 1.7B, di H100). Rasio ini adalah prefix bersama dikali jumlah sampel per baris, sehingga batch/samples_per_row adalah indikator utama: jika nilainya mendekati 1, tidak ada yang dapat dibagikan, dan tuas pengaturnya adalah token_budget. batch/row_fill_frac menjadi penting ketika sampelnya panjang: sampel 10k token mengisi budget 32k dengan buruk (tiga muat, empat tidak pernah muat, sehingga planner sering hanya mendapatkan dua dan barisnya terisi sekitar 77%), sedangkan sampel 1k token mengisinya hampir sempurna.

Nilai tree packing berdasarkan throughput, batch/trained_tokens_per_step / perf/fwd_bwd_s. Micro-batch yang dipacking menampung lebih banyak sampel, sehingga perf/fwd_bwd_s naik dan perf/fwd_bwd_mfu, yang membagi dengan token yang diteruskan, turun: keduanya bukan regresi. Lebih banyak sampel per baris juga berarti lebih banyak rollout yang diambil per langkah, sehingga run yang dibatasi oleh generasi menjadi semakin demikian.

Metrik batch tersusun sebagai berikut: satu langkah memegang gradient_accumulation_steps × num_processes baris, sehingga batch/samples_per_step sekitar sebanyak itu kali batch/samples_per_row, dan hal yang sama berlaku untuk token. Kedua sisi hanya sesuai hingga variasi antar micro-batch dalam satu langkah, karena metrik per-langkah adalah jumlah dan metrik per-baris adalah rata-rata.

Apa pun yang membuat baris menjadi lebih panjang atau lebih sedikit akan menghapus berbagi. Percakapan multi-turn yang tidak pernah bercabang adalah satu sampel panjang, dan rollout/samples_per_rollout menyatakan berapa banyak sampel yang diberikan oleh sebuah percakapan.

Sampling top-k dan top-p

Top-k dan top-p menormalisasi ulang distribusi sampling pada himpunan kandidat yang dibatasi, bukan pada seluruh kosakata. Log-probabilitas dari server mencerminkan hal tersebut (--logprobs-mode processed_logprobs), sehingga trainer harus menormalisasi pada himpunan yang sama; jika tidak, setiap rasio kepentingan akan bias: probabilitas sebuah token pada seluruh kosakata lebih rendah daripada pada himpunan kandidat tempat token tersebut diambil (DeepSeek-V3.2, bagian 3.1). Dengan top_p < 1 atau top_k > 0, worker meminta himpunan kandidat untuk setiap token yang disampelkan dari server, dan trainer menormalisasi ulang log-probabilitasnya pada himpunan tersebut. Hal ini membutuhkan dua flag server tambahan, dan top_k harus diatur, karena vLLM membatasi ukuran himpunan kandidat dengannya:

VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --max-model-len 4096 \
    --return-sampling-mask \
    --enable-scale-out
from trl import AsyncGRPOConfig

training_args = AsyncGRPOConfig(
    ...,
    top_p=0.95,
    top_k=512,
)

--return-sampling-mask membuat vLLM merekam himpunan kandidat (vLLM 0.28 atau lebih baru, pada model runner V2-nya: VLLM_USE_V2_MODEL_RUNNER=1 jika server menolak flag tersebut), dan --enable-scale-out membuka endpoint token-in-token-out yang mengembalikannya. Worker memeriksa keduanya di server saat dimulai. vLLM yang lebih lama tidak dapat mengembalikan himpunan tersebut, sehingga trainer tetap menormalisasi di seluruh kosakata dan memberikan peringatan tentang rasio yang bias.

Latih adapter dengan PEFT

Kami mendukung integrasi yang erat dengan pustaka 🤗 PEFT, memungkinkan Anda melatih adapter dan membagikannya di Hub, alih-alih melatih seluruh model.

from datasets import load_dataset
from peft import LoraConfig
from trl import AsyncGRPOTrainer
from trl.rewards import accuracy_reward

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

    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen3.5-2B",
        reward_funcs=accuracy_reward,
        train_dataset=dataset,
        peft_config=LoraConfig(r=32, lora_alpha=64, target_modules="all-linear"),
    )
    trainer.train()

Setiap sinkronisasi bobot harus mengirimkan kebijakan yang diperbarui ke server. Secara default, trainer menggabungkan adapter ke dalam model dasar dan mengirimkan bobot gabungan penuh, yang ukurannya sekitar 15 GB untuk model 7B pada setiap sinkronisasi. Jalankan server vLLM dengan --enable-lora dan server hanya akan mengirimkan adapter, sekitar 160 MB pada r=32:

VLLM_SERVER_DEV_MODE=1 VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 vllm serve <model_name> \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --max-model-len 4096 \
    --enable-lora \
    --max-lora-rank 32 \
    --max-loras 6

VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 membuka endpoint yang digunakan trainer untuk mengirim setiap adapter baru. Pertahankan --weight-transfer-config meskipun menggunakan --enable-lora: trainer hanya memilih mode sinkronisasi saat dimulai, dan pada saat itu server sudah berjalan, sehingga merged sync menjadi fallback.

--max-lora-rank harus salah satu dari 1, 8, 16, 32, 64, 128, 256, 320, 512. Parameter ini mengatur rank tertinggi yang dapat dilayani oleh server, bukan rank yang akan dilayani, sehingga adapter r=4 tetap berfungsi dengan baik di bawah 8. --max-loras harus setidaknya max_staleness + 2: trainer mempertahankan max_staleness + 1 versi adapter yang terdaftar agar rollout yang dimulai di bawah kebijakan yang lebih lama dapat diselesaikan di bawah kebijakan tersebut, bukan beralih kebijakan di tengah generasi, dan setiap sinkronisasi memuat versi berikutnya sebelum memuat ulang yang tertua. Trainer memeriksa kedua nilai ini saat dimulai dan memberi tahu Anda dengan nilai apa server harus di-restart.

vLLM memuat adapter dari disk, bukan melalui jaringan, sehingga trainer menulis setiap versi di bawah <output_dir>/.vllm_lora/ dan memberikan path tersebut ke server. Jika server berjalan di mesin yang berbeda, direktori tersebut harus berada pada filesystem yang dapat diakses oleh keduanya.

<output_dir>/.vllm_lora/ adalah cache untuk serving, bukan tempat adapter yang Anda latih disimpan. Direktori ini hanya menyimpan versi-versi terbaru, dan masing-masing akan dihapus segera setelah keluar dari jendela keusangan (staleness window). Checkpoint-lah yang melestarikan adapter yang Anda latih, jadi jangan nonaktifkan fitur ini: dengan save_strategy="no", eksekusi berdurasi beberapa jam akan selesai tanpa meninggalkan apa pun. output_dir juga harus dapat dibaca oleh server dan harus bertahan lebih lama dari job, sehingga scratch node-lokal tidak akan berfungsi, meskipun hal itu akan menjaga sinkronisasi agar tidak membebani filesystem bersama yang lambat.

Sinkronisasi adapter tidak selalu lebih cepat. vLLM menghasilkan token sekitar 1,33 hingga 1,39 kali lebih lambat per token saat menyajikan adapter LoRA dibandingkan saat menyajikan bobot yang sudah digabungkan, dan proses generasi biasanya mendominasi waktu nyata dalam RL. Sebagai gantinya, Anda mendapatkan jeda yang jauh lebih singkat di setiap sinkronisasi dan sekitar 1% dari pita lebar sinkronisasi. Jika throughput generasi adalah hambatan utama Anda, sinkronisasi gabungan sering kali tetap menjadi pilihan yang lebih baik.

Menggunakan fungsi reward kustom

AsyncGRPOTrainer mendukung penggunaan fungsi reward kustom. Untuk memastikan kompatibilitas, fungsi reward Anda harus memenuhi persyaratan berikut:

Fungsi reward dapat berupa callable Python sinkron atau coroutine async def asinkron. Ketika Anda menyediakan beberapa fungsi reward, mereka dijalankan secara bersamaan: yang asinkron di-await bersama, dan yang sinkron dijalankan di thread, sehingga latensi mereka saling tumpang tindih.

  1. Argumen input:

    • Fungsi harus menerima argumen berikut sebagai argumen kata kunci:

      • prompts (mengandung prompt),
      • completions (mengandung kelengkapan yang dihasilkan),
      • completion_ids (mengandung pelengkapan yang telah ditokenisasi),
      • Semua nama kolom (kecuali prompt) yang mungkin dimiliki dataset. Misalnya, jika dataset berisi kolom bernama ground_truth, fungsi tersebut akan dipanggil dengan ground_truth sebagai argumen kata kunci.

      Cara termudah untuk memenuhi persyaratan ini adalah dengan menggunakan **kwargs dalam tanda tangan fungsi.

    • Dataset berada dalam format percakapan, sehingga prompts dan completions adalah daftar kamus pesan.

  2. Nilai yang dikembalikan: Fungsi harus mengembalikan daftar float. Setiap float mewakili reward yang sesuai dengan satu completion.

Fungsi reward dijalankan di worker rollout, sebuah proses terpisah, sehingga semua yang diteruskan ke proses tersebut akan di-pickle. Setiap fungsi reward, tool, dan environment_factory (serta apa pun yang mereka tutup) harus dapat di-pickle: gunakan fungsi tingkat modul, functools.partial, atau instans kelas yang dapat dipanggil. Lambda dan closure akan memicu TypeError saat trainer.train(). Ini berbeda dari GRPOTrainer, di mana fungsi reward dipanggil dalam proses dan closure berfungsi.

Proses rollout juga dijalankan dengan CUDA_VISIBLE_DEVICES="", sehingga tidak dapat menggunakan GPU. Model reward berbasis GPU (misalnya scorer AutoModelForSequenceClassification) dimuat tanpa error tetapi secara diam-diam beralih ke CPU. Jaga agar fungsi reward tetap ringan (verifier seperti accuracy_reward, atau pemeriksaan format dan panjang). Jika Anda membutuhkan model reward berbasis GPU, layanannya di belakang mesin inferensinya sendiri (vLLM, TGI, …) pada GPU terpisah, dan buat fungsi reward yang dapat di-pickle untuk memanggilnya melalui HTTP.

Contoh 1: Memberi imbalan pada penyelesaian yang lebih panjang

Berikut adalah contoh fungsi reward yang memberikan reward lebih tinggi untuk penyelesaian yang lebih panjang:

def reward_func(completion_ids, **kwargs):
    """Reward function that assigns higher scores to longer completions (in terms of token count)."""
    return [float(len(ids)) for ids in completion_ids]

Anda dapat mengujinya sebagai berikut:

>>> prompts = [[{"role": "user", "content": "The sky is"}], [{"role": "user", "content": "The sun is"}]]  # not used in the reward function, but the trainer will pass it
>>> completions = [[{"role": "assistant", "content": " blue."}], [{"role": "assistant", "content": " in the sky."}]]  # not used in the reward function, but the trainer will pass it
>>> completion_ids = [[6303, 13], [304, 279, 12884, 13]]
>>> reward_func(prompts=prompts, completions=completions, completion_ids=completion_ids)
[2.0, 4.0]

Contoh 2: Memberikan imbalan untuk penyelesaian dengan format tertentu

Berikut adalah contoh fungsi reward yang memeriksa apakah penyelesaian memiliki format tertentu. Contoh ini terinspirasi dari fungsi format reward yang digunakan dalam makalah DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. Fungsi ini dirancang untuk format percakapan, di mana prompt dan penyelesaian terdiri dari pesan terstruktur.

import re

def format_reward_func(completions, **kwargs):
    """Reward function that checks if the completion has a specific format."""
    pattern = r"^<think>.*?</think><answer>.*?</answer>$"
    completion_contents = [completion[0]["content"] for completion in completions]
    matches = [re.match(pattern, content) for content in completion_contents]
    return [1.0 if match else 0.0 for match in matches]

Anda dapat menguji fungsi ini sebagai berikut:

>>> prompts = [
...     [{"role": "user", "content": "What is the result of (1 + 2) * 4?"}],
...     [{"role": "user", "content": "What is the result of (3 + 1) * 2?"}],
... ]
>>> completions = [
...     [{"role": "assistant", "content": "<think>The sum of 1 and 2 is 3, which we multiply by 4 to get 12.</think><answer>(1 + 2) * 4 = 12</answer>"}],
...     [{"role": "assistant", "content": "The sum of 3 and 1 is 4, which we multiply by 2 to get 8. So (3 + 1) * 2 = 8."}],
... ]
>>> format_reward_func(prompts=prompts, completions=completions)
[1.0, 0.0]

Contoh 3: Memberikan imbalan pada penyelesaian berdasarkan referensi

Di bawah ini adalah contoh fungsi reward yang memeriksa apakah penyelesaian benar. Contoh ini terinspirasi dari fungsi accuracy reward yang digunakan dalam makalah DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. Dataset tersebut berisi kolom bernama ground_truth.

import re

def reward_func(completions, ground_truth, **kwargs):
    # Regular expression to capture content inside \boxed{}
    matches = [re.search(r"\\boxed\{(.*?)\}", completion[0]["content"]) for completion in completions]
    contents = [match.group(1) if match else "" for match in matches]
    # Reward 1 if the content is the same as the ground truth, 0 otherwise
    return [1.0 if c == gt else 0.0 for c, gt in zip(contents, ground_truth)]

Anda dapat menguji fungsi ini sebagai berikut:

>>> prompts = [
...     [{"role": "user", "content": "Solve the equation $2x + 3 = 7$."}],
...     [{"role": "user", "content": "Solve the equation $3x - 5 = 10$."}],
... ]
>>> completions = [
...     [{"role": "assistant", "content": r"The solution is \boxed{2}."}],
...     [{"role": "assistant", "content": r"The solution is \boxed{6}."}],
... ]
>>> ground_truth = ["2", "5"]
>>> reward_func(prompts=prompts, completions=completions, ground_truth=ground_truth)
[1.0, 0.0]

Contoh 4: Fungsi reward multi-tugas

Berikut adalah contoh penggunaan beberapa fungsi reward dalam AsyncGRPOTrainer. Dalam contoh ini, kami mendefinisikan dua fungsi reward yang spesifik untuk tugas: math_reward_func dan coding_reward_func. Fungsi math_reward_func memberikan reward untuk soal matematika berdasarkan kebenarannya, sedangkan coding_reward_func memberikan reward untuk soal pemrograman berdasarkan apakah solusinya berfungsi.

from datasets import Dataset
from trl import AsyncGRPOTrainer

# Define a dataset that contains both math and coding problems
dataset = Dataset.from_list(
    [
        {"prompt": [{"role": "user", "content": "What is 2+2?"}], "task": "math"},
        {"prompt": [{"role": "user", "content": "Write a function that returns the sum of two numbers."}], "task": "code"},
        {"prompt": [{"role": "user", "content": "What is 3*4?"}], "task": "math"},
        {"prompt": [{"role": "user", "content": "Write a function that returns the product of two numbers."}], "task": "code"},
    ]
)

# Math-specific reward function
def math_reward_func(prompts, completions, task, **kwargs):
    rewards = []
    for prompt, completion, t in zip(prompts, completions, task):
        if t == "math":
            # Calculate math-specific reward
            correct = check_math_solution(prompt, completion)
            reward = 1.0 if correct else -1.0
            rewards.append(reward)
        else:
            # Return None for non-math tasks
            rewards.append(None)
    return rewards

# Coding-specific reward function
def coding_reward_func(prompts, completions, task, **kwargs):
    rewards = []
    for prompt, completion, t in zip(prompts, completions, task):
        if t == "code":
            # Calculate coding-specific reward
            works = test_code_solution(prompt, completion)
            reward = 1.0 if works else -1.0
            rewards.append(reward)
        else:
            # Return None for non-coding tasks
            rewards.append(None)
    return rewards

# Use both task-specific reward functions
if __name__ == "__main__":
    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen2.5-0.5B-Instruct",
        reward_funcs=[math_reward_func, coding_reward_func],
        train_dataset=dataset,
    )

    trainer.train()

Pada contoh ini, math_reward_func dan coding_reward_func dirancang untuk bekerja dengan dataset campuran yang berisi soal matematika dan pemrograman. Kolom task dalam dataset digunakan untuk menentukan fungsi reward mana yang akan diterapkan pada setiap soal. Jika tidak ada fungsi reward yang relevan untuk sampel dalam dataset, fungsi reward akan mengembalikan None, dan AsyncGRPOTrainer akan melanjutkan dengan fungsi dan tugas yang valid. Hal ini memungkinkan AsyncGRPOTrainer untuk menangani beberapa fungsi reward dengan tingkat penerapan yang berbeda.

Perhatikan bahwa AsyncGRPOTrainer akan mengabaikan reward None yang dikembalikan oleh fungsi reward dan hanya mempertimbangkan reward yang dikembalikan oleh fungsi yang relevan. Hal ini memastikan bahwa model dilatih pada tugas yang relevan dan mengabaikan tugas yang tidak memiliki fungsi reward yang relevan.

Contoh 5: Fungsi reward asinkron

Fungsi reward kustom juga dapat didefinisikan sebagai korutin async def. Hal ini berguna jika reward Anda bergantung pada I/O yang lambat (misalnya, memanggil layanan jarak jauh). Ketika Anda meneruskan beberapa fungsi reward asinkron, AsyncGRPOTrainer akan mengeksekusinya secara bersamaan sehingga latensinya saling tumpang tindih.

Berikut adalah contoh minimal dari fungsi reward asinkron yang mensimulasikan operasi yang terikat I/O:

import asyncio

async def async_reward_func(prompts, completions, **kwargs):
    # Simulate an I/O-bound call (e.g., HTTP request, database lookup)
    await asyncio.sleep(0.01)
    # Simple toy reward: 1.0 if the completion is non-empty, else 0.0
    return [1.0 if completion else 0.0 for completion in completions]

Menyalurkan fungsi reward ke trainer

Untuk menggunakan fungsi reward kustom Anda, berikan ke AsyncGRPOTrainer sebagai berikut:

from trl import AsyncGRPOTrainer

trainer = AsyncGRPOTrainer(
    reward_funcs=reward_func,
    ...,
)

Anda dapat meneruskan beberapa fungsi reward sebagai daftar; daftar ini dapat mencakup fungsi sinkron dan asinkron:

from trl import AsyncGRPOTrainer

trainer = AsyncGRPOTrainer(
    reward_funcs=[reward_func, async_reward_func1, async_reward_func2],
    ...,
)

dan hadiah akan dihitung sebagai jumlah dari hadiah dari setiap fungsi.

Menyesuaikan loop rollout

Generation, rewards, advantages, dan filtering dijalankan dalam proses rollout, di AsyncRolloutLoop. Untuk mengubah salah satunya, subclass loop tersebut, override metode untuk langkah tersebut, dan set subclass sebagai loop_cls pada subclass trainer. Konstruktor trainer tidak berubah.

MetodeDipanggilDefault
filter_prompt(row_index, row, epoch)sekali per prompt, sebelum generasimenerima setiap prompt
generate_one(prompt, tools, group_id)satu kali per rolloutloop alat multi-putar
generate_one_turn(prompt_ids)sekali per permintaan samplingsatu permintaan vLLM dengan pengaturan sampling dari konfigurasi
compute_advantages(group)satu kali per grup, setelah reward dijumlahkan ke dalam group.rewardsreward yang distandardisasi dalam kelompok
setup(), close()ketika loop dimulai dan dihentikannothing

Sebagai contoh, kurikulum yang menghentikan pengambilan sampel prompt yang sudah dipecahkan oleh kebijakan, dengan ambangnya di dalam subkelas konfigurasi:

from dataclasses import dataclass

import numpy as np

from trl import AsyncGRPOConfig, AsyncGRPOTrainer
from trl.trainer.async_grpo_trainer import 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

Reward dijumlahkan dari reward_funcs, lingkungan yang mendefinisikan get_reward, dan reward yang diset oleh generate_one kustom pada Rollout-nya: untuk menilai dengan judge, berikan fungsi reward asinkron, atau nilai di dalam generate_one. compute_advantages dijalankan untuk setiap grup, termasuk grup yang kemudian dibuang karena semua reward yang dinilai padanya sama; proses pembuangan ini melihat reward, bukan advantage. Loop dibangun di dalam proses yang di-spawn, jadi definisikan subclass di level modul dan simpan kode pelatihan di bawah if __name__ == "__main__":. Buat klien di setup, yang dijalankan di event loop milik loop tersebut, alih-alih menimpa __init__. Prompt yang ditolak oleh filter_prompt dilewati untuk epoch tersebut dan tetap dihitung ke dalamnya, seperti halnya grup yang dibuang. Jika semua prompt pada suatu epoch ditolak, loop akan melempar error.

Melanjutkan dari checkpoint

Trainer dasar melanjutkan dengan melewati dan memutar ulang batch yang sudah dilatih, yang tidak berlaku untuk antrean rollout langsung, sehingga ignore_data_skip selalu True. Sebagai gantinya, indeks prompt pertama yang belum dilatih disimpan ke rollout_state.json bersama setiap checkpoint dan dipulihkan saat melanjutkan, sehingga worker maju cepat ke prompt tersebut tanpa memutar ulang sampel. Ini adalah posisi trained, bukan posisi generator: worker berjalan di depan pelatihan sebesar kedalaman antrean rollout, dan sampel yang dibuffer tersebut hilang ketika run berakhir, sehingga melanjutkan dari posisi generator akan melewati prompt yang sudah dihasilkan tetapi tidak pernah dilatih. Dataset streaming (IterableDataset) tidak dapat diposisikan ulang, sehingga worker-nya dimulai ulang dari prompt pertama saat melanjutkan.

Pelatihan Agen

Asynchronous GRPO mendukung pelatihan agen: model memanggil alat selama generasi dan belajar dari hasilnya.

  • tool adalah fungsi Python polos (sinkron atau asinkron) yang diekspos ke model. Gunakan tools untuk panggilan tanpa status (kalkulator, pencarian web).
  • Environment adalah bentuk yang lebih umum: objek berstatus yang dibuat baru untuk setiap rollout, di mana metode publiknya diekspos sebagai tools, ditambah hook siklus hidup reset dan get_reward opsional yang memungkinkannya memiliki reward. Gunakan environment_factory ketika Anda membutuhkan status per-rollout, hook reset, atau reward yang dimiliki oleh environment.

Mereka dapat dikomposisikan — Anda dapat meneruskan tools mandiri bersama dengan environment_factory.

Alat

Argumen tools mengharapkan daftar fungsi Python (sinkron atau asinkron) yang mendefinisikan alat yang tersedia untuk agen:

from trl import AsyncGRPOTrainer

trainer = AsyncGRPOTrainer(
    tools=[tool1, tool2],
    ...,
)

Setiap tool harus berupa fungsi Python standar dengan argumen dan tipe pengembalian yang diberi type-hint, serta docstring bergaya Google yang menjelaskan tujuannya, argumennya, dan nilai pengembaliannya. Untuk detail lebih lanjut, lihat panduan Passing tools.

Model memanggil alat berdasarkan namanya, sehingga setiap alat didaftarkan di bawah __name__ dan harus berupa fungsi level modul, yang juga menjaganya agar dapat di-pickle untuk worker rollout. Alat sinkron dijalankan pada thread pool yang ukurannya disesuaikan dengan max_concurrent_rollouts, sehingga alat yang lambat tidak akan memblokir rollout lain yang sedang berjalan. Dalam satu giliran asisten, pemanggilan alat dijalankan sesuai urutan yang dikeluarkan oleh model. Oleh karena itu, hingga max_concurrent_rollouts alat sinkron dapat berjalan secara bersamaan, sehingga alat yang membaca atau menulis keadaan bersama harus thread-safe.

Loop panggilan alat memerlukan template obrolan yang menjaga prefiks (menambahkan pesan alat tidak boleh mengubah cara pesan sebelumnya dirender). Untuk keluarga model yang dikenal (misalnya Qwen3, DeepSeek-V3), TRL secara otomatis mengganti dengan template pelatihan yang telah diperbaiki ketika alat diaktifkan. Lihat Template Obrolan untuk daftar lengkap.

Gunakan max_tool_calling_iterations di AsyncGRPOConfig untuk membatasi jumlah giliran pemanggilan alat. Secara default tidak ada batas, dan generasi berhenti ketika model menghasilkan giliran respons tanpa pemanggilan alat.

Contoh:

from trl import AsyncGRPOTrainer

def multiply(a: int, b: int) -> int:
    """
    Multiplies two integers.

    Args:
        a: The first integer.
        b: The second integer.

    Returns:
        The product of the two integers.
    """
    return a * b

async def async_add(a: int, b: int) -> int:
    """
    Asynchronously adds two integers.

    Args:
        a: The first integer.
        b: The second integer.

    Returns:
        The sum of the two integers.
    """
    return a + b

trainer = AsyncGRPOTrainer(
    tools=[multiply, async_add],
    ...,
)

Lingkungan

Anda juga dapat menyediakan alat melalui environment_factory. Dalam mode ini, AsyncGRPOTrainer membuat satu instance lingkungan per rollout dan mengekspos metode publik lingkungan sebagai alat.

Saat Anda menggunakan environment_factory, lingkungan memiliki data: tidak ada train_dataset eksternal. Pada setiap rollout, reset() menghasilkan tugas — pengambilan sampel mandiri dari korpus yang dimiliki lingkungan, atau menghasilkan state secara prosedural — dan mengembalikan prompt. max_steps mengatur panjang pelatihan. Berikut adalah contoh minimal dari lingkungan yang mengambil sampel target secara mandiri dan mengekspos metode increment (diekspos sebagai tool).

import random

from trl import AsyncGRPOConfig, AsyncGRPOTrainer

class IncrementEnv:
    # Reserved methods
    def reset(self, **kwargs) -> str | None:  # required; called at the start of each rollout
        self.counter = 0
        self.target = random.randint(1, 6)  # self-sample the task
        return f"Increment the counter by {self.target}."  # returned string becomes the prompt

    def get_reward(self) -> float:  # optional: the environment scores itself from its own state
        return float(self.counter == self.target)

    # Public methods (exposed as tools)
    def increment(self, step: int) -> int:
        """
        Increment the internal counter.

        Args:
            step: Value to add to the counter.

        Returns:
            The updated counter value.
        """
        self.counter += step
        return self.counter

if __name__ == "__main__":
    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen3-0.6B",
        args=AsyncGRPOConfig(max_steps=1000, chat_template_kwargs={"enable_thinking": False}),
        environment_factory=IncrementEnv,
    )
    trainer.train()

Kelas lingkungan memiliki dua metode cadangan: reset dan get_reward. Berbeda dengan metode publik lainnya, metode-metode ini tidak diungkapkan ke model sebagai alat.

  • reset (wajib) dipanggil saat rollout dimulai. Metode ini dapat mengembalikan None atau sebuah string. Jika mengembalikan string, string tersebut adalah prompt pengguna.
  • get_reward (opsional, sinkron atau asinkron) tidak menerima argumen dan mengembalikan float: lingkungan memberikan skor pada episode yang baru saja dijalankan berdasarkan status internalnya sendiri (apakah permainan berakhir dengan kemenangan? apakah kata tersebut berhasil ditebak?). Fungsi ini dipanggil sekali untuk setiap rollout yang selesai dan berfungsi sebagai sumber reward.

Keduanya berjalan di pool thread tool worker, sehingga lingkungan yang lambat hanya menunda rollout-nya sendiri, bukan rollout lain yang sedang berjalan. Durasi keduanya dicatat sebagai env/reset_s dan env/reward_s.

Karena lingkungan melakukan pengambilan sampel mandiri pada setiap reset(), anggota G dari sebuah grup GRPO mungkin tidak berbagi keadaan awal yang sama, sehingga membuat baseline grup menjadi sedikit lebih bising. Untuk keadaan yang identik di dalam sebuah grup, pastikan reset() menurunkan keadaan secara deterministik dari kunci bersama.

Menyediakan dataset eksternal (opsional)

Alih-alih membiarkan lingkungan melakukan pengambilan sampel mandiri, Anda dapat menyediakan train_dataset eksternal. Misalnya, ketika tugas Anda sudah ada dalam dataset, atau untuk mengalihkan rute antara beberapa lingkungan. Per rollout, trainer mengambil sampel satu baris, menggunakan kolom "prompt" baris tersebut sebagai prompt, dan meneruskan kolom baris ke reset() sebagai argumen kata kunci (sehingga lingkungan membaca tugas dari dataset).

from datasets import Dataset
from trl import AsyncGRPOTrainer

# Each row carries the prompt and the task data (here, the counter target to reach).
dataset = Dataset.from_dict(
    {
        "prompt": [[{"role": "user", "content": f"Increment the counter to {i}."}] for i in range(1, 7)],
        "target": list(range(1, 7)),
    }
)

class IncrementEnv:
    def reset(self, target, **kwargs) -> None:  # the row's `target` column arrives as a keyword argument
        self.counter = 0
        self.target = target

    def get_reward(self) -> float:
        return float(self.counter == self.target)

    def increment(self, step: int) -> int:  # exposed as a tool (see the full docstring above)
        self.counter += step
        return self.counter

if __name__ == "__main__":
    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen3-0.6B",
        train_dataset=dataset,  # the dataset owns the task; the "target" column reaches reset(target=...)
        environment_factory=IncrementEnv,
    )
    trainer.train()

Hadiah

Reward yang dimiliki environment dan reward yang dimiliki trainer tidak bersifat eksklusif. Sampaikan reward_funcs untuk reward yang wajar dihitung dari completion (misalnya pemeriksaan format pada teks) dan biarkan environment mengembalikan reward yang bergantung pada state-nya melalui get_reward. Semua sumber dijumlahkan dengan bobot 1.

def format_reward(completions, **kwargs):  # trainer-owned: scores the completion text
    ...

trainer = AsyncGRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    args=AsyncGRPOConfig(max_steps=1000),
    reward_funcs=format_reward,          # trainer-owned: scores the completion
    environment_factory=IncrementEnv,    # env-owned: scores its internal state via `get_reward`
)

Lingkungan yang beragam

Untuk melatih pada campuran tugas dalam satu eksekusi (misalnya tugas pemrograman dan permainan), teruskan kamus yang memetakan nama lingkungan ke pabrik, bukan satu callable. Setiap rollout memilih lingkungannya melalui kolom environment dalam dataset, dan hanya alat dari lingkungan tersebut yang diekspos. Hal ini mencegah kebocoran alat yang tidak relevan (alat move dari permainan ke contoh pemrograman, dan sebaliknya). Setiap lingkungan tetap memiliki datanya sendiri dan mengembalikan prompt dari reset(), sehingga dataset hanya membutuhkan kolom environment untuk merutekan di antara mereka.

import random

from datasets import Dataset
from trl import AsyncGRPOConfig, AsyncGRPOTrainer


class CodingEnv:
    def reset(self, **kwargs) -> str:
        n = random.randint(1, 20)
        return f"Compute the {n}th Fibonacci number."

    def run_code(self, code: str) -> str:  # exposed as a tool only for "coding" examples
        """Run the given Python code and return its stdout.

        Args:
            code: The Python source to execute.

        Returns:
            The captured standard output.
        """
        ...

class GameEnv:
    def reset(self, **kwargs) -> str:
        return "Reach the goal tile."

    def move(self, action: str) -> str:  # exposed as a tool only for "game" examples
        """Apply an action to the game and return the new observation.

        Args:
            action: One of "up", "down", "left", "right".

        Returns:
            The observation after the move.
        """
        ...

# The dataset only routes: each row picks the environment for that rollout
if __name__ == "__main__":
    dataset = Dataset.from_dict({"environment": ["coding", "game"] * 500})

    trainer = AsyncGRPOTrainer(
        model="Qwen/Qwen3-0.6B",
        args=AsyncGRPOConfig(chat_template_kwargs={"enable_thinking": False}),
        train_dataset=dataset,
        reward_funcs=reward_func,
        environment_factory={"coding": CodingEnv, "game": GameEnv},
    )
    trainer.train()

Instans lingkungan digunakan kembali di antara langkah-langkah (di-reset di antara episode), sehingga __init__ yang mahal hanya dibayar sekali, bukan di setiap langkah. Field environment dikonsumsi oleh trainer dan tidak diteruskan ke reset.

Rollout multi-turn

Setiap giliran merender seluruh percakapan melalui template chat dan menghasilkan darinya. Template chat tidak selalu merender percakapan yang berkembang dengan cara yang sama (misalnya, beberapa membuang penalaran dari giliran sebelumnya), sehingga token prompt dari sebuah giliran dapat berbeda dari token yang telah disimpan sejauh ini. Pada akhir rollout, worker menyelaraskan giliran-giliran tersebut menjadi sampel pelatihan: giliran yang prompt-nya dimulai dengan token yang disimpan akan ditambahkan ke sampel yang sama, dan giliran lainnya memulai sampel baru. Setiap token yang dihasilkan dilatih tepat dalam satu sampel, sehingga percabangan (fork) menimbulkan biaya token forward tetapi tidak memberikan sinyal pelatihan.

Setiap sampel dari rollout menerima keuntungan dari rollout tersebut. rollout/fork_frac dan rollout/drift_tokens_* menunjukkan bagaimana giliran-giliran tersebut diselaraskan.

Integrasi Lingkungan

Untuk melatih agen yang berjalan di dalam harness mereka sendiri, seperti agen coding di sandbox Harbor, lihat Melatih di harness di panduan OpenEnv.

Pelatihan Model Bahasa Visual

Model vision-language (Qwen3.5, Qwen3.6, Qwen3-VL, …) dapat dilatih pada dataset hanya teks. Lewatkan model id seperti biasa; tidak ada perubahan lain.

Tower visi dibekukan. Dataset teks murni tidak pernah menghasilkan token gambar, sehingga tower tidak pernah dijalankan oleh forward pass. Semua di luar model teks (tower visi, proyektor multimodal) memiliki requires_grad=False: tidak menerima gradien maupun state optimizer, dan sinkronisasi bobot melewatinya, sehingga server mempertahankan nilai yang dimuat dari checkpoint. Tower tetap dimuat, sehingga memakan memori GPU untuk bobotnya.

Image belum didukung. Prompt yang berisi image tidak diteruskan ke server vLLM maupun ke forward pass pelatihan. Pelatihan multimodal juga memerlukan jalur packing tanpa padding untuk membangun posisi M-RoPE 3D dari grid image, yang belum diimplementasikan di sini.

AsyncGRPOTrainer

kelas trl.AsyncGRPOTrainer

< >

( model: str | PreTrainedModelreward_funcs: collections.abc.Callable[..., list[float]] | list[collections.abc.Callable[..., list[float]]] | None = Noneargs: trl.trainer.async_grpo_config.AsyncGRPOConfig | None = Nonetrain_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = Noneprocessing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | None = Nonecallbacks: list[transformers.trainer_callback.TrainerCallback] | None = Noneoptimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None)peft_config: PeftConfig | None = Nonetools: list[collections.abc.Callable] | None = Noneenvironment_factory: collections.abc.Callable[[], trl.trainer.async_grpo_trainer._SupportsReset] | dict[str, collections.abc.Callable[[], trl.trainer.async_grpo_trainer._SupportsReset]] | None = None )

Parameter

  • model (str atau PreTrainedModel) — Model yang akan dilatih. Bisa berupa:
    • String, berupa model id dari model pretrained yang dihosting di dalam repo model di huggingface.co, atau path ke directory yang berisi bobot model yang disimpan menggunakan save_pretrained, misalnya './my_model_directory/'. Model dimuat dengan arsitektur yang dideklarasikan di config-nya: AutoModelForImageTextToText untuk checkpoint vision-language (di mana vision tower dimuat tetapi dibekukan, lihat Training Vision Language Models), AutoModelForCausalLM jika tidak.
    • Objek PreTrainedModel. Implementasi atensinya diganti menjadi backend atensi pohon dari trainer untuk pelatihan yang dikemas.

    Nama model dari config digunakan untuk mengidentifikasi model pada server vLLM yang digunakan untuk generasi.

  • reward_funcs (RewardFunc | list[RewardFunc], opsional) — Fungsi reward yang akan digunakan untuk menghitung reward. Untuk menghitung reward, kami memanggil semua fungsi reward dengan prompt dan completion, lalu menjumlahkan reward-nya. Dapat diabaikan ketika reward disediakan oleh lingkungan melalui environment_factory (lihat di bawah). Bisa berupa:
    • Satu fungsi reward: Fungsi ini diberikan prompt dan kelengkapan yang dihasilkan, serta kolom tambahan apa pun dalam dataset. Fungsi ini harus mengembalikan daftar reward. Fungsi reward dapat bersifat sinkron atau asinkron, dan juga dapat mengembalikan None ketika reward tidak berlaku untuk sampel tersebut. Hal ini berguna untuk pelatihan multi-tugas di mana fungsi reward yang berbeda berlaku untuk jenis sampel yang berbeda. Ketika fungsi reward mengembalikan None untuk suatu sampel, fungsi reward tersebut dikecualikan dari perhitungan reward untuk sampel tersebut. Untuk detail lebih lanjut, lihat Menggunakan fungsi reward kustom.
    • Daftar fungsi reward, di mana setiap item adalah fungsi reward seperti yang dijelaskan di atas. Reward dari semua fungsi dijumlahkan.

    Berbeda dengan GRPOTrainer, reward dihitung dalam proses anak yang di-spawn, sehingga setiap fungsi reward (bersama dengan tools dan environment_factory) harus dapat di-pickle: gunakan fungsi tingkat modul, functools.partial, atau instance kelas yang callable — lambda dan closure akan gagal saat startup. Tools didaftarkan berdasarkan __name__ mereka, sehingga harus berupa fungsi tingkat modul. Proses anak juga dijalankan dengan CUDA_VISIBLE_DEVICES="", sehingga model reward berbasis GPU berjalan di CPU (lambat), bukan di GPU trainer.

  • args (AsyncGRPOConfig, opsional) — Konfigurasi untuk trainer ini. Jika None, konfigurasi default akan digunakan.
  • train_dataset (Dataset atau IterableDataset, opsional) — Dataset yang digunakan untuk pelatihan. Dataset ini harus menyertakan kolom "prompt". Kolom tambahan lainnya dalam dataset akan diabaikan. Sampel harus dalam format percakapan : setiap sampel berisi pesan terstruktur (misalnya, role dan content).

    Dapat diabaikan hanya ketika environment_factory disediakan dan lingkungan memiliki (atau menghasilkan secara prosedural) data, dengan mengembalikan prompt dari metode reset()-nya. Dalam kasus tersebut, max_steps harus diatur untuk menentukan panjang pelatihan.

  • processing_class (PreTrainedTokenizerBase, opsional) — Kelas pemrosesan yang digunakan untuk memproses data. Sisi padding harus diatur ke “left”. Jika None, kelas pemrosesan dimuat dari nama model dengan from_pretrained. Token padding, tokenizer.pad_token, harus diatur. Jika kelas pemrosesan belum mengatur token padding, tokenizer.eos_token akan digunakan sebagai default.
  • callbacks (daftar TrainerCallback, opsional) — Daftar callback untuk menyesuaikan loop pelatihan. Callback ini akan ditambahkan ke daftar callback default yang dijelaskan di sini.

    Jika Anda ingin menghapus salah satu callback default yang digunakan, gunakan metode remove_callback.

  • optimizers (tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None], opsional, defaultnya (None, None)) — Tuple yang berisi optimizer dan scheduler yang akan digunakan. Secara default akan menggunakan instance AdamW pada model Anda dan scheduler yang diberikan oleh get_linear_schedule_with_warmup yang dikendalikan oleh args.
  • peft_config (PeftConfig, opsional) — Konfigurasi PEFT yang digunakan untuk membungkus model. Jika None, model tidak dibungkus. Ketika server vLLM dimulai dengan --enable-lora, adapter LoRA disinkronkan ke server tersebut sebagai adapter, bukan sebagai bobot yang digabungkan; lihat bagian LoRA dari dokumentasi AsyncGRPO.
  • tools (list of Callable, opsional) — Daftar fungsi tool yang dapat dipanggil (sinkron atau asinkron) yang dapat diaktifkan oleh model selama proses generasi. Setiap tool harus berupa fungsi Python standar dengan argumen dan nilai return yang diberi type hint dengan benar, serta docstring bergaya Google yang menjelaskan tujuannya, argumennya, dan nilai return-nya. Untuk detail lebih lanjut, lihat: https://huggingface.co/docs/transformers/en/chat_extras#passing-tools. Model menggunakan nama fungsi, type hints, dan docstring untuk menentukan cara memanggilnya. Pastikan bahwa chat template model mendukung penggunaan tool dan bahwa model tersebut telah di-fine-tune untuk tool calling.
  • environment_factory (EnvironmentFactory atau dict[str, EnvironmentFactory], opsional) — Callable yang membuat dan mengembalikan instance environment, atau kamus yang memetakan nama environment ke callable semacam itu. Kelas environment harus mendefinisikan metode yang dapat dipanggil sebagai tools selama generation. Setiap metode harus mematuhi persyaratan yang sama dengan tools yang dijelaskan di atas. Environment juga harus mengimplementasikan metode callable reset yang dapat digunakan untuk mereset state antar generation. Metode reset seharusnya mengembalikan None atau string: ketika mengembalikan string, string tersebut ditambahkan ke pesan user terakhir sebelum generation. Environment juga dapat mendefinisikan metode get_reward yang tidak mengambil argumen dan mengembalikan float: ketika ada, environment memiliki reward, dan get_reward dipanggil sekali per rollout yang selesai untuk memberikan skor berdasarkan state internal environment. Ini berfungsi sebagai sumber reward tambahan (dengan bobot 1, dicatat di bawah nama kelas environment) di samping reward_funcs, yang kemudian menjadi opsional.

    Dengan satu callable, setiap contoh menggunakan lingkungan yang sama, dengan satu instance per rollout sehingga interaksi mereka tetap terisolasi. Dengan dictionary, setiap contoh harus memiliki field environment yang memilih lingkungannya berdasarkan nama, dan hanya tool dari lingkungan tersebut yang diekspos di prompt-nya — memungkinkan satu run mencampur tugas (misalnya lingkungan coding dan game). Fitur ini bersifat eksperimental dan dapat berubah atau dihapus kapan saja tanpa pemberitahuan sebelumnya.

Trainer untuk metode Group Relative Policy Optimization (GRPO). Algoritma ini pertama kali diusulkan dalam makalah DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models. Trainer ini adalah versi asinkron dari GRPO, di mana generasi dialihkan ke server vLLM eksternal yang berjalan secara asinkron bersamaan dengan pelatihan, sehingga memisahkan rollout dari loop pembaruan gradien.

Contoh:

>>> from trl 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()

Untuk menyesuaikan prompt mana yang disampelkan, bagaimana rollout dihasilkan, atau bagaimana keuntungan dihitung, subclass AsyncRolloutLoop dan atur sebagai loop_cls trainer. TRL membangun loop di

proses rollout:

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

latih

< >

( resume_from_checkpoint: str | bool | None = Nonetrial: optuna.Trial | dict[str, Any] | None = Noneignore_keys_for_eval: list[str] | None = None ) → ~trainer_utils.TrainOutput

Parameter

  • resume_from_checkpoint (str atau bool, opsional) — Jika berupa str, jalur lokal ke checkpoint yang disimpan oleh instance Trainer sebelumnya. Jika berupa bool dan bernilai True, muat checkpoint terakhir di args.output_dir yang disimpan oleh instance Trainer sebelumnya. Jika ada, pelatihan akan dilanjutkan dari status model/optimizer/scheduler yang dimuat di sini.
  • trial (optuna.Trial atau dict[str, Any], opsional) — Jalankan trial atau kamus hiperparameter untuk pencarian hiperparameter.
  • ignore_keys_for_eval (list[str], opsional) — Daftar kunci dalam output model Anda (jika berupa dictionary) yang harus diabaikan saat mengumpulkan prediksi untuk evaluasi selama pelatihan.

Mengembalikan

~trainer_utils.TrainOutput

Objek yang berisi jumlah langkah global, kerugian pelatihan, dan metrik.

Titik masuk utama pelatihan.

save_model

< >

( output_dir: str | None = None_internal_call: bool = False )

Akan menyimpan model, sehingga Anda dapat memuatnya kembali menggunakan from_pretrained().

Hanya akan menyimpan dari proses utama.

push_to_hub

< >

( commit_message: str | None = 'End of training'blocking: bool = Truetoken: str | None = Nonerevision: str | None = Noneprivate: bool | None = None**kwargs )

Parameter

  • commit_message (str, opsional, default "End of training") — Pesan untuk commit saat melakukan push.
  • blocking (bool, opsional, default True) — Apakah fungsi harus hanya mengembalikan nilai setelah git push selesai.
  • token (str, opsional, defaultnya None) — Token dengan izin tulis untuk menimpa argumen asli Trainer.
  • revision (str, opsional) — Revisi git untuk di-commit. Secara default menggunakan head dari branch “main”.
  • private (bool, opsional) — Apakah membuat repo menjadi privat saat dibuat. Defaultnya adalah args.hub_private_repo. Tidak berpengaruh jika repo sudah ada.
  • kwargs (dict[str, Any], opsional) — Argumen kata kunci tambahan yang diteruskan ke ~Trainer.create_model_card.

Unggah self.model dan self.processing_class ke 🤗 model hub di repo self.args.hub_model_id.

AsyncGRPOConfig

kelas trl.AsyncGRPOConfig

< >

( output_dir: str | None = Noneper_device_train_batch_size: int = 8num_train_epochs: float = 3.0max_steps: int = -1learning_rate: float = 1e-06lr_scheduler_type: str = 'constant'lr_scheduler_kwargs: dict | str | None = Nonewarmup_steps: float = 0optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused'optim_args: str | None = Noneweight_decay: float = 0.0adam_beta1: float = 0.9adam_beta2: float = 0.999adam_epsilon: float = 1e-08optim_target_modules: None | str | list[str] = Nonegradient_accumulation_steps: int = 1average_tokens_across_devices: bool = Truemax_grad_norm: float = 1.0label_smoothing_factor: float = 0.0bf16: bool | None = Nonefp16: bool = Falsebf16_full_eval: bool = Falsefp16_full_eval: bool = Falsetf32: bool | None = Noneactivation_checkpointing: bool | None = Noneactivation_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonegradient_checkpointing: bool = Truegradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = Nonetorch_compile: bool = Falsetorch_compile_backend: str | None = Nonetorch_compile_mode: str | None = Noneuse_liger_kernel: bool = Falseliger_kernel_config: dict[str, bool] | None = Noneuse_cache: bool = Falseneftune_noise_alpha: float | None = Nonetorch_empty_cache_steps: int | None = Noneauto_find_batch_size: bool = Falselogging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps'logging_steps: float = 1logging_first_step: bool = Falselog_on_each_node: bool = Truelogging_nan_inf_filter: bool = Trueinclude_num_input_tokens_seen: str | bool = 'no'log_level: str = 'passive'log_level_replica: str = 'warning'disable_tqdm: bool | None = Nonereport_to: None | str | list[str] = 'none'run_name: str | None = Noneproject: str = 'huggingface'trackio_space_id: str | None = Nonetrackio_bucket_id: str | None = Nonetrackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = Noneeval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no'eval_steps: float | None = Noneeval_delay: float = 0per_device_eval_batch_size: int = 8prediction_loss_only: bool = Falseeval_on_start: bool = Falseeval_do_concat_batches: bool = Trueeval_use_gather_object: bool = Falseeval_accumulation_steps: int | None = Noneinclude_for_metrics: list[str] = <factory>batch_eval_metrics: bool = Falsesave_only_model: bool = Falsesave_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps'save_steps: float = 500save_on_each_node: bool = Falsesave_total_limit: int | None = Noneenable_jit_checkpoint: bool = Falsepush_to_hub: bool = Falsehub_token: str | None = Nonehub_private_repo: bool | None = Nonehub_model_id: str | None = Nonehub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save'hub_always_push: bool = Falsehub_revision: str | None = Noneload_best_model_at_end: bool = Falsemetric_for_best_model: str | None = Nonegreater_is_better: bool | None = Noneignore_data_skip: bool = Truerestore_callback_states_from_checkpoint: bool = Falsefull_determinism: bool = Falseseed: int = 42data_seed: int | None = Noneuse_cpu: bool = Falseaccelerator_config: dict | str | None = Noneparallelism_config: accelerate.parallelism_config.ParallelismConfig | None = Nonedataloader_drop_last: bool = Falsedataloader_num_workers: int = 0dataloader_pin_memory: bool = Truedataloader_persistent_workers: bool = Falsedataloader_prefetch_factor: int | None = Nonedataloader_multiprocessing_context: str | None = Nonedataloader_in_order: bool = Trueremove_unused_columns: bool = Falselabel_names: list[str] | None = Nonetrain_sampling_strategy: str = 'random'length_column_name: str = 'length'ddp_find_unused_parameters: bool | None = Noneddp_bucket_cap_mb: int | None = Noneddp_broadcast_buffers: bool | None = Noneddp_static_graph: bool | None = Noneddp_backend: str | None = Noneddp_timeout: int = 1800fsdp: str | None = Nonefsdp_config: dict[str, typing.Any] | str | None = Nonedeepspeed: dict | str | None = Nonedebug: str | list[transformers.debug_utils.DebugOption] = ''skip_memory_metrics: bool = Truedo_train: bool = Falsedo_eval: bool = Falsedo_predict: bool = Falseresume_from_checkpoint: str | None = Nonelocal_rank: int = -1model_init_kwargs: dict[str, typing.Any] | str | None = Nonedtype: str = 'float32'trust_remote_code: bool = Falserouter_aux_loss_coef: float | None = Nonenum_generations: int = 8max_completion_length: int = 2048temperature: float = 1.0top_p: float = 1.0top_k: int = 0min_p: float | None = Nonechat_template_kwargs: dict | str | None = Nonemax_tool_calling_iterations: int | None = Nonevllm_server_base_url: str = 'http://localhost:8000'vllm_server_timeout: float = 1800.0epsilon: float = 0.2epsilon_high: float | None = Nonescore_centering: bool = Truevllm_importance_sampling_clip_min: float = 0.5vllm_importance_sampling_clip_max: float = 5.0num_sampler_logprobs: int = 8token_budget: int | None = Nonemax_concurrent_rollouts: int = 512max_staleness: int = 4weight_sync_steps: int = 1rollout_worker_timeout: float = 300.0log_completions: bool = Falsenum_completions_to_print: int | None = None )

Parameter yang mengontrol model

  • model_init_kwargs (dict[str, Any] atau str, opsional) — Argumen kata kunci untuk from_pretrained, digunakan saat menginstansiasi model dari sebuah path. Nilai revision juga digunakan saat memuat kelas pemrosesan.
  • dtype (str, opsional, defaultnya "float32") — Tipe data untuk memuat model, salah satu dari "auto", "bfloat16", "float16" atau "float32". Defaultnya adalah "float32" karena ketidakcocokan pelatihan-inferensi yang menjadi acuan trainer ini (Defeating the Training-Inference Mismatch via FP16) sangat sensitif terhadap presisi trainer itu sendiri. Menutup celah tersebut secara end-to-end juga memerlukan penyajian server vLLM dalam dtype yang sama (vllm serve --dtype); ketidakcocokan akan dicatat sebagai peringatan saat pelatihan dimulai. Sebuah dtype di dalam model_init_kwargs memiliki prioritas.

    Ini hanya mengatur dtype tempat bobot dimuat. Di bawah FSDP dengan presisi campuran (bf16=True adalah default), accelerate menaikkan setiap parameter yang dapat dilatih ke fp32 sebelum sharding, sehingga bobot master dan state optimizer adalah fp32 apa pun yang dikatakan dtype, sementara forward dan backward berjalan dalam bf16 atau fp16. Checkpoint kemudian ditulis dalam dtype presisi campuran tersebut, bukan dalam fp32. Tanpa FSDP, tidak ada yang menaikkan: dtype="bfloat16" dengan bf16=True mempertahankan bobot dan state optimizer dalam bf16, yang merupakan pelatihan bf16 murni.

  • trust_remote_code (bool, opsional, default False) — Apakah mengizinkan pemuatan model dan tokenizer yang menyertakan kode Python kustom dari Hub. Diteruskan ke from_pretrained dan from_pretrained.
  • router_aux_loss_coef (float, opsional) — Koefisien dari loss tambahan penyeimbangan beban untuk model Mixture-of-Experts (MoE), yang ditambahkan ke loss pelatihan dengan bobot ini. Jika tidak diatur, nilai yang dideklarasikan oleh konfigurasi model akan digunakan. Atur ke 0.0 untuk menonaktifkannya. Gagal jika digunakan dengan model non-MoE.

Parameter yang mengontrol generasi

  • num_generations (int, opsional, default 8) — Jumlah generasi per prompt yang akan disampel.
  • max_completion_length (int, opsional, default 2048) — Jumlah maksimum token yang dihasilkan per permintaan vLLM, sehingga per giliran dalam rollout multi-giliran.
  • temperature (float, opsional, default 1.0) — Suhu untuk sampling. Semakin tinggi suhu, semakin acak hasil pelengkapannya.
  • top_p (float, opsional, default 1.0) — Float yang mengontrol probabilitas kumulatif dari token teratas yang dipertimbangkan. Harus berada dalam rentang (0, 1]. Atur ke 1.0 untuk mempertimbangkan semua token. Di bawah 1.0, top_k juga harus diatur, dan server vLLM (>= 0.28) harus dimulai dengan --return-sampling-mask --enable-scale-out: trainer akan menormalisasi ulang log-probabilitasnya di atas himpunan kandidat tempat setiap token diambil, sama seperti yang dilakukan server. vLLM versi lama mempertahankan seluruh kosakata.
  • top_k (int, opsional, default 0) — Jumlah token kosakata dengan probabilitas tertinggi yang dipertahankan untuk top-k-filtering. Jika 0, top-k-filtering dinonaktifkan dan semua token dipertimbangkan. Nilai lain memerlukan flag server yang dijelaskan di bawah top_p.
  • min_p (float, opsional) — Probabilitas token minimum, yang akan diskalakan oleh probabilitas token yang paling mungkin. Nilainya harus berada di antara 0.0 dan 1.0. Nilai tipikal berada dalam rentang 0.01-0.2. Di atas 0.0, top_k juga harus diatur, dengan flag server yang dijelaskan di bawah top_p.
  • chat_template_kwargs (dict[str, Any], opsional) — Argumen kata kunci tambahan untuk diteruskan ke fungsi apply_chat_template saat menghasilkan kelengkapan.
  • max_tool_calling_iterations (int, opsional) — Jumlah maksimum giliran pemanggilan alat saat melatih agen. Jika None, tidak ada batas dan generasi berhenti ketika model menghasilkan giliran respons tanpa pemanggilan alat.

Parameter yang mengontrol server vLLM

  • vllm_server_base_url (str, opsional, defaultnya "http --//localhost:8000"): URL dasar dari server vLLM yang digunakan untuk generasi (misalnya, "http://localhost:8000").
  • vllm_server_timeout (float, opsional, default 1800.0) — Timeout dalam detik untuk panggilan ke server vLLM: menunggu server siap saat startup, setiap permintaan generasi, dan setiap panggilan sinkronisasi bobot. Menunggu server dan panggilan sinkronisasi bobot akan mengangkat error jika waktu habis; permintaan generasi yang melebihi timeout akan dicoba ulang.

Parameter yang mengontrol pelatihan

  • epsilon (float, opsional, default 0.2) — Nilai epsilon untuk clipping.
  • epsilon_high (float, opsional) — Nilai epsilon batas atas untuk clipping. Jika tidak ditentukan, nilainya secara default sama dengan nilai batas bawah yang ditentukan dalam argumen epsilon. Kertas DAPO merekomendasikan 0.28.
  • score_centering (bool, opsional, default True) — Apakah akan melatih dengan score centering (paper) alih-alih tujuan yang dipangkas: skor berbobot kepentingan dari setiap token yang disampel dikurangi harapannya di bawah sampler vLLM, sehingga keuntungan konstan tidak menarik kebijakan ke arah sampler. Harapan diambil atas num_sampler_logprobs token yang paling mungkin di setiap posisi, yang log-probabilitasnya dilaporkan oleh sampler.
  • vllm_importance_sampling_clip_min (float, opsional, default 0.5) — Batas bawah C_min dari rasio importance antara policy dan sampler vLLM. Token yang rasionya berada di luar [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] akan dihapus dari loss (masked importance sampling).
  • vllm_importance_sampling_clip_max (float, opsional, default 5.0) — Batas atas C_max dari rasio importance.
  • num_sampler_logprobs (int, opsional, default 8) — Jumlah log-probabilitas teratas yang diminta dari vLLM sampler untuk setiap token yang dihasilkan, digunakan oleh score centering. Semakin banyak, semakin besar massa probabilitas sampler yang tercakup, tetapi biayanya lebih mahal untuk diserialisasi; batasnya ditentukan oleh --max-logprobs server.
  • token_budget (int, opsional) — Jumlah maksimum token yang diteruskan dalam satu baris (satu forward dari satu DP rank). TokenBudgetBatcher membentuk micro-batch yang seimbang berdasarkan biaya attention, di mana setiap barisnya tetap berada dalam batas anggaran ini, sehingga membatasi memori puncak secara independen dari jumlah sampel (jumlah sampel per baris menjadi dinamis). Anggaran ini membatasi token unik, bukan token mentah, sehingga token yang dibagikan oleh beberapa sampel hanya dihitung sekali, dan anggaran ini juga membatasi istilah loss dari baris tersebut. Jika None (default), nilainya diatur ke max_model_len dari server vLLM (ditanyakan saat pelatihan dimulai) — yaitu batas atas panjang prompt + completion — sehingga tidak ada sampel rollout yang dapat melebihi anggaran. Sampel yang lebih panjang dari token_budget tidak muat dalam baris mana pun dan akan dibuang dengan peringatan.

Parameter yang mengontrol pipeline rollout asinkron

  • max_concurrent_rollouts (int, opsional, default 512) — Jumlah maksimum rollout yang berjalan secara bersamaan. Masing-masing memegang satu lingkungan, dapat menjalankan panggilan tool sinkron, dan mempertahankan koneksi ke server vLLM, sehingga atur nilainya sesuai dengan kapasitas sumber daya tersebut. Di bawahnya, jumlah rollout yang sedang berjalan mengikuti penggunaan KV-cache server vLLM dan max_staleness.
  • max_staleness (int, opsional, default 4) — Jumlah maksimum langkah pembaran bobot yang boleh tertinggal oleh sampel rollout di belakang versi model saat ini sebelum sampel tersebut dibuang. Proses generasi ditahan sesuai batas ini: grup rollout baru hanya dimulai selama token yang berada dalam antrean dan sedang diproses muat dalam apa yang dikonsumsi trainer dalam max(max_staleness, 1) langkah.
  • weight_sync_steps (int, opsional, default 1) — Jumlah langkah pelatihan antara sinkronisasi bobot ke server vLLM.
  • rollout_worker_timeout (float, opsional, default 300.0) — Detik sejak heartbeat terakhir dari rollout worker, setelahnya trainer menganggapnya macet dan membatalkan proses.

Parameter yang mengontrol logging

  • log_completions (bool, opsional, default False) — Apakah akan mencatat sampel pasangan (prompt, completion) setiap logging_steps langkah.
  • num_completions_to_print (int, opsional) — Jumlah completion yang dicetak dengan rich. Jika None, semua completion dicatat.

Kelas konfigurasi untuk AsyncGRPOTrainer.

Kelas ini hanya mencakup parameter yang spesifik untuk pelatihan GRPO asinkron. Untuk daftar lengkap argumen pelatihan, silakan merujuk ke dokumentasi TrainingArguments. Perhatikan bahwa nilai default dalam kelas ini mungkin berbeda dari yang ada di TrainingArguments.

Parameter-parameter ini memiliki nilai default yang berbeda dari TrainingArguments:

  • logging_steps: Bawaan adalah 1 alih-alih 500.
  • gradient_checkpointing: Beralih ke True sebagai nilai bawaan, bukan False.
  • bf16: Beralih ke True jika fp16 tidak diatur, alih-alih False.
  • learning_rate: Bawaan adalah 1e-6 alih-alih 5e-5.
  • lr_scheduler_type: Bawaan adalah constant alih-alih linear (lihat di bawah).
  • ignore_data_skip: Bawaan menjadi True alih-alih False; loop lewati-dan-ulangi dari Trainer dasar tidak berlaku untuk antrean rollout asinkron.
  • remove_unused_columns: Beralih ke False alih-alih True, dan harus tetap False: setiap kolom dataset diteruskan ke fungsi reward.

Durasi pelatihan dan learning rate di bawah rekonsiliasi mode pesan: Percakapan multi-turn dapat bercabang menjadi sejumlah baris pelatihan yang bervariasi (penulisan ulang percakapan memulai baris baru), sehingga jumlah sampel, dan oleh karena itu jumlah langkah optimizer, per epoch tidak diketahui di awal. Akibatnya:

  • num_train_epochs membatasi pelatihan berdasarkan jumlah lintasan penuh pada dataset prompt, dihitung sebagai jumlah prompt berbeda yang benar-benar dilatih. Hal ini independen dari berapa banyak baris yang dihasilkan oleh fork, sehingga permintaan N epoch selalu melatih pada N lintasan data. Ketika max_steps tidak disetel, ini menjadi kondisi berhenti dan max_steps hanyalah batas atas pengaman.
  • max_steps, jika diset secara eksplisit (> 0), mengambil alih sebagai kondisi berhenti (membatasi berdasarkan langkah optimizer, bukan epoch) dan menonaktifkan kondisi berhenti berbasis epoch.
  • lr_scheduler_type secara default bernilai constant karena horizon peluruhan diukur dalam langkah optimizer, yang tidak dapat diketahui di awal ketika jumlah langkah bergantung pada tingkat fork. Untuk learning rate yang meluruh, atur jadwal peluruhan bersama dengan max_steps yang eksplisit.

AsyncRolloutLoop

kelas trl.trainer.async_grpo_trainer.AsyncRolloutLoop

< >

( config: AsyncGRPOConfigmodel_name: strdataset: Datasetreward_funcs: list[collections.abc.Callable[..., list[float]]]processing_class: PreTrainedTokenizerBaseeos_token_ids: list[int]rollout_buffer: Queuemodel_version_value: Synchronizedtoken_allowance: Synchronizedheartbeat_value: Synchronizedfailed_event: Eventexception_info_queue: Queuemetrics_queue: Queuetools: list[collections.abc.Callable] | None = Noneenvironment_factory: collections.abc.Callable[[], object] | dict[str, collections.abc.Callable[[], object]] | None = Nonescore_queue_maxsize: int = 16lora_name: str | None = Nonedataset_start_index: int = 0 )

Membuat dan menilai rollout untuk AsyncGRPOTrainer, dalam proses rollout yang di-spawn.

Implementasi default menggunakan GRPO. Untuk menyesuaikan eksekusi, buat subclass, override hanya metode yang berubah, dan tetapkan subclass tersebut sebagai loop_cls trainer. Setiap prompt diproses secara berurutan:

  • filter_prompt(): apakah prompt akan diolah untuk menghasilkan output.
  • generate_one(): satu rollout penuh, yang memanggil generate_one_turn() untuk setiap permintaan sampling.
  • Grup num_generations rollout diberi skor: reward-nya adalah jumlah dari reward_funcs trainer, dari lingkungan yang mendefinisikan get_reward, dan dari Rollout.reward. Kemudian compute_advantages() dijalankan sekali per grup.

setup() dan close() membuat dan melepaskan sumber daya pada event loop dari loop, seperti klien HTTP. Hook dapat membaca self.config (subclass dari AsyncGRPOConfig dapat membawa field miliknya sendiri) dan self.tokenizer. Karena loop dibangun dalam proses yang di-spawn, subclass harus dapat diimpor (didefinisikan pada level modul).

filter_prompt

< >

( row_index: introw: dict[str, typing.Any]epoch: int ) → bool

Parameter

  • row_index (int) — Indeks baris dalam dataset pelatihan.
  • row (dict[str, Any]) — Baris dataset.
  • epoch (int) — Jumlah lintasan penuh pada dataset sebelum lintasan ini.

Mengembalikan

bool

True untuk menghasilkan num_generations rollout untuk prompt, False untuk melewatinya.

Apakah akan menghasilkan untuk sebuah prompt. Prompt yang ditolak akan dilewati untuk epoch ini dan dihitung sebagai sudah dikonsumsi, seperti grup yang dibuang. Secara default, setiap prompt diterima. Menolak semua prompt dari satu epoch penuh akan memicu error, karena tidak ada batch yang dapat mencapai trainer setelah itu.

generate_one

< >

( prompt: list[dict[str, str]]tools: list[collections.abc.Callable]group_id: int = 0 ) → Rollout

Parameter

  • prompt (list[dict[str, Any]]) — Pesan prompt.
  • tools (list[Callable]) — Tools yang tersedia untuk rollout ini: tools dari trainer, ditambah metode publik dari environment saat menggunakan environment_factory.
  • group_id (int, opsional, default 0) — Pengidentifikasi grup tempat rollout tersebut berada.

Mengembalikan

Rollout

Rollout yang telah selesai.

Generate satu rollout untuk sebuah prompt.

Secara default, sebuah loop tool multi-turn: setiap turn merender seluruh percakapan dengan chat template, mengambil sampel balasan dengan generate_one_turn() dan menjalankan panggilan tool yang dikandungnya, hingga model berhenti memanggil tool atau max_tool_calling_iterations tercapai. Timpa perilaku ini untuk menghasilkan output dengan cara berbeda, misalnya dengan kerangka kerja agen. Kembalikan setiap permintaan pengambilan sampel dalam Rollout.turns, karena urutan pelatihan dibangun dari mereka, dan atur Rollout.reward untuk menilai rollout di sini.

generate_one_turn

< >

( prompt_ids: list[int] ) → TurnRecord

Parameter

  • prompt_ids (list[int]) — ID token dari prompt lengkap.

Mengembalikan

TurnRecord

Prompt dan token yang disampelkan beserta log-probabilitasnya. Dengan top_k atau top_p, ini juga menyimpan himpunan kandidat untuk setiap token yang disampelkan, dan dengan num_sampler_logprobs, log-probabilitas teratas dari sampler.

Ambil satu balasan dari server vLLM, dengan pengaturan sampling dari konfigurasi (temperature, top_p, top_k, min_p, repetition_penalty dan max_completion_length).

compute_advantages

< >

( group: RolloutGroup ) → np.ndarray

Parameter

  • group (RolloutGroup) — num_generations rollout dari satu prompt, dengan total reward mereka di group.rewards.

Mengembalikan

np.ndarray

Satu keuntungan per rollout, dalam urutan group.rewards.

Hitung satu keuntungan per rollout dari sebuah grup. Secara default, setiap reward dinormalisasi di dalam grup; rollout dengan reward NaN mendapatkan keuntungan 0 dan dikecualikan dari perhitungan mean dan std.

It berjalan untuk setiap grup. Grup yang reward-nya yang diberi skor semuanya sama akan dihapus, apa pun keuntungan yang dikembalikan.

setup

< >

( )

Buat sumber daya yang dibutuhkan hook lainnya, seperti klien HTTP. Berjalan di event loop loop sebelum prompt pertama. Tidak melakukan apa pun secara default.

tutup

< >

( )

Lepaskan apa yang dibuat oleh setup(). Berjalan saat loop berhenti, termasuk saat terjadi kegagalan. Tidak melakukan apa pun secara default.

Rollout

kelas trl.trainer.async_grpo_trainer.Rollout

< >

( completion: list[dict[str, str]]completion_ids: list[int]turns: list[trl.trainer.async_grpo_trainer.TurnRecord]tool_call_count: int = 0tool_failure_count: int = 0reward: float | None = Nonerollout_id: str = <factory> )

Parameter

  • completion (list[dict[str, Any]]) — Messages generated after the prompt, in conversational format. Passed to the reward functions as completions.
  • completion_ids (list[int]) — ID token dari completion yang dihasilkan. Diteruskan ke fungsi reward sebagai completion_ids.
  • turns (list[TurnRecord]) — Permintaan sampling yang menghasilkan rollout, sesuai urutannya. Urutan pelatihan dibangun dari mereka: token yang disampelkan dilatih, sedangkan bagian lain dari setiap prompt menjadi konteks.
  • tool_call_count (int, opsional, default 0) — Jumlah pemanggilan alat yang dilakukan selama rollout.
  • tool_failure_count (int, opsional, default 0) — Jumlah panggilan tool yang gagal.
  • reward (float, opsional) — Reward yang dihitung saat menghasilkan, misalnya oleh grader eksternal. Nilai ini ditambahkan ke reward dari fungsi reward dan lingkungan. Jika None, rollout ini tidak mendapatkan reward dari sumber ini.
  • rollout_id (str, opsional) — Mengidentifikasi rollout pada baris latihannya, untuk keperluan debugging. Nilainya secara default adalah id hex acak baru.

Satu rollout yang selesai, sebagaimana dikembalikan oleh generate_one().

TurnRecord

kelas trl.trainer.async_grpo_trainer.TurnRecord

< >

( prompt_ids: list[int]output_ids: list[int]output_log_probs: list[float] = <factory>output_mask: list[int] | None = Noneoutput_sampling_mask: list[list[int]] | None = Noneoutput_sampler_logprobs: list[dict[int, float]] | None = None )

Parameter

  • prompt_ids (list[int]) — ID token dari prompt lengkap yang dikirim untuk giliran ini, termasuk semua giliran sebelumnya dalam percakapan.
  • output_ids (list[int]) — ID token yang dihasilkan oleh sampler.
  • output_log_probs (list[float], opsional, default []) — Log-probability sampler untuk setiap token dalam output_ids. Wajib diisi jika salah satu dari token tersebut sedang dilatih.
  • output_mask (list[int], opsional) — Satu nilai per token di output_ids: 1 untuk melatih pada token tersebut, 0 untuk menjadikannya sebagai konteks saja. Jika None, setiap token output akan dilatih.
  • output_sampling_mask (list[list[int]], opsional) — Satu daftar untuk setiap token dalam output_ids: id token yang dapat diambil oleh sampler berdasarkan pemotongan top_k / top_p. Jika None, seluruh kosakata.
  • output_sampler_logprobs (list[dict[int, float]], opsional) — Satu dict per token di output_ids: log-probabilitas token yang paling mungkin dari sampler, dengan kunci berupa id token. Digunakan oleh score centering (num_sampler_logprobs).

Satu permintaan sampling: prompt yang dikirim ke sampler dan token yang dihasilkannya.

RolloutGroup

kelas trl.trainer.async_grpo_trainer.RolloutGroup

< >

( prompts: list[list[dict[str, str]]]reward_kwargs: dict[str, list[typing.Any]]completions: list[list[dict[str, str]]]completions_ids: list[list[int]]completions_sequences: list[list[trl.trainer.async_grpo_trainer.TrainingSequence]]tool_call_counts: list[int]tool_failure_counts: list[int]model_version: intgroup_id: introw_index: intenv_rewards: list[tuple[type, float] | None]rollout_rewards: list[float | None]queued_at: float = 0.0rewards: numpy.ndarray | None = None )

Parameter

  • prompts (list[list[dict[str, Any]]]) — Prompt dari setiap rollout.
  • reward_kwargs (dict[str, list[Any]]) — Kolom lain dari baris dataset prompt, yang diteruskan ke fungsi reward sebagai argumen kata kunci.
  • completions (list[list[dict[str, Any]]]) — Pesan completion dari setiap rollout.
  • completions_ids (list[list[int]]) — ID token completion untuk setiap rollout.
  • completions_sequences (list[list[TrainingSequence]]) — Urutan pelatihan yang dibangun dari setiap rollout. Rollout yang riwayatnya yang di-tokenisasi ulang berubah antar giliran menghasilkan lebih dari satu.
  • tool_call_counts (list[int]) — Jumlah pemanggilan alat di setiap rollout.
  • tool_failure_counts (list[int]) — Jumlah panggilan alat yang gagal di setiap rollout.
  • model_version (int) — Versi kebijakan saat rollout pertama grup dimulai.
  • group_id (int) — Pengidentifikasi grup, dihitung dari 0 dalam proses rollout.
  • row_index (int) — Indeks baris prompt dalam dataset pelatihan.
  • env_rewards (list[tuple[type, float] or None]) — Untuk rollout yang lingkungannya mendefinisikan get_reward, kelas lingkungan dan reward-nya; selain itu None.
  • rollout_rewards (list[float or None]) — Rollout.reward dari setiap rollout.
  • queued_at (float, opsional, default 0.0) — time.monotonic() saat grup diantre untuk penilaian.
  • rewards (np.ndarray, opsional) — Total reward dari setiap rollout, dijumlahkan dari semua sumber reward, bernilai NaN jika tidak ada sumber yang memberikan skor. Diatur sebelum compute_advantages() dipanggil.

Rollout num_generations dari satu prompt, dinilai secara bersama. Setiap daftar memiliki satu entri per rollout.

Update on GitHub