# Pelatih GRPO Asinkron

[![model badge](https://img.shields.io/badge/All_models-Asynchronous_GRPO-blue)](https://huggingface.co/models?other=async-grpo,trl)

## Ikhtisar

[AsyncGRPOTrainer](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.AsyncGRPOTrainer) mengimplementasikan algoritma [GRPO](grpo_trainer) 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](https://huggingface.co/aminediroHF) dan [Quentin Gallouédec](https://huggingface.co/qgallouedec).

## Mulai cepat

Contoh ini menunjukkan cara melatih model menggunakan metode Asynchronous GRPO. Kami melatih [Qwen3.5 2B model](https://huggingface.co/Qwen/Qwen3.5-2B) dengan prompt dari [DeepMath-103K dataset](https://huggingface.co/datasets/trl-lib/DeepMath-103K). Anda dapat melihat data dalam dataset di sini:

<iframe src="https://huggingface.co/datasets/trl-lib/DeepMath-103K/embed/viewer/default/train?row=0" frameborder="0" width="100%" height="560px"
>

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]`.

```python
# 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:

```bash
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:

```bash
CUDA_VISIBLE_DEVICES=1 python train_async_grpo.py
```

## Kompatibilitas dan batasan

Beberapa kombinasi argumen sengaja dibatasi dalam implementasi [AsyncGRPOTrainer](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.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](dataset_formats#conversational). 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](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel) tidak didukung, lihat [Menggunakan fungsi reward kustom](#using-a-custom-reward-function).
- 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-vision-language-models).

Training memuat kernel attention-nya dari Hub melalui pustaka [`kernels`](https://github.com/huggingface/kernels): [`kernels-community/aiter-flash-attn`](https://huggingface.co/kernels-community/aiter-flash-attn) pada GPU AMD (ROCm), [`kernels-community/flash-attn4`](https://huggingface.co/kernels-community/flash-attn4) pada GPU NVIDIA Blackwell, dan [`kernels-community/flash-attn3`](https://huggingface.co/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](/docs/trl/v1.18.0/id/grpo_trainer#trl.GRPOTrainer), proses generasi dan pelatihan bersifat berurutan: menghasilkan batch, menghitung loss, memperbarui bobot, lalu diulang. Bahkan dalam [colocate mode](grpo_trainer#option-1-colocate-mode), satu fase harus selesai sebelum fase lainnya dimulai. Di [AsyncGRPOTrainer](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.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, worker ini menghasilkan sekelompok \\( G \\) penyelesaian (`num_generations`) dan, setelah seluruh kelompok selesai, memberikan skor serta menghitung keuntungannya. Sampel pelatihan yang dihasilkan masuk ke dalam antrean, yang kemudian diambil oleh loop pelatihan. Proses generasi hanya menunggu ketika berada `max_staleness` langkah di depan pelatihan (lihat [Konkurensi](#concurrency)), 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 **group** adalah satu prompt beserta  \\( G \\) rollouts-nya. Advantage dihitung di dalam grup tersebut.
- 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](#multi-turn-rollouts)).
- a **row** adalah apa yang diteruskan oleh satu proses dalam satu micro-batch: beberapa sampel yang dikemas bersama (lihat [Tree packing](#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 penyelesaian  \\( G \\) dari sebuah grup, reward adalah jumlah dari reward dari masing-masing fungsi reward. Advantage dinormalisasi di dalam grup, seperti pada GRPO:

$$\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 milik trainer: kernel yang berbeda, presisi yang berbeda, dan kebijakan yang beberapa langkah tertinggal (lihat [Dealing with the Training-Inference Mismatch](grpo_trainer#dealing-with-the-training-inference-mismatch)). Trainer menggunakan log-probabilities dari sampler sebagai kebijakan lama, sehingga satu rasio importance mencakup baik ketidakcocokan maupun keterlambatan tersebut:

$$ 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](paper_index#masked-importance-sampling).

Secara default (`score_centering=True`), trainer menggunakan [Score Centering](paper_index#score-centering-stabilizes-off-policy-reinforcement-learning). Bobot kepentingan saja tidak menghilangkan ketidakcocokan: skor  \\( \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:

$$ \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 \\) di dalam \\( [C_{\min}, C_{\max}] \\) dan \\( 0 \\) di luar. Ekspektasi dalam diambil atas `num_sampler_logprobs` token paling mungkin dari sampler di setiap posisi, yang diminta oleh worker rollout dari server.

Dengan `score_centering=False`, trainer menggunakan tujuan pengganti terpotong (clipped surrogate objective) dari GRPO, dengan rasio tersembunyi (masked ratio) yang sama:

$$ \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 \\( \epsilon_{\text{low}} \\) adalah `epsilon` dan \\( \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](#saturation-and-duplicates).
- `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 yang kemudian dibuang. Ketika lingkungan memiliki reward melalui `get_reward`, `{reward_func_name}` adalah nama kelas lingkungan 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](#saturation-and-duplicates) 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 \\( 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: \\( \text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_\mathrm{low}, 1 + \epsilon_\mathrm{high} \right) \\). Dengan `score_centering=True`, loss tidak melakukan pemangkasan, sehingga metrik `clip_ratio/*` menghitung token yang berada di luar trust region.
- `clip_ratio/low_mean`: Rata-rata rasio probabilitas token yang dipangkas pada batas bawah trust region: \\(r_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}\\).
- `clip_ratio/low_min`: Fraksi per-penyelesaian terkecil dari token yang dipangkas pada batas bawah trust region: \\(r_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}\\).
- `clip_ratio/high_mean`: Rata-rata rasio probabilitas token yang dipangkas pada batas atas trust region: \\(r_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}\\).
- `clip_ratio/high_max`: Fraksi per-penyelesaian terbesar dari token yang dipangkas pada batas atas trust region: \\(r_{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](#concurrency).
- `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](#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](#the-rollout-queue).
- `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](#concurrency).
- `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 bagian yang berada di proses API server, membangun respons.
- `rollout/vllm_queued_requests`: Jumlah permintaan yang telah diterima server tetapi belum dijadwalkan (`num_requests_waiting` dari vLLM, dijumlahkan di seluruh mesin).
- `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](openenv#metrics) 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](#the-rollout-queue).
- `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. Nilai 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`):

```bash
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`.

> [!WARNING]
> 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`.

> [!WARNING]
> 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](https://github.com/vllm-project/vllm/pull/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 dilampaui oleh proses generasi. 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 naik 25%, maksimal sekali per sejumlah cap rollout yang selesai. Ketika penggunaan melebihi 80%, batasnya turun 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:

```python
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.

> [!TIP]
> Metrik yang dicatat menunjukkan batas mana yang menahan proses generasi:
>
> - `rollout/backpressure_s` di atas nol: batas keusangan. Generasi berada di depan pelatihan, yang diharapkan 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 akan memiliki keuntungan nol, sehingga grup tersebut dibuang (lihat [Metriks yang dicatat](#logged-metrics)) dan tidak mengajarkan apa pun kepada kebijakan. Seiring jalannya eksekusi menjadi jenuh, semakin banyak grup yang berakhir seperti ini, baik karena setiap rollout berhasil 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:

| metrik | pertanyaan |
| --- | --- |
| `frac_zero_std_groups` | bagian dari kelompok yang tidak membawa sinyal |
| `reward_zero_std_groups` | di 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 |
| `reward` | seberapa baik kebijakan tersebut di setiap grup yang dinilai, termasuk yang dihapus |
| `completions/duplicate_frac` | apakah sampling masih menghasilkan rollout yang berbeda untuk prompt yang sama |

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

| `frac_zero_std_groups` | `reward_zero_std_groups` | `reward` | diagnosis | apa yang harus dilakukan |
| --- | --- | --- | --- | --- |
| rendah | any (berisik di beberapa grup) | any | **sehat**: sebagian besar grup menghasilkan gradien | nothing |
| mendaki | di bagian atas rentang | mendaki | **jenuh di bagian atas**: prompt telah menjadi terlalu mudah bagi kebijakan, yang merupakan cara sebuah run yang sukses biasanya berakhir | hentikan eksekusi, atau beralih ke prompt yang lebih sulit |
| tinggi | di bagian bawah rentang | rendah dan datar | **terjebak di bagian bawah**: prompt terlalu sulit, atau fungsi reward tidak pernah memberikan kredit | Periksa `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 |
| mendaki | turun | turun | **regression**: grup yang sebelumnya lulus kini gagal bersama | periksa `completions/duplicate_frac` dan `entropy` untuk melihat adanya kolaps |
| tinggi | di tengah | any | **campuran**: 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 sama | membaca 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_frac` | diagnosis |
| --- | --- |
| dekat 0, dengan baseline kecil pada tugas-tugas yang penyelesaiannya cukup pendek sehingga dapat diulang secara kebetulan | **sehat**: rollout dari sebuah grup disampel secara independen |
| melonjak menuju `(num_generations - 1) / num_generations` | **sampling 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 turun | **collapse**: 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 hasil kali prefix bersama dengan 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.

> [!TIP]
> 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](https://huggingface.co/papers/2512.02556), 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 disetel, karena vLLM membatasi ukuran himpunan kandidat dengannya:

```bash
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
```

```python
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.

```python
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`:

```bash
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.

> [!WARNING]
> `<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.

> [!TIP]
> 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](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.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](dataset_formats#conversational), 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.

> [!WARNING]
> 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`](https://docs.python.org/3/library/functools.html#functools.partial), atau **instans kelas yang dapat dipanggil**. Lambda dan closure akan memicu `TypeError` saat `trainer.train()`. Ini berbeda dari [GRPOTrainer](/docs/trl/v1.18.0/id/grpo_trainer#trl.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:

```python
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:

```python
>>> 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](https://huggingface.co/papers/2501.12948). Fungsi ini dirancang untuk format percakapan, di mana prompt dan penyelesaian terdiri dari pesan terstruktur.

```python
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:

```python
>>> 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](https://huggingface.co/papers/2501.12948). Dataset tersebut berisi kolom bernama `ground_truth`.

```python
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:

```python
>>> 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](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.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.

```python
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](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.AsyncGRPOTrainer) akan melanjutkan dengan fungsi dan tugas yang valid. Hal ini memungkinkan [AsyncGRPOTrainer](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.AsyncGRPOTrainer) untuk menangani beberapa fungsi reward dengan tingkat penerapan yang berbeda.

Perhatikan bahwa [AsyncGRPOTrainer](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.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](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.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:

```python
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](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.AsyncGRPOTrainer) sebagai berikut:

```python
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:

```python
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](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.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.

| Metode | Dipanggil | Default |
|---|---|---|
| `filter_prompt(row_index, row, epoch)` | sekali per prompt, sebelum generasi | menerima setiap prompt |
| `generate_one(prompt, tools, group_id)` | satu kali per rollout | loop alat multi-putar |
| `generate_one_turn(prompt_ids)` | sekali per permintaan sampling | satu permintaan vLLM dengan pengaturan sampling dari konfigurasi |
| `compute_advantages(group)` | satu kali per grup, setelah reward dijumlahkan ke dalam `group.rewards` | reward yang distandardisasi dalam kelompok |
| `setup()`, `close()` | ketika loop dimulai dan dihentikan | nothing |

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

```python
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](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.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](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.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 telah dihasilkan tetapi tidak pernah dilatih. Dataset streaming ([IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.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:

```python
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 meneruskan tools](https://huggingface.co/docs/transformers/en/chat_extras#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.

> [!TIP]
> 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](chat_templates#training-templates) untuk daftar lengkap.

Gunakan `max_tool_calling_iterations` di [AsyncGRPOConfig](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.AsyncGRPOConfig) untuk membatasi jumlah giliran pemanggilan alat. Secara default tidak ada batas, dan generasi berhenti ketika model menghasilkan giliran respons tanpa pemanggilan alat.

Contoh:

```python
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](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.AsyncGRPOTrainer) membuat satu instance lingkungan per rollout dan mengekspos metode publik lingkungan tersebut 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).

```python
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`.

> [!NOTE]
> 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](#multiple-environments). 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).

```python
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.

```python
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.

```python
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. Di 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](openenv#training-on-harnesses-training-real-coding-agents-harbor) 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.

> [!WARNING]
> **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[[trl.AsyncGRPOTrainer]]

#### trl.AsyncGRPOTrainer[[trl.AsyncGRPOTrainer]]

```python
trl.AsyncGRPOTrainer(model: str | PreTrainedModel, reward_funcs: collections.abc.Callable[..., list[float]] | list[collections.abc.Callable[..., list[float]]] | None = None, args: trl.trainer.async_grpo_config.AsyncGRPOConfig | None = None, train_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = None, processing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | None = None, callbacks: list[transformers.trainer_callback.TrainerCallback] | None = None, optimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None), peft_config: PeftConfig | None = None, tools: list[collections.abc.Callable] | None = None, environment_factory: collections.abc.Callable[[], trl.trainer.async_grpo_trainer._SupportsReset] | dict[str, collections.abc.Callable[[], trl.trainer.async_grpo_trainer._SupportsReset]] | None = None)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_trainer.py#L2805)

**Parameter:**

model (`str` atau [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel)) : Model yang akan dilatih. Bisa berupa:  - String, yaitu *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](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.save_pretrained), misalnya `'./my_model_directory/'`. Model dimuat dengan arsitektur yang dideklarasikan di konfigurasinya: [AutoModelForImageTextToText](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForImageTextToText) untuk checkpoint vision-language (di mana vision tower dimuat tetapi dibekukan, lihat [Training Vision Language Models](async_grpo_trainer#training-vision-language-models)), [AutoModelForCausalLM](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM) selain itu. - Objek [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel). Implementasi atensinya diganti ke backend tree attention trainer untuk pelatihan yang dikemas.  Nama model dari konfigurasi digunakan untuk mengidentifikasi model di 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 penyelesaian, lalu menjumlahkan reward-nya. Dapat diabaikan ketika reward disediakan oleh lingkungan melalui `environment_factory` (lihat di bawah). Dapat berupa:  - Satu fungsi reward: Fungsi ini diberikan prompt dan penyelesaian 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. 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](#using-a-custom-reward-function). - Daftar fungsi reward, di mana setiap item adalah fungsi reward seperti yang dijelaskan di atas. Reward dari semua fungsi dijumlahkan.  Berbeda dengan [GRPOTrainer](/docs/trl/v1.18.0/id/grpo_trainer#trl.GRPOTrainer), reward dihitung dalam proses anak yang dibuat (spawned), sehingga setiap fungsi reward (bersama dengan `tools` dan `environment_factory`) harus dapat di-pickle: gunakan fungsi tingkat modul, `functools.partial`, atau instance kelas yang dapat dipanggil — lambda dan closure akan gagal saat startup. Tools didaftarkan di bawah `__name__` mereka, sehingga harus berupa fungsi tingkat modul. Proses anak juga berjalan dengan `CUDA_VISIBLE_DEVICES=""`, sehingga model reward yang didukung GPU berjalan di CPU (lambat), bukan di GPU trainer.

args ([AsyncGRPOConfig](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.AsyncGRPOConfig), *opsional*) : Konfigurasi untuk trainer ini. Jika `None`, konfigurasi default akan digunakan.

train_dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) atau [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset), *opsional*) : Dataset yang digunakan untuk pelatihan. Dataset ini harus menyertakan kolom `"prompt"`. Kolom tambahan apa pun dalam dataset akan diabaikan. Sampel harus dalam format [conversational](dataset_formats#conversational): setiap sampel berisi pesan terstruktur (misalnya, role dan content). Parameter ini hanya boleh diabaikan jika `environment_factory` disediakan dan lingkungan memiliki (atau menghasilkan secara prosedural) data tersebut, dengan mengembalikan prompt dari metode `reset()`-nya. Dalam kasus itu, `max_steps` harus diatur untuk menentukan panjang pelatihan.

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/v5.23.0/en/internal/tokenization_utils#transformers.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](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoTokenizer.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](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback), *opsional*) : Daftar callback untuk menyesuaikan loop pelatihan. Callback tersebut akan ditambahkan ke daftar callback default yang dijelaskan di [di sini](https://huggingface.co/docs/transformers/main_classes/callback). Jika Anda ingin menghapus salah satu callback default yang digunakan, gunakan metode [remove_callback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.Trainer.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](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/optimizer_schedules#transformers.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 (daftar `Callable`, *opsional*) : Daftar fungsi tool yang dapat dipanggil (sinkron atau asinkron) yang dapat diaktifkan oleh model selama generasi. Setiap tool harus berupa fungsi Python standar dengan argumen dan nilai pengembalian yang diberi type-hint dengan benar, serta docstring bergaya Google yang menjelaskan tujuannya, argumennya, dan nilai pengembaliannya. 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 telah di-fine-tune untuk pemanggilan tool.

environment_factory (`EnvironmentFactory` atau `dict[str, EnvironmentFactory]`, *opsional*) : Callable yang membuat dan mengembalikan instance environment, atau dictionary yang memetakan nama environment ke callable tersebut. 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 `reset` yang callable dan dapat digunakan untuk mereset state antar generation. Metode `reset` harus 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`: jika ada, environment memiliki reward, dan `get_reward` dipanggil sekali per rollout yang selesai untuk memberikan skor berdasarkan state internal environment. Metode ini bertindak sebagai sumber reward tambahan (dengan bobot 1, dicatat di bawah nama kelas environment) berdampingan dengan `reward_funcs`, yang kemudian menjadi opsional. Dengan satu callable, setiap contoh menggunakan environment yang sama, dengan satu instance per rollout sehingga interaksi mereka tetap terisolasi. Dengan dictionary, setiap contoh harus memiliki field `environment` yang memilih environment-nya berdasarkan nama, dan hanya tools dari environment tersebut yang diekspos dalam prompt-nya — memungkinkan satu run mencampur tugas (misalnya environment 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](https://huggingface.co/papers/2402.03300). Trainer ini adalah versi asinkron dari GRPO, di mana proses generasi dialihkan ke server vLLM eksternal yang berjalan secara asinkron bersamaan dengan pelatihan, sehingga memisahkan rollout dari loop pembaruan gradien.

Contoh:

```python
>>> 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](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.AsyncRolloutLoop) dan atur sebagai `loop_cls` trainer. TRL membangun loop di

proses rollout:

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

#### train[[trl.AsyncGRPOTrainer.train]]

```python
train(resume_from_checkpoint: str | bool | None = None, trial: optuna.Trial | dict[str, Any] | None = None, ignore_keys_for_eval: list[str] | None = None)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L1450)

**Parameter:**

resume_from_checkpoint (`str` atau `bool`, *opsional*) : Jika berupa `str`, path 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 state model/optimizer/scheduler yang dimuat di sini.

trial (`optuna.Trial` atau `dict[str, Any]`, *opsional*) : Jalur percobaan atau kamus hiperparameter untuk pencarian hiperparameter.

ignore_keys_for_eval (`list[str]`, *opsional*) : Daftar kunci dalam output model Anda (jika berupa kamus) 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[[trl.AsyncGRPOTrainer.save_model]]

```python
save_model(output_dir: str | None = None, _internal_call: bool = False)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L4077)

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

Hanya akan menyimpan dari proses utama.

#### push_to_hub[[trl.AsyncGRPOTrainer.push_to_hub]]

```python
push_to_hub(commit_message: str | None = 'End of training', blocking: bool = True, token: str | None = None, revision: str | None = None, private: bool | None = None, **kwargs)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L4337)

**Parameter:**

commit_message (`str`, *opsional*, defaultnya `"End of training"`) : Pesan untuk commit saat push.

blocking (`bool`, *opsional*, defaultnya `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 cabang "main".

private (`bool`, *opsional*) : Apakah membuat repo menjadi privat saat dibuat. Bawaan 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`.

**Mengembalikan:**

URL repositori tempat model didorong jika `blocking=False`, atau objek `Future` yang melacak kemajuan commit jika `blocking=True`.

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

## AsyncGRPOConfig[[trl.AsyncGRPOConfig]]

#### trl.AsyncGRPOConfig[[trl.AsyncGRPOConfig]]

```python
trl.AsyncGRPOConfig(output_dir: str | None = None, per_device_train_batch_size: int = 8, num_train_epochs: float = 3.0, max_steps: int = -1, learning_rate: float = 1e-06, lr_scheduler_type: str = 'constant', lr_scheduler_kwargs: dict | str | None = None, warmup_steps: float = 0, optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused', optim_args: str | None = None, weight_decay: float = 0.0, adam_beta1: float = 0.9, adam_beta2: float = 0.999, adam_epsilon: float = 1e-08, optim_target_modules: None | str | list[str] = None, gradient_accumulation_steps: int = 1, average_tokens_across_devices: bool = True, max_grad_norm: float = 1.0, label_smoothing_factor: float = 0.0, bf16: bool | None = None, fp16: bool = False, bf16_full_eval: bool = False, fp16_full_eval: bool = False, tf32: bool | None = None, activation_checkpointing: bool | None = None, activation_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, gradient_checkpointing: bool = True, gradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, torch_compile: bool = False, torch_compile_backend: str | None = None, torch_compile_mode: str | None = None, use_liger_kernel: bool = False, liger_kernel_config: dict[str, bool] | None = None, use_cache: bool = False, neftune_noise_alpha: float | None = None, torch_empty_cache_steps: int | None = None, auto_find_batch_size: bool = False, logging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps', logging_steps: float = 1, logging_first_step: bool = False, log_on_each_node: bool = True, logging_nan_inf_filter: bool = True, include_num_input_tokens_seen: str | bool = 'no', log_level: str = 'passive', log_level_replica: str = 'warning', disable_tqdm: bool | None = None, report_to: None | str | list[str] = 'none', run_name: str | None = None, project: str = 'huggingface', trackio_space_id: str | None = None, trackio_bucket_id: str | None = None, trackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = None, eval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no', eval_steps: float | None = None, eval_delay: float = 0, per_device_eval_batch_size: int = 8, prediction_loss_only: bool = False, eval_on_start: bool = False, eval_do_concat_batches: bool = True, eval_use_gather_object: bool = False, eval_accumulation_steps: int | None = None, include_for_metrics: list[str] = <factory>, batch_eval_metrics: bool = False, save_only_model: bool = False, save_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps', save_steps: float = 500, save_on_each_node: bool = False, save_total_limit: int | None = None, enable_jit_checkpoint: bool = False, push_to_hub: bool = False, hub_token: str | None = None, hub_private_repo: bool | None = None, hub_model_id: str | None = None, hub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save', hub_always_push: bool = False, hub_revision: str | None = None, load_best_model_at_end: bool = False, metric_for_best_model: str | None = None, greater_is_better: bool | None = None, ignore_data_skip: bool = True, restore_callback_states_from_checkpoint: bool = False, full_determinism: bool = False, seed: int = 42, data_seed: int | None = None, use_cpu: bool = False, accelerator_config: dict | str | None = None, parallelism_config: accelerate.parallelism_config.ParallelismConfig | None = None, dataloader_drop_last: bool = False, dataloader_num_workers: int = 0, dataloader_pin_memory: bool = True, dataloader_persistent_workers: bool = False, dataloader_prefetch_factor: int | None = None, dataloader_multiprocessing_context: str | None = None, dataloader_in_order: bool = True, remove_unused_columns: bool = False, label_names: list[str] | None = None, train_sampling_strategy: str = 'random', length_column_name: str = 'length', ddp_find_unused_parameters: bool | None = None, ddp_bucket_cap_mb: int | None = None, ddp_broadcast_buffers: bool | None = None, ddp_static_graph: bool | None = None, ddp_backend: str | None = None, ddp_timeout: int = 1800, fsdp: str | None = None, fsdp_config: dict[str, typing.Any] | str | None = None, deepspeed: dict | str | None = None, debug: str | list[transformers.debug_utils.DebugOption] = '', skip_memory_metrics: bool = True, do_train: bool = False, do_eval: bool = False, do_predict: bool = False, resume_from_checkpoint: str | None = None, local_rank: int = -1, model_init_kwargs: dict[str, typing.Any] | str | None = None, dtype: str = 'float32', trust_remote_code: bool = False, router_aux_loss_coef: float | None = None, num_generations: int = 8, max_completion_length: int = 2048, temperature: float = 1.0, top_p: float = 1.0, top_k: int = 0, min_p: float | None = None, chat_template_kwargs: dict | str | None = None, max_tool_calling_iterations: int | None = None, vllm_server_base_url: str = 'http://localhost:8000', vllm_server_timeout: float = 1800.0, epsilon: float = 0.2, epsilon_high: float | None = None, score_centering: bool = True, vllm_importance_sampling_clip_min: float = 0.5, vllm_importance_sampling_clip_max: float = 5.0, num_sampler_logprobs: int = 8, token_budget: int | None = None, max_concurrent_rollouts: int = 512, max_staleness: int = 4, weight_sync_steps: int = 1, rollout_worker_timeout: float = 300.0, log_completions: bool = False, num_completions_to_print: int | None = None)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_config.py#L22)

**Parameter yang mengontrol model:**

model_init_kwargs (`dict[str, Any]` atau `str`, *opsional*) : Argumen kata kunci untuk [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.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 pengukuran trainer ini ([Defeating the Training-Inference Mismatch via FP16](https://huggingface.co/papers/2510.26788)) 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. `dtype` di dalam `model_init_kwargs` memiliki prioritas lebih tinggi. 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 presisi: `dtype="bfloat16"` dengan `bf16=True` mempertahankan bobot dan state optimizer dalam bf16, yang merupakan pelatihan murni bf16.

trust_remote_code (`bool`, *opsional*, defaultnya `False`) : Apakah mengizinkan pemuatan model dan tokenizer yang menyertakan kode Python kustom dari Hub. Diteruskan ke [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) dan [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoTokenizer.from_pretrained).

router_aux_loss_coef (`float`, *opsional*) : Koefisien dari loss tambahan load-balancing 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. Akan gagal jika digunakan dengan model non-MoE.

**Parameter yang mengontrol generasi:**

num_generations (`int`, *opsional*, defaultnya `8`) : Jumlah generasi per prompt yang akan disampel.

max_completion_length (`int`, *opsional*, defaultnya `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*, defaultnya `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 memicu error saat timeout habis; permintaan generasi yang timeout akan dicoba ulang.

**Parameter yang mengontrol pelatihan:**

epsilon (`float`, *opsional*, defaultnya `0.2`) : Nilai epsilon untuk pemotongan (clipping).

epsilon_high (`float`, *opsional*) : Nilai epsilon batas atas untuk pemotongan (clipping). Jika tidak ditentukan, nilainya secara default sama dengan nilai batas bawah yang ditentukan dalam argumen `epsilon`. Kertas [DAPO](https://huggingface.co/papers/2503.14476) merekomendasikan `0.28`.

score_centering (`bool`, *opsional*, defaultnya `True`) : Apakah akan melatih dengan score centering ([paper](https://huggingface.co/papers/2609.20807)) 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 menuju sampler. Harapan diambil dari `num_sampler_logprobs` token 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 kepentingan antara kebijakan 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 kepentingan.

num_sampler_logprobs (`int`, *opsional*, default `8`) : Jumlah top log-probabilities yang diminta dari sampler vLLM untuk setiap token yang dihasilkan, digunakan oleh score centering. Semakin banyak yang dicakup, semakin besar massa probabilitas sampler yang tercakup, tetapi biayanya lebih mahal untuk diserialisasi; `--max-logprobs` server membatasinya.

token_budget (`int`, *opsional*) : Jumlah maksimum token yang diteruskan dalam satu baris (forward dari satu rank DP). `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 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*, defaultnya `512`) : Jumlah maksimum rollout yang berjalan sekaligus. 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*, defaultnya `4`) : Jumlah maksimum langkah pembaruan bobot yang dapat tertinggal oleh sampel rollout di belakang versi model saat ini sebelum dibuang. Proses generasi ditahan hingga 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*, defaultnya `1`) : Jumlah langkah pelatihan antara sinkronisasi bobot ke server vLLM.

