GRPO غير المتزامن

يتطلب هذا المدرب vllm وtransformers>=5.2.0 وkernels (حيث يقوم التدريب بتحميل FlashAttention من Hub عبره). فيما يتعلق بالتدريب الموزع، يُدعم FSDP2 فقط (لا يُدعم DeepSpeed ZeRO).

حاليًا، توجد قيود متضاربة على التبعيات بين vllm وtransformers. للتحايل على ذلك، ثبّت vLLM أولاً، ثم ثبّت transformers قسريًا، ثم أضف kernels عبر الإضافة الإضافية لـ TRL، والتي تثبّت الإصدار الذي يقبله transformers:

تم النسخ

pip install vllm
pip install 'transformers>=5.2.0' --no-deps
pip install 'trl[kernels]'

نظرة عامة

تنفّذ experimental.async_grpo.AsyncGRPOTrainer خوارزمية GRPO نفسها، لكنها تفصل بين توليد النتائج (rollout) والتدريب. يعمل عامل في الخلفية على بثّ الاكتمالات (completions) بشكل مستمر من خادم vLLM، بينما تستهلك حلقة التدريب هذه الاكتمالات، مما يؤدي إلى تداخل عمليات التوليد وتحديثات التدرّجات بدلاً من تعاقبها. تعكس واجهة البرمجة (API) تلك الخاصة بـ GRPOTrainer — للحصول على تفاصيل كاملة حول طريقة GRPO نفسها (حساب الميزة، تقدير KL، صياغة الدالة الخاسرة، دوال المكافأة، إلخ)، راجع وثائق GRPO Trainer. ليست جميع الميزات المتوفرة في GRPOTrainer مدعومة؛ يُرجى الرجوع إلى experimental.async_grpo.AsyncGRPOConfig للاطلاع على المعلمات المدعومة.

تمت مساهمة هذا المدرب بواسطة Quentin Gallouédec و Amine Dirhoussi.

كيف يختلف عن GRPOTrainer

في GRPOTrainer القياسي، تكون عملية التوليد والتدريب متسلسلة: توليد دفعة، حساب الخسارة، تحديث الأوزان، ثم التكرار. وحتى في وضع vLLM colocate، حيث يتم تنفيذ التوليد على وحدات معالجة الرسوميات نفسها، يجب أن ينتهي أحد المرحلتين قبل أن تبدأ الأخرى.

يفصل experimental.async_grpo.AsyncGRPOTrainer بين هاتين المسألتين:

• عامل النشر (عملية في الخلفية) — يرسل الاستعلامات إلى خادم vLLM، ويقيّم المكملات باستخدام دوال المكافأة، ويحسب المزايا، ويدفع العينات الجاهزة للتدريب إلى طابور.
• حلقة التدريب (العملية الرئيسية) — تستخرج العينات من الطابور، وتحسب خسارة الوكيل المقصوصة، وتحديث أوزان النموذج.

يعمل عامل النشر (rollout worker) في عملية منفصلة تنشأ من المُدرِّب، لذا لا تتنافس عملية حساب المكافأة مع حلقة التدريب على قفل GIL. لهذا الأمر نتيجتان فيما يتعلق بما يمكنك تمريره كـ reward_funcs وtools وenvironment_factory (بالنسبة للأخير، راجد دليل OpenEnv الذي يغطي العقد والتكاملات المتاحة):

بما أننا نُشغّل عامل التوليد (rollout worker) في عملية منفصلة، فإن كل ما يُمرَّر إليه يكون مُجمَّداً (pickled). وعليه، يجب أن تكون كل دالة مكافأة، وأداة، وenvironment_factory (وأي شيء تغلق عليه) قابلة للتجميد: استخدم دالة على مستوى الوحدة (module-level function)، أو functools.partial، أو كائن فئة قابل للاستدعاء (callable class instance). الأدوات هي الاستثناء: يستدعي النموذج الأداة باسمها، لذا تُسجَّل كل أداة تحت __name__ الخاصة بها، ويجب أن تكون دالة على مستوى الوحدة. ستُثير الدوال اللامبدا (Lambdas) والدوال المغلقة (closures) خطأً من نوع TypeError عند trainer.train(). وهذا يختلف عن GRPOTrainer، حيث تُستدعى دوال المكافأة داخل العملية نفسها وتعمل الدوال المغلقة بشكل صحيح.

تعمل عملية النشر أيضًا مع CUDA_VISIBLE_DEVICES=""، لذا لا يمكنها استخدام وحدة معالجة الرسوميات. يتم تحميل نموذج مكافأة مدعوم بوحدة معالجة الرسوميات (مثل مُقيّم AutoModelForSequenceClassification) دون خطأ، لكنه يعود بصمت إلى CPU (لاحظ أنه في GRPOTrainer، يتشارك نموذج المكافأة من هذا النوع وحدات معالجة الرسوميات الخاصة بالمدرّب). حافظ على دوال المكافأة على جانب المعالج المركزي وخفيفة الوزن (مثل أدوات التحقق accuracy_reward، وفحوصات التنسيق والطول).

إذا كنت بحاجة إلى نموذج مكافآت يعمل على وحدة معالجة رسومية، فإن النهج الموصى به هو تقديمه خلف محرك استدلال خاص به (vLLM، TGI، …) على وحدات معالجة رسومية منفصلة، مع استخدام دالة مكافآت خفيفة الوزن وقابلة للتسلسل (picklable) لاستدعائه عبر HTTP. هذا يحافظ على بقاء نموذج المكافآت على جهازه الخاص بينما تبقى عملية النشر (rollout) تعمل على وحدة المعالجة المركزية فقط، كما أنه يتوسع بشكل مستقل عن المدرب.

