GRPO Trainer

Ikhtisar

TRL mendukung GRPO Trainer untuk melatih model bahasa, seperti yang dijelaskan dalam makalah DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models oleh Zhihong Shao, Peiyi Wang, Qihao Zhu, Runxin Xu, Junxiao Song, Mingchuan Zhang, Y. K. Li, Y. Wu, Daya Guo.

Abstrak dari makalah tersebut adalah sebagai berikut:

Penalaran matematika merupakan tantangan signifikan bagi model bahasa karena sifatnya yang kompleks dan terstruktur. Dalam makalah ini, kami memperkenalkan DeepSeekMath 7B, yang melanjutkan pra-pelatihan DeepSeek-Coder-Base-v1.5 7B dengan 120B token terkait matematika yang bersumber dari Common Crawl, bersama dengan data bahasa alami dan kode. DeepSeekMath 7B telah mencapai skor mengesankan sebesar 51,7% pada benchmark MATH tingkat kompetisi tanpa mengandalkan toolkit eksternal dan teknik voting, mendekati tingkat kinerja Gemini-Ultra dan GPT-4. Self-consistency atas 64 sampel dari DeepSeekMath 7B mencapai 60,9% pada MATH. Kemampuan penalaran matematika dari DeepSeekMath dikaitkan dengan dua faktor kunci: Pertama, kami memanfaatkan potensi signifikan dari data web yang tersedia secara publik melalui pipeline seleksi data yang dirancang dengan cermat. Kedua, kami memperkenalkan Group Relative Policy Optimization (GRPO), sebuah varian dari Proximal Policy Optimization (PPO), yang meningkatkan kemampuan penalaran matematika sambil secara bersamaan mengoptimalkan penggunaan memori dari PPO.

Metode pasca-pelatihan ini disumbangkan oleh Quentin Gallouédec.

Mulai cepat

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

Berikut adalah skrip untuk melatih model. accuracy_reward memerlukan math-verify, yang dapat Anda instal dengan pip install trl[math_verify].

# train_grpo.py
from datasets import load_dataset
from trl import GRPOTrainer
from trl.rewards import accuracy_reward

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

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

Jalankan skrip menggunakan perintah berikut:

accelerate launch train_grpo.py

Distribusi di 8 GPU, pelatihan memakan waktu sekitar 1 hari.

Catatan: Kurva reward di atas dihasilkan dengan Qwen/Qwen2-0.5B-Instruct. Hasil dengan Qwen/Qwen2.5-0.5B-Instruct akan serupa secara kualitatif.

Menggali lebih dalam ke metode GRPO

GRPO adalah algoritma pembelajaran online, yang berarti ia meningkatkan secara iteratif dengan menggunakan data yang dihasilkan oleh model terlatih itu sendiri selama pelatihan. Intuisi di balik tujuan GRPO adalah memaksimalkan keuntungan dari penyelesaian yang dihasilkan, sambil memastikan bahwa model tetap dekat dengan kebijakan referensi. Untuk memahami cara kerja GRPO, hal ini dapat dipecah menjadi empat langkah utama: menghasilkan penyelesaian, menghitung keuntungan, mengestimasi divergensi KL, dan menghitung loss.

Membuat kelengkapan

Pada setiap langkah pelatihan, kami mengambil sampel batch prompt dan menghasilkan satu set $G$ komplemen untuk setiap prompt (dilambangkan sebagai $o_i$).

Menghitung keuntungan

Untuk masing-masing dari $G$ urutan, kami menghitung reward menggunakan model reward atau fungsi reward. Untuk selaras dengan sifat komparatif model reward—yang biasanya dilatih pada dataset perbandingan antara output untuk pertanyaan yang sama—advantage dihitung untuk mencerminkan perbandingan relatif ini. Dinormalisasi sebagai berikut: $$\hat{A}_{i,t} = \frac{r_i - \text{mean}(\mathbf{r})}{\text{std}(\mathbf{r})}$$

Pendekatan ini memberikan nama pada metode tersebut: Group Relative Policy Optimization (GRPO).

Ditunjukkan dalam makalah Understanding R1-Zero-Like Training: A Critical Perspective bahwa penskalaan dengan $\text{std}(\mathbf{r})$ dapat menyebabkan bias tingkat kesulitan per pertanyaan. Anda dapat menonaktifkan penskalaan ini dengan mengatur scale_rewards=False di GRPOConfig. Perlu dicatat bahwa menonaktifkan penskalaan berbasis std juga menghilangkan normalisasi varians, sehingga magnitudo pembaruan bergantung langsung pada skala reward mentah dan komposisi batch.

Seperti ditunjukkan dalam Bagian I: Trik atau Jebakan? Pendalaman tentang RL untuk Penalaran LLM (Lite PPO), menghitung rata-rata pada level lokal (grup) dan deviasi standar pada level global (batch) memungkinkan pembentukan reward yang lebih robust. Anda dapat menggunakan strategi penskalaan ini dengan mengatur scale_rewards="batch" di GRPOConfig.

Mengestimasi divergensi KL

Divergensi KL diperkirakan menggunakan aproksimator yang diperkenalkan oleh Schulman et al. (2020). Aproksimator tersebut didefinisikan sebagai berikut: $$\mathbb{D}_{\text{KL}}\left[\pi_\theta \|\pi_{\text{ref}}\right] = \frac{\pi_{\text{ref}}(o_{i,t} \mid q, o_{i,<t})}{\pi_\theta(o_{i,t} \mid q, o_{i,<t})} - \log \frac{\pi_{\text{ref}}(o_{i,t} \mid q, o_{i,<t})}{\pi_\theta(o_{i,t} \mid q, o_{i,<t})} - 1,$$

Menghitung loss

Tujuannya adalah memaksimalkan keuntungan sambil memastikan model tetap dekat dengan kebijakan referensi. Oleh karena itu, loss didefinisikan sebagai berikut: $$\mathcal{L}_{\text{GRPO}}(\theta) = -\frac{1}{\sum_{i=1}^G |o_i|} \sum_{i=1}^G \sum_{t=1}^{|o_i|} \left[ \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\left[\pi_\theta(o_{i,t} \mid q, o_{i,< t})\right]_{\text{no grad}}} \hat{A}_{i,t} - \beta \mathbb{D}_{\text{KL}}\left[\pi_\theta \| \pi_{\text{ref}}\right] \right],$$