rollout_worker_timeout (`float`, *opsional*, defaultnya `300.0`) : Detik sejak heartbeat terakhir worker rollout, setelahnya trainer menganggapnya macet dan membatalkan proses.

**Parameter yang mengontrol pencatatan log:**

log_completions (`bool`, *opsional*, defaultnya `False`) : Apakah akan mencatat sampel dari pasangan (prompt, completion) setiap `logging_steps` langkah.

num_completions_to_print (`int`, *opsional*) : Jumlah penyelesaian yang dicetak dengan `rich`. Jika `None`, semua penyelesaian dicatat.

Kelas konfigurasi untuk [AsyncGRPOTrainer](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.AsyncGRPOTrainer).

Kelas ini hanya mencakup parameter yang spesifik untuk pelatihan GRPO asinkron. Untuk daftar lengkap argumen pelatihan, silakan merujuk ke dokumentasi [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments). Perhatikan bahwa nilai default dalam kelas ini mungkin berbeda dari yang ada di [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments).

> [!NOTE]
> Parameter ini memiliki nilai default yang berbeda dari [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments): - `logging_steps`: Defaultnya adalah `1`, bukan `500`. - `gradient_checkpointing`: Defaultnya adalah `True`, bukan `False`. - `bf16`: Defaultnya adalah `True` jika `fp16` tidak diatur, bukan `False`. - `learning_rate`: Defaultnya adalah `1e-6`, bukan `5e-5`. - `lr_scheduler_type`: Defaultnya adalah `constant`, bukan `linear` (lihat di bawah). - `ignore_data_skip`: Defaultnya adalah `True`, bukan `False`; loop skip-and-replay dari Trainer dasar tidak berlaku untuk antrean rollout asinkron. - `remove_unused_columns`: Defaultnya adalah `False`, bukan `True`, dan harus tetap `False`: setiap kolom dataset diteruskan ke fungsi reward.