يمكن أن تكون أدوات وبيئة الأساليب متزامنة أو غير متزامنة. تعمل الأدوات المتزامنة على مجموعة خيوط (thread pool) بحجم max_concurrent_rollouts، لذا فإن الأداة البطيئة لا تحجب أبدًا طلبات vLLM الأخرى الجارية. ضمن دور مساعد واحد، تُنفَّذ استدعاءات الأدوات بالترتيب الذي أصدرها به النموذج. لذلك، يمكن أن تعمل حتى max_concurrent_rollouts أداة متزامنة في وقت واحد، مما يعني أن أي أداة تقرأ أو تكتب حالة مشتركة يجب أن تكون آمنة من الخيوط (thread-safe).

بعد كل weight_sync_steps خطوات تدريب، يتم نقل الأوزان المحدّثة إلى خادم vLLM عبر NCCL بحيث تعكس عمليات التوليد اللاحقة أحدث سياسة.

بما أن التوليد والتدريب يعملان بالتوازي، فقد تكون عينات التدريب قد تم توليدها بواسطة إصدار أقدم قليلاً من النموذج. يتحكم معامل max_staleness في عدد تحديثات الأوزان التي يمكن أن تتأخر عنها العينة قبل أن يتم تجاهلها.

التزامن

يُحدَّد عدد الطلبات المتزامنة المرسلة إلى خادم vLLM بواسطة max_concurrent_rollouts. افتراضيًا، يتم ضبطه تلقائيًا على max(max_staleness, 1) × per_device_train_batch_size × gradient_accumulation_steps × num_processes — وهو الحد الأقصى لعدد العينات التي يمكن للمدرِّب استهلاكها قبل أن تصبح قديمة. توليد عدد أكبر من ذلك يُعدّ هدرًا لأن العينات الزائدة ستُستبعد.

max_concurrent_rollouts هو حد أقصى وليس العدد الفعلي للطلبات قيد التنفيذ. يستطلع العامل نقطة النهاية /metrics على الخادم كل بضع ثوانٍ ويحافظ على حد حي تحته (rollout/concurrency_cap): فبعد تجاوز حد معين من التزامن، تؤدي الطلبات الإضافية إلى إبطاء vLLM بشكل أكبر، لأن ذاكرة KV cache تمتلئ، وتُستبق السلاسل وتُعاد حسابها، وتُطرد البادئات المخزنة وتُعاد تعبئتها. يبدأ الحد عند KV cache tokens / max_model_len، ويُقرأ من الخادم عند الإقلاع: أي عدد من الطلبات يتسع بطول كامل، بحيث لا يمكن للخطوة الأولى أن تسبب اضطراباً. طالما يبقى الاستخدام دون 0.6 دون أي طلبات في الطابور، يزداد الحد بنسبة 25% كل مرة يكتمل فيها عدد من عمليات rollout يعادل الحد، حتى يصل إلى الحد الأقصى. عندما يتجاوز استخدام ذاكرة KV cache قيمة 0.8، يُخفَّض الحد بنسبة 30%؛ لا يُلغى أي طلب قيد التنفيذ، بل تتوقف القبولات فقط حتى ينخفض مستوى الطابور دون الحد الجديد، ولا يُجرى أي تخفيض إضافي حتى ذلك الحين. إذا لم يعرض الخادم /metrics، يبقى الحد عند الحد الأقصى.

التحقق من الحالة واستئناف التدريب: القيمة الافتراضية لـ ignore_data_skip هي True؛ حلقة التخطي وإعادة التشغيل الأساسية في Trainer لا تنطبق على طابور النشر المباشر. بدلاً من ذلك، يتم حفظ فهرس أول موجه لم يتم تدريبه بعد في rollout_state.json جنباً إلى جنب مع كل نقطة تحقق، ويُستعاد عند الاستئناف، بحيث يتقدم العامل بسرعة إلى ذلك الموجه دون إعادة تشغيل العينات. إنه موضع التدريب، وليس موضع المولّد: يعمل العامل بأكثر من عمق طابور النشر من التدريب، وتُفقد العينات المخزنة مؤقتاً عند انتهاء التشغيل، لذا فإن الاستئناف من موضع المولّد سيتخطى الموجهات التي تم توليدها لكن لم يتم تدريبها عليها. لا يمكن إعادة تموضع مجموعات البيانات البثية (IterableDataset)؛ حيث يعيد عاملها التشغيل من الموجه 0 عند الاستئناف. عند استخدام FSDP مع bf16=True (الافتراضي) أو fp16=True، يُكتب model.safetensors في ذلك النوع من البيانات على الرغم من أن الأوزان الرئيسية هي fp32، لذا فإن نقطة التحقق المُرسلة تكون بحجم النموذج المُقدَّم، وليس ضعفه؛ لا تزال الأوزان الرئيسية fp32 وحالة المُحسِّن تذهب إلى ملفات الاستئناف (pytorch_model_fsdp.bin، optimizer.bin)، وهي ما يقرأه الاستئناف، لذا لا يتأثر الاستئناف. بدون FSDP، تكون نقطة التحقق هي أيضاً ملف الاستئناف، لذا فهي تحتفظ بنوع البيانات الرئيسي.

البدء السريع

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

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

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