di mana suku pertama mewakili keuntungan yang diskalakan dan suku kedua menghukum penyimpangan dari kebijakan referensi melalui divergensi KL.

Perhatikan bahwa dibandingkan dengan formulasi asli dalam DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, kami tidak melakukan penskalaan dengan $\frac{1}{|o_i|}$ karena ditunjukkan dalam makalah Understanding R1-Zero-Like Training: A Critical Perspective bahwa hal ini memperkenalkan bias panjang pada tingkat respons. Detail lebih lanjut ada di tipe loss.

Perhatikan bahwa dibandingkan dengan formulasi asli dalam DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, kami menggunakan $\beta = 0.0$ secara default, yang berarti bahwa istilah divergensi KL tidak digunakan. Pilihan ini didorong oleh beberapa studi terbaru (misalnya, Open-Reasoner-Zero: An Open Source Approach to Scaling Up Reinforcement Learning on the Base Model) yang telah menunjukkan bahwa istilah divergensi KL tidak esensial untuk pelatihan dengan GRPO. Akibatnya, telah menjadi praktik umum untuk mengecualikannya (misalnya Understanding R1-Zero-Like Training: A Critical Perspective, DAPO: An Open-Source LLM Reinforcement Learning System at Scale). Jika Anda ingin menyertakan istilah divergensi KL, Anda dapat mengatur beta di GRPOConfig ke nilai yang tidak nol.

Dalam paper aslinya, formulasi ini digeneralisasi untuk memperhitungkan beberapa pembaruan setelah setiap generasi (dilambangkan dengan $\mu$, dapat diatur dengan num_iterations di GRPOConfig) dengan memanfaatkan objektif surogat yang dipangkas: $$\mathcal{L}_{\text{GRPO}}(\theta) = - \frac{1}{\sum_{i=1}^G |o_i|} \sum_{i=1}^G \sum_{t=1}^{|o_i|} \left[ \min \left( \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\theta_{\text{old}}}(o_{i,t} \mid q, o_{i,< t})} \hat{A}_{i,t}, \, \text{clip}\left( \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\theta_{\text{old}}}(o_{i,t} \mid q, o_{i,< t})}, 1 - \epsilon, 1 + \epsilon \right) \hat{A}_{i,t} \right) - \beta \mathbb{D}_{\text{KL}}\left[\pi_\theta \| \pi_{\text{ref}}\right] \right],$$

di mana $\text{clip}(\cdot, 1 - \epsilon, 1 + \epsilon)$ memastikan bahwa pembaruan tidak menyimpang secara berlebihan dari kebijakan referensi dengan membatasi rasio kebijakan antara $1 - \epsilon$ dan $1 + \epsilon$. Ketika $\mu = 1$ (default di TRL), tujuan pengganti yang dipangkas disederhanakan menjadi tujuan asli.

Jenis-jenis Loss

Beberapa formulasi dari fungsi tujuan telah diusulkan dalam literatur. Awalnya, fungsi tujuan GRPO didefinisikan sebagai berikut: $$\mathcal{L}_{\text{GRPO}}(\theta) = - \frac{1}{G} \sum_{i=1}^G \frac{1}{|o_i|} \sum_{t=1}^{|o_i|} l_{i,t},$$

di mana $$l_{i,t} = \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\left[\pi_\theta(o_{i,t} \mid q, o_{i,< t})\right]_{\text{no grad}}} \hat{A}_{i,t} - \beta \mathbb{D}_{\text{KL}}\left[\pi_\theta \| \pi_{\text{ref}}\right].$$

Kertas DAPO menyoroti keterbatasan loss tingkat sampel dari algoritma GRPO dalam skenario long-CoT, di mana respons yang lebih panjang kurang dihukum, sehingga menghasilkan output dengan kualitas yang lebih buruk. Solusi yang diusulkan adalah normalisasi tingkat token, yang menangani urutan yang lebih panjang dengan lebih baik dengan memberikan imbalan yang lebih seimbang untuk setiap token, terlepas dari panjang respons: $$\mathcal{L}_{\text{DAPO}}(\theta) = - \frac{1}{\sum_{i=1}^G |o_i|} \sum_{i=1}^G \sum_{t=1}^{|o_i|} l_{i,t},$$

Untuk menggunakan formulasi ini, atur loss_type="dapo" di GRPOConfig.

Selain itu, dalam makalah Understanding R1-Zero-Like Training: A Critical Perspective dibuktikan bahwa formulasi awal GRPO memperkenalkan bias panjang respons. Mereka menunjukkan bahwa meskipun formulasi DAPO mengurangi bias ini, bias tersebut tidak sepenuhnya dihilangkan. Untuk sepenuhnya menghilangkan bias ini, mereka mengusulkan pembagian dengan konstanta alih-alih panjang sekuens, yang menghasilkan formulasi berikut: $$\mathcal{L}_{\text{Dr. GRPO}}(\theta) = - \frac{1}{LG} \sum_{i=1}^G \sum_{t=1}^{|o_i|} l_{i,t},$$

Konstanta ini disarankan untuk menjadi panjang penyelesaian maksimum. Untuk menggunakan formulasi ini, atur loss_type="dr_grpo" di GRPOConfig.

Sebagai alternatif, dalam makalah SAPO, tim Qwen mengusulkan penggantian mekanisme pemotongan “keras” pada GRPO dengan mekanisme gerbang lunak yang halus dan dikendalikan suhu. Sementara GRPO menolkan gradien ketika kebijakan menyimpang terlalu jauh dari referensi, SAPO menggunakan wilayah kepercayaan lunak yang secara halus meredam bobot gradien. Hal ini memungkinkan model untuk mempertahankan sinyal pembelajaran yang berguna dari token “dekat-on-policy” sambil menekan noise dari penyimpangan ekstrem.

