مدرب GRPO

نظرة عامة

يدعم TRL مُدرّب GRPO لتدريب نماذج اللغة، كما هو موصوف في ورقة DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models التي كتبها Zhihong Shao، Peiyi Wang، Qihao Zhu، Runxin Xu، Junxiao Song، Mingchuan Zhang، Y. K. Li، Y. Wu، Daya Guo.

المستخلص من الورقة البحثية هو كالتالي:

يُشكّل الاستدلال الرياضي تحديًا كبيرًا لنماذج اللغة بسبب طبيعته المعقدة والمنظمة. في هذه الورقة، نُقدّم DeepSeekMath 7B، الذي يستمر في التدريب المسبق لـ DeepSeek-Coder-Base-v1.5 7B باستخدام 120 مليار رمز متعلق بالرياضيات مستمد من Common Crawl، إلى جانب بيانات اللغة الطبيعية والكود. حقق DeepSeekMath 7B نتيجة مبهرة بلغت 51.7% على معيار MATH على مستوى المسابقات، دون الاعتماد على أدوات خارجية أو تقنيات التصويت، مما يقترب من مستوى أداء Gemini-Ultra و GPT-4. يحقق اتساق الذات على 64 عينة من DeepSeekMath 7B نسبة 60.9% على MATH. يُعزى قدرة الاستدلال الرياضي في DeepSeekMath إلى عاملين رئيسيين: أولاً، نستغل الإمكانات الكبيرة للبيانات المتاحة علنًا على الويب من خلال خط أنابيب هندسي دقيق لاختيار البيانات. ثانيًا، نُقدّم Group Relative Policy Optimization (GRPO)، وهو متغير من Proximal Policy Optimization (PPO)، يعزز قدرات الاستدلال الرياضي مع تحسين استخدام الذاكرة في PPO في الوقت نفسه.

تمت مساهمة Quentin Gallouédec في هذه طريقة ما بعد التدريب.

البدء السريع

يُظهر هذا المثال كيفية تدريب نموذج باستخدام طريقة GRPO. نقوم بتدريب نموذج Qwen2.5 0.5B Instruct باستخدام الأوامر من مجموعة بيانات DeepMath-103K. يمكنك عرض البيانات في مجموعة البيانات هنا:

فيما يلي السكربت لتدريب النموذج. يحتاج accuracy_reward إلى math-verify، والذي يمكنك تثبيته باستخدام 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()

نفّذ السكربت باستخدام الأمر التالي:

accelerate launch train_grpo.py

عند توزيع التدريب على 8 وحدات معالجة رسومية (GPU)، يستغرق التدريب حوالي يوم واحد.

ملاحظة: تم توليد منحنيات المكافآت أعلاه باستخدام Qwen/Qwen2-0.5B-Instruct. ستكون النتائج باستخدام Qwen/Qwen2.5-0.5B-Instruct مشابهة نوعياً.

النظر بعمق أكبر في طريقة GRPO

GRPO هو خوارزمية تعلّم عبر الإنترنت، مما يعني أنه يتحسّن بشكل تكراري من خلال استخدام البيانات التي يولّدها النموذج المدرَّب نفسه أثناء التدريب. الفكرة الكامنة وراء هدف GRPO هي تعظيم ميزة المكملات المولَّدة، مع ضمان بقاء النموذج قريبًا من سياسة المرجع. لفهم كيفية عمل GRPO، يمكن تقسيمه إلى أربع خطوات رئيسية: توليد المكملات، حساب الميزة، تقدير تباعد KL، وحساب الخسارة.

توليد الاكتمالات

في كل خطوة تدريب، نختار دفعة من الأوامر ونولّد مجموعة من $G$ الإكمالات لكل أمر (يُرمز إليها بـ $o_i$).

حساب الميزة

لكلٍّ من $G$ التسلسلات، نحسب المكافأة باستخدام نموذج مكافآت أو دالة مكافآت. ولتوافق مع الطبيعة المقارنة لنماذج المكافآت — التي تُدرَّب عادةً على مجموعات بيانات من المقارنات بين المخرجات للسؤال نفسه — يتم حساب الميزة لتعكس هذه المقارنات النسبية. يتم تطبيعها على النحو التالي: $$\hat{A}_{i,t} = \frac{r_i - \text{mean}(\mathbf{r})}{\text{std}(\mathbf{r})}$$

يمنح هذا النهج الطريقة اسمه: تحسين السياسة النسبي للمجموعات (GRPO).

أُظهر في الورقة البحثية Understanding R1-Zero-Like Training: A Critical Perspective أن التوسيع بواسطة $\text{std}(\mathbf{r})$ قد يسبب انحيازًا في صعوبة مستوى السؤال. يمكنك تعطيل هذا التوسيع عن طريق تعيين scale_rewards=False في GRPOConfig. يُرجى ملاحظة أن إيقاف التوسيع القائم على std يزيل أيضًا تطبيع التباين، لذا تعتمد أحجام التحديث مباشرةً على مقياس المكافأة الخام وتكوين الدفعة.

كما هو موضح في الجزء الأول: حيل أم فخاخ؟ غوص عميق في التعلم المعزز لاستدلال نماذج اللغة الكبيرة (Lite PPO)، فإن حساب المتوسط على المستوى المحلي (المجموعة) والانحراف المعياري على المستوى العام (الدفع) يتيح تشكيل مكافآت أكثر متانة. يمكنك استخدام استراتيجية التوسيع هذه عن طريق تعيين scale_rewards="batch" في GRPOConfig.

تقدير تباعد كولباك-ليبل

يُقدَّر تباعد KL باستخدام المُقدِّر الذي قدمه Schulman et al. (2020). يُعرَّف المُقدِّر على النحو التالي: $$\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,$$

حساب الخسارة

الهدف هو تعظيم الميزة مع ضمان بقاء النموذج قريبًا من سياسة المرجع. وبالتالي، يُعرَّف الخسارة على النحو التالي: $$\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],$$

حيث يمثل الحد الأول الميزة المُقيّمة، بينما يعاقب الحد الثاني الانحرافات عن سياسة المرجع من خلال تباعد كوهين-ليبلينغ.

لاحظ أنه مقارنةً بالصياغة الأصلية في DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, لا نضرب في $\frac{1}{|o_i|}$ لأنه تم إثبات في الورقة Understanding R1-Zero-Like Training: A Critical Perspective أن هذا يُدخل تحيّزًا في طول الاستجابة على مستوى الرد. مزيد من التفاصيل في أنواع الدالة الخاسرة.