> [!NOTE]
> Durasi pelatihan dan laju pembelajaran di bawah rekonsiliasi mode pesan: Percakapan multi-putar 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 lintasan penuh atas dataset *prompt*, dihitung sebagai jumlah prompt berbeda yang benar-benar dilatih. Ini independen dari berapa banyak baris yang dihasilkan oleh cabang, sehingga meminta N epoch selalu melatih pada N lintasan atas data. Ketika `max_steps` dibiarkan tidak disetel, ini adalah kondisi berhenti dan `max_steps` hanyalah batas atas keselamatan. - `max_steps`, jika disetel secara eksplisit (`> 0`), mengambil alih sebagai kondisi berhenti (membatasi berdasarkan langkah optimizer alih-alih epoch) dan menonaktifkan kondisi berhenti berbasis epoch. - `lr_scheduler_type` secara default adalah `constant` karena cakupan peluruhan diukur dalam langkah optimizer, yang tidak dapat diketahui di awal ketika jumlah langkah bergantung pada tingkat percabangan. Untuk laju pembelajaran yang meluruh, setel jadwal peluruhan bersama dengan `max_steps` yang eksplisit.

## AsyncRolloutLoop[[trl.trainer.async_grpo_trainer.AsyncRolloutLoop]]

#### trl.trainer.async_grpo_trainer.AsyncRolloutLoop[[trl.trainer.async_grpo_trainer.AsyncRolloutLoop]]