Fungsi loss didefinisikan sebagai: $$\mathcal{L}_{\text{SAPO}}(\theta) = - \frac{1}{G} \sum_{i=1}^G \frac{1}{|o_i|} \sum_{t=1}^{|o_i|} f_{i,t} \left( \frac{\pi_\theta(o_{i,t} | q, o_{i,<t})}{\pi_{\theta_{old}}(o_{i,t} | q, o_{i,<t})} \right) \hat{A}_{i,t}$$

Fungsi soft-gating $f_{i,t}$ didefinisikan menggunakan fungsi sigmoid $\sigma$ sebagai berikut: $$f_{i,t}(x) = \sigma \left( \tau_{i,t} (x - 1) \right) \cdot \frac{4}{\tau_{i,t}}$$

Suhu $\tau_{i,t}$ dipilih berdasarkan tanda dari keuntungan $\hat{A}_{i,t}$: $$\tau_{i,t} = \begin{cases} \tau_{\text{pos}}, & \text{if } \hat{A}_{i,t} > 0 \\ \tau_{\text{neg}}, & \text{otherwise} \end{cases}$$

Mereka merekomendasikan penggunaan suhu asimetris, $\tau_{\text{neg}} > \tau_{\text{pos}}$ (nilai default adalah $\tau_{\text{pos}}=1.0, \tau_{\text{neg}}=1.05$ ). Hal ini memastikan bahwa model dihukum lebih ketat untuk aksi “buruk” guna mencegah ketidakstabilan, sementara lebih longgar untuk aksi “baik”.

Untuk menggunakan formulasi ini, atur loss_type="sapo" di GRPOConfig.

Metrik yang dicatat

Selama pelatihan dan evaluasi, kami mencatat metrik berikut:

• num_tokens: Total jumlah token yang diproses sejauh ini, termasuk prompt dan completion. Saat menggunakan tools, hanya token non-tool yang dihitung.
• step_time: Rata-rata waktu (dalam detik) yang dibutuhkan per langkah pelatihan (termasuk generasi).
• 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 dipotong (clipped).
• tools/call_frequency: Rata-rata jumlah pemanggilan alat per penyelesaian dalam batch generasi. Dicatat hanya ketika tools disediakan.
• tools/failure_frequency: Proporsi pemanggilan alat yang gagal (alat tidak ditemukan, memicu pengecualian, atau tipe pemanggilan tidak didukung). Nilainya 0.0 jika tidak ada alat yang dipanggil. Dicatat hanya ketika tools disediakan.
• rewards/{reward_func_name}/mean: Rata-rata reward dari fungsi reward tertentu. Ketika lingkungan memiliki reward melalui get_reward, {reward_func_name} adalah nama kelas lingkungan tersebut.
• rewards/{reward_func_name}/std: Deviasi standar dari reward yang dihasilkan oleh fungsi reward tertentu.
• reward: Rata-rata keseluruhan reward setelah menjumlahkan reward di seluruh fungsi (diberi bobot oleh reward_weights).
• reward_std: Standar deviasi dari total reward di seluruh fungsi (diberat oleh reward_weights), dihitung pada batch penuh.
• frac_reward_zero_std: Proporsi sampel dalam batch generasi yang memiliki standar deviasi reward nol, yang mengindikasikan bahwa terdapat sedikit keberagaman untuk prompt tersebut (semua jawaban benar atau salah).
• 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 penyelesaian. Nilai yang meningkat menunjukkan ketidakcocokan pelatihan-inferensi yang melebar. Dicatat hanya ketika use_vllm=True dan vllm_importance_sampling_correction=True.
• sampling/sampling_logp_difference/max: Selisih absolut terbesar seperti itu. Dicatat hanya ketika use_vllm=True dan vllm_importance_sampling_correction=True.
• sampling/importance_sampling_ratio/min: Rasio importance sampling terkecil yang digunakan untuk mengoreksi ketidakcocokan antara pelatihan dan inferensi, setelah kendala yang dipilih oleh vllm_importance_sampling_mode diterapkan (dipangkas ke [C_min, C_max] untuk mode *_truncate, diatur ke nol untuk mode *_mask). Dihitung pada token penyelesaian, atau pada urutan untuk mode sequence_*. Dicatat hanya ketika use_vllm=True dan vllm_importance_sampling_correction=True.
• sampling/importance_sampling_ratio/mean: Rasio importance sampling terikat rata-rata. Dicatat hanya ketika use_vllm=True dan vllm_importance_sampling_correction=True.
• sampling/importance_sampling_ratio/max: Rasio importance sampling terkonstrain terbesar. Dicatat hanya ketika use_vllm=True dan vllm_importance_sampling_correction=True.
• policy_loss: Nilai kerugian gradien kebijakan (sebelum bonus entropi apa pun). Dicatat ketika entropy_coef tidak nol atau use_adaptive_entropy=True.
• entropy: Entropi rata-rata dari prediksi token di seluruh kelengkapan yang dihasilkan. (Jika mask_truncated_completions=True, token dari urutan yang dimasker dikecualikan.)
• entropy_coef: Koefisien regularisasi entropi saat ini. Dicatat ketika entropy_coef tidak nol atau use_adaptive_entropy=True. Diperbarui sekali per langkah optimizer ketika use_adaptive_entropy=True.
• 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.
• kl: Rata-rata divergensi KL antara model dan model referensi, dihitung di atas kelengkapan yang dihasilkan. Dicatat hanya jika beta tidak nol.
• clip_ratio/region_mean: Rasio token (atau urutan, jika importance_sampling_level="sequence") probabilitas di mana tujuan GRPO dipangkas agar tetap berada dalam wilayah kepercayaan: $\text{clip}\left( r_{i,t}(\theta), 1 - \epsilon_\mathrm{low}, 1 + \epsilon_\mathrm{high} \right)\,, \quad r_{i,t}(\theta) = \frac{\pi_\theta(o_{i,t} \mid q, o_{i,< t})}{\pi_{\theta_{\text{old}}}(o_{i,t} \mid q, o_{i,< t})}$. Nilai yang lebih tinggi berarti lebih banyak token yang dipangkas, yang membatasi seberapa besar kebijakan $\pi_\theta$ dapat berubah.
• clip_ratio/low_mean: Rata-rata rasio probabilitas token (atau urutan, jika importance_sampling_level="sequence") yang dipangkas pada batas bawah trust region: $r_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}$.
• clip_ratio/low_min: Fraksi token per-penyelesaian terkecil (atau urutan itu sendiri, jika importance_sampling_level="sequence") dipangkas pada batas bawah trust region: $r_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}$.
• clip_ratio/high_mean: Rata-rata rasio probabilitas token (atau urutan, jika importance_sampling_level="sequence") yang dipangkas pada batas atas trust region: $r_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}$.
• clip_ratio/high_max: Fraksi token terbesar per penyelesaian (atau urutan itu sendiri, jika importance_sampling_level="sequence") dipangkas pada batas atas trust region: $r_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}$.
• cispo_clip_ratio: Rasio token (atau urutan, jika importance_sampling_level="sequence") bobot importance sampling yang dipangkas pada epsilon_high sambil memiliki keuntungan positif: $r_{i,t}(\theta) > \epsilon_\mathrm{high}$. Dicatat hanya ketika loss_type="cispo".
• vespo/phi_seq_mean: Nilai rata-rata dari pembobotan Gamma VESPO $\varphi(w)$ yang diterapkan pada bobot kepentingan tingkat sekuens. Nilai di bawah 1.0 berarti sekuens diberi bobot lebih rendah. Dicatat hanya ketika loss_type="vespo".