يجب أن يعمل خادم vLLM والمدرب على وحدات معالجة رسومية منفصلة. استخدم CUDA_VISIBLE_DEVICES لتقسيم وحدات المعالجة الرسومية لديك. على سبيل المثال، مع وجود وحدتين، يمكنك تشغيل خادم vLLM على وحدة 0 والمدرب على وحدة 1 على النحو التالي:

# Terminal 1: vLLM server on GPU 0 (dev mode + NCCL weight transfer are required)
CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen3-4B \
    --max-model-len 4096 \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --weight-transfer-config '{"backend":"nccl"}'

اضبط --max-model-len على أقصى طول إجمالي للتسلسل (الموجّه + الإكمال) الذي تتوقعه. تقلل القيمة المنخفضة من استخدام ذاكرة وحدة معالجة الرسوميات على الخادم، مما يحرر مساحة أكبر لذاكرة KV cache ويزيد من الإنتاجية. نقطة بداية جيدة هي طول الموجّه بالإضافة إلى max_completion_length من إعداداتك.

# Terminal 2: training on GPU 1
CUDA_VISIBLE_DEVICES=1 accelerate launch train_async_grpo.py

بطاقات AMD الرسومية

يعمل المدرب على معالجات AMD الرسومية (ROCm) دون أي إعداد إضافي: فالأوامر المذكورة أعلاه تعمل كما هي. يستخدم التدريب نواة الانتباه kernels-community/aiter-flash-attn على معالجات AMD الرسومية، وkernels-community/flash-attn4 على معالجات NVIDIA Blackwell الرسومية، وkernels-community/flash-attn3 على معالجات NVIDIA الرسومية الأخرى، وكلها تُحمَّل من Hub بواسطة مكتبة kernels. النماذج التي تحدّ من قيم الانتباه (attn_logit_softcapping)، مثل Gemma 2، غير مدعومة على معالجات AMD الرسومية أو على معالجات NVIDIA Blackwell الرسومية.

نماذج الرؤية واللغة

يمكن تدريب نماذج الرؤية واللغة (Qwen3.5, Qwen3.6, Qwen3-VL, …) على مجموعات بيانات نصية فقط. مرّر معرّف النموذج كما هو معتاد؛ لا يتغير شيء آخر:

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

برج الرؤية مجمّد. مجموعة البيانات النصية فقط لا تنتج رموز صور أبدًا، لذا لا يُختبر البرج أبدًا عبر مسار الأمامي. كل ما يقع خارج برج النص (برج الرؤية، المُشغِّل متعدد الوسائط) يحمل requires_grad=False: فلا يتلقى تدرجات ولا حالة مُحسِّن، ويتخطى مزامنة الأوزان البرج بالكامل — حيث يحتفظ الخادم بالقيم التي حمّلها من نقطة التفتيش. لا يزال البرج محمّلًا، لذا يستهلك ذاكرة وحدة معالجة الرسوميات لأوزانه.

لا تُدعَم الصور بعد. لا يتم تمرير الأوامر التي تحتوي على صور إلى خادم vLLM أو إلى مسار التقدّم في التدريب. كما يتطلب التدريب متعدد الوسائط مسار التعبئة الخالية من الحشو لبناء مواضع M-RoPE ثلاثية الأبعاد من شبكة الصورة، وهو ما لم يُنفَّذ هنا.

عينة أعلى ك وأعلى با

يعيد Top-k و top-p تطبيع توزيع العينة على مجموعة مرشّحة محدودة بدلاً من المفردات الكاملة. تعكس احتمالات السجلات (log-probabilities) التي يعيدها الخادم ذلك (--logprobs-mode processed_logprobs)، لذا يجب على المُدرِّب (trainer) أن يُطبِّع على المجموعة نفسها، وإلا فستكون كل نسبة أهمية (importance ratio) منحازة: فاحتمال الرمز (token) ضمن المفردات الكاملة أقل منه ضمن مجموعة المرشحين التي سُحِب منها فعلياً (DeepSeek-V3.2، القسم 3.1). عند استخدام top_p < 1 أو top_k > 0، يطلب العامل (worker) من الخادم مجموعة المرشحين لكل رمز مُسحوب، ثم يُعيد المُدرِّب تطبيع احتمالات السجلات الخاصة به عليها. يتطلب ذلك علمين إضافيين للخادم، ويجب تعيين top_k، لأن vLLM يحدّ حجم مجموعة المرشحين به:

CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 vllm serve Qwen/Qwen3-4B \
    --max-model-len 4096 \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --weight-transfer-config '{"backend":"nccl"}' \
    --return-sampling-mask \
    --enable-scale-out

config = AsyncGRPOConfig(top_p=0.95, top_k=512)

يجعل --return-sampling-mask نظام vLLM يسجّل مجموعة المرشحين (vLLM 0.28 أو أحدث، على مشغّل نماذج V2 الخاص به: VLLM_USE_V2_MODEL_RUNNER=1 إذا رفض الخادم هذا العلم)، بينما يكشف --enable-scale-out نقطة النهاية التي تستقبل الرموز وتُخرجها والتي تُرجع هذه المجموعة. يتحقق العامل من كلا العَلَمَين على الخادم عند بدء التشغيل. لا يمكن لنسخة أقدم من vLLM إرجاع المجموعة، لذا يستمر المدرب في تطبيع التوزيع على كامل المفردات ويصدر تحذيرًا بشأن النسبة المتحيزة.

مركزية الدرجات