```python
trl.trainer.async_grpo_trainer.AsyncRolloutLoop(config: AsyncGRPOConfig, model_name: str, dataset: Dataset, reward_funcs: list[collections.abc.Callable[..., list[float]]], processing_class: PreTrainedTokenizerBase, eos_token_ids: list[int], rollout_buffer: Queue, model_version_value: Synchronized, token_allowance: Synchronized, heartbeat_value: Synchronized, failed_event: Event, exception_info_queue: Queue, metrics_queue: Queue, tools: list[collections.abc.Callable] | None = None, environment_factory: collections.abc.Callable[[], object] | dict[str, collections.abc.Callable[[], object]] | None = None, score_queue_maxsize: int = 16, lora_name: str | None = None, dataset_start_index: int = 0)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_trainer.py#L755)

Membuat dan menilai rollout untuk [AsyncGRPOTrainer](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.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 melewati, secara berurutan:

- [filter_prompt()](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.AsyncRolloutLoop.filter_prompt): apakah prompt akan diolah untuk menghasilkan output.
- [generate_one()](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.AsyncRolloutLoop.generate_one): satu rollout penuh, yang memanggil [generate_one_turn()](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.AsyncRolloutLoop.generate_one_turn) untuk setiap permintaan sampling.
- Grup dari `num_generations` rollout diberi skor: reward-nya adalah jumlah dari `reward_funcs` trainer, dari lingkungan yang mendefinisikan `get_reward`, dan dari [Rollout](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.Rollout)`.reward`. Kemudian [compute_advantages()](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.AsyncRolloutLoop.compute_advantages) dijalankan sekali per grup.

[setup()](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.AsyncRolloutLoop.setup) dan [close()](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.AsyncRolloutLoop.close) membuat dan melepaskan sumber daya pada event loop dari loop, seperti klien HTTP. Hook dapat membaca `self.config` (subkelas dari [AsyncGRPOConfig](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.AsyncGRPOConfig) dapat membawa field miliknya sendiri) dan `self.tokenizer`. Karena loop dibangun dalam proses yang di-spawn, subkelas tersebut harus dapat diimpor (didefinisikan pada level modul).

#### filter_prompt[[trl.trainer.async_grpo_trainer.AsyncRolloutLoop.filter_prompt]]

```python
filter_prompt(row_index: int, row: dict[str, typing.Any], epoch: int)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_trainer.py#L1486)