لاحظ أنه مقارنةً بالصياغة الأصلية في DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models, نستخدم $\beta = 0.0$ كقيمة افتراضية، مما يعني أن حد تباعد KL لا يُستخدم. ينبع هذا الاختيار من عدة دراسات حديثة (مثل Open-Reasoner-Zero: An Open Source Approach to Scaling Up Reinforcement Learning on the Base Model) ) التي أظهرت أن حد تباعد KL ليس ضروريًا للتدريب باستخدام GRPO. ونتيجةً لذلك، أصبح من الشائع استبعاده (مثل Understanding R1-Zero-Like Training: A Critical Perspective, DAPO: An Open-Source LLM Reinforcement Learning System at Scale). إذا كنت ترغب في تضمين حد تباعد KL، يمكنك تعيين beta في GRPOConfig إلى قيمة غير صفرية.

في الورقة الأصلية، يتم تعميم هذه الصياغة لتأخذ في الاعتبار عدة تحديثات بعد كل توليد (يُرمز لها بـ $\mu$, يمكن ضبطها عبر num_iterations في GRPOConfig) عن طريق الاستفادة من دالة الهدف البديلة المقصوصة: $$\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],$$

حيث $\text{clip}(\cdot, 1 - \epsilon, 1 + \epsilon)$ على ضمان عدم انحراف التحديثات بشكل مفرط عن سياسة المرجع من خلال تحديد نطاق نسبة السياسة بين $1 - \epsilon$ و $1 + \epsilon$. عندما $\mu = 1$ (القيمة الافتراضية في TRL)، فإن الدالة البديلة المقصوصة تتبسط لتصبح الدالة الأصلية.

أنواع الدالة

قُدِّمت عدة صيغ للدالة الهدف في الأدبيات. في البداية، عُرِّفت دالة هدف GRPO على النحو التالي: $$\mathcal{L}_{\text{GRPO}}(\theta) = - \frac{1}{G} \sum_{i=1}^G \frac{1}{|o_i|} \sum_{t=1}^{|o_i|} l_{i,t},$$

حيث $$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].$$

يُبرز ورقة DAPO قيود خسارة مستوى العينة في خوارزمية GRPO في سيناريوهات CoT الطويلة، حيث تُعاقَب الاستجابات الأطول بشكل غير كافٍ، مما يؤدي إلى مخرجات ذات جودة أدنى. الحل المقترح هو تطبيع على مستوى الرمز (token-level normalization)، والذي يتعامل بشكل أفضل مع التسلسلات الأطول من خلال منح مكافآت أكثر توازناً للأفراد الرموز، بغض النظر عن طول الاستجابة: $$\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},$$

لاستخدام هذه الصياغة، اضبط loss_type="dapo" في GRPOConfig.

علاوة على ذلك، تم إثبات في الورقة Understanding R1-Zero-Like Training: A Critical Perspective أن صياغة GRPO الأولية تُدخل انحيازًا في طول الاستجابة. يُظهرون أنه على الرغم من أن صياغة DAPO تقلل من هذا الانحياز، إلا أنها لا تلغيه تمامًا. لإزالة هذا الانحياز بالكامل، يقترحون القسمة على ثابت بدلاً من طول التسلسل، مما يؤدي إلى الصياغة التالية: $$\mathcal{L}_{\text{Dr. GRPO}}(\theta) = - \frac{1}{LG} \sum_{i=1}^G \sum_{t=1}^{|o_i|} l_{i,t},$$

يُوصى بأن تكون هذه الثابتة هي الحد الأقصى لطول الإكمال. لاستخدام هذه الصياغة، اضبط loss_type="dr_grpo" في GRPOConfig.

بديلًا عن ذلك، في ورقة SAPO، يقترح فريق Qwen استبدال آلية القصّ “الصلبة” في GRPO بآلية بوابة ناعمة سلسة تتحكم فيها درجة الحرارة. بينما تُصفّر GRPO التدرّجات عندما ينحرف النموذج عن المرجع بشكل مفرط، يستخدم SAPO منطقة ثقة ناعمة تُضعف وزن التدرّج بسلاسة. وهذا يتيح للنموذج الاحتفاظ بإشارات التعلم المفيدة من الرموز “القريبة من السياسة” مع كبح الضوضاء الناتجة عن الانحرافات الشديدة.

يُعرَّف دالة الخسارة على النحو التالي: $$\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}$$

دالة البوابة الناعمة $f_{i,t}$ تُعرَّف باستخدام دالة السيغمويد $\sigma$ على النحو التالي: $$f_{i,t}(x) = \sigma \left( \tau_{i,t} (x - 1) \right) \cdot \frac{4}{\tau_{i,t}}$$

درجة الحرارة $\tau_{i,t}$ تُختار بناءً على إشارة الميزة $\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}$$

يوصون باستخدام درجات حرارة غير متماثلة، $\tau_{\text{neg}} > \tau_{\text{pos}}$ (القيم الافتراضية هي $\tau_{\text{pos}}=1.0, \tau_{\text{neg}}=1.05$ ). يضمن هذا أن يُعاقب النموذج بشكل أكثر صرامة على الإجراءات «السيئة» لمنع عدم الاستقرار، مع كونه أكثر تساهلاً مع الإجراءات «الجيدة».

لاستخدام هذه الصياغة، اضبط loss_type="sapo" في GRPOConfig.

المقاييس المسجّلة

أثناء التدريب والتقييم، نسجّل المقاييس التالية:

