# مدرب GRPO

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

## نظرة عامة

يدعم TRL مُدرّب GRPO لتدريب نماذج اللغة، كما هو موصوف في ورقة [DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models](https://huggingface.co/papers/2402.03300) التي كتبها [Zhihong Shao](https://huggingface.co/syhia)، [Peiyi Wang](https://huggingface.co/peiyiwang89)، [Qihao Zhu](https://huggingface.co/zqh11)، Runxin Xu، [Junxiao Song](https://huggingface.co/haha-point)، Mingchuan Zhang، Y. K. Li، Y. Wu، [Daya Guo](https://huggingface.co/guoday).

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

> يُشكّل الاستدلال الرياضي تحديًا كبيرًا لنماذج اللغة بسبب طبيعته المعقدة والمنظمة. في هذه الورقة، نُقدّم 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](https://huggingface.co/qgallouedec) في هذه طريقة ما بعد التدريب.

## البدء السريع

يُظهر هذا المثال كيفية تدريب نموذج باستخدام طريقة GRPO. نقوم بتدريب [نموذج Qwen2.5 0.5B Instruct](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct) باستخدام الأوامر من [مجموعة بيانات DeepMath-103K](https://huggingface.co/datasets/trl-lib/DeepMath-103K). يمكنك عرض البيانات في مجموعة البيانات هنا:

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

فيما يلي السكربت لتدريب النموذج. يحتاج `accuracy_reward` إلى math-verify، والذي يمكنك تثبيته باستخدام `pip install trl[math_verify]`.

```python
# 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()
```

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

```bash
torchrun --nproc_per_node 8 train_grpo.py
```

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

![GRPO curves](https://huggingface.co/datasets/trl-lib/documentation-images/resolve/main/grpo_curves.png)

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

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

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

![GRPO visual](https://huggingface.co/datasets/trl-lib/documentation-images/resolve/main/grpo_visual.png)

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

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

### حساب الميزة

لكلٍّ من تسلسلات \\( G \\)، نحسب المكافأة باستخدام نموذج مكافآت أو دالة مكافآت. ولتوافق مع الطبيعة المقارنة لنماذج المكافآت — التي تُدرَّب عادةً على مجموعات بيانات من المقارنات بين المخرجات للسؤال نفسه — تُحسب الميزة لتعكس هذه المقارنات النسبية. وتُطبع على النحو التالي:

$$\hat{A}_{i,t} = \frac{r_i - \text{mean}(\mathbf{r})}{\text{std}(\mathbf{r})}$$

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

> [!TIP]
> أظهرت الورقة [Understanding R1-Zero-Like Training: A Critical Perspective](https://huggingface.co/papers/2503.20783) أن التوسيع بواسطة \\( \text{std}(\mathbf{r}) \\) قد يسبب انحيازاً في صعوبة مستوى السؤال. يمكنك تعطيل هذا التوسيع عن طريق تعيين `scale_rewards=False` في [GRPOConfig](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOConfig). لاحظ أن إيقاف التوسيع القائم على الانحراف المعياري يزيل أيضاً تطبيع التباين، لذا فإن أحجام التحديث تعتمد بشكل مباشر على مقياس المكافأة الخام وتكوين الدفعة.

> [!TIP]
> كما هو موضح في [الجزء الأول: حيل أم فخاخ؟ غوص عميق في التعلم المعزز لاستدلال نماذج اللغة الكبيرة (Lite PPO)](https://huggingface.co/papers/2508.08221)، فإن حساب المتوسط على المستوى المحلي (المجموعة) والانحراف المعياري على المستوى العام (الدفع) يتيح تشكيل مكافآت أكثر متانة. يمكنك استخدام استراتيجية التوسيع هذه عن طريق تعيين `scale_rewards="batch"` في [GRPOConfig](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOConfig).

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

تُقدَّر تباعد كولباك-ليبلير باستخدام المُقدِّر الذي قدمه [Schulman et al. (2020)](http://joschu.net/blog/kl-approx.html). يُعرَّف المُقدِّر على النحو التالي:

$$\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], $$

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

> [!TIP]
> لاحظ أنه مقارنةً بالصياغة الأصلية في [DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models](https://huggingface.co/papers/2402.03300)، لا نضرب في \\( \frac{1}{|o_i|} \\) لأنه تم إثبات في الورقة [Understanding R1-Zero-Like Training: A Critical Perspective](https://huggingface.co/papers/2503.20783) أن ذلك يُدخل تحيّزاً في طول الاستجابة على مستوى الرد. مزيد من التفاصيل في [أنواع الدالة الخاسرة](#loss-types).

> [!TIP]
> لاحظ أنه مقارنةً بالصياغة الأصلية في [DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models](https://huggingface.co/papers/2402.03300)، نستخدم \\( \beta = 0.0 \\) افتراضيًا، مما يعني أن حد تباعد KL لا يُستخدم. وقد دُفعنا إلى هذا الاختيار بعدة دراسات حديثة (مثل [Open-Reasoner-Zero: An Open Source Approach to Scaling Up Reinforcement Learning on the Base Model](https://huggingface.co/papers/2503.24290)) التي أظهرت أن حد تباعد KL ليس ضروريًا للتدريب باستخدام GRPO. ونتيجةً لذلك، أصبح من الشائع استبعاده (مثل [Understanding R1-Zero-Like Training: A Critical Perspective](https://huggingface.co/papers/2503.20783)، [DAPO: An Open-Source LLM Reinforcement Learning System at Scale](https://huggingface.co/papers/2503.14476)). إذا كنت ترغب في تضمين حد تباعد KL، يمكنك تعيين `beta` في [GRPOConfig](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOConfig) إلى قيمة غير صفرية.

في الورقة الأصلية، يتم تعميم هذه الصياغة لتأخذ في الاعتبار عدة تحديثات بعد كل توليد (يُرمز لها بـ \\( \mu \\)، ويمكن ضبطها عبر `num_iterations` في [GRPOConfig](/docs/trl/v1.18.0/ar/grpo_trainer#trl.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](https://huggingface.co/papers/2503.14476) قيود خسارة مستوى العينة في خوارزمية 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](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOConfig).

علاوة على ذلك، أثبتت الورقة [Understanding R1-Zero-Like Training: A Critical Perspective](https://huggingface.co/papers/2503.20783) أن صياغة 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](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOConfig).

بديلًا عن ذلك، في [ورقة SAPO](https://huggingface.co/papers/2511.20347)، يقترح فريق 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](/docs/trl/v1.18.0/ar/grpo_trainer#trl.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](https://github.com/vllm-project/vllm)، وهو محرك استدلال عالي الإنتاجية ومنخفض الكمون للنماذج اللغوية الكبيرة. لتفعيله، قم أولاً بتثبيت الحزمة باستخدام

```shell
pip install trl[vllm]
```

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

> [!TIP]
> بشكل افتراضي، يتم تفعيل أخذ عينات الأهمية المقنّعة على مستوى التسلسل (`vllm_importance_sampling_mode="sequence_mask"`) لتوليد vLLM لمعالجة عدم التطابق بين التوليد والتدريب الذي يحدث عند استخدام أطر عمل مختلفة. يمكن تعطيل ذلك عن طريق تعيين `vllm_importance_sampling_correction=False`. لمزيد من المعلومات، راجع [أخذ عينات الأهمية المقنّعة](paper_index#masked-importance-sampling) و [أخذ عينات الأهمية على مستوى التسلسل](paper_index#sequence-level-importance-sampling)

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

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

```python
from trl import GRPOConfig

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

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

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

1. **بدء خادم vLLM**:

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

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

   ```python
   from trl import GRPOConfig

   training_args = GRPOConfig(
       ...,
       use_vllm=True,
       vllm_mode="server",
   )
   ```

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

> [!TIP]
> يعتمد على حجم النموذج ومتطلبات ذاكرة وحدة معالجة الرسوميات (GPU) الإجمالية للتدريب، قد تحتاج إلى ضبط معامل `vllm_gpu_memory_utilization` في [GRPOConfig](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOConfig) لتجنب سوء الاستخدام أو أخطاء نفاد الذاكرة.
>
> نوفر [مساحة HF](https://huggingface.co/spaces/trl-lib/recommend-vllm-memory) لمساعدتك في تقدير استهلاك ذاكرة وحدة معالجة الرسوميات الموصى به بناءً على إعدادات النموذج وإعدادات التجربة الخاصة بك. ما عليك سوى استخدامه على النحو التالي للحصول على توصية `vllm_gpu_memory_utilization`:
>
> 
>
> إذا لم يعمل القيمة الموصى بها في بيئتك، نقترح إضافة هامش صغير (مثل +0.05 أو +0.1) إلى القيمة الموصى بها لضمان الاستقرار.
>
> إذا كنت لا تزال تواجه أخطاء نفاد الذاكرة، فاضبط `vllm_enable_sleep_mode` على True وسيتم تفريغ معاملات vllm والذاكرة المؤقتة أثناء خطوة التحسين. لمزيد من المعلومات، راجع [تقليل استخدام الذاكرة مع وضع السكون في vLLM](reducing_memory_usage#vllm-sleep-mode).

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

لمزيد من المعلومات، راجع [تسريع التدريب باستخدام vLLM](speeding_up_training#vllm-for-fast-generation-in-online-methods).

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

يؤدي هذا الاختلاف إلى تحديث متحيز للتدرج، وقد لوحظ أنه يُزعزع استقرار التدريب ([[1]](https://fengyao.notion.site/off-policy-rl)[[2]](https://yingru.notion.site/When-Speed-Kills-Stability-Demystifying-RL-Collapse-from-the-Training-Inference-Mismatch-271211a558b7808d8b12d403fd15edda)[[3]](https://thinkingmachines.ai/blog/defeating-nondeterminism-in-llm-inference/#true-on-policy-rl)[[4]](https://huggingface.co/papers/2510.26788)[[5]](https://huggingface.co/papers/2510.18855)). وبسبب البساطة، لنفترض تدرج سياسة 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]. $$

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

الطريقة القياسية لتصحيح هذا الانزياح في التوزيع هي **العينة المهمة (IS)**. نقدم متغيرين من العينة المهمة: [العينة المهمة المقطوعة (TIS)](paper_index#truncated-importance-sampling) و [العينة المهمة المقنّعة (MIS)](paper_index#masked-importance-sampling). يمكن تطبيق كلا المتغيرين على مستوى الرمز (token) أو على مستوى التسلسل. ليكن  \\( \rho \\) يرمز إلى وزن الأهمية، على سبيل المثال  \\( \rho_t \\) لكل رمز أو  \\( \rho_{\text{seq}} \\) لكل تسلسل. في إطار TIS، يتم اقتصاص النسب خارج النطاق `[vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max]`،

$$ \rho \leftarrow \text{clip}(\rho, C_{\min}, C_{\max}). $$

اقترح [ورقة TIS الأصلية](https://huggingface.co/papers/1606.02647) آلية قصّ واحدة للحد الأعلى، أي \\( \min(\rho, C_{\max}) \\). وقد عمّم التنفيذ في TRL ذلك من خلال إدخال حدّ أدنى أيضاً، مما أدى إلى الصياغة ذات الجانبين المعروضة أعلاه، مستوحاة من طريقة [IcePop](paper_index#masked-importance-sampling). لاحظ أنه في IcePop، تُسمّى الحدود \\( \alpha \\) و \\( \beta \\) بينما نستخدم في TRL \\( C_{\min} \\) و \\( C_{\max} \\).

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

يُعدّ أخذ العينات حسب الأهمية (Importance sampling) الاستجابة الخوارزمية المبنية على مبادئ منهجية لاختلاف التدريب عن الاستدلال. ومع ذلك، هناك أيضاً أساليب أكثر مباشرةً تهدف إلى تقليل الفجوة بين المحركين نفسيهما. معظم هذه الأساليب حلول هندسية. فعلى سبيل المثال، يستخدم [MiniMax M1 رأس نموذج لغوي بدقة FP32](https://huggingface.co/papers/2506.13585) في محرك الاستدلال. وقد استكشفت Thinking Machines [أنوية استدلال حتمية](https://thinkingmachines.ai/blog/defeating-nondeterminism-in-llm-inference/)، على الرغم من أن ذلك يأتي على حساب كفاءة كبيرة. وقد أظهر vLLM [سياسات متطابقة على مستوى البت](https://blog.vllm.ai/2025/11/10/bitwise-consistent-train-inference.html) من خلال البناء على أنوية الاستدلال الحتمية غير المعتمدة على حجم الدفعة (batch invariant) من Thinking Machines، لكن حتى نوفمبر 2025 لا يزال هناك انخفاض كبير في معدل الإنتاجية مقارنةً بالاستدلال القياسي في vLLM.

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

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

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

```python
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
    },
)
```

> [!TIP]
> تعيّن TRL قيمة `max_memory_percent` افتراضيًا إلى `0.5` (بدلًا من `0.9` في transformers) لتوفير مساحة كافية من ذاكرة VRAM لمرحلة الرجوع الخلفي في التدريب. اضبطها إلى ما بين `0.3` و`0.4` عند استخدام دفعات توليد كبيرة (N≥32) أو عند ظهور أخطاء نفاد الذاكرة.

لمثال تدريب كامل، راجع [`examples/grpo_continuous_batching/grpo_continuous_batching.py`](https://github.com/huggingface/trl/blob/main/examples/grpo_continuous_batching/grpo_continuous_batching.py).

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

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

- **DeepSpeed ZeRO Stage 3**: يستفيد ZeRO من توازي البيانات لتوزيع حالات النموذج (الأوزان، التدرجات، حالات المُحسِّن) على وحدات معالجة رسومية ووحدات معالجة مركزية متعددة، مما يقلل من متطلبات الذاكرة والحساب على كل جهاز. وبما أن النماذج الكبيرة لا يمكن استيعابها على وحدة معالجة رسومية واحدة، فإن استخدام ZeRO Stage 3 مطلوب لتدريب مثل هذه النماذج. لمزيد من التفاصيل، راجع [DeepSpeed Integration](deepspeed_integration).
- **torchrun**: يبدأ مُشغِّل PyTorch عملية واحدة لكل وحدة معالجة رسومية على كل عقدة، ويربطها عبر نقطة تجمع مشتركة. لمزيد من التفاصيل، راجع [توزيع التدريب](distributing_training).
- **vLLM**: راجع القسم السابق لمعرفة كيفية استخدام vLLM لتسريع عملية التوليد.

فيما يلي مثال على سكربت SLURM لتدريب نموذج بحجم 70B باستخدام GRPO على عدة عقد. يقوم هذا السكربت بتدريب النموذج على 4 عقد ويستخدم العُقدة الخامسة للتوليد المدعوم بـ vLLM.

```sh
#!/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}" torchrun \
     --nnodes 4 \
     --nproc_per_node 8 \
     --node_rank $SLURM_PROCID \
     --rdzv_backend c10d \
     --rdzv_endpoint ${NODELIST[0]}:29500 \
     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
```

```python
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,
        deepspeed="examples/deepspeed_configs/zero3.json",
        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](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOTrainer) استخدام دوال مكافأة مخصصة بدلاً من نماذج المكافأة الكثيفة. لضمان التوافق، يجب أن تستوفي دالة المكافأة الخاصة بك المتطلبات التالية:

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

1. **حجج الإدخال**:
   - يجب أن تقبل الدالة ما يلي كحجج مُسمّاة:
     - `prompts` (تحتوي على الأوامر)،
     - `completions` (تحتوي على الاكتمالات المولّدة)،
     - `completion_ids` (تحتوي على المكملات المُرمَّزة)،
     - `trainer_state` ([TrainerState](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.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` بدلاً من ذلك — راجع [المكافآت](#rewards).
     - جميع أسماء الأعمدة (باستثناء `prompt`) التي قد يحتوي عليها مجموعة البيانات. على سبيل المثال، إذا كانت مجموعة البيانات تحتوي على عمود باسم `ground_truth`، فسيتم استدعاء الدالة مع `ground_truth` كحجة اسمية.

     أسهل طريقة للامتثال لهذا المتطلب هي استخدام `**kwargs` في توقيع الدالة.
   - يعتمد شكل المدخلات على صيغة مجموعة البيانات:
     - في [الصيغة القياسية](dataset_formats#standard)، ستكون `prompts` و`completions` قوائم من النصوص.
     - في [الصيغة الحوارية](dataset_formats#conversational)، ستكون `prompts` و`completions` قوائم من قواميس الرسائل.

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

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

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

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

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

```python
>>> 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: مكافأة الإكمالات الأطول (بناءً على عدد الأحرف)

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

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

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

```python
>>> 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](https://huggingface.co/papers/2501.12948). وهي مصممة لتنسيق محادثة، حيث تتكون المحفزات (prompts) والإكمالات (completions) من رسائل منظمة.

```python
import re

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

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

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

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

فيما يلي مثال على دالة مكافأة تتحقق من صحة الإكمال. يستلهم هذا المثال دالة _مكافأة الدقة_ المستخدمة في ورقة [DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning](https://huggingface.co/papers/2501.12948). صُمم هذا المثال لـ[التنسيق القياسي](dataset_formats#standard)، حيث يحتوي مجموعة البيانات على عمود باسم `ground_truth`.

```python
import re

def reward_func(completions, ground_truth, **kwargs):
    # Regular expression to capture content inside \boxed{}
    matches = [re.search(r"\\boxed\{(.*?)\}", completion) 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)]
```

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

```python
>>> 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](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOTrainer). في هذا المثال، نعرّف دالتي مكافأة مخصصتين للمهام: `math_reward_func` و`coding_reward_func`. تمنح `math_reward_func` مكافأة للمسائل الرياضية بناءً على صحتها، بينما تمنح `coding_reward_func` مكافأة لمسائل البرمجة بناءً على ما إذا كانت الحل يعمل.

```python
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](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOTrainer) العمل بالدوال والمهام الصالحة. وهذا يتيح لـ[GRPOTrainer](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOTrainer) التعامل مع دوال مكافأة متعددة ذات نطاقات تطبيق مختلفة.

لاحظ أن [GRPOTrainer](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOTrainer) سيتجاهل مكافآت `None` التي تُعاد من دوال المكافآت، وسيأخذ في الاعتبار فقط المكافآت التي تُعاد من الدوال ذات الصلة. وهذا يضمن تدريب النموذج على المهام ذات الصلة وتجاهل المهام التي لا توجد لها دالة مكافآت ذات صلة.

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

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

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

```python
import asyncio

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

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

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

```python
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](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOTrainer) على النحو التالي:

```python
from trl import GRPOTrainer

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

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

```python
from trl import GRPOTrainer

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

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

لاحظ أن [GRPOTrainer](/docs/trl/v1.18.0/ar/grpo_trainer#trl.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` يحمل المعنى نفسه لجميع أنواع الخسارة.

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

```python
from trl import GRPOConfig, GRPOTrainer

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

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

```python
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](rapidfire_integration).

## تدريب الوكيل

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

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

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

### الأدوات

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

```python
from trl import GRPOTrainer

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

يجب أن يكون كل أداة دالة بايثون قياسية مع **حُجج وأنواع إرجاع مُعلَّمة بالنوع**، إلى جانب **سلسلة توثيق بنمط Google** تصف غرضها وحُججها وقيمة الإرجاع. لمزيد من التفاصيل، راجد [دليل تمرير الأدوات](https://huggingface.co/docs/transformers/en/chat_extras#passing-tools).

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

استخدم `max_tool_calling_iterations` في [GRPOConfig](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOConfig) لتحديد الحد الأقصى لعدد جولات استدعاء الأدوات. افتراضيًا، لا يوجد حد، ويتوقف التوليد عندما ينتج النموذج ردًا بدون استدعاءات أدوات، أو عندما يصل الاكتمال (جميع الجولات ونتائج الأدوات) إلى `max_completion_length` رمزًا، أو عندما يصل التسلسل الكامل إلى الحد الأقصى لطول النموذج (`vllm_max_model_length` مع `vllm_mode="colocate"`، وإلا `max_position_embeddings` للنموذج).

مثال:

```python
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](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOTrainer) بإنشاء نسخة واحدة من البيئة لكل تمريرة (rollout) ويعرض الدوال العامة للبيئة كأدوات.

> [!IMPORTANT]
> يتطلب `environment_factory` وجود `transformers>=5.2.0`.

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

```python
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`: حيث يقوم البيئة بتقييم الحلقة التي أكّدها للتو بناءً على حالته الداخلية (هل انتهت اللعبة بفوز؟ هل تم تخمين الكلمة؟). يُستدعى مرة واحدة لكل تمريرة مكتملة ويعمل كمصدر للمكافأة.

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

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

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

```python
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` فقط (البيئة تملك مقياسها الخاص).

```python
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`](async_grpo_trainer).

### بيئات متعددة

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

```python
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) حيث يوفر الأداة تغذية راجعة بصرية (مثل لقطات الشاشة، والمخططات، والتقاطات الكاميرا).

```python
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**](https://huggingface.co/collections/deepseek-ai/deepseek-r1) — على سبيل المثال، `deepseek-ai/DeepSeek-R1`
- [**Gemma4**](https://huggingface.co/collections/google/gemma-4) — على سبيل المثال، `google/gemma-4-E2B-it`
- **GLM-4-MoE** ([4.5](https://huggingface.co/collections/zai-org/glm-45) أو [4.6](https://huggingface.co/collections/zai-org/glm-46) أو [4.7](https://huggingface.co/collections/zai-org/glm-47)) — على سبيل المثال `zai-org/GLM-4.7`
- [**GPT-OSS**](https://huggingface.co/collections/openai/gpt-oss) — على سبيل المثال، `openai/gpt-oss-20b`
- [**Llama 3.1**](https://huggingface.co/collections/meta-llama/llama-31) — على سبيل المثال، `meta-llama/Llama-3.1-8B-Instruct`
- [**Llama 3.2**](https://huggingface.co/collections/meta-llama/llama-32) — على سبيل المثال، `meta-llama/Llama-3.2-3B-Instruct`
- [**Qwen2.5**](https://huggingface.co/collections/Qwen/qwen25) — على سبيل المثال، `Qwen/Qwen2.5-0.5B-Instruct`
- [**Qwen3**](https://huggingface.co/collections/Qwen/qwen3) — على سبيل المثال، `Qwen/Qwen3-0.6B`
- [**Qwen3-VL**](https://huggingface.co/collections/Qwen/qwen3-vl) — على سبيل المثال، `Qwen/Qwen3-VL-2B-Instruct`
- [**Qwen3.5**](https://huggingface.co/collections/Qwen/qwen35) — على سبيل المثال، `Qwen/Qwen3.5-2B`
- [**Qwen3.6**](https://huggingface.co/collections/Qwen/qwen36) — على سبيل المثال، `Qwen/Qwen3.6-35B-A3B`

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

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

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

| التكامل | ما هو | استخدمه عندما |
|---|---|---|
| [OpenEnv](openenv) | معيار البيئة المفتوحة (واجهة برمجة تطبيقات بأسلوب Gymnasium، تُقدَّم عبر WebSocket أو التنفيذ المُحاوِر)، مدعوم من Hugging Face والمجتمع. | أنت تستخدم بيئة OpenEnv جاهزة من Hub، أو تُعرّف بيئتك الخاصة وفقًا للمعيار المفتوح (مثل Wordle وSudoku وCatch). |
| [OpenReward](openreward) | تكامل مع بيئات تدعم لغة ORS (كتالوج [openreward.ai](https://openreward.ai) أو خادم ORS الخاص بك)؛ حيث تُقدَّم المهام **و** المكافآت عبر HTTP. | تريد التدريب في بيئة ORS: الكتالوج (مثل `Eigent/SETA`)، أو بيئة تستضيفها بنفسك على بنيتك التحتية، أو خادم محلي تقوم بتطويره. |
| [Harbor](harbor) | تكامل مع مجموعات مهام Harbor: كل مهمة هي تعليمات، صورة رملية حقيقية (`docker`، `e2b`، ...)، ومُتحقِّق داخل البيئة الرملية. | تريد التدريب مقابل مجموعة مهام Harbor: وهي شجرة من المهام، كل منها عبارة عن بيئة معزولة مكتفية ذاتياً بالإضافة إلى مُتحقق (على سبيل المثال، وكيل تحليل بيانات يستكشف الملفات داخل بيئة معزولة ويكتب إجابة يتحقق منها مُقيّم). |

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

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`

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

### البدء السريع

استخدم [grpo\_vlm.py](https://github.com/huggingface/trl/blob/main/examples/grpo_visual_math/grpo_visual_math.py) لضبط نموذج VLM. مثال على الأمر للتدريب على [`lmms-lab/multimodal-open-r1-8k-verified`](https://huggingface.co/datasets/lmms-lab/multimodal-open-r1-8k-verified):

```bash
torchrun --nproc_per_node 8 examples/grpo_visual_math/grpo_visual_math.py \
  --deepspeed examples/deepspeed_configs/zero3.json \
  --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[[trl.GRPOTrainer]]

#### trl.GRPOTrainer[[trl.GRPOTrainer]]

```python
trl.GRPOTrainer(model: str | PreTrainedModel | PeftModel, reward_funcs: str | transformers.modeling_utils.PreTrainedModel | collections.abc.Callable[..., list[float | None]] | list[str | transformers.modeling_utils.PreTrainedModel | collections.abc.Callable[..., list[float | None]]] | None = None, args: trl.trainer.grpo_config.GRPOConfig | None = None, train_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | None = None, eval_dataset: datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset | datasets.dataset_dict.DatasetDict | datasets.dataset_dict.IterableDatasetDict | dict[str, datasets.arrow_dataset.Dataset | datasets.iterable_dataset.IterableDataset] | None = None, processing_class: transformers.tokenization_utils_base.PreTrainedTokenizerBase | transformers.processing_utils.ProcessorMixin | None = None, reward_processing_classes: transformers.tokenization_utils_base.PreTrainedTokenizerBase | list[transformers.tokenization_utils_base.PreTrainedTokenizerBase] | None = None, callbacks: list[transformers.trainer_callback.TrainerCallback] | None = None, optimizers: tuple[typing.Optional[torch.optim.Optimizer], typing.Optional[torch.optim.lr_scheduler.LambdaLR]] = (None, None), quantization_config: BitsAndBytesConfig | None = None, peft_config: PeftConfig | None = None, tools: list[collections.abc.Callable] | None = None, rollout_func: collections.abc.Callable[[list[str], 'GRPOTrainer'], dict[str, typing.Any]] | None = None, environment_factory: collections.abc.Callable[[], trl.trainer.grpo_trainer._SupportsReset] | dict[str, collections.abc.Callable[[], trl.trainer.grpo_trainer._SupportsReset]] | None = None)
```

[المصدر](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/grpo_trainer.py#L143)

**المعاملات:**

model (`str` أو [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel) أو `PeftModel`) : النموذج المراد تدريبه. يمكن أن يكون: - نصًا، وهو *معرف النموذج* لنموذج مُدرَّب مسبقًا مستضاف داخل مستودع نماذج على huggingface.co، أو مسارًا إلى *مجلد* يحتوي على أوزان النموذج المحفوظة باستخدام [save_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.save_pretrained)، مثل `'./my_model_directory/'`. يتم تحميل النموذج باستخدام `<ModelArchitecture>.from_pretrained` (حيث يُشتق `<ModelArchitecture>` من إعدادات النموذج) مع حُجج الكلمات المفتاحية الموجودة في `args.model_init_kwargs`. إذا لم يُحدد `dtype` في `args.model_init_kwargs`، فإن القيمة الافتراضية هي `float32`. وهذا يختلف عن [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.from_pretrained)، حيث (منذ Transformers v5) يُستنتج نوع البيانات من إعدادات النموذج. - كائن [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel). يتم دعم نماذج اللغة السببية فقط. - كائن `PeftModel`. يتم دعم نماذج اللغة السببية فقط.

reward_funcs (`RewardFunc | list[RewardFunc]`، *اختياري*) : دوال المكافآت المستخدمة لحساب المكافآت. لحساب المكافآت، نستدعي جميع دوال المكافآت باستخدام الأوامر (prompts) والإكمالات (completions) ثم نجمع المكافآت. يمكن إهمال هذا المعامل عندما تُوفَّر المكافأة من خلال البيئة عبر `environment_factory` (انظر أدناه). يمكن أن يكون: - دالة مكافأة واحدة، مثل: - نص: *معرف النموذج* لنموذج مُدرَّب مسبقًا مستضاف داخل مستودع نماذج على huggingface.co، أو مسار إلى *مجلد* يحتوي على أوزان النموذج المحفوظة باستخدام [save_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel.save_pretrained)، على سبيل المثال `'./my_model_directory/'`. يتم تحميل النموذج باستخدام [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForSequenceClassification.from_pretrained) مع `num_labels=1` وحقول الكلمات المفتاحية في `args.model_init_kwargs`. - كائن [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel): يتم دعم نماذج تصنيف التسلسل فقط. - دالة مكافأة مخصصة: تُوفَّر للدالة الأوامر والإكمالات المولَّدة، بالإضافة إلى أي أعمدة إضافية في مجموعة البيانات. يجب أن تعيد قائمة بالمكافآت. يمكن أن تكون دوال المكافأة المخصصة متزامنة أو غير متزامنة، كما يمكن أن تعيد `None` عندما لا تنطبق المكافأة على تلك العينات. هذا مفيد للتدريب متعدد المهام حيث تنطبق دوال مكافأة مختلفة على أنواع مختلفة من العينات. عندما تعيد دالة مكافأة `None` لعينة، تُستبعد تلك الدالة من حساب المكافأة لتلك العينة. لمزيد من التفاصيل، راجع [استخدام دالة مكافأة مخصصة](#using-a-custom-reward-function). كما يتم تمرير حالة المدرب (trainer's state) إلى دالة المكافأة. حالة المدرب هي نسخة من [TrainerState](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerState) ويمكن الوصول إليها عن طريق الوصول إلى معامل `trainer_state` في توقيع دالة المكافأة. - قائمة من دوال المكافآت، حيث يمكن أن يكون كل عنصر بشكل مستقل أيًا من الأنواع المذكورة أعلاه. يُسمح بخلط أنواع مختلفة داخل القائمة (مثلًا، معرف نموذج نصي ودالة مكافأة مخصصة).

args ([GRPOConfig](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOConfig)، *اختياري*) : إعدادات لهذا المدرب. إذا كانت `None`، يتم استخدام إعداد افتراضي.

train_dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) أو [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset)، *اختياري*) : مجموعة البيانات المستخدمة للتدريب. يجب أن تتضمن عمودًا `"prompt"`. يتم تجاهل أي أعمدة إضافية في مجموعة البيانات. يمكن أن يكون تنسيق العينات إما: - [قياسي](dataset_formats#standard): تحتوي كل عينة على نص عادي. - [حواري](dataset_formats#conversational): تحتوي كل عينة على رسائل منظمة (مثل الدور والمحتوى).  يمكن حذفه فقط عند توفير `environment_factory` وتتملك البيئة (أو تولّد إجرائيًا) البيانات، مع إرجاع الموجه من طريقة `reset()` الخاصة بها. في هذه الحالة، يجب تعيين `max_steps` لتحديد طول التدريب.  عندما تكون `train_dataset` من نوع [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset) (مثل مجموعة بيانات التدفق)، يجب تعيين `max_steps` في حُجج التدريب، نظرًا لعدم إمكانية استنتاج طولها، ولأن العدد الإجمالي لخطوات التدريب مطلوب لتحديد حدود حلقة التدريب وإعداد مجدول معدل التعلم.

eval_dataset ([Dataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.Dataset) أو [IterableDataset](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDataset) أو [DatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.DatasetDict) أو [IterableDatasetDict](https://huggingface.co/docs/datasets/v5.2.0/en/package_reference/main_classes#datasets.IterableDatasetDict) أو `dict[str, Dataset | IterableDataset]`) : مجموعة البيانات المستخدمة للتقييم. يجب أن تستوفي نفس المتطلبات التي تستوفيها `train_dataset`.

processing_class ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/v5.23.0/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase)، [ProcessorMixin](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/processors#transformers.ProcessorMixin)، *اختياري*) : فئة المعالجة المستخدمة لمعالجة البيانات. يجب تعيين جانب الحشو إلى "left". إذا كانت `None`، يتم تحميل فئة المعالجة من اسم النموذج باستخدام [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoProcessor.from_pretrained). يجب تعيين رمز الحشو، `tokenizer.pad_token`. إذا لم تقم فئة المعالجة بتعيين رمز الحشو، سيتم استخدام `tokenizer.eos_token` كقيمة افتراضية.

reward_processing_classes ([PreTrainedTokenizerBase](https://huggingface.co/docs/transformers/v5.23.0/en/internal/tokenization_utils#transformers.PreTrainedTokenizerBase) أو `list[PreTrainedTokenizerBase]`، *اختياري*) : فئات المعالجة المقابلة لدوال المكافأة المحددة في `reward_funcs`. يمكن أن تكون: - فئة معالجة واحدة: تُستخدم عندما تحتوي `reward_funcs` على دالة مكافأة واحدة فقط. - قائمة بفئات المعالجة: يجب أن تتطابق مع ترتيب وطول دوال المكافأة في `reward_funcs`. إذا تم تعيينها إلى `None`، أو إذا كان العنصر في القائمة المقابل لـ [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel) هو `None`، يتم تحميل مُجزّئ النصوص للنموذج تلقائيًا باستخدام [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoTokenizer.from_pretrained). بالنسبة للعناصر في `reward_funcs` التي هي دوال مكافأة مخصصة (ليست [PreTrainedModel](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/model#transformers.PreTrainedModel))، يتم تجاهل الإدخالات المقابلة لها في `reward_processing_classes`.

callbacks (قائمة من [TrainerCallback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/callback#transformers.TrainerCallback)، *اختياري*) : قائمة من الاستدعاءات المخصصة لتخصيص حلقة التدريب. ستُضاف هذه الاستدعاءات إلى قائمة الاستدعاءات الافتراضية المفصّلة في [هنا](https://huggingface.co/docs/transformers/main_classes/callback). إذا كنت ترغب في إزالة أحد الاستدعاءات الافتراضية المستخدمة، فاستخدم طريقة [remove_callback](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.Trainer.remove_callback).

optimizers (`tuple[torch.optim.Optimizer | None, torch.optim.lr_scheduler.LambdaLR | None]`، *اختياري*، القيمة الافتراضية `(None, None)`) : مجموعة (tuple) تحتوي على المُحسِّن (optimizer) والمُجدوِل (scheduler) المطلوبين للاستخدام. ستكون القيمة الافتراضية هي نسخة من `AdamW` على نموذجك ومُجدوِل يُعطى بواسطة [get_linear_schedule_with_warmup](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/optimizer_schedules#transformers.get_linear_schedule_with_warmup) ويُتحكم به عبر `args`.

quantization_config ([BitsAndBytesConfig](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/quantization#transformers.BitsAndBytesConfig)، *اختياري*) : إعدادات التكميم المستخدمة عند تحميل النموذج من معرّف النموذج. ادمجها مع `peft_config` لتدريب QLoRA. يتم تجاهلها إذا كان النموذج مُنشأً بالفعل.

peft_config (`PeftConfig`، *اختياري*) : إعدادات PEFT المستخدمة لتغليف النموذج. إذا كانت `None`، فلن يتم تغليف النموذج.

tools (قائمة من `Callable`، *اختياري*) : قائمة من دوال الأدوات القابلة للاستدعاء (متزامنة أو غير متزامنة) يمكن للنموذج استدعاؤها أثناء التوليد. يجب أن تكون كل أداة دالة بايثون قياسية مع حُجج وقيم إرجاع مُعلَّمة الأنواع بشكل صحيح، وتعليق مستند بنمط Google يصف غرضها، وحُججها، وقيمة الإرجاع. لمزيد من التفاصيل، راجع: https://huggingface.co/docs/transformers/en/chat_extras#passing-tools. يستخدم النموذج اسم الدالة، وتلميحات الأنواع، وتعليق المستند لتحديد كيفية استدعائها. تأكد من أن قالب الدردشة الخاص بالنموذج يدعم استخدام الأدوات وأنه تم ضبطه الدقيق (fine-tuned) لاستدعاء الأدوات.

rollout_func (`RolloutFunc`، *اختياري*) : الدالة المستخدمة لتوليد الإكمالات. تستقبل قائمة الأوامر المخصصة للعملية الحالية ومثال المدرب. يجب أن تُرجع قاموسًا يحتوي على الحقول `"prompt_ids"` و`"completion_ids"` و`"logprobs"`، ويمكنها اختيارًا أن تُرجع `"logprob_token_ids"` (بنفس شكل `"logprobs"`). تُمرَّر أي حقول أخرى إلى دوال المكافأة. تستقبل الدالة شريحة الأوامر الخام لكل عملية دون تكرار؛ وهي مسؤولة عن إرجاع العدد الصحيح من الإكمالات لكل أمر (انظر `num_generations` / `num_generations_eval` على المدرب). هذه الميزة تجريبية وقد تتغير أو تُزال في أي وقت دون إشعار مسبق.

environment_factory (`EnvironmentFactory` أو `dict[str, EnvironmentFactory]`، *اختياري*) : دالة قابلة للاستدعاء تنشئ وتعيد نسخة من بيئة، أو قاموس يربط أسماء البيئات بدوال قابلة للاستدعاء من هذا النوع. يجب أن تعرّف فئة البيئة طرقًا يمكن استدعاؤها كأدوات أثناء التوليد. يجب أن تلتزم كل طريقة بنفس المتطلبات المطبّقة على `tools` المذكورة أعلاه. كما يجب على البيئة تنفيذ طريقة `reset` قابلة للاستدعاء يمكن استخدامها لإعادة تعيين الحالة بين عمليات التوليد. يجب أن تعيد طريقة `reset` إما `None` أو نصًا: عند إرجاع نص، يُضاف ذلك النص إلى آخر رسالة مستخدم قبل التوليد. قد تعرّف البيئة أيضًا طريقة `get_reward` لا تستقبل أي حرج وتعيد قيمة من نوع `float`: عند وجودها، تمتلك البيئة المكافأة، وتُستدعى `get_reward` مرة واحدة لكل تمريرة مكتملة لتقييمها من الحالة الداخلية للبيئة. تعمل كمصدر مكافأة إضافي (بوزن 1، ويُسجَّل باسم فئة البيئة) إلى جانب `reward_funcs`، الذي يصبح اختياريًا في هذه الحالة. عند استخدام دالة قابلة للاستدعاء واحدة، تستخدم كل أمثلة نفس البيئة، مع نسخة واحدة لكل تمريرة لضمان عزل تفاعلاتها. عند استخدام قاموس، يجب أن تحمل كل أمثلة حقل `environment` لاختيار بيئتها بالاسم، ولا تُعرض إلا أدوات تلك البيئة في موجهها — مما يتيح لتمريرة واحدة خلط المهام (مثل بيئة برمجة وبيئة لعبة). هذه الميزة تجريبية وقد تتغير أو تُحذف في أي وقت دون إشعار مسبق.

مدرّب لطريقة تحسين السياسة النسبية للمجموعات (GRPO). تم اقتراح هذه الخوارزمية في الأصل في ورقة [DeepSeekMath: دفع حدود الاستدلال الرياضي في النماذج اللغوية المفتوحة](https://huggingface.co/papers/2402.03300).

مثال:

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

#### train[[trl.GRPOTrainer.train]]

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

[المصدر](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L1450)

**المعاملات:**

resume_from_checkpoint (`str` أو `bool`، *اختياري*) : إذا كان `str`، فهو المسار المحلي لنقطة تحقق محفوظة بواسطة نسخة سابقة من `Trainer`. إذا كان `bool` ويساوي `True`، يتم تحميل آخر نقطة تحقق في *args.output_dir* كما حفظتها نسخة سابقة من `Trainer`. إذا كانت موجودة، فسيستأنف التدريب من حالات النموذج/المُحسِّن/المُجدوِل المحمَّلة هنا.

trial (`optuna.Trial` أو `dict[str, Any]`، *اختياري*) : الجولة التجريبية أو قاموس معاملات الضبط للبحث في معاملات الضبط.

ignore_keys_for_eval (`list[str]`، *اختياري*) : قائمة بمفاتيح في مخرجات نموذجك (إذا كان قاموسًا) يجب تجاهلها عند جمع التوقعات للتقييم أثناء التدريب.

**يعيد:** `~trainer_utils.TrainOutput`

كائن يحتوي على عدد الخطوات العالمية، وخسارة التدريب، والمقاييس.

نقطة الدخول الرئيسية للتدريب.

#### save_model[[trl.GRPOTrainer.save_model]]

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

[المصدر](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L4077)

سيحفظ النموذج، بحيث يمكنك إعادة تحميله باستخدام `from_pretrained()`.

سيتم الحفظ من العملية الرئيسية فقط.

#### push_to_hub[[trl.GRPOTrainer.push_to_hub]]

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

[المصدر](https://github.com/huggingface/trl/blob/v1.18.0/transformers/trainer.py#L4337)

**المعاملات:**

commit_message (`str`، *اختياري*، القيمة الافتراضية `"End of training"`) : الرسالة التي سيتم الالتزام بها أثناء الدفع.

blocking (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان ينبغي للوظيفة أن تُرجع القيمة فقط بعد اكتمال `git push`.

token (`str`، *اختياري*، القيمة الافتراضية `None`) : رمز (Token) يملك صلاحية الكتابة لتجاوز الحجج الأصلية الخاصة بـ Trainer.

revision (`str`، *اختياري*) : المراجعة (revision) في git التي سيتم الالتزام منها. الافتراضي هو رأس فرع "main".

private (`bool`, *اختياري*) : ما إذا كان يجب جعل المستودع خاصًا عند إنشائه. القيمة الافتراضية هي `args.hub_private_repo`. لا يؤثر هذا الإعداد إذا كان المستودع موجودًا مسبقًا.

kwargs (`dict[str, Any]`، *اختياري*) : حُجج إضافية تُمرَّر إلى `~Trainer.create_model_card`.

**يعيد:**

عنوان URL للمستودع الذي تم دفع النموذج إليه إذا كان `blocking=False`، أو كائن `Future` يتتبع تقدم عملية الالتزام إذا كان `blocking=True`.

ارفع `self.model` و`self.processing_class` إلى مركز النماذج 🤗 في المستودع `self.args.hub_model_id`.

## GRPOConfig[[trl.GRPOConfig]]

#### trl.GRPOConfig[[trl.GRPOConfig]]

```python
trl.GRPOConfig(output_dir: str | None = None, per_device_train_batch_size: int = 8, num_train_epochs: float = 3.0, max_steps: int = -1, learning_rate: float = 1e-06, lr_scheduler_type: transformers.trainer_utils.SchedulerType | str = 'linear', lr_scheduler_kwargs: dict | str | None = None, warmup_steps: float = 0, optim: transformers.training_args.OptimizerNames | str = 'adamw_torch_fused', optim_args: str | None = None, weight_decay: float = 0.0, adam_beta1: float = 0.9, adam_beta2: float = 0.999, adam_epsilon: float = 1e-08, optim_target_modules: None | str | list[str] = None, gradient_accumulation_steps: int = 1, average_tokens_across_devices: bool = True, max_grad_norm: float = 1.0, label_smoothing_factor: float = 0.0, bf16: bool | None = None, fp16: bool = False, bf16_full_eval: bool = False, fp16_full_eval: bool = False, tf32: bool | None = None, activation_checkpointing: bool | None = None, activation_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, gradient_checkpointing: bool = True, gradient_checkpointing_kwargs: dict[str, typing.Any] | str | None = None, torch_compile: bool = False, torch_compile_backend: str | None = None, torch_compile_mode: str | None = None, use_liger_kernel: bool = False, liger_kernel_config: dict[str, bool] | None = None, use_cache: bool = False, neftune_noise_alpha: float | None = None, torch_empty_cache_steps: int | None = None, auto_find_batch_size: bool = False, logging_strategy: transformers.trainer_utils.IntervalStrategy | str = 'steps', logging_steps: float = 10, logging_first_step: bool = False, log_on_each_node: bool = True, logging_nan_inf_filter: bool = True, include_num_input_tokens_seen: str | bool = 'no', log_level: str = 'passive', log_level_replica: str = 'warning', disable_tqdm: bool | None = None, report_to: None | str | list[str] = 'none', run_name: str | None = None, project: str = 'huggingface', trackio_space_id: str | None = None, trackio_bucket_id: str | None = None, trackio_static_space_id: typing.Union[str, NoneType, typing.Literal[False]] = None, eval_strategy: transformers.trainer_utils.IntervalStrategy | str = 'no', eval_steps: float | None = None, eval_delay: float = 0, per_device_eval_batch_size: int = 8, prediction_loss_only: bool = False, eval_on_start: bool = False, eval_do_concat_batches: bool = True, eval_use_gather_object: bool = False, eval_accumulation_steps: int | None = None, include_for_metrics: list[str] = <factory>, batch_eval_metrics: bool = False, save_only_model: bool = False, save_strategy: transformers.trainer_utils.SaveStrategy | str = 'steps', save_steps: float = 500, save_on_each_node: bool = False, save_total_limit: int | None = None, enable_jit_checkpoint: bool = False, push_to_hub: bool = False, hub_token: str | None = None, hub_private_repo: bool | None = None, hub_model_id: str | None = None, hub_strategy: transformers.trainer_utils.HubStrategy | str = 'every_save', hub_always_push: bool = False, hub_revision: str | None = None, load_best_model_at_end: bool = False, metric_for_best_model: str | None = None, greater_is_better: bool | None = None, ignore_data_skip: bool = False, restore_callback_states_from_checkpoint: bool = False, full_determinism: bool = False, seed: int = 42, data_seed: int | None = None, use_cpu: bool = False, accelerator_config: dict | str | None = None, parallelism_config: accelerate.parallelism_config.ParallelismConfig | None = None, dataloader_drop_last: bool = False, dataloader_num_workers: int = 0, dataloader_pin_memory: bool = True, dataloader_persistent_workers: bool = False, dataloader_prefetch_factor: int | None = None, dataloader_multiprocessing_context: str | None = None, dataloader_in_order: bool = True, remove_unused_columns: bool | None = False, label_names: list[str] | None = None, train_sampling_strategy: str = 'random', length_column_name: str = 'length', ddp_find_unused_parameters: bool | None = None, ddp_bucket_cap_mb: int | None = None, ddp_broadcast_buffers: bool | None = None, ddp_static_graph: bool | None = None, ddp_backend: str | None = None, ddp_timeout: int = 1800, fsdp: str | None = None, fsdp_config: dict[str, typing.Any] | str | None = None, deepspeed: dict | str | None = None, debug: str | list[transformers.debug_utils.DebugOption] = '', skip_memory_metrics: bool = True, do_train: bool = False, do_eval: bool = False, do_predict: bool = False, resume_from_checkpoint: str | None = None, local_rank: int = -1, model_init_kwargs: dict[str, typing.Any] | str | None = None, trust_remote_code: bool = False, router_aux_loss_coef: float | None = None, disable_dropout: bool = False, cast_lm_head_to_fp32: bool = False, num_generations: int | None = 8, num_generations_eval: int | None = None, max_completion_length: int | None = 512, ds3_gather_for_generation: bool = True, shuffle_dataset: bool | None = True, pad_to_multiple_of: int | str | None = 'auto', generation_batch_size: int | None = None, steps_per_generation: int | None = None, temperature: float = 1.0, top_p: float = 1.0, top_k: int = 0, min_p: float | None = None, generation_kwargs: dict | str | None = None, chat_template_kwargs: dict | str | None = None, repetition_penalty: float = 1.0, cache_implementation: str | None = None, use_vllm: bool = False, vllm_mode: str = 'colocate', vllm_model_impl: str = 'vllm', vllm_enable_sleep_mode: bool = False, vllm_structured_outputs_regex: str | None = None, vllm_server_base_url: str | None = None, vllm_server_host: str = '0.0.0.0', vllm_server_port: int = 8000, vllm_server_timeout: float = 240.0, vllm_group_port: int = 51216, vllm_gpu_memory_utilization: float = 0.3, vllm_max_model_length: int | None = None, vllm_tensor_parallel_size: int = 1, beta: float = 0.0, num_iterations: int = 1, epsilon: float = 0.2, delta: float | None = None, epsilon_high: float | None = None, sapo_temperature_neg: float = 1.05, sapo_temperature_pos: float = 1.0, vespo_k_pos: float = 2.0, vespo_lambda_pos: float = 3.0, vespo_k_neg: float = 3.0, vespo_lambda_neg: float = 2.0, importance_sampling_level: str = 'token', reward_weights: list[float] | None = None, multi_objective_aggregation: str = 'sum_then_normalize', scale_rewards: str = 'group', loss_type: str = 'dapo', mask_truncated_completions: bool = False, sync_ref_model: bool = False, ref_model_mixup_alpha: float = 0.6, ref_model_sync_steps: int = 512, top_entropy_quantile: float = 1.0, entropy_coef: float = 0.0, use_adaptive_entropy: bool = False, entropy_coef_min: float = 0.0, entropy_coef_max: float = 1.0, entropy_coef_delta: float = 0.005, entropy_target: float = 0.2, max_tool_calling_iterations: int | None = None, vllm_importance_sampling_correction: bool = True, vllm_importance_sampling_mode: str = 'sequence_mask', vllm_importance_sampling_clip_max: float | None = 3.0, vllm_importance_sampling_clip_min: float | None = None, off_policy_mask_threshold: float | None = None, use_bias_correction_kl: bool = True, log_completions: bool = False, log_multimodal: bool = True, num_completions_to_print: int | None = None, log_unique_prompts: bool = False, log_completions_hub_repo: str | None = None, use_transformers_continuous_batching: bool = False, transformers_continuous_batching_config: dict | str | None = None, use_transformers_paged: bool = False, vllm_importance_sampling_cap: float | None = None)
```

[المصدر](https://github.com/huggingface/trl/blob/v1.18.0/trl/trainer/grpo_config.py#L23)

**المعاملات التي تتحكم في النموذج ونموذج المرجع:**

model_init_kwargs (`str` أو `dict[str, Any]`، *اختياري*) : حُجج الكلمات المفتاحية لـ [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained)، تُستخدم عندما يُقدَّم الحُجج `model` الخاص بـ [GRPOTrainer](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOTrainer) كنص. كما يُستخدم قيمة `revision` عند تحميل فئات المعالجة.

trust_remote_code (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم السماح بتحميل النماذج ومعالجات الرموز التي تتضمن أكواد بايثون مخصصة من Hub. يتم تمرير هذا الإعداد إلى [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoModelForCausalLM.from_pretrained) و [from_pretrained](https://huggingface.co/docs/transformers/v5.23.0/en/model_doc/auto#transformers.AutoProcessor.from_pretrained). كما يُطبَّق على عمليات تحميل نماذج المكافآت ومعالجات رموز المكافآت.

router_aux_loss_coef (`float`, *اختياري*) : معامل خسارة التوازن بين الأحمال المساعدة لنماذج مزيج الخبراء (MoE)، تُضاف إلى خسارة التدريب بهذا الوزن. عند عدم تعيينه، يُستخدم القيمة المُعلنة في إعدادات النموذج. عيّن `0.0` لتعطيله. يفشل عند استخدامه مع نموذج غير MoE.

disable_dropout (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم تعطيل إسقاط البيانات (dropout) في النموذج. هذا مفيد للتدريب مع نموذج مرجعي، حيث يمنع النموذج من توليد قيم احتمالية (logprobs) مختلفة لنفس المدخل.

cast_lm_head_to_fp32 (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم تحويل رأس نمذجة اللغة في نموذجي السياسة والمرجع إلى float32. كما يوصي به وصف [ScaleRL](https://huggingface.co/papers/2510.13786). يُدعم هذا العلم فقط عندما يحتوي النموذج على طبقات مضمنة للكلمات ورأس لنمذجة اللغة غير مرتبطة، أي أن `tie_word_embeddings` في إعدادات النموذج تساوي False.

**المعاملات التي تتحكم في معالجة البيانات المسبقة:**

remove_unused_columns (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب الإبقاء على العمود `"prompt"` فقط في مجموعة البيانات. إذا كنت تستخدم دالة مكافأة مخصصة تتطلب أي عمود غير `"prompts"` و`"completions"`، فيجب عليك إبقاء هذا الخيار على `False`.

num_generations (`int`، *اختياري*، القيمة الافتراضية `8`) : عدد الأجيال لكل موجه يُعتمد على أخذ عينات منه. يجب أن يكون حجم الدفعة الفعّال (num_processes * per_device_batch_size * gradient_accumulation_steps) قابلاً للقسمة على هذا الرقم دون باقي.

num_generations_eval (`int`, *اختياري*) : عدد الأجيال التي سيتم أخذ عينات منها أثناء التقييم. يتيح ذلك استخدام عدد أقل من الأجيال أثناء التقييم لتوفير الحسابات. إذا كان `None`، يتم استخدام قيمة `num_generations`.

max_completion_length (`int` أو `None`، *اختياري*، القيمة الافتراضية `512`) : الحد الأقصى لطول الإكمال المولّد.

ds3_gather_for_generation (`bool`، *اختياري*، القيمة الافتراضية `True`) : تنطبق هذه الإعدادات على DeepSpeed ZeRO-3. إذا تم تفعيلها، يتم تجميع أوزان نموذج السياسة للتوليد، مما يحسّن سرعة التوليد. ومع ذلك، فإن تعطيل هذا الخيار يتيح تدريب نماذج تتجاوز سعة ذاكرة VRAM لبطاقة رسومات واحدة، على الرغم من أن ذلك يأتي على حساب بطء التوليد. إن تعطيل هذا الخيار غير متوافق مع توليد vLLM.

shuffle_dataset (`bool`، *اختياري*، الافتراضي `True`) : ما إذا كان سيتم خلط مجموعة بيانات التدريب.

pad_to_multiple_of (`int` أو `str`، *اختياري*، القيمة الافتراضية `"auto"`) : إذا تم تعيينه، فسيتم ملء معرّفات المحفّزات ومعرّفات الإكمالات إلى مضاعف لهذا القيمة. يقوم `"auto"` بملء القيم إلى مضاعف لـ 128 على Neuron (AWS Trainium)، الذي يُجمَّع مرة واحدة لكل شكل إدخال، ولا يقوم بالملء في أي مكان آخر.

**المعاملات التي تتحكم في التوليد:**

generation_batch_size (`int`, *اختياري*) : حجم الدفعة (Batch size) المستخدم للتوليد. إذا كان `None`، فإنه يتحول افتراضيًا إلى حجم دفعة التدريب الفعلية: `per_device_train_batch_size * num_processes * steps_per_generation`. بمعنى آخر، يتم معالجة دفعة توليد واحدة لكل خطوة تحسين. يتعارض مع `steps_per_generation` بشكل متبادل.

steps_per_generation (`int`, *اختياري*) : عدد الخطوات لكل عملية توليد. إذا كانت `None`، فإن القيمة الافتراضية هي `gradient_accumulation_steps`. يتعارض مع `generation_batch_size` بشكل متبادل.

temperature (`float`، *اختياري*، القيمة الافتراضية `1.0`) : درجة الحرارة للعينات. كلما زادت درجة الحرارة، زادت عشوائية المكملات.

top_p (`float`، *اختياري*، القيمة الافتراضية `1.0`) : قيمة عشرية تتحكم في الاحتمال التراكمي لأعلى الرموز المراد أخذها في الاعتبار. يجب أن تكون ضمن المجال (0، 1]. اضبطها على `1.0` لاعتبار جميع الرموز.

top_k (`int`، *اختياري*، القيمة الافتراضية `0`) : عدد رموز المفردات ذات أعلى احتمالات التي يجب الاحتفاظ بها لتصفية top-k. إذا كانت القيمة `0`، يتم تعطيل تصفية top-k وتُعتبر جميع الرموز.

min_p (`float`، *اختياري*) : الحد الأدنى لاحتمالية الرمز، والذي يتم تحديده بالنسبة لاحتمالية الرمز الأكثر احتمالاً. يجب أن يكون قيمة بين `0.0` و`1.0`. القيم النموذجية تقع ضمن نطاق `0.01-0.2`.

generation_kwargs (`dict[str, Any]`، *اختياري*) : حُجج إضافية بالكلمات المفتاحية تُمرَّر إلى [GenerationConfig](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/text_generation#transformers.GenerationConfig) (عند استخدام transformers) أو `SamplingParams` (عند استخدام vLLM) عند أخذ عينات من الاكتمالات. يمكن استخدام هذا لتخصيص سلوك التوليد بشكل أكبر، مثل تعيين `suppress_tokens`، `num_beams`، وما إلى ذلك. إذا احتوى على مفاتيح تتعارض مع معاملات التوليد الأخرى (مثل `min_p`، `top_p`، وما إلى ذلك)، فستتجاوز تلك المعاملات.

chat_template_kwargs (`dict[str, Any]`، *اختياري*) : حُجج إضافية بالكلمات المفتاحية تُمرَّر إلى دالة `apply_chat_template` عند توليد الإكمالات.

repetition_penalty (`float`، *اختياري*، القيمة الافتراضية `1.0`) : قيمة عشرية تعاقب الرموز الجديدة بناءً على ما إذا كانت تظهر في الاستعلام والنص المولَّد حتى الآن. القيم الأكبر من `1.0` تشجع النموذج على استخدام رموز جديدة، بينما القيم الأصغر من `1.0` تشجع النموذج على تكرار الرموز.

cache_implementation (`str`, *اختياري*) : تنفيذ طريقة التخزين المؤقت لتسريع عملية التوليد عندما يكون `use_vllm` مضبوطًا على `False`.

**المعاملات التي تتحكم في تسريع التوليد المدعوم بواسطة vLLM:**

use_vllm (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم استخدام vLLM لتوليد الإكمالات. إذا تم ضبطه على `True`، فسيستخدم المدرب vLLM للتوليد بدلاً من model.generate() الافتراضي. يتطلب تثبيت `vllm`.

vllm_mode (`str`، *اختياري*، القيمة الافتراضية `"colocate"`) : الوضع المستخدم لتكامل vLLM عند ضبط `use_vllm` على `True`. يجب أن يكون أحد `"server"` أو `"colocate"`. - `"server"`: سيقوم المدرب بإرسال طلبات التوليد إلى خادم vLLM منفصل. تأكد من أن خادم vLLM قيد التشغيل (ابدأه باستخدام `vllm serve`). - `"colocate"`: سيعمل vLLM في نفس العملية ويشارك وحدات معالجة الرسوميات (GPUs) الخاصة بالتدريب. هذا يتجنب الحاجة إلى خادم منفصل لكنه قد يسبب تنافساً على الموارد مع التدريب.

vllm_model_impl (`str`، *اختياري*، القيمة الافتراضية `"vllm"`) : تنفيذ النموذج الذي سيتم استخدامه في vLLM. يجب أن يكون أحد `"transformers"` أو `"vllm"`. `"transformers"`: استخدم واجهة `transformers` لتنفيذ النموذج. `"vllm"`: استخدم مكتبة `vllm` لتنفيذ النموذج.

vllm_enable_sleep_mode (`bool`، *اختياري*، القيمة الافتراضية `False`) : تفعيل وضع السكون في vLLM لتفريغ الأوزان/الذاكرة المؤقتة أثناء خطوة المُحسِّن. يُبقي استخدام ذاكرة وحدة معالجة الرسوميات منخفضًا، لكن استيقاظ المحرّك يضيف زمن انتقال بين المضيف والوحدة.

vllm_structured_outputs_regex (`str`، *اختياري*) : تعبير نمطي (Regex) للمخرجات المهيكلة في vLLM. إذا كان `None` (الافتراضي)، فإن المخرجات المهيكلة معطّلة.

**المعاملات التي تتحكم في خادم vLLM (تُستخدم فقط عندما يكون `vllm_mode` هو `"server"`):**

vllm_server_base_url (`str`, *اختياري*) : عنوان URL الأساسي لخادم vLLM (على سبيل المثال، `"http://localhost:8000"`). إذا تم تقديمه، يتم تجاهل `vllm_server_host` و`vllm_server_port`.

vllm_server_host (`str`، *اختياري*، القيمة الافتراضية `"0.0.0.0"`) : مضيف خادم vLLM الذي سيتم الاتصال به. يتم تجاهله إذا تم تقديم `vllm_server_base_url`.

vllm_server_port (`int`، *اختياري*، القيمة الافتراضية `8000`) : منفذ خادم vLLM الذي يجب الاتصال به. يتم تجاهله إذا تم تقديم `vllm_server_base_url`.

vllm_server_timeout (`float`، *اختياري*، القيمة الافتراضية `240.0`) : إجمالي مدة المهلة بالثواني للانتظار حتى يصبح خادم vLLM قيد التشغيل. إذا لم يكن الخادم قيد التشغيل بعد انتهاء المهلة، يتم رفع `ConnectionError`.

vllm_group_port (`int`، *اختياري*، القيمة الافتراضية `51216`) : رقم المنفذ لمجموعة تحديث الأوزان. يُستخدم هذا للتواصل مع خادم vLLM. ما لم يكن المنفذ مشغولاً، فلا حاجة لتغييره.

**المعاملات التي تتحكم في تنفيذ vLLM المتشارك (يُستخدم فقط عندما يكون `vllm_mode` هو `"colocate"`):**

vllm_gpu_memory_utilization (`float`، *اختياري*، القيمة الافتراضية `0.3`) : يتحكم في استخدام ذاكرة وحدة معالجة الرسوميات (GPU) في vLLM. لا تنطبق هذه الإعدادات إلا عند ضبط `vllm_mode` على `"colocate"`. إذا كنت تستخدم `vllm_mode="server"`، فيجب تمرير هذا المعامل بشكل منفصل عند تشغيل خادم vLLM عبر علم `--vllm_gpu_memory_utilization`.

vllm_max_model_length (`int`, *اختياري*) : نافذة السياق لـ vLLM. اضبطها على الأقل على طول الإدخال الأقصى في مجموعة البيانات مضافًا إليه `max_completion_length`؛ وإذا تم تجاهلها، فستُستنتج من إعدادات النموذج.

vllm_tensor_parallel_size (`int`، *اختياري*، القيمة الافتراضية `1`) : يتحكم في حجم التوازي للتensors في vLLM. لا تنطبق هذه الإعدادات إلا عند ضبط `vllm_mode` على `"colocate"`. إذا كنت تستخدم `vllm_mode="server"`، فيجب تمرير هذا المعامل بشكل منفصل عند تشغيل خادم vLLM عبر علم `--vllm_tensor_parallel_size`.

**المعاملات التي تتحكم في التدريب:**

beta (`float`، *اختياري*، القيمة الافتراضية `0.0`) : معامل KL. إذا كانت القيمة `0.0` (الافتراضية)، فلن يتم تحميل النموذج المرجعي، مما يقلل من استهلاك الذاكرة ويحسّن سرعة التدريب. يستخدم [DeepSeek-R1 incentivizes reasoning in LLMs through reinforcement learning](https://huggingface.co/papers/2501.12948) قيمة `0.001`.

num_iterations (`int`، *اختياري*، القيمة الافتراضية `1`) : عدد التكرارات لكل دفعة (يُرمز له بـ μ في الخوارزمية).

epsilon (`float`، *اختياري*، القيمة الافتراضية `0.2`) : قيمة إبسيلون للقص.

delta (`float`, *اختياري*) : يُفعّل حدّ القص العلوي في خسارة GRPO ذات الجانبين عند تعيينه كقيمة float. إذا كان `None` (الافتراضي)، يُستخدم القص القياسي لـ GRPO. يُوصى بأن يكون أكبر من `1 + ε` عند التفعيل. تم تقديم هذه الطريقة في [تقرير INTELLECT-2 التقني](https://huggingface.co/papers/2505.07291).

epsilon_high (`float`, *اختياري*) : قيمة إبسيلون الحد الأعلى للتقليم. إذا لم يتم تحديدها، فإنها تتخذ القيمة نفسها المحددة كحد أدنى في الحجة `epsilon`. يوصي الورق [DAPO](https://huggingface.co/papers/2503.14476) بقيمة `0.28`. عند الاستخدام مع `loss_type='cispo'`، يتوافق هذا مع معامل ε_max المحدد في [ورقة ScaleRL](https://huggingface.co/papers/2510.13786)، ويتخذ القيمة الموصى بها `5.0` افتراضيًا.

sapo_temperature_neg (`float`، *اختياري*، القيمة الافتراضية `1.05`) : درجة الحرارة للرموز ذات درجات الأفضلية غير الموجبة المستخدمة في دالة الخسارة `sapo`. تم تقديم هذا المعامل في [ورقة Soft Adaptive Policy Optimization](https://huggingface.co/papers/2511.20347).

sapo_temperature_pos (`float`، *اختياري*، القيمة الافتراضية `1.0`) : درجة الحرارة للرموز ذات درجات الأفضلية الموجبة المستخدمة في دالة الخسارة `sapo`. تم تقديم هذا المعامل في [ورقة Soft Adaptive Policy Optimization](https://huggingface.co/papers/2511.20347).

vespo_k_pos (`float`، *اختياري*، القيمة الافتراضية `2.0`) : معامل k الخاص بالمزايا الإيجابية، وهو أُس القوة في خسارة VESPO. يتحكم في مدى تقليل وزن العينات ذات أوزان الأهمية المنخفضة (عندما يكون نسبة أخذ العينات المهمة < 1).

vespo_lambda_pos (`float`، *اختياري*، القيمة الافتراضية `3.0`) : معامل lambda للمزايا الإيجابية، وهو عامل التلاشي في خسارة VESPO. يتحكم في مدى تقليل وزن العينات ذات أوزان الأهمية العالية (عندما يكون نسبة أخذ العينات المهمة > 1).

vespo_k_neg (`float`، *اختياري*، القيمة الافتراضية `3.0`) : معامل k الخاص بالمزايا السلبية، وهو أُس القوة في خسارة VESPO. يتحكم في مدى تقليل وزن العينات ذات أوزان الأهمية المنخفضة (عندما يكون نسبة أخذ العينات المهمة < 1).

vespo_lambda_neg (`float`، *اختياري*، القيمة الافتراضية `2.0`) : معامل lambda الخاص بالمزايا السلبية، وهو عامل الاضمحلال الأسي في خسارة VESPO. يتحكم في مدى تقليل وزن العينات ذات أوزان الأهمية العالية (عندما يكون نسبة أخذ العينات المهمة > 1).

importance_sampling_level (`str`، *اختياري*، القيمة الافتراضية `"token"`) : يتحكم في ما إذا كانت نسب أخذ العينات المهمة تُحسب على مستوى `"token"` أو `"sequence"`. يحافظ `"token"` على نسب احتمالات السجل الخام لكل رمز (وزن واحد لكل رمز). أما `"sequence"` فيحسب متوسط نسب احتمالات السجل عبر الرموز الصالحة لإنتاج نسبة واحدة لكل تسلسل. تُظهر [ورقة GSPO](https://huggingface.co/papers/2507.18071) أن أخذ العينات على مستوى التسلسل غالبًا ما يؤدي إلى تدريب أكثر استقرارًا ومواءمة أفضل مع المكافآت على مستوى التسلسل.

reward_weights (`list[float]`، *اختياري*) : أوزان لكل دالة مكافأة. يجب أن تتطابق مع عدد دوال المكافأة. إذا كانت `None`، فجميع المكافآت موزونة بالتساوي مع وزن `1.0`.

multi_objective_aggregation (`str`، *اختياري*، القيمة الافتراضية `"sum_then_normalize"`) : الطريقة المستخدمة لتجميع دوال المكافآت المتعددة. القيم المدعومة هي: - `"sum_then_normalize"` (الافتراضي): يقوم أولاً بجمع المكافآت الموزونة من كل دالة مكافآت، ثم يطبّق تحجيم/تطبيع المكافآت كما هو محدد بواسطة `scale_rewards` (راجع `scale_rewards` للتفاصيل). - `"normalize_then_sum"`: يقوم أولاً بتطبيع/تحجيم كل دالة مكافآت عبر الأجيال (داخل كل مجموعة)، ثم يجمع المكافآت المطبّعة باستخدام الأوزان المحددة. يتم بعد ذلك تطبيع المكافأة المجمعة على مستوى الدفعة عند تشكيل المزايا. هذا هو النهج المقترح من الورقة البحثية [GDPO: Group reward-Decoupled Normalization Policy Optimization for Multi-reward RL Optimization](https://huggingface.co/papers/2601.05242).

scale_rewards (`str` أو `bool`، *اختياري*، القيمة الافتراضية `"group"`) : يحدد استراتيجية توسيع المكافآت. القيم المدعومة هي: - `True` أو `"group"` (الافتراضي): يتم توسيع المكافآت بناءً على الانحراف المعياري داخل كل مجموعة، مما يضمن تبايناً لوحدياً داخل المجموعة. - `"batch"`: يتم توسيع المكافآت بناءً على الانحراف المعياري عبر الدفعة بأكملها، كما هو موصى به في [ورقة PPO Lite](https://huggingface.co/papers/2508.08221). - `False` أو `"none"`: لا يُطبق أي توسيع. يوصي [ورقة Dr. GRPO](https://huggingface.co/papers/2503.20783) بعدم توسيع المكافآت، لأن التوسيع بناءً على الانحراف المعياري يُدخل تحيزاً في صعوبة مستوى السؤال.

loss_type (`str`، *اختياري*، القيمة الافتراضية `"dapo"`) : يحدد صيغة الخسارة المستخدمة. القيم المدعومة هي: - `"grpo"`: يجمع خسائر مستوى الرمز (token) عن طريق التطبيع على طول التسلسل. لا يُنصح باستخدامه بسبب انحياز الطول—فمنهجية هذا النهج تميل إلى تفضيل الإكمالات الأقصر ذات المزايا الإيجابية والأطول ذات المزايا السلبية. - `"dr_grpo"`: يجمع خسائر مستوى الرمز عن طريق التطبيع باستخدام ثابت عام. تم تقديم هذه الطريقة في [ورقة Dr. GRPO](https://huggingface.co/papers/2503.20783) للقضاء على انحياز الطول. قيمة الثابت تتوافق مع `max_completion_length`. - `"dapo"` (الافتراضي): يجمع خسائر مستوى الرمز عن طريق التطبيع على عدد الرموز النشطة في الدفعة المتراكمة عالمياً. تم تقديم هذه الطريقة في [ورقة DAPO](https://huggingface.co/papers/2503.14476) للقضاء على انحياز الطول. - `"bnpo"`: يجمع خسائر مستوى الرمز عن طريق التطبيع على عدد الرموز النشطة في الدفعة المحلية. لاحظ أن التطبيع يتم على الدفعة المحلية فقط، لذا قد تختلف النتائج قليلاً اعتماداً على حجم الدفعة المحلية، على الرغم من ثبات حجم الدفعة الفعالة. عند استخدام `per_device_train_batch_size==1`، تكون الخسارة مكافئة لخسارة GRPO. - `"cispo"`: يقص أوزات أخذ العينات المهمة بدلاً من أوزات أخذ العينات المهمة المُقيّسة بالمزايا. ثم تُضرب الأوزات المقصوصة في المزايا واحتمالات السجل لنموذج السياسة. تُجمع خسائر الرموز الفردية عن طريق التطبيع على عدد الرموز النشطة في الدفعة المتراكمة عالمياً. تم تقديم هذه الطريقة في [ورقة MiniMax-M1](https://huggingface.co/papers/2506.13585). - `"sapo"`: خسارة تحسين السياسة التكيفي الناعم، كما تم تقديمها في [ورقة Soft Adaptive Policy Optimization](https://huggingface.co/papers/2511.20347). تحل محل القص الصارم ببوابة سلسة تتحكم فيها درجة الحرارة، تخمد التحديثات خارج السياسة بشكل تكيفي مع الحفاظ على إشارات التعلم المفيدة. - `"luspo"`: خسارة تحسين سياسة التسلسل غير المنحازة للطول. خسارة على مستوى التسلسل تُقيّم خسارة كل تسلسل بطوله. هذا تعديل على GSPO ويتطلب `importance_sampling_level="sequence"`. تم تقديمه في [ورقة LUSPO](https://huggingface.co/papers/2602.05261). - `"vespo"`: تحسين سياسة التسلسل الناعم التبايني على مستوى التسلسل. يحل محل القص الصارم بدالة وزن Gamma غير متماثلة سلسة تُطبق مباشرة على أوزات أهمية مستوى التسلسل. تم تقديمه في [ورقة VESPO](https://huggingface.co/papers/2602.10693).

mask_truncated_completions (`bool`، *اختياري*، القيمة الافتراضية `False`) : عند التفعيل، تُستبعد الاكتمالات المقطوعة من حساب الخسارة، مما يمنع معاقبتها بشكل غير صحيح وتدخل ضوضاء أثناء التدريب. وفقًا لورقة [DAPO](https://huggingface.co/papers/2503.14476)، يُعد هذا ممارسة جيدة لاستقرار التدريب.

sync_ref_model (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان يجب مزامنة النموذج المرجعي مع النموذج النشط كل `ref_model_sync_steps` خطوات، باستخدام معامل `ref_model_mixup_alpha`. تنبع هذه المزامنة من ورقة [TR-DPO](https://huggingface.co/papers/2404.09656).

ref_model_mixup_alpha (`float`، *اختياري*، القيمة الافتراضية `0.6`) : معامل α من ورقة [TR-DPO](https://huggingface.co/papers/2404.09656)، والذي يتحكم في المزيج بين السياسة الحالية والسياسة المرجعية السابقة أثناء التحديثات. يتم تحديث السياسة المرجعية وفقًا للمعادلة: `π_ref = α * π_θ + (1 - α) * π_ref_prev`. لاستخدام هذا المعامل، يجب عليك تعيين `sync_ref_model=True`.

ref_model_sync_steps (`int`، *اختياري*، القيمة الافتراضية `512`) : معامل τ من ورقة [TR-DPO](https://huggingface.co/papers/2404.09656)، وهو يحدد مدى تكرار مزامنة السياسة الحالية مع السياسة المرجعية. لاستخدام هذا المعامل، يجب عليك تعيين `sync_ref_model=True`.

top_entropy_quantile (`float`، *اختياري*، القيمة الافتراضية `1.0`) : معامل ρ من [Beyond the 80/20 Rule](https://huggingface.co/papers/2506.01939). يحتفظ في حد خسارة السياسة فقط بأعلى ρ نسبة مئوية من الرموز حسب إنتروبيا توزيع الاحتمالات عند كل موضع في التسلسل، مما يحسّن النتائج. النطاق: `[0.0-1.0]`. القيمة `0.0` تخفي جميع الرموز عدا الرمز ذي الإنتروبيا الأعلى؛ `1.0` يحتفظ بجميع الرموز. يوصي البحث بقيمة `0.2`. إذا استُخدم مع `mask_truncated_completions=True`، تُؤخذ في الاعتبار فقط الرموز من الإكمالات غير المقطوعة.

entropy_coef (`float`, *اختياري*, القيمة الافتراضية `0.0`) : معامل حد تنظيم الإنتروبيا في دالة الخسارة. القيمة الموجبة تضيف مكافأة إنتروبيا تشجع على الاستكشاف من خلال منع انهيار السياسة إلى مخرجات شبه حتمية. تكون المكافأة دائمًا متوسط إنتروبيا الرمز الواحد بغض النظر عن `loss_type`؛ فهي لا تُعاد مقياستها لتتطابق مع تطبيع السياسة الخاص بنوع الخسارة، لذا فإن `entropy_coef` يحمل المعنى نفسه لجميع أنواع الخسارة. عند تعيين `use_adaptive_entropy=True`، يعمل هذا المعامل كمعامل أولي ويُحدَّث في كل خطوة من خطوات المُحسِّن. لا يؤثر عند تعيينه إلى `0.0` (الافتراضي).

use_adaptive_entropy (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم استخدام التحكم التكيفي في الإنتروبيا، الذي تم تقديمه في [Skywork-OR1](https://huggingface.co/papers/2505.22312). عند التفعيل، يتم تحديث معامل الإنتروبيا `entropy_coef` في كل خطوة من خطوات المُحسِّن: يُزاد بمقدار `entropy_coef_delta` عندما تكون الإنتروبيا الحالية أقل من `entropy_target`، وتُنقص في الحالات الأخرى. لا يُطبَّق المعامل إلا عندما تكون الإنتروبيا عند `entropy_target` أو أقل.

entropy_coef_min (`float`، *اختياري*، القيمة الافتراضية `0.0`) : الحد الأدنى لمعامل الإنتروبيا عند استخدام التحكم التكيفي في الإنتروبيا.

entropy_coef_max (`float`، *اختياري*، القيمة الافتراضية `1.0`) : الحد الأعلى لمعامل الإنتروبيا عند استخدام التحكم التكيفي في الإنتروبيا.

entropy_coef_delta (`float`، *اختياري*، القيمة الافتراضية `0.005`) : حجم الخطوة لضامل معامل الإنتروبيا في كل خطوة من خطوات المُحسِّن أثناء التحكم التكيفي بالإنتروبيا.

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

max_tool_calling_iterations (`int`, *اختياري*) : الحد الأقصى لعدد جولات استدعاء الأدوات عند تدريب وكيل. إذا كانت `None`، فلا يوجد حد، ويتوقف التوليد عندما يولّد النموذج ردًا في جولة دون أي استدعاءات للأدوات، أو عندما يصل الاكتمال (جميع الجولات ونتائج الأدوات) إلى `max_completion_length` من الرموز، أو عندما يصل التسلسل الكامل إلى الحد الأقصى لطول النموذج (`vllm_max_model_length` مع `vllm_mode="colocate"`، وإلا `max_position_embeddings` للنموذج).

vllm_importance_sampling_correction (`bool`, *optional*, defaults to `True`) : Whether to apply Importance Sampling (IS) to correct for the mismatch between vLLM completion logprobs and recomputed training logprobs. If set to `False`, no IS is applied regardless of `vllm_importance_sampling_mode`. When `True`, the selected mode determines how the IS ratios are computed and constrained. With `top_p < 1`, `top_k > 0` or `min_p > 0`, the recomputed logprobs are normalized over the candidate set each token was sampled from, which requires vLLM 0.28 or later and, in server mode, a server started with `--return-sampling-mask` (and `--enable-scale-out` from vLLM 0.30); otherwise, the IS ratios are biased. vLLM bounds that candidate set with `top_k`, so `top_p < 1`, `min_p > 0` and structured outputs, which restrict it to the tokens the grammar allows, require `top_k > 0` (e.g. `top_k=512`). Structured outputs, which would otherwise stall training, also require that candidate set. vLLM also applies `repetition_penalty` to the logprobs it returns, so `repetition_penalty != 1.0` requires `vllm_importance_sampling_correction=False`.

vllm_importance_sampling_mode (`str`، *اختياري*، القيمة الافتراضية `"sequence_mask"`) : يحدد كيفية تنفيذ أخذ العينات حسب الأهمية (Importance Sampling) عندما يكون `vllm_importance_sampling_correction=True`. القيم الممكنة هي: - `"token_truncate"`: أخذ عينات حسب الأهمية المقطوع على مستوى الرموز (Token). يتم قص نسب كل رمز إلى [C_min, C_max]. - `"token_mask"`: أخذ عينات حسب الأهمية المقنّع على مستوى الرموز. تُضبط نسب الرموز خارج نطاق [C_min, C_max] إلى صفر. - `"sequence_truncate"`: أخذ عينات حسب الأهمية المقطوع على مستوى التسلسل. يتم قص نسبة التسلسل الواحدة إلى [C_min, C_max] وتطبيقها على جميع الرموز في التسلسل. - `"sequence_mask"`: أخذ عينات حسب الأهمية المقنّع على مستوى التسلسل. تُقنّع التسلسلات التي تكون نسبها خارج نطاق [C_min, C_max].

vllm_importance_sampling_clip_max (`float`، *اختياري*، القيمة الافتراضية `3.0`) : الحد الأعلى C_max لعينة الأهمية (Importance sampling) المستخدم بواسطة `vllm_importance_sampling_mode`. في أوضاع `*_truncate`، يتم قص نسب الأهمية من الأعلى عند C_max. في أوضاع `*_mask`، تُضبط النسب الأكبر من C_max إلى صفر.

vllm_importance_sampling_clip_min (`float`, *اختياري*) : الحد الأدنى C_min لعينة الأهمية المستخدم بواسطة `vllm_importance_sampling_mode`. في أوضاع `*_truncate`، يتم قص النسب من الأسفل عند C_min. في أوضاع `*_mask`، تُضبط النسب الأقل من C_min إلى صفر. لتقنيع النسب الأقل من C_min بشكل صارم دون حد أعلى، اضبط `vllm_importance_sampling_clip_max=None`.

off_policy_mask_threshold (`float`, *اختياري*) : عتبة لإخفاء تسلسلات خارج السياسة. إذا كانت `None`، يتم تعطيل إخفاء تسلسلات خارج السياسة. عند ضبطها، تُخفى التسلسلات ذات المزايا السالبة وانحراف كولباك-ليبل العالي لتثبيت التدريب. يتوافق هذا المعامل مع عتبة `delta` في المعادلة 9 من [ورقة DeepSeek-V3.2](https://huggingface.co/papers/2512.02556). يتوقع قيمة موجبة (مثل 0.5).

use_bias_correction_kl (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب ضرب حد KL في نسبة أخذ العينات المهمة، بحيث يصبح تدرج KL هو تدرج reverse-KL غير المتحيز، كما هو موصوف في [ورقة DeepSeek-V3.2](https://huggingface.co/papers/2512.02556). يغيّر هذا تدرج KL في كل مرة يكون فيها `beta != 0`، بما في ذلك على السياسة: النسبة قابلة للاشتقاق، لذا تؤثر على التدرج حتى عندما تكون قيمتها تساوي 1 تمامًا. خاصية reverse-KL غير المتحيز تنطبق عند `importance_sampling_level="token"`؛ أما مع `"sequence"` فيتم بث وزن على مستوى التسلسل على KL لكل رمز.

**المعاملات التي تتحكم في التسجيل:**

log_completions (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم تسجيل عينة من أزواج (الموجّه، الإكمال) كل `logging_steps` خطوات. إذا كان `rich` مثبّتًا، فسيتم طباعة العينة. إذا كان تسجيل `wandb` و/أو `trackio` مفعّلًا، فسيتم تسجيلها في `wandb` و/أو `trackio`.

log_multimodal (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم تسجيل المحتوى متعدد الوسائط (الصور، مقاطع الفيديو، إلخ) مع الإكمالات. عطّل هذا الخيار لتقليل حجم السجلات عند استخدام بيانات متعددة الوسائط عالية الدقة.

num_completions_to_print (`int`, *اختياري*) : عدد المكملات التي سيتم طباعتها باستخدام `rich`. إذا كانت `None`، فسيتم تسجيل جميع المكملات.

log_unique_prompts (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان سيتم تسجيل الموجهات الفريدة. إذا كان `True`، يتم تسجيل الموجهات الفريدة فقط. إذا كان `False`، يتم تسجيل جميع الموجهات.

log_completions_hub_repo (`str`, *اختياري*) : مستودع Hugging Face Hub لحفظ الاكتمالات. يجب أن يكون اسم مستودع كاملًا مثل `'username/reponame'` أو `'orgname/reponame'`، أو مجرد `'reponame'` وفي هذه الحالة سيتم إنشاء المستودع في مساحة اسم مستخدم Hugging Face المسجّل حاليًا. لاحظ أن هذا المستودع سيكون عامًا ما لم تضبط `hub_private_repo=True` أو كان الافتراضي في مؤسستك هو إنشاء مستودعات خاصة.

**المعاملات التي تتحكم في تسريع التوليد المدعوم من خلال الدفع المستمر المتصل في transformers:**

use_transformers_continuous_batching (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم استخدام محرك الدفع المستمر (continuous batching) الخاص بـ transformers لتوليد الإكمالات. يتطلب `transformers>=5.8.0`.

transformers_continuous_batching_config (`dict`، *اختياري*) : حُجج الكلمات المفتاحية لـ`ContinuousBatchingConfig`.

**معاملات غير مستخدمة:**

use_transformers_paged :   تم إيقاف استخدام المعامل `use_transformers_paged` وسيتم حذفه في الإصدار v2.0.0. استخدم `use_transformers_continuous_batching` بدلاً منه.

vllm_importance_sampling_cap :   تم إيقاف استخدام المعامل `vllm_importance_sampling_cap` وسيتم حذفه في الإصدار v2.0.0. استخدم `vllm_importance_sampling_clip_max` بدلاً منه.

فئة التهيئة الخاصة بـ [GRPOTrainer](/docs/trl/v1.18.0/ar/grpo_trainer#trl.GRPOTrainer).

تتضمن هذه الفئة فقط المعلمات الخاصة بتدريب GRPO. للحصول على قائمة كاملة بحجج التدريب، يُرجى الرجوع إلى توثيق [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments). لاحظ أن القيم الافتراضية في هذه الفئة قد تختلف عن تلك الموجودة في [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments).

باستخدام [HfArgumentParser](https://huggingface.co/docs/transformers/v5.23.0/en/internal/trainer_utils#transformers.HfArgumentParser) يمكننا تحويل هذه الفئة إلى حُجج [argparse](https://docs.python.org/3/library/argparse#module-argparse) يمكن تحديدها على سطر الأوامر.

> [!NOTE]
> تتميز هذه المعلمات بقيم افتراضية مختلفة عن [TrainingArguments](https://huggingface.co/docs/transformers/v5.23.0/en/main_classes/trainer#transformers.TrainingArguments): - `logging_steps`: القيمة الافتراضية هي `10` بدلاً من `500`. - `gradient_checkpointing`: القيمة الافتراضية هي `True` بدلاً من `False`. - `bf16`: القيمة الافتراضية هي `True` إذا لم يتم تعيين `fp16`، بدلاً من `False`. - `learning_rate`: القيمة الافتراضية هي `1e-6` بدلاً من `5e-5`.