احتمالات السجلات (log-probabilities) التي يعيدها الخادم لا تتطابق تمامًا مع تلك الخاصة بمدرّب النموذج: نواة مختلفة، ودقة مختلفة، وسياسة متأخرة بخطوات قليلة. أوزان الأهمية وحدها لا تُصحّح ذلك، لأن $\nabla_\theta \log \pi_\theta$ الرمز المُعيَّن لا تتوسط إلى صفر تحت مُعيّن العينة، لذا فإن كل تحديث يسحب السياسة نحو مُعيّن العينة (توسيط الدرجات). بشكل افتراضي، يطرح المدرّب ذلك التوقع في كل موضع (score_centering=True), يُقدَّر عبر num_sampler_logprobs أكثر الرموز احتمالًا لدى مُعيّن العينة، ويستبعد الرموز التي يقع نسبة الأهمية الخاصة بها مقارنةً بمُعيّن العينة خارج [vllm_importance_sampling_clip_min, vllm_importance_sampling_clip_max]. لذلك، يطلب العامل أعلى احتمالات السجلات لكل رمز مُولَّد من الخادم، والتي يقوم بتسلسلها لكل رمز: قيمة كبيرة لـ num_sampler_logprobs تُبطئ الخادم، و --max-logprobs تحدد ما يقبله. score_centering=False يُدرّب باستخدام الدالة الهدف المقصوصة فقط. sampling/masked_mean هو نسبة الرموز التي استُبعدت بسبب الحدود، و sampling/sampler_mass هو كتلة الاحتمال الخاصة بمُعيّن العينة (sampler) المغطاة بأعلى الرموز احتمالًا.

تُعدّ تسلسلية أعلى قيم الاحتمال اللوغاريتمي (log-probabilities) عملاً يُنفَّذ على وحدة المعالجة المركزية (CPU) في خادم واجهة برمجة التطبيقات (API server) الخاص بـ vLLM، ومع خادم واجهة برمجة التطبيقات المفرد الافتراضي، يُقلّص الإعداد num_sampler_logprobs=8 من إنتاجية التوليد إلى النصف. ابدأ الخادم باستخدام --api-server-count 8 في إصدار vLLM 0.32 أو أحدث: فقد قُيِّس على بطاقة H100 واحدة مع نماذج تتراوح بين 1.5 مليار و7 مليارات معامل، فتكلفة أعلى 8 قيم للوغ-احتمالات لا تتجاوز 3% من إنتاجية التوليد. أما في إصدار vLLM 0.31، فإن نفس العلم (flag) لا يزال يُسبّب خسارة تتراوح بين 20% و40%، وقد تم إصلاح ذلك في المصدر الأصلي عبر vllm-project/vllm#58181.

LoRA

مرّر peft_config لتدريب مُكيّف LoRA بدلاً من النموذج الكامل:

from peft import LoraConfig

trainer = AsyncGRPOTrainer(
    model="Qwen/Qwen3-4B",
    reward_funcs=reward_len,
    train_dataset=dataset,
    peft_config=LoraConfig(r=32, lora_alpha=64, target_modules="all-linear"),
)

يجب أن تحصل كل مزامنة للأوزان على السياسة المحدّثة على الخادم. افتراضيًا، يدمج المدرب المُكيّف (adapter) في النموذج الأساسي ويرسل الأوزان المدمجة كاملة، وهو ما يعادل حوالي 15 غيغابايت لنموذج بحجم 7B في كل مزامنة. ابدأ خادم vLLM باستخدام --enable-lora وسيكتفي بإرسال المُكيّف فقط، أي حوالي 160 ميغابايت عند r=32:

CUDA_VISIBLE_DEVICES=0 VLLM_SERVER_DEV_MODE=1 VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 vllm serve Qwen/Qwen3-4B \
    --max-model-len 4096 \
    --logprobs-mode processed_logprobs \
    --api-server-count 8 \
    --weight-transfer-config '{"backend":"nccl"}' \
    --enable-lora \
    --max-lora-rank 32 \
    --max-loras 6

يعرّف VLLM_ALLOW_RUNTIME_LORA_UPDATING=1 نقطة النهاية التي يرسل إليها المُدرِّب كل مُكيِّف جديد. احتفظ بـ --weight-transfer-config حتى عند استخدام --enable-lora: فمُحدِّد وضع المزامنة يُختار فقط عند بدء المُدرِّب، وحينها يكون الخادم قيد التشغيل بالفعل، وتُعدّ المزامنة المدمجة هي الوضع الاحتياطي.

يجب أن يكون --max-lora-rank أحد القيم التالية: 1, 8, 16, 32, 64, 128, 256, 320, 512. يحدد هذا الخيار أعلى رتبة يمكن للخادم تقديمها، وليس الرتبة التي سيقدمها بالضرورة، لذا فإن مُكيّف r=4 يعمل بشكل سليم تحت حد 8. يجب أن يكون --max-loras مساوياً على الأقل لـ max_staleness + 2: حيث يحتفظ المُدرّب بعدد من إصدارات المُكيّفات يساوي max_staleness + 1 مسجّلة، حتى يتمكن التمرين الذي بدأ تحت سياسة أقدم من الاكتمال تحت تلك السياسة بدلاً من تبديل السياسات في منتصف التوليد، كما يقوم كل مزامنة بتحميل الإصدار التالي قبل تفريغ أقدم إصدار. يتحقق المُدرّب من كلا القيمتين عند بدء التشغيل ويخبرك بالقيم التي يجب إعادة تشغيل الخادم بها.