• num_tokens: إجمالي عدد الرموز التي تمت معالجتها حتى الآن، بما في ذلك كل من الاستعلامات (prompts) والإكمالات (completions). عند استخدام الأدوات، يتم احتساب الرموز غير المرتبطة بالأدوات فقط.
• step_time: متوسط الوقت (بالثواني) المستغرق لكل خطوة تدريب (بما في ذلك التوليد).
• completions/mean_length: متوسط طول المكملات المولّدة. عند استخدام الأدوات، تُحتسب الرموز غير المتعلقة بالأدوات فقط.
• completions/min_length: الحد الأدنى لطول المكملات المولّدة. عند استخدام الأدوات، تُحتسب الرموز غير المرتبطة بالأدوات فقط.
• completions/max_length: الحد الأقصى لطول المكملات المولّدة. عند استخدام الأدوات، يتم احتساب رموز غير الأدوات فقط.
• completions/mean_terminated_length: متوسط طول الإكمالات المولّدة التي تنتهي بـ EOS. عند استخدام الأدوات، يتم احتساب رموز غير الأدوات فقط.
• completions/min_terminated_length: الحد الأدنى لطول المكملات المولّدة التي تنتهي بـ EOS. عند استخدام الأدوات، يتم احتساب رموز غير الأدوات فقط.
• completions/max_terminated_length: الحد الأقصى لطول المكملات المولّدة التي تنتهي بـ EOS. عند استخدام الأدوات، يتم احتساب رموز غير الأدوات فقط.
• completions/clipped_ratio: نسبة الإكمالات المقطوعة (المُقصاة).
• tools/call_frequency: متوسط عدد استدعاءات الأدوات لكل إكمال في دفعة التوليد. يُسجَّل فقط عند توفير tools.
• tools/failure_frequency: نسبة استدعاءات الأدوات التي فشلت (لم يتم العثور على الأداة، أو أثار استثناءً، أو أن نوع الاستدعاء غير مدعوم). تكون قيمتها 0.0 عندما لم يتم استدعاء أي أداة. تُسجَّل فقط عند توفير tools.
• rewards/{reward_func_name}/mean: متوسط المكافأة من دالة مكافأة محددة. عندما تمتلك البيئة المكافأة عبر get_reward، يكون {reward_func_name} اسم فئة البيئة.
• rewards/{reward_func_name}/std: الانحراف المعياري للمكافأة من دالة مكافأة محددة.
• reward: متوسط المكافأة الإجمالي بعد جمع المكافآت عبر الدوال (موزونة بـ reward_weights).
• reward_std: الانحراف المعياري للمكافآت المجمعة عبر الدوال (موزونة بـ reward_weights)، محسوبًا على الدفعة الكاملة.
• frac_reward_zero_std: نسبة العينات في دفعة التوليد التي يكون انحراف مكافأتها المعياري صفراً، مما يعني أن التنوع ضئيل لذلك الاستدعاء (جميع الإجابات صحيحة أو خاطئة).
• sampling/sampling_logp_difference/mean: متوسط الفرق المطلق بين احتمالات اللوغاريتم التي يعيدها العيّان (vLLM) وتلك التي يعيد حسابها نموذج التدريب، على مستوى رموز الإكمال. يشير ارتفاع القيمة إلى اتساع فجوة عدم التطابق بين التدريب والاستدلال. يُسجَّل فقط عند تعيين use_vllm=True وvllm_importance_sampling_correction=True.
• sampling/sampling_logp_difference/max: أكبر فرق مطلق من هذا النوع. يُسجَّل فقط عندما يكون use_vllm=True وvllm_importance_sampling_correction=True.
• sampling/importance_sampling_ratio/min: أصغر نسبة أخذ عينات بالوزن المستخدمة لتصحيح عدم التطابق بين التدريب والاستدلال، بعد تطبيق القيد المحدد بواسطة vllm_importance_sampling_mode (يتم قصّها إلى [C_min, C_max] في أوضاع *_truncate، وتُضبط إلى صفر في أوضاع *_mask). تُحسب على رموز الإكمال، أو على التسلسلات في أوضاع sequence_*. تُسجَّل فقط عندما يكون use_vllm=True وvllm_importance_sampling_correction=True.
• sampling/importance_sampling_ratio/mean: متوسط نسبة أخذ العينات المهمة المقيدة. يُسجَّل فقط عندما يكون use_vllm=True وvllm_importance_sampling_correction=True.
• sampling/importance_sampling_ratio/max: أكبر نسبة أخذ عينات بالوزن المقيدة. يُسجَّل فقط عندما يكون use_vllm=True وvllm_importance_sampling_correction=True.
• policy_loss: قيمة خسارة تدرج السياسة (قبل أي مكافأة إنتروبيا). تُسجَّل عندما يكون entropy_coef غير صفري أو use_adaptive_entropy=True.
• entropy: متوسط إنتروبيا توقعات الرموز عبر المكملات المولّدة. (إذا كان mask_truncated_completions=True، يتم استبعاد رموز التسلسلات المقنّعة.)
• entropy_coef: معامل تنظيم الإنتروبيا الحالي. يُسجَّل عندما يكون entropy_coef غير صفري أو عندما يكون use_adaptive_entropy=True. يُحدَّث مرة واحدة في كل خطوة مُحسِّن عندما يكون use_adaptive_entropy=True.
• aux_loss: خسارة التوازن على الأحمال المساعدة لنموذج مزيج الخبراء، قبل أن تُضرب في router_aux_loss_coef وتُضاف إلى الخسارة. تُسجَّل فقط عندما يكون النموذج من نوع MoE وrouter_aux_loss_coef غير صفري.
• kl: متوسط تباعد كوهين-ليبلر بين النموذج ونموذج المرجع، محسوبًا على المكملات المولّدة. يُسجَّل فقط إذا كان beta غير صفري.
• clip_ratio/region_mean: نسبة الرموز (أو التسلسل، إذا كان importance_sampling_level="sequence") للاحتمالات التي يُقصّ فيها هدف GRPO ليبقى ضمن منطقة الثقة: $\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})}$. تدل قيمة أعلى على أن عددًا أكبر من الرموز يُقصّ، مما يقيّد مدى تغيير السياسة $\pi_\theta$ .
• clip_ratio/low_mean: متوسط نسبة احتمالات الرموز (أو التسلسل، إذا كان importance_sampling_level="sequence") مقصوصة عند الحد الأدنى لمنطقة الثقة: $r_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}$.
• clip_ratio/low_min: أصغر نسبة لكل إكمال من الرموز (أو التسلسل نفسه، إذا importance_sampling_level="sequence") تم اقتطاعه عند الحد الأدنى لمنطقة الثقة: $r_{i,t}(\theta) < 1 - \epsilon_\mathrm{low}$.
• clip_ratio/high_mean: متوسط نسبة احتمالات الرموز (أو التسلسل، إذا كان importance_sampling_level="sequence") مقصوصة عند الحد الأعلى لمنطقة الثقة: $r_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}$.
• clip_ratio/high_max: أعلى نسبة لكل إكمال من الرموز (أو التسلسل نفسه، إذا importance_sampling_level="sequence") تم اقتطاعه عند الحد الأعلى لمنطقة الثقة: $r_{i,t}(\theta) > 1 + \epsilon_\mathrm{high}$.
• cispo_clip_ratio: نسبة أوزات أخذ العينات المهمة (على مستوى الرمز، أو التسلسل إذا كان importance_sampling_level="sequence") مقصوصة عند epsilon_high مع امتلاك ميزة إيجابية: $r_{i,t}(\theta) > \epsilon_\mathrm{high}$. يُسجَّل فقط عندما يكون loss_type="cispo".
• vespo/phi_seq_mean: القيمة المتوسطة لوزن VESPO Gamma $\varphi(w)$ المُطبَّق على أوزان الأهمية على مستوى التسلسل. تشير القيم الأقل من 1.0 إلى تخفيض وزن التسلسلات. يُسجَّل هذا فقط عندما يكون loss_type="vespo".

التخصيص

تسريع التدريب باستخدام التوليد المدعوم من vLLM

غالبًا ما يكون التوليد هو العائق الرئيسي عند التدريب باستخدام الأساليب المباشرة. لتسريع التوليد، يمكنك استخدام vLLM، وهو محرك استدلال عالي الإنتاجية ومنخفض الكمون للنماذج اللغوية الكبيرة. لتفعيله، قم أولاً بتثبيت الحزمة باستخدام