**Parameter:**

row_index (`int`) : Indeks baris dalam dataset pelatihan.

row (`dict[str, Any]`) : Baris dataset.

epoch (`int`) : Jumlah penerusan penuh pada dataset sebelum penerusan 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[[trl.trainer.async_grpo_trainer.AsyncRolloutLoop.generate_one]]

```python
generate_one(prompt: list[dict[str, str]], tools: list[collections.abc.Callable], group_id: int = 0)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_trainer.py#L1532)

**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*, defaultnya `0`) : Pengidentifikasi grup tempat rollout berada.

**Mengembalikan:** [Rollout](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.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()](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.AsyncRolloutLoop.generate_one_turn) dan menjalankan panggilan tool yang dikandungnya, hingga model berhenti memanggil tool atau `max_tool_calling_iterations` tercapai. Override-nya untuk menghasilkan dengan cara berbeda, misalnya dengan kerangka kerja agen. Kembalikan setiap permintaan sampling di `Rollout.turns`, karena urutan pelatihan dibangun dari mereka, dan atur `Rollout.reward` untuk menilai rollout di sini.

#### generate_one_turn[[trl.trainer.async_grpo_trainer.AsyncRolloutLoop.generate_one_turn]]

```python
generate_one_turn(prompt_ids: list[int])
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_trainer.py#L1649)