Kustomisasi

Percepat pelatihan dengan generasi yang didukung vLLM

Generasi sering menjadi bottleneck utama saat melatih dengan metode online. Untuk mempercepat generasi, Anda dapat menggunakan vLLM, mesin inferensi ber-throughput tinggi dan ber-latensi rendah untuk LLM. Untuk mengaktifkannya, pertama instal paketnya dengan

pip install trl[vllm]

Kami mendukung dua cara penggunaan vLLM selama pelatihan: mode server dan mode colocate.

Secara default, sequence-level Masked Importance Sampling (vllm_importance_sampling_mode="sequence_mask") diaktifkan untuk generasi vLLM guna mengatasi ketidakcocokan antara generasi dan pelatihan yang terjadi saat menggunakan framework yang berbeda. Fitur ini dapat dimatikan dengan mengatur vllm_importance_sampling_correction=False. Untuk informasi lebih lanjut, lihat Masked Importance Sampling dan Sequence-level Importance Sampling

Opsi 1: Mode Colocate

Pada mode ini, vLLM berjalan di dalam proses trainer dan berbagi memori GPU dengan model pelatihan. Hal ini menghindari peluncuran server terpisah dan dapat meningkatkan pemanfaatan GPU, tetapi dapat menyebabkan perebutan memori pada GPU pelatihan. Ini adalah mode default.

from trl import GRPOConfig

training_args = GRPOConfig(
    ...,
    use_vllm=True,  # vllm_mode="colocate" by default
)

Opsi 2: Mode server

Pada mode ini, vLLM berjalan dalam proses terpisah (dan menggunakan GPU terpisah) serta berkomunikasi dengan trainer melalui HTTP. Ini ideal jika Anda memiliki GPU khusus untuk inferensi.

1. Mulai server vLLM:

   Disalin

   VLLM_SERVER_DEV_MODE=1 vllm serve <model_name> \
       --weight-transfer-config '{"backend": "nccl"}' \
       --logprobs-mode processed_logprobs \
       --max-logprobs -1

2. Aktifkan mode server di skrip pelatihan Anda:

   Disalin

   from trl import GRPOConfig
   
   training_args = GRPOConfig(
       ...,
       use_vllm=True,
       vllm_mode="server",
   )

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.

Tergantung pada ukuran model dan kebutuhan memori GPU keseluruhan untuk pelatihan, Anda mungkin perlu menyesuaikan parameter vllm_gpu_memory_utilization di GRPOConfig untuk menghindari underutilization atau error out-of-memory.

Kami menyediakan HF Space untuk membantu memperkirakan pemanfaatan memori GPU yang direkomendasikan berdasarkan konfigurasi model dan pengaturan eksperimen Anda. Cukup gunakan sebagai berikut untuk mendapatkan rekomendasi vllm_gpu_memory_utilization:

Jika nilai yang direkomendasikan tidak berfungsi di lingkungan Anda, kami menyarankan untuk menambahkan buffer kecil (misalnya, +0.05 atau +0.1) ke nilai yang direkomendasikan untuk memastikan stabilitas.

Jika Anda masih mengalami error out-of-memory, atur vllm_enable_sleep_mode ke True sehingga parameter vllm dan cache akan di-offload selama langkah optimasi. Untuk informasi lebih lanjut, lihat Mengurangi Penggunaan Memori dengan vLLM Sleep Mode.

Secara default, GRPO menggunakan MASTER_ADDR=localhost dan MASTER_PORT=12345 untuk vLLM, tetapi Anda dapat menimpa nilai-nilai ini dengan mengatur variabel lingkungan secara sesuai.

Untuk informasi lebih lanjut, lihat Mempercepat pelatihan dengan vLLM.

Mengatasi Ketidakcocokan antara Pelatihan dan Inferensi

Meskipun vLLM sangat mempercepat inferensi, ia juga memisahkan mesin inferensi dari mesin pelatihan. Secara teori, mesin-mesin ini identik secara matematis, namun dalam praktiknya mereka dapat menghasilkan output yang berbeda akibat efek presisi dan optimasi yang spesifik pada perangkat keras. Divergensi ini mencerminkan tujuan optimasi yang berbeda dari kedua sistem tersebut. Mesin inferensi bertujuan untuk memaksimalkan throughput sampling, yang biasanya diukur dalam token per detik, sambil mempertahankan fidelitas sampling yang dapat diterima. Sebaliknya, framework pelatihan berfokus pada stabilitas numerik dan presisi untuk komputasi gradien, sering kali menggunakan format presisi yang lebih tinggi seperti FP32 untuk bobot master dan status optimizer. Prioritas dan kendala yang berbeda ini memperkenalkan ketidakcocokan yang tidak terhindarkan, meskipun halus, antara pelatihan dan inferensi.