pip install trl[vllm]

ندعم طريقتين لاستخدام vLLM أثناء التدريب: وضع الخادم ووضع التجميع.

بشكل افتراضي، يتم تفعيل أخذ عينات الأهمية المقنّعة على مستوى التسلسل (vllm_importance_sampling_mode="sequence_mask") لتوليد vLLM لمعالجة عدم التطابق بين التوليد والتدريب الذي يحدث عند استخدام أطر عمل مختلفة. يمكن تعطيل ذلك عن طريق تعيين vllm_importance_sampling_correction=False. لمزيد من المعلومات، راجع أخذ عينات الأهمية المقنّعة و أخذ عينات الأهمية على مستوى التسلسل

الخيار 1: وضع التجميع

في هذا الوضع، يعمل vLLM داخل عملية المُدرِّب ويتشارك ذاكرة GPU مع نموذج التدريب. يتجنّب هذا إطلاق خادم منفصل ويمكن أن يحسّن استخدام GPU، لكنه قد يؤدي إلى تنافس على الذاكرة في وحدات GPU الخاصة بالتدريب. هذا هو الوضع الافتراضي.

from trl import GRPOConfig

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

الخيار 2: وضع الخادم

في هذا الوضع، يعمل vLLM في عملية منفصلة (ويعتمد على وحدات معالجة رسومية منفصلة) ويتواصل مع المُدرِّب عبر HTTP. وهذا مثالي إذا كانت لديك وحدات معالجة رسومية مخصصة للاستدلال.

1. بدء خادم vLLM:

   تم النسخ

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

2. تفعيل وضع الخادم في سكربت التدريب الخاص بك:

   تم النسخ

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

تأكد من أن الخادم يستخدم وحدات معالجة رسومية مختلفة عن تلك التي يستخدمها المدرب، وإلا فقد تواجه أخطاء NCCL. يمكنك تحديد وحدات المعالجة الرسومية المراد استخدامها باستخدام متغير البيئة CUDA_VISIBLE_DEVICES.

يعتمد على حجم النموذج ومتطلبات ذاكرة وحدة معالجة الرسوميات (GPU) الإجمالية للتدريب، قد تحتاج إلى ضبط معامل vllm_gpu_memory_utilization في GRPOConfig لتجنب سوء الاستخدام أو أخطاء نفاد الذاكرة.

نوفر مساحة HF لمساعدتك في تقدير استهلاك ذاكرة وحدة معالجة الرسوميات الموصى به بناءً على إعدادات النموذج وإعدادات التجربة الخاصة بك. ما عليك سوى استخدامه على النحو التالي للحصول على توصية vllm_gpu_memory_utilization:

إذا لم يعمل القيمة الموصى بها في بيئتك، نقترح إضافة هامش صغير (مثل +0.05 أو +0.1) إلى القيمة الموصى بها لضمان الاستقرار.

إذا كنت لا تزال تواجه أخطاء نفاد الذاكرة، فاضبط vllm_enable_sleep_mode على True وسيتم تفريغ معاملات vllm والذاكرة المؤقتة أثناء خطوة التحسين. لمزيد من المعلومات، راجع تقليل استخدام الذاكرة مع وضع السكون في vLLM.

افتراضيًا، يستخدم GRPO MASTER_ADDR=localhost وMASTER_PORT=12345 لـ vLLM، لكن يمكنك تجاوز هذه القيم عن طريق تعيين متغيرات البيئة وفقًا لذلك.

لمزيد من المعلومات، راجع تسريع التدريب باستخدام vLLM.

التعامل مع عدم التطابق بين التدريب والاستدلال

في حين أن vLLM يُسرّع الاستدلال بشكل كبير، فإنه يفصل محرك الاستدلال عن محرك التدريب. نظريًا، هذان المحركان متطابقان رياضيًا، لكن عمليًا قد ينتجان مخرجات مختلفة بسبب تأثيرات الدقة والتحسينات الخاصة بالمعدات. يعكس هذا الاختلاف أهداف التحسين المختلفة للنظامين. تهدف محركات الاستدلال إلى تعظيم معدل إنتاج العينات، والذي يُقاس عادةً بعدد الرموز في الثانية، مع الحفاظ على دقة عينات مقبولة. في المقابل، تركز أطر التدريب على الاستقرار العددي والدقة في حساب التدرجات، وغالبًا ما تستخدم صيغًا ذات دقة أعلى مثل FP32 للأوزان الرئيسية وحالات المُحسِّن. تُدخل هذه الأولويات والقيود المختلفة عدم تطابق حتمي، وإن كان دقيقًا، بين التدريب والاستدلال.

يؤدي هذا الاختلاف إلى تحديث متدرج منحاز، وقد لوحظ أنه يُزعزع استقرار التدريب ([1][2][3][4][5]). للبساطة، لنفترض متدرج سياسة 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]$$

هنا $x$ تُشير إلى الأوامر المُستخرجة من توزيع بيانات معين، و $\pi^\text{train}$ هو السياسة المُنفَّذة بواسطة محرك التدريب. عند تضمين vLLM في العملية، نحصل على سياسة استدلال منفصلة $\pi^\text{inference}$, لذا يصبح تدرج السياسة الفعّال $$\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].$$

يُحوِّل هذا مشكلة تعلُّم معزَّز كانت في الأصل ضمن السياسة إلى مشكلة خارج السياسة.

The standard way to correct for this distribution shift is importance sampling (IS). We provide two IS variants: Truncated Importance Sampling (TIS) and Masked Importance Sampling (MIS). Both variants can be applied either at the token level or at the sequence level. Let $\rho$ denote the importance weight, for example $\rho_t$ per token or $\rho_{\text{seq}}$ per sequence. Under TIS, ratios outside of the range [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max] are clipped, $$\rho \leftarrow \text{clip}(\rho, C_{\min}, C_{\max}).$$

الورقة الأصلية TIS اقترحت آلية قصّ واحدة للحد الأعلى، أي $\min(\rho, C_{\max})$. عمّم التنفيذ في TRL هذا المفهوم من خلال تقديم حد أدنى أيضًا، مما أدى إلى الصياغة ذات الجانبين المعروضة أعلاه، مستوحاة من IcePop طريقة.
يُلاحظ أنه في IcePop، تُسمّى الحدود $\alpha$ و $\beta$ بينما نستخدم في TRL $C_{\min}$ و $C_{\max}$.

في إطار MIS، تُضبط النسب خارج هذا النطاق إلى صفر، وبالتالي لا تساهم تلك العينات في التدرج. بعبارة أخرى، يتم تخفيف وزن العينات الشاذة في إطار TIS، بينما تُستبعد في إطار MIS. يحدد علم التهيئة vllm_importance_sampling_mode كلا من متغير IS (الإخفاء أو القص) والحُبيبية (على مستوى الرمز أو على مستوى التسلسل).