يحمّل vLLM المُكيّفات من القرص بدلاً من الشبكة، لذا يكتب المُدرّب كل إصدار تحت <output_dir>/.vllm_lora/ ويمنح الخادم المسار. إذا كان الخادم يعمل على جهاز مختلف، فيجب أن يكون ذلك المجلد على نظام ملفات يمكن لكلٍّ منهما رؤيته.

<output_dir>/.vllm_lora/ هو ذاكرة تخزين مؤقتة للخدمة، وليس المكان الذي يُحفظ فيه المُكيّف الذي درّبتَه. فهو يحتفظ فقط بأحدث الإصدارات، ويُحذف كل إصدار بعد فترة وجيزة من خروجه من نافذة الصلاحية. نقاط التفتيش هي ما يحفظ المُكيّف الذي درّبتَه، لذا لا تُعطِلها: مع save_strategy="no"، تنتهي عملية تدريب تستغرق ساعات دون أن تترك أي أثر. كما يجب أن يكون output_dir قابلاً للقراءة من قِبل الخادم، وأن يستمر في الوجود بعد انتهاء المهمة، لذا لن تعمل المساحة المؤقتة المحلية على العقدة، رغم أنها كانت ستُبقي عمليات المزامنة بعيداً عن نظام الملفات المشترك البطيء.

لا يكون مزامنة المُكيِّف (Adapter) أسرع دائمًا. يولّد vLLM بطيئًا بحوالي 1.33–1.39 مرة لكل رمز عند تقديم مُكيِّف LoRA مقارنةً بتقديم الأوزان المدمجة، وعادةً ما يكون التوليد هو ما يهيمن على الوقت الكلي (wall-clock) في التعلم المعزز. ما تحصل عليه مقابل ذلك هو توقف أقصر بكثير عند كل مزامنة، ونحو 1% من عرض نطاق المزامنة. إذا كان معدل إنتاجية التوليد هو عنق الزجاجة لديك، فإن المزامنة المدمجة غالبًا ما تبقى الخيار الأفضل.

تخصيص حلقة النشر

تتم عمليات التوليد والمكافآت والمزايا والتصفية في عملية التمرير (rollout) داخل experimental.async_grpo.AsyncRolloutLoop. لتعديل إحدى هذه العمليات، قم بإنشاء فئة فرعية من الحلقة، ثم تجاوز (override) الطريقة الخاصة بالخطوة المعنية، واضبط الفئة الفرعية كقيمة لـ loop_cls على فئة فرعية من المدرب. لا يتغير منشئ المدرب.

على سبيل المثال، منهج يتوقف عن أخذ عينات من الأوامر التي يحلها بالفعل، مع تحديد عتبة في فئة فرعية من التهيئة:

from dataclasses import dataclass

import numpy as np

from trl.experimental.async_grpo import AsyncGRPOConfig, AsyncGRPOTrainer, AsyncRolloutLoop


@dataclass
class CurriculumConfig(AsyncGRPOConfig):
    pass_rate_cap: float = 0.9


class CurriculumRolloutLoop(AsyncRolloutLoop):
    def filter_prompt(self, row_index, row, epoch):
        return self.pass_rates.get(row_index, 0.0) < self.config.pass_rate_cap

    async def setup(self):
        self.pass_rates = {}

    def compute_advantages(self, group):
        scored = group.rewards[~np.isnan(group.rewards)]
        if len(scored):
            self.pass_rates[group.row_index] = float(np.mean(scored > 0))
        return super().compute_advantages(group)


class CurriculumTrainer(AsyncGRPOTrainer):
    loop_cls = CurriculumRolloutLoop

تُجمع المكافآت عبر reward_funcs، والبيئات التي تُعرّف get_reward، وreward الذي يضبطه generate_one المخصص على experimental.async_grpo.Rollout الخاص به: لتقييم بواسطة قاضٍ، مرّر دالة مكافأة غير متزامنة، أو قيّم داخل generate_one. يُنفَّذ compute_advantages لكل مجموعة، بما في ذلك المجموعة التي تُستبعد لاحقًا لأن جميع مكافآتها المُقيَّمة متساوية؛ فالاستبعاد ينظر إلى المكافآت، لا إلى المزايا. يُبنى الحلقة في عملية مولَّدة، لذا عرّف الفئة الفرعية على مستوى الوحدة. أنشئ العملاء في setup، الذي يعمل على حلقة أحداث الحلقة، بدلاً من تجاوز __init__. يُتخطى أي موجه ترفضه filter_prompt لذلك العصر ويُحتسب ضمنه، كما هو الحال مع المجموعة المستبعدة. إذا رفضت كل موجهات العصر، ترمي الحلقة استثناءً.

فلسفة التصميم

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

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

يمرّ التوليد بعدة مراحل قبل أن يتحول إلى تدرّج. لنلقِ نظرة أولاً على المراحل المختلفة، من الموجه إلى تكوين الدفعة النهائية لدينا:

Dataset row = PROMPT (message list + reward kwargs)
 └─ GROUP                  (1 prompt, `num_generations` rollouts, 1 advantage baseline)
     └─ ROLLOUT            (1 conversation, keyed by `rollout_id`)
         ├─ TURN           (1 vLLM /v1/completions call + tool messages fed back)
         │   └─ TurnRecord (prompt_ids, output_ids, output_log_probs)
         └─ reconcile      (`_chain_to_sequences` classifies drift per turn: CLEAN/REALIGN/FORK)
             └─ SEQUENCE   (≥1 per rollout; new one per fork; dropped if no trained token)
                 └─ SAMPLE (Sequence + group advantage + reward + metrics)