Ketidakcocokan ini menyebabkan pembaruan gradien yang bias, yang telah diamati dapat mendestabilkan pelatihan ([1][2][3][4][5]). Untuk kesederhanaan, pertimbangkan gradien kebijakan REINFORCE: $$\nabla_\theta \mathcal{J}(x,\theta) = \mathbb{E}_{y \sim \pi^\text{train}(\cdot \mid x,\theta)} \left[ \nabla_\theta \log \pi^\text{train}(y \mid x,\theta) \cdot R(x,y) \right]$$

Di sini $x$ menyatakan prompt yang diambil dari beberapa distribusi data, dan $\pi^\text{train}$ adalah kebijakan yang diimplementasikan oleh mesin pelatihan. Dengan vLLM dalam alur kerja, kita memperoleh kebijakan inferensi terpisah $\pi^\text{inference}$, sehingga gradien kebijakan efektif menjadi $$\nabla_\theta \mathcal{J}_{\text{biased}}(x,\theta) = \mathbb{E}_{y \sim \pi^\text{inference}(\cdot \mid x,\theta)} \left[ \nabla_\theta \log \pi^\text{train}(y \mid x,\theta) \cdot R(x,y) \right].$$

Hal ini mengubah masalah RL on policy menjadi masalah off policy.

Cara standar untuk mengoreksi pergeseran distribusi ini adalah importance sampling (IS). Kami menyediakan dua varian IS: Truncated Importance Sampling (TIS) dan Masked Importance Sampling (MIS). Kedua varian ini dapat diterapkan baik pada level token maupun level sekuens. Misalkan $\rho$ menyatakan bobot importance, misalnya $\rho_t$ per token atau $\rho_{\text{seq}}$ per sekuens. Di bawah TIS, rasio di luar rentang [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] dipangkas, $$\rho \leftarrow \text{clip}(\rho, C_{\min}, C_{\max}).$$

Asli makalah TIS mengusulkan mekanisme pemotongan batas atas tunggal, yaitu, $\min(\rho, C_{\max})$. Implementasi di TRL menggeneralisasi hal ini dengan juga memperkenalkan batas bawah, menghasilkan formulasi dua sisi yang ditunjukkan di atas, terinspirasi oleh IcePop metode.
Perhatikan bahwa di IcePop, batas-batas tersebut diberi label sebagai $\alpha$ dan $\beta$ sedangkan di TRL kami menggunakan $C_{\min}$ dan $C_{\max}$.

Di bawah MIS, rasio di luar rentang ini diatur menjadi nol, sehingga sampel-sampel tersebut tidak berkontribusi terhadap gradien. Dengan kata lain, sampel outlier diberi bobot lebih rendah di bawah TIS dan dibuang di bawah MIS. Flag konfigurasi vllm_importance_sampling_mode memilih kedua varian IS (masking atau truncation) dan granularitas (level token atau level sequence).

Importance sampling adalah respons algoritmik yang berprinsip terhadap ketidakcocokan antara pelatihan dan inferensi. Namun, terdapat juga pendekatan yang lebih langsung yang berupaya mengurangi ketidakcocokan antara kedua mesin tersebut. Sebagian besar dari pendekatan ini merupakan solusi rekayasa. Misalnya, MiniMax M1 menggunakan kepala model bahasa FP32 di mesin inferensi. Thinking Machines telah mengeksplorasi kernel inferensi deterministik, meskipun hal ini datang dengan biaya efisiensi yang signifikan. vLLM telah menunjukkan kebijakan yang konsisten secara bitwise dengan membangun di atas kernel deterministik yang invarian terhadap batch dari Thinking Machines, tetapi per November 2025 masih terdapat penalti throughput yang substansial dibandingkan dengan inferensi vLLM standar.

Percepat pelatihan dengan continuous batching transformers

Sebagai alternatif vLLM, Anda dapat menggunakan mesin continuous batching bawaan transformers untuk generasi yang lebih cepat. Continuous batching menghapus urutan yang sudah selesai dari batch secara langsung, bukan menunggu yang paling lambat untuk selesai. Untuk tugas dengan panjang penyelesaian yang bervariasi (misalnya, penalaran matematika), hal ini menghasilkan generasi yang lebih cepat dan penggunaan VRAM yang lebih rendah dibandingkan generate() default pada ukuran batch besar (N≥32).

Continuous batching adalah peningkatan langsung tanpa perlu pengaturan server atau sinkronisasi bobot. Proses ini berjalan dalam proses dan sangat cocok untuk pelatihan single-GPU atau lingkungan dengan keterbatasan memori. Untuk throughput generasi maksimum dalam skala besar, gunakan vLLM sebagai gantinya.

from trl import GRPOConfig

training_args = GRPOConfig(
    ...,
    use_transformers_continuous_batching=True,
    transformers_continuous_batching_config={
        "use_cuda_graph": False,
        "max_memory_percent": 0.4,  # lower values leave more VRAM for the training backward pass
    },
)

TRL menetapkan max_memory_percent secara default ke 0.5 (bukan 0.9 seperti pada transformers) untuk menyisakan VRAM yang cukup bagi backward pass pelatihan. Turunkan nilainya ke 0.3–0.4 untuk batch generasi besar (N≥32) atau jika Anda melihat error out-of-memory.

Untuk contoh pelatihan lengkap, lihat examples/grpo_continuous_batching/grpo_continuous_batching.py.

GRPO berskala besar: latih model 70B+ di beberapa node

Saat melatih model besar seperti Qwen2.5-72B, Anda memerlukan beberapa optimasi kunci untuk membuat pelatihan efisien dan dapat diskalakan di beberapa GPU dan node. Optimasi ini meliputi:

• DeepSpeed ZeRO Stage 3: ZeRO memanfaatkan data parallelism untuk mendistribusikan state model (weights, gradients, optimizer states) ke beberapa GPU dan CPU, sehingga mengurangi kebutuhan memori dan komputasi pada setiap perangkat. Karena model besar tidak muat di satu GPU, penggunaan ZeRO Stage 3 diperlukan untuk melatih model semacam itu. Untuk detail lebih lanjut, lihat DeepSpeed Integration.
• Accelerate: Accelerate adalah pustaka yang menyederhanakan pelatihan terdistribusi di beberapa GPU dan node. Pustaka ini menyediakan API sederhana untuk meluncurkan pelatihan terdistribusi dan menangani kompleksitas pelatihan terdistribusi, seperti paralelisme data, akumulasi gradien, dan pemuatan data terdistribusi. Untuk detail lebih lanjut, lihat Distributing Training.
• vLLM: Lihat bagian sebelumnya tentang cara menggunakan vLLM untuk mempercepat generasi.