يُعدّ أخذ العينات حسب الأهمية (Importance sampling) الاستجابة الخوارزمية المبنية على مبادئ منهجية لاختلاف التدريب عن الاستدلال. ومع ذلك، هناك أيضاً أساليب أكثر مباشرةً تهدف إلى تقليل الفجوة بين المحركين نفسيهما. معظم هذه الأساليب حلول هندسية. فعلى سبيل المثال، يستخدم MiniMax M1 رأس نموذج لغوي بدقة FP32 في محرك الاستدلال. وقد استكشفت Thinking Machines أنوية استدلال حتمية، على الرغم من أن ذلك يأتي على حساب كفاءة كبيرة. وقد أظهر vLLM سياسات متطابقة على مستوى البت من خلال البناء على أنوية الاستدلال الحتمية غير المعتمدة على حجم الدفعة (batch invariant) من Thinking Machines، لكن حتى نوفمبر 2025 لا يزال هناك انخفاض كبير في معدل الإنتاجية مقارنةً بالاستدلال القياسي في vLLM.

تسريع التدريب باستخدام التدريج المستمر في transformers

كبديل لـ vLLM، يمكنك استخدام محرك الدفع المستمر المدمج في transformers لتوليد أسرع. يقوم الدفع المستمر بإزالة التسلسلات المكتملة من الدفعة فوراً بدلاً من الانتظار حتى يكتمل أبطأها. في المهام التي تتفاوت فيها أطوال الإكمال (مثل الاستدلال الرياضي)، يؤدي ذلك إلى توليد أسرع واستهلاك أقل لذاكرة VRAM مقارنة بـ generate() الافتراضي عند أحجام دفع كبيرة (N≥32).

يُعدّ الدفع المتواصل (Continuous batching) ترقيةً جاهزةً للاستخدام دون الحاجة إلى إعداد خادم أو مزامنة الأوزان. يعمل داخل العملية (in-process) وهو مناسب بشكل جيد لتدريب على وحدة معالجة رسومية واحدة (single-GPU) أو البيئات ذات القيود على الذاكرة. لتحقيق أقصى معدل إنتاجية توليد على نطاق واسع، استخدم vLLM بدلاً من ذلك.

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 قيمة max_memory_percent افتراضيًا إلى 0.5 (بدلًا من 0.9 في transformers) لتوفير مساحة كافية من ذاكرة VRAM لمرحلة الرجوع الخلفي في التدريب. اضبطها إلى ما بين 0.3 و0.4 عند استخدام دفعات توليد كبيرة (N≥32) أو عند ظهور أخطاء نفاد الذاكرة.

لمثال تدريب كامل، راجع examples/grpo_continuous_batching/grpo_continuous_batching.py.

GRPO على نطاق واسع: تدريب نموذج بحجم 70B+ على عدة عقد

عند تدريب نماذج كبيرة مثل Qwen2.5-72B، تحتاج إلى عدة تحسينات رئيسية لجعل التدريب فعالاً وقابلاً للتوسع عبر وحدات معالجة الرسوميات (GPUs) وعُقد متعددة. وتشمل هذه التحسينات:

• DeepSpeed ZeRO Stage 3: يستفيد ZeRO من توازي البيانات لتوزيع حالات النموذج (الأوزان، التدرجات، حالات المُحسِّن) على وحدات معالجة رسومية ووحدات معالجة مركزية متعددة، مما يقلل من متطلبات الذاكرة والحساب على كل جهاز. وبما أن النماذج الكبيرة لا يمكن استيعابها على وحدة معالجة رسومية واحدة، فإن استخدام ZeRO Stage 3 مطلوب لتدريب مثل هذه النماذج. لمزيد من التفاصيل، راجع DeepSpeed Integration.
• Accelerate: هي مكتبة تُبسّط التدريب الموزّع عبر وحدات معالجة رسومية متعددة وعُقد متعددة. فهي توفر واجهة برمجة تطبيقات بسيطة لإطلاق التدريب الموزّع، وتتعامل مع تعقيدات التدريب الموزّع، مثل توازي البيانات، وتراكم التدرجات، وتحميل البيانات الموزّع. لمزيد من التفاصيل، راجع توزيع التدريب.
• vLLM: راجع القسم السابق لمعرفة كيفية استخدام vLLM لتسريع عملية التوليد.

فيما يلي مثال على سكربت SLURM لتدريب نموذج بحجم 70B باستخدام GRPO على عدة عقد. يقوم هذا السكربت بتدريب النموذج على 4 عقد ويستخدم العُقدة الخامسة للتوليد المدعوم بـ 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()

استخدام دالة مكافأة مخصصة

يدعم GRPOTrainer استخدام دوال مكافأة مخصصة بدلاً من نماذج المكافأة الكثيفة. لضمان التوافق، يجب أن تستوفي دالة المكافأة الخاصة بك المتطلبات التالية:

يمكن أن تكون دوال المكافآت إما دوال Python متزامنة قابلة للاستدعاء، أو دوال async def غير متزامنة. عند تقديم عدة دوال مكافأة غير متزامنة، يتم انتظارها بشكل متزامن (تُنفَّذ بالتوازي عبر asyncio.gather) بحيث تتداخل أزمنتها المستجيب.

1. حجج الإدخال:

   • يجب أن تقبل الدالة ما يلي كحجج مُسمّاة:

     • prompts (تحتوي على الأوامر)،
     • completions (تحتوي على الاكتمالات المولّدة)،
     • completion_ids (تحتوي على المكملات المُرمَّزة)،
     • trainer_state (TrainerState): الحالة الحالية للمدرّب. يمكن استخدام هذا لتنفيذ دوال مكافأة ديناميكية، مثل التعلم المنهجي (curriculum learning)، حيث يتم تعديل المكافأة بناءً على تقدم التدريب.
     • log_extra: دالة قابلة للاستدعاء log_extra(column: str, values: list) لإضافة أعمدة إضافية إلى جدول الاكتمالات. انظر إلى المثال 6.
     • log_metric: دالة قابلة للاستدعاء log_metric(name: str, value: float) لتسجيل مقاييس قياسية على شكل رسوم بيانية إلى جانب kl، entropy، وما إلى ذلك. راجع المثال 6.
     • environments: قائمة من أمثلة البيئة، مثال واحد لكل إكمال. لا تظهر إلا عند تقديم environment_factory. استخدم هذا لقراءة الحالة المتراكمة خلال الحلقة (مثل env.counter). للبيئات ذات الحالة، يُفضَّل ترك البيئة تمتلك المكافأة عبر طريقة get_reward بدلاً من ذلك — راجع المكافآت.
     • جميع أسماء الأعمدة (باستثناء prompt) التي قد يحتوي عليها مجموعة البيانات. على سبيل المثال، إذا كانت مجموعة البيانات تحتوي على عمود باسم ground_truth، فسيتم استدعاء الدالة مع ground_truth كحجة اسمية.

     أسهل طريقة للامتثال لهذا المتطلب هي استخدام **kwargs في توقيع الدالة.

   • يعتمد شكل المدخلات على صيغة مجموعة البيانات:

     • في الصيغة القياسية، ستكون prompts وcompletions قوائم من النصوص.
     • في الصيغة الحوارية، ستكون prompts وcompletions قوائم من قواميس الرسائل.