**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[[trl.trainer.async_grpo_trainer.AsyncRolloutLoop.compute_advantages]]

```python
compute_advantages(group: RolloutGroup)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_trainer.py#L1782)

**Parameter:**

group ([RolloutGroup](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.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 dikembalikannya.

#### setup[[trl.trainer.async_grpo_trainer.AsyncRolloutLoop.setup]]

```python
setup()
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_trainer.py#L1004)

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[[trl.trainer.async_grpo_trainer.AsyncRolloutLoop.close]]

```python
close()
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_trainer.py#L1010)

Lepaskan apa yang dibuat oleh [setup()](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.AsyncRolloutLoop.setup). Berjalan saat loop berhenti, termasuk saat terjadi kegagalan. Secara default tidak melakukan apa pun.

## Rollout[[trl.trainer.async_grpo_trainer.Rollout]]

#### trl.trainer.async_grpo_trainer.Rollout[[trl.trainer.async_grpo_trainer.Rollout]]

```python
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 = 0, tool_failure_count: int = 0, reward: float | None = None, rollout_id: str = <factory>)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_trainer.py#L558)

**Parameter:**

completion (`list[dict[str, Any]]`) : Pesan yang dihasilkan setelah prompt, dalam format percakapan. Diteruskan ke fungsi reward sebagai `completions`.