════════════ Trainer process boundary: `rollout_buffer` (mp.Queue) ════════════

                 └─ SAMPLE (Pulled 1 at a time; dropped if staleness > `max_staleness`)
                     └─ ROW            (Planner inserts it into one of `dp` prefix tries, attention-cost-balanced)
                         └─ MICRO-BATCH (`dp` rows, one per rank)
                             └─ PACKED ROW (Collator lays each trie out: unique tokens, depth as `position_ids`)
                                 └─ FORWARD (`compute_loss`, bs=1, padding stripped, FA3 per trie segment)
                     └─ OPTIMIZER STEP (from `grad_accum` micro-batches)

عند قراءتها من الأعلى إلى الأسفل:

• المجموعة group هي موجه واحد تم توليده num_generations مرات. يتم حساب خط الأساس المميز داخلها، ولهذا السبب تُعد المجموعة هي الوحدة التي يتم تقييمها.
• التوليد rollout هو محادثة واحدة. يعيد كل دور ترقيم قائمة الرسائل بأكملها، لذا يجب معالجة أي انحراف بين الأدوار في النهاية.
• يمكن أن يؤدي التوفيق إلى تفرّع مسار واحد إلى عدة سلاسل، ولهذا السبب يمكن أن ينتج عن محادثة واحدة أكثر من عينة تدريب واحدة.
• يُعدّ عينة تسلسلاً مع فائدتها ومكافأتها ومقاييسها. وهذا ما يعبر عن حد العملية.
• عند تجاوز الحد، يخطط المدرب العينات إلى صفوف (واحد لكل رتبة DP)، ثم يطوي كل صف في شجرة بادئة (prefix trie) بحيث تُمرَّر الرموز المشتركة مرة واحدة فقط، ويجمع grad_accum من الدُفعات الدقيقة (micro-batches) في خطوة مُحسِّن واحدة.

لذلك نقسم مقاييسنا بناءً على المرحلة (أو الكيان) التي تتعلق بها:

لنعرّف أيضًا بعض المصطلحات لجعل مقاييس الرموز غير ملتبسة:

• الرموز المولّدة هي ما أنتجه النموذج (completions/*).
• الرموز المُعاد توجيهها هي كل رمز يعالجه مسار forward: النص التوجيهي، وأي نتائج للأدوات، والرموز المُولَّدة.
• الرموز المدربة هي المجموعة الفرعية التي يُحسب عليها الخسارة حيث completion_mask == 1. على سبيل المثال، يمكن أن يؤدي التفرع أو إعادة المحاذاة إلى تخفيض مستوى الرموز المولَّدة مسبقًا إلى سياق، وبالتالي فإن المدربة ≠ المولَّدة.

كيف تتكوّن أرقام الدفعة

الـ صف هو ما يمرّره رتبة واحدة من DP في دفعة مصغّرة واحدة: عدة عينات مُجمَّعة في غابة بادئة واحدة، بحيث تُمرَّر الرموز المشتركة بينها مرة واحدة — راجع تعبئة الشجرة. ويحدد المخطط أيّ العينات تقع في أيّ صف (مع موازنة تكلفة الانتباه حتى لا تتأخر أيّ رتبة)، بينما يتولى مُجمِّع البيانات عملية التعبئة.

في جميع مقاييسنا، يعني مصطلح «خطوة» دائمًا خطوة مُحسِّن كاملة، وليس دفعة فرعية. تُشكّل gradient_accumulation_steps من الدفعات الفرعية خطوة واحدة، وكل مقياس يحمل اسم _per_step يكون لكل خطوة مُحسِّن، بما يتوافق مع global_step وlogging_steps وباقي مصطلحات Trainer. حيث يكون المقياس لكل دفعة فرعية، يُصرَّح بذلك صراحةً (batch/microbatches_per_step) أو يكون كمية لكل صف (batch/row_*، batch/samples_per_row).

لذلك، يحتوي كل خطوة على عدد ثابت من row-slots:

row-slots per step = gradient_accumulation_steps x world_size

مما يجعل مقاييس الدفعة تتكوّن في سلّم يمكنك التحقق من بعضها البعض:

sample                                     sample/forwarded_tokens_mean
  └─ packed into a ROW                     batch/samples_per_row, batch/row_tokens_mean
      └─ one row per DP rank               = one micro-batch
          └─ gradient_accumulation_steps micro-batches = one STEP
                                           batch/samples_per_step, batch/forwarded_tokens_per_step

لذا batch/samples_per_step ≈ row-slots x batch/samples_per_row، وكذلك الأمر بالنسبة للرموز. يتطابق الجانبان فقط حتى مستوى التباين بين الدُفعات الدقيقة داخل الخطوة الواحدة — فمقاييس كل خطوة هي مجموع، بينما مقاييس كل صف هي متوسط — لذا توقع فرقًا بنسبة جزء من المئوية، وليس تطابقًا تامًا.

batch/row_fill_frac هو المؤشر الذي يجب مراقبته عندما تكون العينات طويلة: عينة من 10 آلاف رمز لا تملأ ميزانية 32 ألف رمز بشكل جيد (ثلاث عينات تتسع، وأربع لا تتسع أبدًا، لذا غالبًا ما يحصل الحاصد على عينتين فقط وتكون الصف ممتلئًا بنسبة 77% تقريبًا)، بينما تملأ العينات المكونة من 1000 رمز الميزانية بشكل شبه مثالي. هذا هو التكميم وليس خطأً برمجيًا، وtoken_budget هو العنصر الذي يمكن التحكم به — مع مراعاة أن الانتباه يعمل بتعقيد O(L²) لكل تسلسل، لذا فإن صفًا أكثر امتلاءً من التسلسلات الطويلة لا يستهلك ذاكرة أكثر بشكل خطي.

تعبئة الأشجار

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

مكان حدوثه:

planner    TreeRow.add            the trie grows sample by sample; a sample is priced by its novel tokens
   │                              (TreeRow.fits), so `token_budget` bounds unique tokens, not raw ones
collator   TreeRow.pack           DFS layout: unique tokens, depth as position_ids, one loss term per
   │                              original trained token (token_index), and per segment its queries and
   │                              the K/V indices of its root-to-segment path, all built on CPU
attention  tree_attention         gather K/V along the paths, one FA3 varlen call, causal

كيف يعمل، على مسارين من تنفيذ موجه واحد:

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

2. Trie (one per row)   S0 [p1 p2] ─┬─ S1 [p3 a1 a2]          nodes are keyed on (token, next token),
                                   └─ S2 [p3 b1 b2]          so the fork happens one token early and
                                                              every node predicts exactly one token;
                                                              chains without a fork become segments

3. Packed row           idx           0  1 | 2  3  4 | 5  6  7
   (DFS order)          input_ids    p1 p2 | p3 a1 a2 | p3 b1 b2  8 tokens: MLPs, norms and projections
                        position_ids  0  1 |  2  3  4 |  2  3  4  run once per unique token
                        segment      S0    | S1       | S2

4. Attention            seg   queries      K/V gathered            kv_index
   (one FA3 call)       S0    [p1 p2]      [p1 p2]                 0 1
                        S1    [p3 a1 a2]   [p1 p2 | p3 a1 a2]      0 1 2 3 4
                        S2    [p3 b1 b2]   [p1 p2 | p3 b1 b2]      0 1 5 6 7

                        FA3 aligns the causal mask bottom-right      K:  p1 p2 p3 a1 a2
                        when queries are fewer than keys, so a       Q: p3   ■  ■  ■  ·  ·
                        segment's queries see their ancestors and       a1   ■  ■  ■  ■  ·
                        their own causal past, and nothing else.        a2   ■  ■  ■  ■  ■

5. Loss                 p2 (idx 1) predicts p3 for both rollouts; token_index points every trained
                        token of every rollout at the position that predicts it

بعض العواقب:

• يُشارَك أي بادئة مشتركة: فمسارات التنفيذ لموجّه واحد، وكذلك الموجّه النظامي أو مخطط الأداة المشترك بين الموجّهات. يرسل المخطّط عينةً إلى الصف الذي يحتفظ بالفعل بمعرّف group_id الخاص به، حيث يوجد موجّهه مسبقًا. وعندما يمتلئ ذلك الصف، تنتقل العينة إلى صف آخر إذا كان هناك ترتيب فارغ، أو إذا لم يُسبّب ذلك زيادةً في الصف الأكثر تحميلًا، وهو ما يحدد زمن الدفعة الجزئية؛ وإلا تُغلق الدفعة الجزئية.
• عدم مشاركة أي شيء يعني التعبئة العادية: حيث يكون كل عينة في هذه الحالة مقطعًا واحدًا يكون مساره هو نفسه، وهي تعبئة FA3 varlen بدون حشو عادية.
• يتم تكرار K/V فقط: يتم جمع البادئة المشتركة مرة واحدة لكل مقطع فرع، وهو ما يعادل تقريبًا ما يحتفظ به التدريب غير المُفكَّك، وهو صغير في حالة GQA.
• تُدعَّم هجائن Gated DeltaNet (Qwen3.5, Qwen3.6, Qwen3-Next, …): حيث تقرأ طبقة الالتفاف في كل منها أسلاف الرمز الخاص بها، وتبدأ قاعدة دلتا المقطّعة كل مقطع من الحالة النهائية لوالدها (trl/experimental/async_grpo/tree_gated_delta_rule.py). ويتطلب ذلك transformers>=5.15.0، حيث تستدعي هذه الطبقات الدوال على مستوى الوحدة التي تعيد حزم الشجرة تكييفها. وتُرفض النماذج التي تحتوي على أي طبقة غير انتباه أخرى عند التهيئة.

ما يقدّمه: عند عدم مشاركة أي شيء، يعمل بسرعة تقارب سرعة التعبئة بدون حشو، وتزداد السرعة تقريبًا مع نسبة التعبئة (حوالي 2.8–3 أضعاف عند نسبة 3.4 على Qwen3-0.6B/1.7B، H100). النسبة هي البادئة المشتركة × عدد العينات لكل صف، لذا فإن batch/samples_per_row هو المؤشر الرئيسي: عند اقترابه من 1، لا يمكن مشاركة أي شيء، والعنصر المؤثر هو token_budget.

احكم عليه من حيث الإنتاجية، batch/trained_tokens_per_step / perf/fwd_bwd_s. يحتوي الدُفع المصغّر المُجمَّع على عينات أكثر، لذا يرتفع perf/fwd_bwd_s وينخفض perf/mfu_*، الذي يُقسَّم على الرموز المُرسَلة، — ولا يُعدّ أيٌّ منهما تراجعاً. كما أن وجود عينات أكثر في كل صف يعني سحب المزيد من عمليات التوليد في كل خطوة، مما يجعل التشغيل المعتمد على التوليد أكثر اعتماداً عليه.

أي إجراء يُطيل الصفوف أو يُقلل عددها يُزيل المشاركة. تحقق أولاً من fork_threshold_tokens: لا يتحول الدور إلى صف مستقل إلا عندما ينحرف إعادة الترميز بمقدار ذلك العدد من الرموز، والانحراف في الوكلاء يكون عادةً بعشرات الرموز مقابل القيمة الافتراضية 1024، لذا لا يحدث أي تفرع وتنهار المحادثة إلى صف واحد لكل رتبة. يُظهر rollout/fork_frac النظام الذي تعمل فيه.

قائمة الانتظار للنشر

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

المقياسان الأخيران (perf/rollout_wait_s وrollout/backpressure_s) هما انعكاسان لبعضهما البعض ولا يكونان كبيرين معًا أبدًا! قراءة هذين المقياسين معًا مع حجم الطابور تُظهر لك أي الجانب هو عنق الزجاجة:

• الطابور شبه فارغ، وperf/rollout_wait_s مرتفع → مقيّد بالتوليد. المدرب يعاني من الجوع؛ راجع rollout/generated_tok_s وrollout/concurrency وrollout/score_queue_size.
• الطابور شبه ممتلئ، وrollout/backpressure_s مرتفع → مقيّد بالمدرب. يتم تقييد التوليد وتعتري مخرجاته العتاقة في الطابور، لذا راقب ارتفاع sample/staleness_mean.
• كلاهما قريب من الصفر → متوازن!

إكمالات

اكتمال هو ما ولّده vLLM لموجّه واحد، محسوبًا عبر كل جولة من التمرين.

التشغيل

التوليد هو محادثة كاملة واحدة: موجه يُولَّد حتى اكتماله، بما في ذلك كل جولة ذهاب وإياب للأدوات التي استُخدمت للوصول إلى ذلك. تتشارك num_generations من عمليات التوليد موجهًا واحدًا وتكوّن مجموعة.

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

الأدوات

تُسجَّل فقط عند تنفيذ النموذج للأدوات. يتكرر tools/<name>/* لكل اسم أداة، بنفس الطريقة التي يتكرر بها rewards/<func>/* لكل دالة مكافأة، لأن فشل أداة واحدة يكون غير مرئي في المتوسط العام لجميع الأدوات. يسجّل حلقة الأدوات المدمجة ومدرب إطار OpenEnv (HarnessAsyncGRPOTrainer، انظر التدريب على الأطر) نفس الأسماء، بحيث تقرأ لوحة تحكم واحدة كلا المصدرين؛ وتوضح عمود path المصدر الذي ينتج كل مقياس.

البيئات

يُسجَّل فقط مع environment_factory. تُنفَّذ كلا الاستدعاءين على مجموعة خيالات أدوات العامل، لذا فإن البيئة البطيئة تؤخر تنفيذها الخاص فقط دون التأثير على العمليات الأخرى الجارية.

عينات تصل من الطابور

كل عينة هي RolloutSample: تسلسل مُتوافق مع مجموعة المزايا، والمكافأة ومقاييسها لكل عينة، تُجمّعها الوحدة العاملة في _score_group بمجرد انتهاء كل جيل في المجموعة وتقييمه. تدفع الوحدة العاملة هذه العينات إلى rollout_buffer؛ وكل ما يلي يُقاس على جانب المُدرِّب، حيث يسحبها للتدريب.

المكافآت وبعيداً عن السياسة

الدفعات

تتكوّن كل دفعة فرعية مصغّرة من world_size صفوف (تذكّر أن التعبئة تسطّح البيانات في تسلسل واحد)، أي صف واحد لكل رتبة من رتب التوازي، بحيث تمرّر الرتبة i الصف i. وتُشكّل gradient_accumulation_steps من هذه الدفعات خطوة واحدة لمُحسِّن المعاملات. وتغطي الخطوة إجمالاً gradient_accumulation_steps × world_size صفًا. وكل مقياس من مقاييس _per_step أدناه هو مجموع على مدى الخطوة كاملة وعبر كل الرتب؛ أما مقاييس batch/row_* فهي متوسطات على الصفوف.

الأداء

تقيس الإنتاجية عدد الرموز التي يعالجها المدرب في الثانية. استغلال عمليات النموذج (MFU) يقدّر النسبة المئوية من القدرة الحسابية النظرية لأجهزة التدريب المستخدمة في عمليات النموذج الأمامية والعكسية. تعتمد القدرة المستخدمة في هذا التقدير على العتاد ودقة التدريب.

يُبلَّغ عن معدل الإنتاجية وMFU على أساسَي زمنَين:

• _fwd_bwd يقيس الأداء خلال المرورين الأمامي والخلفي.
• _wall_clock يقيس الأداء على مدى خطوة المُحسِّن الكاملة، بما في ذلك تحديثات المُحسِّن، ومزامنة الأوزان، والوقت المنقضي في انتظار النتائج.

يساعد هذا الفرق في التمييز بين أداء الحساب وتكلفة الانتظار والتنسيق. تصف كلا مقياسي MFU أجهزة التدريب فقط: فهي لا تشمل قدرات الحساب أو العتاد لخوادم النشر الخارجي أو الخوادم المعلمة. يعكس مقياس MFU الزمني الفعلي الوقت الذي يقضيه المدرب في الانتظار على تلك الخدمات، وليس معدل استخدام تلك الخدمات نفسها.

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

AsyncGRPOConfig

AsyncGRPOTrainer

>>> from trl.experimental.async_grpo import AsyncGRPOTrainer
>>> from trl.rewards import accuracy_reward
>>> from datasets import load_dataset

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

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

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

AsyncRolloutLoop

التنفيذ

TurnRecord

RolloutGroup