2. القيمة المُعادَة: يجب أن تُعيد الدالة قائمة من الأرقام العشرية. يمثل كل رقم عشري المكافأة المقابلة لإكمال واحد.

المثال 1: مكافأة الإكمالات الأطول

فيما يلي مثال على دالة مكافأة لتنسيق قياسي يكافئ الإكمالات الأطول:

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]

يمكنك اختباره على النحو التالي:

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

المثال 1.1: مكافأة الإكمالات الأطول (بناءً على عدد الأحرف)

نفس المثال السابق، لكن هذه المرة تعتمد دالة المكافأة على عدد الأحرف بدلاً من الرموز.

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]

يمكنك اختباره على النحو التالي:

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

المثال 2: مكافأة الإكمالات بصيغة محددة

فيما يلي مثال على دالة مكافأة تتحقق مما إذا كانت الإكمال (completion) يتبع تنسيقًا محددًا. استُوحِي هذا المثال من دالة format reward المستخدمة في ورقة DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. تم تصميمها لتنسيق محادثة، حيث تتكون المحفزات (prompts) والإكمالات (completions) من رسائل منظمة.

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]

يمكنك اختبار هذه الدالة على النحو التالي:

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

المثال 3: مكافأة الاكتمالات بناءً على مرجع

فيما يلي مثال على دالة مكافأة تتحقق من صحة الإكمال. يستلهم هذا المثال دالة مكافأة الدقة المستخدمة في ورقة DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. تم تصميم هذا المثال لـ التنسيق القياسي، حيث يحتوي مجموعة البيانات على عمود باسم 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)]

يمكنك اختبار هذه الدالة على النحو التالي:

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

المثال 4: دوال المكافآت متعددة المهام

فيما يلي مثال على استخدام دوال مكافأة متعددة في GRPOTrainer. في هذا المثال، نعرّف دالتي مكافأة مخصصتين للمهام: math_reward_func وcoding_reward_func. تمنح math_reward_func مكافأة للمسائل الرياضية بناءً على صحتها، بينما تمنح coding_reward_func مكافأة لمسائل البرمجة بناءً على ما إذا كانت الحل يعمل.

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

في هذا المثال، صُمِّم math_reward_func وcoding_reward_func للعمل مع مجموعة بيانات مختلطة تحتوي على مسائل رياضية ومسائل برمجية. يُستخدم عمود task في مجموعة البيانات لتحديد دالة المكافأة التي يجب تطبيقها على كل مسألة. إذا لم تكن هناك دالة مكافأة ذات صلة لعينة في مجموعة البيانات، فإن دالة المكافأة ستعيد None، وسيواصل GRPOTrainer العمل بالدوال والمهام الصالحة. وهذا يتيح لـGRPOTrainer التعامل مع دوال مكافأة متعددة ذات نطاقات تطبيق مختلفة.

لاحظ أن GRPOTrainer سيتجاهل مكافآت None التي تُعاد من دوال المكافآت، وسيأخذ في الاعتبار فقط المكافآت التي تُعاد من الدوال ذات الصلة. وهذا يضمن تدريب النموذج على المهام ذات الصلة وتجاهل المهام التي لا توجد لها دالة مكافآت ذات صلة.

المثال 5: دوال المكافآت غير المتزامنة

يمكن أيضًا تعريف دوال المكافأة المخصصة كدوال async def غير متزامنة. وهذا مفيد إذا كانت مكافأتك تعتمد على عمليات إدخال/إخراج بطيئة (على سبيل المثال، استدعاء خدمة عن بُعد). عند تمرير عدة دوال مكافأة غير متزامنة، ينفذ GRPOTrainer هذه الدوال بشكل متوازٍ بحيث تتداخل أزمنه استجابتها.

فيما يلي مثال مبسّط لدالة مكافأة غير متزامنة تحاكي عملية تعتمد على الإدخال/الإخراج:

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]

المثال 6: تسجيل أعمدة ومؤشرات إضافية

فيما يلي مثال على دالة مكافأة تسجّل أعمدة إضافية في جدول الإكمالات والمقاييس القياسية على شكل رسوم بيانية.

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

تمرير دالة المكافأة إلى المدرب

لاستخدام دالة المكافأة المخصصة الخاصة بك، قم بتمريرها إلى GRPOTrainer على النحو التالي:

from trl import GRPOTrainer

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

يمكنك تمرير عدة دوال مكافأة كقائمة؛ وقد تتضمن هذه القائمة دوالًا متزامنة وغير متزامنة على حد سواء:

from trl import GRPOTrainer

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

وستُحسب المكافأة على أنها مجموع المكافآت من كل دالة، أو المجموع الموزون إذا تم تقديم reward_weights في الإعدادات.

لاحظ أن GRPOTrainer يدعم دوال مكافأة متعددة من أنواع مختلفة. راجع توثيق المعلمات لمزيد من التفاصيل.

تنظيم الإنتروبيا

لشجيع الاستكشاف ومنع انهيار السياسة إلى مخرجات شبه حتمية، يمكنك إضافة مكافأة إنتروبيا إلى هدف التدريب. تعمل تنظيم الإنتروبيا على تعزيز خسارة GRPO على النحو التالي: $$\mathcal{L}(\theta) = \mathcal{L}_{\text{GRPO}}(\theta) - \alpha \cdot \mathcal{H}(\pi_\theta),$$

حيث$\mathcal{H}(\pi_\theta)$ هو متوسط إنتروبيا الرمز الواحد للسياسة، و$\alpha$ هو معامل الإنتروبيا. المكافأة هي دائمًا متوسط إنتروبيا الرمز الواحد بغض النظر عن loss_type; ، فهي لا تُعاد مقياستها لتتوافق مع تطبيع السياسة الخاص بنوع الخسارة (مثل مقام batch_size * max_completion_length في Dr. GRPO)، لذا فإن entropy_coef يحمل نفس المعنى لجميع أنواع الخسارة.

إنتروبيا ثابتة — معامل ثابت طوال التدريب:

from trl import GRPOConfig, GRPOTrainer

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

الإنتروبيا التكيفية — يتم تحديث المعامل في كل خطوة من خطوات المُحسِّن بناءً على إنتروبيا مستهدفة، كما تم تقديمه في Skywork-OR1. عندما تكون الإنتروبيا الحالية عند أو أقل من entropy_target، يتم زيادة المعامل بمقدار entropy_coef_delta؛ وإلا يتم إنقاصه. يُطبَّق المعامل (أي يكون غير صفري) فقط عندما تكون الإنتروبيا عند أو أقل من الهدف:

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,
    ...
)