Di bawah ini adalah contoh skrip SLURM untuk melatih model 70B dengan GRPO pada beberapa node. Skrip ini melatih model pada 4 node dan menggunakan node ke-5 untuk generasi yang didukung vLLM.

#!/bin/bash
#SBATCH --nodes=5
#SBATCH --gres=gpu:8

# Get the list of allocated nodes
NODELIST=($(scontrol show hostnames $SLURM_JOB_NODELIST))

# Assign the first 4 nodes for training and the 5th node for vLLM
TRAIN_NODES="${NODELIST[@]:0:4}"  # Nodes 0, 1, 2, 3 for training
VLLM_NODE="${NODELIST[4]}"  # Node 4 for vLLM

# Run training on the first 4 nodes (Group 1)
srun --nodes=4 --ntasks=4 --nodelist="${NODELIST[@]:0:4}" accelerate launch \
     --config_file examples/accelerate_configs/deepspeed_zero3.yaml \
     --num_processes 32 \
     --num_machines 4 \
     --main_process_ip ${NODELIST[0]} \
     --machine_rank $SLURM_PROCID \
     --rdzv_backend c10d \
     train_grpo.py \
     --server_ip $VLLM_NODE &

# Run vLLM server on the 5th node (Group 2)
srun --nodes=1 --ntasks=1 --nodelist="${NODELIST[4]}" env VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen2.5-72B --tensor-parallel-size 8 \
    --weight-transfer-config '{"backend": "nccl"}' \
    --logprobs-mode processed_logprobs \
    --max-logprobs -1 &

wait

import argparse

from datasets import load_dataset
from trl import GRPOTrainer, GRPOConfig
from trl.rewards import accuracy_reward

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--vllm_server_host", type=str, default="", help="The server IP")
    args = parser.parse_args()

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

    training_args = GRPOConfig(
        per_device_train_batch_size=4,
        use_vllm=True,
        vllm_mode="server",
        vllm_server_host=args.vllm_server_host.replace("ip-", "").replace("-", "."),  # from ip-X-X-X-X to X.X.X.X
    )

    trainer = GRPOTrainer(
        model="Qwen/Qwen2.5-72B",
        args=training_args,
        reward_funcs=accuracy_reward,
        train_dataset=dataset
    )
    trainer.train()

if __name__=="__main__":
    main()

Menggunakan fungsi reward kustom

GRPOTrainer mendukung penggunaan fungsi reward kustom sebagai pengganti model reward padat. 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 asinkron, fungsi-fungsi tersebut ditunggu secara bersamaan (dijalankan paralel melalui asyncio.gather) sehingga latensinya 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),
     • trainer_state (TrainerState): Status terkini dari trainer. Hal ini dapat digunakan untuk mengimplementasikan fungsi reward dinamis, seperti pembelajaran kurikulum, di mana reward disesuaikan berdasarkan kemajuan pelatihan.
     • log_extra: callable log_extra(column: str, values: list) untuk menambahkan kolom tambahan ke tabel completions. Lihat Contoh 6.
     • log_metric: callable log_metric(name: str, value: float) untuk mencatat metrik skalar sebagai plot di samping kl, entropy, dll. Lihat Contoh 6.
     • environments: daftar instance lingkungan, satu per completion. Hanya ada ketika environment_factory disediakan. Gunakan ini untuk membaca state yang terakumulasi selama episode (misalnya, env.counter). Untuk lingkungan stateful, lebih baik biarkan lingkungan memiliki reward melalui metode get_reward — lihat Rewards.
     • 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.

   • Tergantung pada format dataset, input akan bervariasi:

     • Untuk format standar, prompts dan completions akan berupa daftar string.
     • Untuk format percakapan, prompts dan completions akan berupa daftar kamus pesan.

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

Contoh 1: Memberi imbalan pada penyelesaian yang lebih panjang

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

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

Anda dapat mengujinya sebagai berikut:

>>> prompts = ["The sky is", "The sun is"]  # not used in the reward function, but the trainer will pass it
>>> completions = [" blue.", " 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 1.1: Memberi imbalan untuk penyelesaian yang lebih panjang (berdasarkan jumlah karakter)

Sama seperti contoh sebelumnya, tetapi kali ini fungsi reward didasarkan pada jumlah karakter, bukan token.

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

Anda dapat mengujinya sebagai berikut:

>>> prompts = ["The sky is", "The sun is"]
>>> completions = [" blue.", " in the sky."]
>>> completion_ids = [[6303, 13], [304, 279, 12884, 13]]  # not used in the reward function, but the trainer will pass it
>>> reward_func(prompts=prompts, completions=completions, completion_ids=completion_ids)
[6.0, 12.0]

Contoh 2: Memberikan imbalan untuk penyelesaian dengan format tertentu

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

import re

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

Anda dapat menguji fungsi ini sebagai berikut:

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

Contoh 3: Memberikan imbalan pada penyelesaian berdasarkan referensi

Berikut adalah contoh fungsi reward yang memeriksa apakah penyelesaian benar. Contoh ini terinspirasi dari fungsi reward akurasi yang digunakan dalam makalah DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. Contoh ini dirancang untuk format standar, di mana dataset berisi kolom bernama ground_truth.

import re

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

Anda dapat menguji fungsi ini sebagai berikut:

>>> prompts = ["Problem: Solve the equation $2x + 3 = 7$. Solution:", "Problem: Solve the equation $3x - 5 = 10$."]
>>> completions = [r" The solution is \boxed{2}.", 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 GRPOTrainer. Dalam contoh ini, kami mendefinisikan dua fungsi reward yang spesifik untuk tugas: math_reward_func dan coding_reward_func. Fungsi math_reward_func memberikan reward untuk soal matematika berdasarkan kebenarannya, sedangkan coding_reward_func memberikan reward untuk soal pemrograman berdasarkan apakah solusinya berfungsi.

from datasets import Dataset
from trl import GRPOTrainer

# Define a dataset that contains both math and coding problems
dataset = Dataset.from_list(
    [
        {"prompt": "What is 2+2?", "task": "math"},
        {"prompt": "Write a function that returns the sum of two numbers.", "task": "code"},
        {"prompt": "What is 3*4?", "task": "math"},
        {"prompt": "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
trainer = GRPOTrainer(
    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 GRPOTrainer akan melanjutkan dengan fungsi dan tugas yang valid. Hal ini memungkinkan GRPOTrainer untuk menangani beberapa fungsi reward dengan tingkat penerapan yang berbeda.

Perhatikan bahwa GRPOTrainer 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, GRPOTrainer akan mengeksekusinya secara bersamaan sehingga latensinya saling tumpang tindih.

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

import asyncio

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

Contoh 6: Pencatatan kolom dan metrik tambahan

Di bawah ini adalah contoh fungsi reward yang mencatat kolom tambahan ke tabel completions dan metrik skalar sebagai plot.

import re

def reward_func(completions, ground_truth, log_extra=None, log_metric=None, **kwargs):
    extracted = [re.search(r"\\boxed\{(.*?)\}", c) for c in completions]
    extracted = [m.group(1) if m else None for m in extracted]
    rewards = [1.0 if e == gt else 0.0 for e, gt in zip(extracted, ground_truth)]

    if log_extra:
        log_extra("golden_answer", list(ground_truth))
        log_extra("extracted_answer", [e or "[none]" for e in extracted])

    if log_metric:
        log_metric("accuracy", sum(rewards) / len(rewards))

    return rewards

Menyalurkan fungsi reward ke trainer

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

from trl import GRPOTrainer

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

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

from trl import GRPOTrainer

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

dan hadiah akan dihitung sebagai jumlah dari hadiah dari setiap fungsi, atau jumlah berbobot jika reward_weights disediakan dalam konfigurasi.

Perhatikan bahwa GRPOTrainer mendukung beberapa fungsi reward dengan tipe yang berbeda. Lihat dokumentasi parameter untuk detail lebih lanjut.

Regularisasi entropi

Untuk mendorong eksplorasi dan mencegah kebijakan runtuh ke output yang hampir deterministik, Anda dapat menambahkan bonus entropi ke tujuan pelatihan. Regularisasi entropi memperluas loss GRPO sebagai berikut: $$\mathcal{L}(\theta) = \mathcal{L}_{\text{GRPO}}(\theta) - \alpha \cdot \mathcal{H}(\pi_\theta),$$

di mana$\mathcal{H}(\pi_\theta)$ adalah entropi rata-rata per token dari kebijakan, dan$\alpha$ adalah koefisien entropi. Bonus selalu berupa entropi rata-rata per token, terlepas dari loss_type; tidak diskalakan ulang untuk menyesuaikan normalisasi kebijakan dari tipe loss (misalnya penyebut batch_size * max_completion_length dari Dr. GRPO), sehingga entropy_coef memiliki makna yang sama untuk setiap tipe loss.

Entropi statis — koefisien tetap selama pelatihan:

from trl import GRPOConfig, GRPOTrainer

training_args = GRPOConfig(entropy_coef=0.05, ...)

Entropi adaptif — koefisien diperbarui pada setiap langkah optimizer berdasarkan entropi target, sebagaimana diperkenalkan dalam Skywork-OR1. Ketika entropi saat ini berada pada atau di bawah entropy_target, koefisien ditambah sebesar entropy_coef_delta; selain itu, koefisien dikurangi. Koefisien hanya diterapkan (yaitu tidak nol) selama entropi berada pada atau di bawah target:

training_args = GRPOConfig(
    entropy_coef=0.01,          # initial coefficient
    use_adaptive_entropy=True,
    entropy_target=5.0,         # target mean per-token entropy (nats); tune for your model
    entropy_coef_delta=0.005,   # step size per optimizer step
    entropy_coef_min=0.0,
    entropy_coef_max=1.0,
    ...
)

Model bahasa yang umum memiliki entropi per token sebesar 2–10 nats, sehingga nilai default entropy_target=0.2 hampir tidak pernah memicu regularisasi — bonus hanya aktif ketika entropi berada pada atau di bawah target, yaitu saat terjadi kolaps hampir total. Atur nilainya menjadi angka yang bermakna untuk model Anda, misalnya mendekati entropi yang Anda amati di awal pelatihan (dicatat sebagai metrik entropy). Saat menggunakan top_entropy_quantile < 1.0, entropy_target diterapkan pada subset token ber-entropi tinggi — entropi subset tersebut akan lebih tinggi daripada entropy penuh-token yang dicatat, sehingga kalibrasikan sesuai dengan itu.

Ketika use_adaptive_entropy=True, koefisien entropi saat ini entropy_coef disimpan bersama setiap checkpoint dan dipulihkan saat resume, sehingga pelatihan sepenuhnya dapat dilanjutkan.

Eksperimen Cepat untuk GRPO

RapidFire AI adalah mesin eksperimen open-source yang berada di atas TRL dan memungkinkan Anda meluncurkan beberapa konfigurasi GRPO sekaligus, bahkan pada satu GPU. Alih-alih mencoba konfigurasi secara berurutan, RapidFire memungkinkan Anda melihat semua kurva pembelajaran mereka lebih awal, menghentikan run yang kinerjanya rendah, dan mengkloning yang menjanjikan dengan pengaturan baru saat berjalan tanpa perlu memulai ulang. Untuk informasi lebih lanjut, lihat RapidFire AI Integration.

Pelatihan Agen

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

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

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

Alat

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

from trl import GRPOTrainer

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

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

Loop panggilan alat GRPO memerlukan template chat 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 template pelatihan dengan template yang telah diperbaiki ketika alat diaktifkan. Lihat Chat Templates untuk daftar lengkap.

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

Contoh:

from trl import GRPOTrainer

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 = GRPOTrainer(
    tools=[multiply, async_add],
    ...,
)

Lingkungan

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

environment_factory membutuhkan transformers>=5.2.0.

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

import random

from trl import GRPOConfig, GRPOTrainer

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

trainer = GRPOTrainer(
    model="Qwen/Qwen3-0.6B",
    args=GRPOConfig(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. Dalam GRPO, 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.

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

Menyediakan dataset eksternal (opsional)

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

from datasets import Dataset
from trl import GRPOTrainer

# 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

trainer = GRPOTrainer(
    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; reward_weights hanya berlaku untuk reward_funcs (environment memiliki skala miliknya sendiri).

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

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

reward_func juga dapat membaca status lingkungan secara langsung: ketika environment_factory diset, trainer meneruskan kwarg environments (satu instance per completion). Ini kadang berguna, tetapi untuk reward yang bergantung pada status, lebih disarankan menggunakan get_reward.

Ini bekerja identik untuk AsyncGRPOTrainer.

Lingkungan yang beragam

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

import random

from datasets import Dataset
from trl import GRPOConfig, GRPOTrainer


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
dataset = Dataset.from_dict({"environment": ["coding", "game"] * 500})

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

Fungsi reward masih menerima lingkungan dari setiap contoh melalui reward_kwargs["environments"], sehingga dapat bercabang berdasarkan tipe lingkungan (mis. isinstance(env, CodingEnv)). Instance lingkungan digunakan ulang di antara 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.

Respons Alat Multimodal

Tools dapat mengembalikan gambar bersama teks dengan mengembalikan daftar blok konten. Hal ini berguna untuk pelatihan agen VLM di mana tools menyediakan umpan balik visual (misalnya, tangkapan layar, plot, tangkapan kamera).

from PIL import Image

def take_screenshot() -> list:
    """
    Takes a screenshot of the current screen.

    Returns:
        The screenshot image with a description.
    """
    img = Image.open("screenshot.png")
    return [{"type": "image", "image": img}, {"type": "text", "text": "Here is the screenshot."}]

Gambar yang dikembalikan secara otomatis disuntikkan ke dalam percakapan dan diteruskan ke VLM untuk giliran generasi berikutnya.

Model yang Didukung

Diuji dengan:

• Beam — misalnya, reflection/Beam-1.0-501B-A23B
• DeepSeek-R1 — misalnya, deepseek-ai/DeepSeek-R1
• Gemma4 — misalnya, google/gemma-4-E2B-it
• GLM-4-MoE (4.5, 4.6 atau 4.7) — misalnya, zai-org/GLM-4.7
• GPT-OSS — misalnya, openai/gpt-oss-20b
• Llama 3.1 — misalnya, meta-llama/Llama-3.1-8B-Instruct
• Llama 3.2 — misalnya, meta-llama/Llama-3.2-3B-Instruct
• Qwen2.5 — misalnya, Qwen/Qwen2.5-0.5B-Instruct
• Qwen3 — misalnya, Qwen/Qwen3-0.6B
• Qwen3-VL — misalnya, Qwen/Qwen3-VL-2B-Instruct
• Qwen3.5 — misalnya, Qwen/Qwen3.5-2B
• Qwen3.6 — misalnya, Qwen/Qwen3.6-35B-A3B

Kompatibilitas dengan semua LLM tidak dijamin. Jika Anda yakin suatu model harus didukung, silakan buka issue di GitHub — atau lebih baik lagi, kirimkan pull request dengan perubahan yang diperlukan.

Integrasi Lingkungan

Semua lingkungan terhubung ke slot environment_factory yang sama, sehingga dapat dipertukarkan pada level TRL — pilih yang ekosistemnya sesuai dengan tugas Anda:

Pelatihan Model Bahasa Visual

GRPO mendukung pelatihan Vision-Language Models (VLM) pada dataset multimodal yang berisi teks dan gambar.

Model yang Didukung

Diuji dengan:

• Gemma3 — misalnya, google/gemma-3-4b-it
• LLaVA-NeXT — misalnya, llava-hf/llava-v1.6-mistral-7b-hf
• Qwen2-VL — misalnya, Qwen/Qwen2-VL-2B-Instruct
• Qwen2.5-VL — misalnya, Qwen/Qwen2.5-VL-3B-Instruct
• SmolVLM2 — misalnya, HuggingFaceTB/SmolVLM2-2.2B-Instruct

Kompatibilitas dengan semua VLM tidak dijamin. Jika Anda yakin suatu model harus didukung, silakan buka issue di GitHub — atau lebih baik lagi, kirimkan pull request dengan perubahan yang diperlukan.

Mulai Cepat

Gunakan grpo_vlm.py untuk fine-tune sebuah VLM. Contoh perintah untuk pelatihan pada lmms-lab/multimodal-open-r1-8k-verified:

accelerate launch \
  --config_file=examples/accelerate_configs/deepspeed_zero3.yaml \
  examples/grpo_visual_math/grpo_visual_math.py \
  --model_name_or_path Qwen/Qwen2.5-VL-3B-Instruct \
  --output_dir grpo-Qwen2.5-VL-3B-Instruct \
  --learning_rate 1e-5 \
  --dtype bfloat16 \
  --max_completion_length 1024 \
  --use_vllm \
  --vllm_mode colocate \
  --use_peft \
  --lora_target_modules "q_proj", "v_proj" \
  --log_completions

Tips Konfigurasi

• Gunakan LoRA pada lapisan proyeksi bahasa-visi
• Aktifkan kuantisasi 4-bit untuk mengurangi penggunaan memori
• VLMs sangat intensif terhadap memori — mulailah dengan ukuran batch yang lebih kecil
• Sebagian besar model kompatibel dengan vLLM (mode server dan colocate)

Format Dataset

Setiap sampel pelatihan harus mencakup:

• prompt: Teks yang diformat melalui template chat prosesor
• image/images: Gambar PIL atau daftar Gambar PIL

Trainer secara otomatis menangani konversi gambar-ke-tensor melalui image processor model.

GRPOTrainer

>>> from trl import GRPOTrainer
>>> from trl.rewards import accuracy_reward
>>> from datasets import load_dataset

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

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

GRPOConfig