completion_ids (`list[int]`) : ID token dari kelengkapan 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*, defaultnya `0`) : Jumlah pemanggilan alat yang dilakukan selama rollout.

tool_failure_count (`int`, *opsional*, defaultnya `0`) : Jumlah panggilan alat tersebut 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 debugging. Secara default menggunakan id hex acak baru.

Satu rollout yang selesai, sebagaimana dikembalikan oleh [generate_one()](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.AsyncRolloutLoop.generate_one).

## TurnRecord[[trl.trainer.async_grpo_trainer.TurnRecord]]

#### trl.trainer.async_grpo_trainer.TurnRecord[[trl.trainer.async_grpo_trainer.TurnRecord]]

```python
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 = None, output_sampling_mask: list[list[int]] | None = None, output_sampler_logprobs: list[dict[int, float]] | None = None)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_trainer.py#L424)

**Parameter:**

prompt_ids (`list[int]`) : ID token dari prompt lengkap yang dikirim untuk giliran ini, termasuk setiap giliran sebelumnya dalam percakapan.

output_ids (`list[int]`) : ID token yang dihasilkan oleh sampler.

output_log_probs (`list[float]`, *opsional*, defaultnya `[]`) : Probabilitas log dari setiap token dalam `output_ids`. Wajib diisi jika salah satunya 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 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[[trl.trainer.async_grpo_trainer.RolloutGroup]]

#### trl.trainer.async_grpo_trainer.RolloutGroup[[trl.trainer.async_grpo_trainer.RolloutGroup]]

```python
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: int, group_id: int, row_index: int, env_rewards: list[tuple[type, float] | None], rollout_rewards: list[float | None], queued_at: float = 0.0, rewards: numpy.ndarray | None = None)
```

[Sumber](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/async_grpo_trainer.py#L592)

**Parameter:**

prompts (`list[list[dict[str, Any]]]`) : Prompt dari setiap rollout.

reward_kwargs (`dict[str, list[Any]]`) : Kolom lain dari baris dataset prompt, diteruskan ke fungsi reward sebagai argumen kata kunci.

completions (`list[list[dict[str, Any]]]`) : Pesan penyelesaian dari setiap rollout.

completions_ids (`list[list[int]]`) : ID token penyelesaian 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 dalam 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](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.Rollout)`.reward` dari setiap rollout.

queued_at (`float`, *opsional*, defaultnya `0.0`) : `time.monotonic()` saat grup ditambahkan ke antrean untuk penilaian.

rewards (`np.ndarray`, *opsional*) : Total reward dari setiap rollout, dijumlahkan dari semua sumber reward, NaN jika tidak ada sumber yang memberikan skor. Diatur sebelum [compute_advantages()](/docs/trl/v1.18.0/id/async_grpo_trainer#trl.trainer.async_grpo_trainer.AsyncRolloutLoop.compute_advantages) dipanggil.

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