تتميز نماذج اللغة النموذجية بإنثروبيا لكل رمز تتراوح بين 2 و10 نات، لذا فإن القيمة الافتراضية entropy_target=0.2 لا تُفعّل التنظيم تقريبًا أبدًا — إذ لا يعمل المكافأة إلا عندما تكون الإنثروبيا عند الهدف أو أدنى منه، أي عند الانهيار شبه الكامل. اضبطها على قيمة ذات معنى لنموذجك، مثلًا قريبة من الإنثروبيا التي تلاحظها في المراحل المبكرة من التدريب (المُسجَّلة كمقياس entropy). عند استخدام top_entropy_quantile < 1.0، تُطبَّق entropy_target على مجموعة الرموز ذات الإنثروبيا العالية — وستكون إنثروبيا هذه المجموعة أعلى من entropy المُسجَّلة لجميع الرموز، لذا اضبط الإعدادات وفقًا لذلك.

عند تعيين use_adaptive_entropy=True، يُحفظ معامل الإنتروبيا الحالي entropy_coef جنبًا إلى جنب مع كل نقطة تحقق، ويُستعاد عند الاستئناف، مما يجعل التدريب قابلاً للاستئناف بالكامل.

التجارب السريعة لـ GRPO

RapidFire AI هو محرك تجارب مفتوح المصدر يعمل فوق TRL ويتيح لك إطلاق عدة تكوينات GRPO في وقت واحد، حتى على وحدة معالجة رسومية واحدة. بدلاً من تجربة التكوينات بشكل تسلسلي، يتيح لك RapidFire رؤية منحنيات التعلم الخاصة بها جميعاً في وقت أبكر، وإيقاف التشغيلات ذات الأداء الضعيف، ونسخ الواعدة منها بإعدادات جديدة أثناء التنفيذ دون إعادة التشغيل. لمزيد من المعلومات، راجع تكامل RapidFire AI.

تدريب الوكيل

يدعم GRPO تدريب الوكلاء: حيث يستدعي النموذج الأدوات أثناء التوليد ويتعلم من النتيجة.

• الأداة tool هي دالة بايثون بسيطة (متزامنة أو غير متزامنة) تُعرَض للنموذج. استخدم tools للاستدعاءات التي لا تعتمد على حالة (آلة حاسبة، بحث على الويب).
• يُعدّ البيئة الشكل الأكثر شمولاً: فهو كائن ذو حالة يُنشأ من جديد لكل تمريرة، وتُعرض دواله العامة كأدوات، بالإضافة إلى خطاف دورة حياة reset وخطاف اختياري get_reward يتيح له امتلاك المكافأة. استخدم environment_factory عندما تحتاج إلى حالة لكل تمريرة، أو خطاف إعادة تعيين، أو مكافأة تملكها البيئة.

يمكنك دمجها — حيث يمكنك تمرير tools مستقلة جنبًا إلى جنب مع environment_factory.

الأدوات

يتوقع الحجة tools قائمة من دوال بايثون (متزامنة أو غير متزامنة) تُعرّف الأدوات المتاحة للوكيل:

from trl import GRPOTrainer

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

يجب أن يكون كل أداة دالة بايثون قياسية مع حُجج وأنواع إرجاع مُعلَّمة بالنوع، إلى جانب سلسلة توثيق بنمط Google تصف غرضها وحُججها وقيمة الإرجاع. لمزيد من التفاصيل، راجد دليل تمرير الأدوات.

يتطلب حلقة استدعاء الأدوات في GRPO أن يكون قالب المحادثة حافظًا على البادئة (يجب ألا يؤدي إضافة رسالة أداة إلى تغيير طريقة عرض الرسائل السابقة). بالنسبة لعائلات النماذج المعروفة (مثل Qwen3 وDeepSeek-V3)، تقوم TRL تلقائيًا باستبدال قالب التدريب المُصلَح عند تمكين الأدوات. راجع قوالب المحادثة للحصول على القائمة الكاملة.

استخدم max_tool_calling_iterations في GRPOConfig لتحديد الحد الأقصى لعدد جولات استدعاء الأدوات. افتراضيًا، لا يوجد حد، ويتوقف التوليد عندما ينتج النموذج ردًا لا يتضمن أي استدعاءات للأدوات.

مثال:

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],
    ...,
)

البيئات

يمكنك أيضًا توفير الأدوات من خلال environment_factory. في هذا الوضع، يقوم GRPOTrainer بإنشاء نسخة واحدة من البيئة لكل تمريرة (rollout) ويعرض الدوال العامة للبيئة كأدوات.

يتطلب environment_factory وجود transformers>=5.2.0.

عند استخدام environment_factory، تمتلك البيئة البيانات: فلا يوجد train_dataset خارجي. في كل تمريرة، يُنتج reset() المهمة — إما عبر أخذ عينات ذاتية من مجموعة نصوص تحتفظ بها البيئة، أو عبر توليد حالة إجرائياً — ويعيد الموجه. يحدد max_steps طول التدريب. فيما يلي مثال مبسط لبيئة تأخذ عينات ذاتية من هدف وتعرض طريقة increment (مُعرَّضة كأداة).

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

تحتوي فئة البيئة على طريقتين محجوزتين: reset وget_reward. على عكس أي طرق عامة أخرى، لا تُعرَض هذه الطرق للنموذج كأدوات.

• يُستدعى reset (إلزامي) عند بدء التمرين. يمكن أن يعيد None أو نصًا. في GRPO، عندما يعيد نصًا، يكون ذلك النص هو موجه المستخدم.
• get_reward (اختياري، متزامن أو غير متزامن) لا يستقبل أي حجة ويعيد قيمة من نوع float: حيث يقوم البيئة بتقييم الحلقة التي أكّدها للتو بناءً على حالته الداخلية (هل انتهت اللعبة بفوز؟ هل تم تخمين الكلمة؟). يُستدعى مرة واحدة لكل تمريرة مكتملة ويعمل كمصدر للمكافأة.

بما أن البيئة تُعيد أخذ العينات من نفسها عند كل reset()، فقد لا تتشارك أعضاء مجموعة GRPO الـG نفس الحالة الأولية، مما يجعل خط الأساس للمجموعة أكثر ضوضاءً قليلاً. للحصول على حالات متطابقة داخل المجموعة، اجعل reset() يُشتق الحالة بشكل حتمي من مفتاح مشترك.

توفير مجموعة بيانات خارجية (اختياري)

بدلاً من السماح للبيئة بأخذ عينات ذاتية، يمكنك توفير train_dataset خارجي. على سبيل المثال، عندما تكون مهامك موجودة بالفعل في مجموعة بيانات، أو للتوجيه بين بيئات متعددة. في كل تمريرة تدريبية، يأخذ المدرب صفًا واحدًا، ويستخدم عموده "prompt" كموجّه، ويمرر أعمدة الصف الأخرى إلى reset() كحجج باسم (حتى تقرأ البيئة المهمة من مجموعة البيانات).

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

المكافآت

لا تتعارض المكافآت التي يديرها البيئة مع المكافآت التي يديرها المدرب. مرّر reward_funcs للمكافآت التي يُعدّ حسابها من الإكمال أمراً طبيعياً (مثل فحص التنسيق على النص) و اترك البيئة تُرجع مكافأتها المعتمدة على حالتها عبر get_reward. تُجمع جميع المصادر؛ reward_weights ينطبق على reward_funcs فقط (البيئة تملك مقياسها الخاص).

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 أيضاً قراءة حالة البيئة مباشرة: عند تعيين environment_factory، يمرّن المدرب معامل environments (نسخة واحدة لكل إكمال). قد يكون هذا مفيداً في بعض الأحيان، لكن تفضّل استخدام get_reward للمكافآت المعتمدة على الحالة.

يعمل هذا بنفس الطريقة تمامًا مع AsyncGRPOTrainer.

بيئات متعددة

لتدريب النموذج على مزيج من المهام في تشغيل واحد (مثل مهمة برمجة ولعبة)، مرر قاموسًا يربط أسماء البيئات بمصانعها بدلاً من دالة قابلة للاستدعاء واحدة. يختار كل تمرين بيئته عبر حقل environment في مجموعة البيانات، وتُعرض أدوات تلك البيئة فقط. يتجنب هذا تسريب أدوات غير ذات صلة (أداة move الخاصة باللعبة إلى مثال برمجي، والعكس صحيح). ما تزال كل بيئة تمتلك بياناتها وتعيد الموجه من reset()، لذا لا تحتاج مجموعة البيانات سوى عمود environment للتوجيه بينها.

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

لا تزال دالة المكافأة تستقبل بيئة كل مثال عبر reward_kwargs["environments"]، مما يتيح لها التفرع بناءً على نوع البيئة (مثل isinstance(env, CodingEnv)). تُعاد استخدام أمثلة البيئة عبر الخطوات (مع إعادة الضبط بين الحلقات)، لذا يُدفع ثمن __init__ المكلف مرة واحدة بدلاً من كل خطوة. يُستهلك حقل environment من قِبل المدرب ولا يُمرَّر إلى reset.

استجابات الأدوات متعددة الوسائط

يمكن للأدوات إرجاع الصور إلى جانب النص عن طريق إرجاع قائمة من كتل المحتوى. وهذا مفيد لتدريب وكلاء نماذج اللغة المرئية (VLM) حيث يوفر الأداة تغذية راجعة بصرية (مثل لقطات الشاشة، والمخططات، والتقاطات الكاميرا).

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."}]

تُحقن الصور المُعادَة تلقائيًا في المحادثة وتُمرَّر إلى VLM لجولات التوليد اللاحقة.

النماذج المدعومة

تم الاختبار مع:

• Beam — على سبيل المثال، reflection/Beam-1.0-501B-A23B
• DeepSeek-R1 — على سبيل المثال، deepseek-ai/DeepSeek-R1
• Gemma4 — على سبيل المثال، google/gemma-4-E2B-it
• GLM-4-MoE (4.5 أو 4.6 أو 4.7) — على سبيل المثال zai-org/GLM-4.7
• GPT-OSS — على سبيل المثال، openai/gpt-oss-20b
• Llama 3.1 — على سبيل المثال، meta-llama/Llama-3.1-8B-Instruct
• Llama 3.2 — على سبيل المثال، meta-llama/Llama-3.2-3B-Instruct
• Qwen2.5 — على سبيل المثال، Qwen/Qwen2.5-0.5B-Instruct
• Qwen3 — على سبيل المثال، Qwen/Qwen3-0.6B
• Qwen3-VL — على سبيل المثال، Qwen/Qwen3-VL-2B-Instruct
• Qwen3.5 — على سبيل المثال، Qwen/Qwen3.5-2B
• Qwen3.6 — على سبيل المثال، Qwen/Qwen3.6-35B-A3B

لا يُكفَل التوافق مع جميع نماذج اللغة الكبيرة. إذا كنت تعتقد أنه ينبغي دعم نموذج معين، فلا تتردد في فتح مشكلة على GitHub — أو الأفضل من ذلك، تقديم طلب سحب يتضمن التغييرات المطلوبة.

التكاملات مع البيئات

تتصل جميع البيئات بنفس خانة environment_factory، لذا فهي قابلة للاستبدال على مستوى TRL — اختر البيئة التي يناسب نظامها البيئي مهمتك:

تدريب نماذج اللغة البصرية

GRPO يدعم تدريب نماذج الرؤية واللغة (VLMs) على مجموعات بيانات متعددة الوسائط تحتوي على نص وصور.

النماذج المدعومة

تم الاختبار مع:

• Gemma3 — على سبيل المثال، google/gemma-3-4b-it
• LLaVA-NeXT — على سبيل المثال، llava-hf/llava-v1.6-mistral-7b-hf
• Qwen2-VL — على سبيل المثال، Qwen/Qwen2-VL-2B-Instruct
• Qwen2.5-VL — على سبيل المثال، Qwen/Qwen2.5-VL-3B-Instruct
• SmolVLM2 — على سبيل المثال، HuggingFaceTB/SmolVLM2-2.2B-Instruct

لا يُكفَل التوافق مع جميع نماذج VLM. إذا كنت تعتقد أنه ينبغي دعم نموذج معين، فلا تتردد في فتح مشكلة على GitHub — أو الأفضل من ذلك، تقديم طلب سحب يتضمن التغييرات المطلوبة.

البدء السريع

استخدم grpo_vlm.py لضبط نموذج VLM. مثال على الأمر للتدريب على 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

نصائح حول التهيئة

• استخدام LoRA على طبقات الإسقاط الخاصة بلغة الرؤية
• تفعيل التكميم بدقة 4 بت لتقليل استهلاك الذاكرة
• تستهلك نماذج اللغة المرئية (VLMs) ذاكرة كبيرة — ابدأ بحجم دفعات أصغر
• تتوافق معظم النماذج مع vLLM (أوضاع server وcolocate)

تنسيق مجموعة البيانات

يجب أن يتضمن كل عينة تدريب:

• prompt: نص منسّق عبر قالب المحادثة الخاص بالمعالج
• image/images: صورة PIL أو قائمة بصور PIL

يتولى المدرب تلقائياً تحويل الصور إلى متجهات (تensors) عبر معالج الصور الخاص بالنموذج.

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