التدريب على وحدات معالجة رسومية متعددة

تتدرب LeRobot على وحدات معالجة رسومية متعددة من خلال Hugging Face Accelerate. يتم دعم ثلاثة تخطيطات متوازية للبيانات:

التثبيت

accelerate مضمّن في الحزمة الإضافية training:

pip install 'lerobot[training]'

الإطلاق

يمكن بدء التدريب الموزع عبر كلٍّ من torchrun وaccelerate launch. يُستخدم Accelerate كمُشغِّل بسيط: فهو لا يدير إعدادات التدريب، بل تُخزَّن جميع إعدادات التدريب الموزع في نظام الإعدادات الخاص بـ LeRobot.

باستخدام torchrun:

torchrun --nproc-per-node=2 $(which lerobot-train) \
  --dataset.repo_id=${HF_USER}/my_dataset \
  --policy.type=act \
  --policy.repo_id=${HF_USER}/my_trained_policy \
  --output_dir=outputs/train/act_multi_gpu \
  --job_name=act_multi_gpu \
  --trackio.enable=true

مع accelerate launch (كمُشغِّل عادي):

accelerate launch --num_processes=2 $(which lerobot-train) \
  --dataset.repo_id=${HF_USER}/my_dataset \
  --policy.type=act \
  --policy.repo_id=${HF_USER}/my_trained_policy \
  --output_dir=outputs/train/act_multi_gpu \
  --job_name=act_multi_gpu \
  --trackio.enable=true

بدون أعلام --parallelism.*، يعمل الإقلاع متعدد العمليات بتشغيل DDP عادي. تستخدم عمليات التشغيل متعددة العقد أعلام torchrun --nnodes/--node-rank/--rdzv-endpoint القياسية (أو accelerate launch --num_machines/--machine_rank/--main_process_ip).

ملفات الإعداد بصيغة YAML الخاصة بـ Accelerate (accelerate launch --config_file some.yaml، accelerate config) غير مدعومة. فهي تُهيّئ المحرّك عبر متغيرات البيئة، متجاوزةً نظام إعدادات LeRobot، مما يعني أن train_config.json لن يعيد بعد الآن وصف الإعدادات التي استخدمها التشغيل فعليًا. لذلك يرفض lerobot-train البدء عند ضبط متغيرات بيئة accelerate. ضع الإعدادات بدلاً من ذلك في أعلام --parallelism.* / --accelerator.*، أو اضبط LEROBOT_ALLOW_ACCELERATE_ENV=1 للاعتراف بالتجاوز والمتابعة على أي حال.

دلالات الدفعة، ومعدل التعلم، وعدد الخطوات

يحمّل كل عامل من عمال التوازي البيانات dp_replicate × dp_shard دفعةً مصغّرة خاصة به بحجم --batch_size في كل خطوة، لذا تستهلك خطوة التدريب الواحدة batch_size × dp_world_size عينة، و× gradient_accumulation_steps من تلك العينات تدخل في كل تحديث لمُحسِّن:

effective_batch_size = batch_size × dp_world_size × gradient_accumulation_steps

يطبع شريط التدريب هذا التحليل عند بدء التشغيل. --steps يعدّ خطوات الحلقة (الدفعات الدقيقة لكل عامل)، وليس تحديثات المُحسِّن.

تُعدّ تدرّج التراكم (Gradient accumulation) علمًا من الدرجة الأولى:

torchrun --nproc-per-node=2 $(which lerobot-train) \
  --batch_size=8 --accelerator.gradient_accumulation.steps=4 ...

لا يقوم LeRobot تلقائيًا بتعديل معدل التعلم أو عدد الخطوات عندما يزداد حجم الدفعة الفعّال. إذا قمت بالتوسع وأردت تدريبًا مكافئًا، فيرجى ضبط الإعدادات يدويًا، على سبيل المثال مع معالجي رسمين: ضاعف --optimizer.lr (توسّع خطي)، أو انقص --steps إلى النصف.

التدريب المجزأ (FSDP)

إذا كان النموذج كبيرًا جدًا للتدريب باستخدام DDP، فقسّمه باستخدام FSDP2:

torchrun --nproc-per-node=4 $(which lerobot-train) \
  --dataset.repo_id=${HF_USER}/my_dataset \
  --policy.type=<your_policy> \
  --parallelism.dp_shard=4 \
  --accelerator.mixed_precision=bf16 \
  --output_dir=outputs/train/my_policy_fsdp

يقوم --parallelism.dp_shard=-1 بتقسيم النموذج على عدد العمليات التي بدأها المُشغِّل.

يدعم --accelerator.mixed_precision كلًا من bf16 وfp16. التفاصيل في الدقة المختلطة

تغليف الوحدات

يقوم FSDP بتجزئة النموذج في وحدات (عادةً كتلة الترانسفورمر المتكررة) ويجمع وحدة واحدة في كل مرة أثناء التقدّم/الارتداد. تُعلن السياسات عن وحدات التفافها عبر _fsdp_wrap_modules على فئة السياسة. على سبيل المثال، تعلن ACT عن ["ACTEncoderLayer", "ACTDecoderLayer"] وتعلن FastWAM عن ["MoTLayer"]. بالنسبة لسياسة لا تحتوي على إعلان _fsdp_wrap_modules، مرّر أحد الأعلام أدناه. يمكنك تحديد اسم فئة الوحدة صراحةً، أو استخدام سياسة مبنية على الحجم بدلاً من ذلك:

--accelerator.fsdp.wrap_modules='["MyTransformerBlock"]'   # explicit class names
--accelerator.fsdp.min_num_params=1000000                  # or: wrap every submodule above 1M params

إذا لم يُعلن عن سياسة _fsdp_wrap_modules ولم يُمرَّر أي من --accelerator.fsdp.wrap_modules أو --accelerator.fsdp.min_num_params، فإن التشغيل يفشل عند الإقلاع بدلاً من التفاف جذر الوحدة فقط بصمت (وهو ما سيؤدي إلى فقدان جميع وفورات الذاكرة الناتجة عن التقسيم).

إعدادات تقسيم أخرى:

• --accelerator.fsdp.reshard_after_forward: ما إذا كان يجب إبقاء معاملات كل وحدة مقيمة بعد التمرير الأمامي.
• --accelerator.fsdp.cpu_offload: يُبقي المعاملات والتدرجات وحالات المُحسِّن على وحدة المعالجة المركزية (CPU).
• --accelerator.fsdp.ignored_modules: تعبير نمطي لمسارات الوحدات التي يجب إبقاؤها غير مجزأة.
• --accelerator.fsdp.mixed_precision_policy.{param_dtype,reduce_dtype,output_dtype,cast_forward_inputs}: حقول MixedPrecisionPolicy الخاصة بـ PyTorch، وتُطبَّق على كل وحدة FSDP. بمجرد تعيين أي حقل، يُبنى هذا السياسة من هذه الحقول فقط ويستبدل تلك المشتقة من --accelerator.mixed_precision، لذا يجب تعيين param_dtype أيضًا. يتطلب float16 استخدام --accelerator.mixed_precision=fp16، وهو ما يُنشئ مُقيِّم الخسارة (loss scaler).

HSDP

التوازي الهجين المجزأ للبيانات: تُجزَّأ المعاملات والتدرجات وحالات المُحسِّن عبر dp_shard من الرتب، ويُكرَّر هذا التجزئة dp_replicate مرة. تبقى عمليات جمع المعاملات (all-gathers) وتجميع التدرجات (reduce-scatters) داخل مجموعة التجزئة؛ بينما تعبر عملية الاختزال الشامل (all-reduce) التي تُزامن النسخ بين المجموعات فقط. يجب أن يكون حاصل ضرب هذين البعدين مساوياً لحجم العالم:

# 16 GPUs = 2 nodes × 8: shard within each node, replicate across nodes
torchrun --nnodes=2 --nproc-per-node=8 ... $(which lerobot-train) \
  --parallelism.dp_replicate=2 --parallelism.dp_shard=8 ...

PEFT

يعمل التدريب الدقيق باستخدام PEFT (--peft.*) تحت FSDP2 وHSDP. يتم تقسيم النموذج الأساسي المجمّد مع المُكيّفات (adapters)، بحيث يحتفظ كل رتبة (rank) فقط بشقته من أوزان النموذج الأساسي:

torchrun --nproc-per-node=4 $(which lerobot-train) \
  --policy.path=${HF_USER}/my_base_policy \
  --peft.method_type=LORA --peft.r=16 \
  --parallelism.dp_shard=4 \
  --accelerator.mixed_precision=bf16 \
  --output_dir=outputs/train/my_policy_fsdp_lora

• تأتي وحدات التغليف (Wrap units) من إعلان _fsdp_wrap_modules في السياسة (أو --accelerator.fsdp.wrap_modules).
• استخدم الدقة المختلطة عندما يكون النموذج الأساسي مخزّنًا في bf16 أو fp16. يحتفظ PEFT بمُكيّساته (adapters) في fp32 بينما تحتفظ النسخ من --peft.full_training_modules بنوع البيانات (dtype) للنموذج الأساسي، ويحتاج FSDP2 إلى نوع بيانات واحد للمعاملات القابلة للتدريب التي يقسّمها معًا. عند تفعيل الدقة المختلطة، يقوم accelerate بترقية كل معامل قابل للتدريب إلى fp32.
• تُخزّن نقاط التفتيش المُكيّف بدلاً من الأوزان الكاملة، في كل --checkpoint_format (انظر نقاط التفتيش).
• يُطابَق --accelerator.fsdp.ignored_modules مع أسماء وحدات نموذج PEFT، والتي تبدأ بـ base_model.model.. ابدأ النمط بـ .* لمطابقتها.

نقاط التفتيش

تحتوي كل نقطة تحقق على مجلد pretrained_model/ ومجلد training_state/:

005000/  # the training step at that checkpoint
├── pretrained_model/
│   ├── config.json  # policy config
│   ├── train_config.json  # the full training config
│   ├── model.safetensors  # full weights (checkpoint_format ∈ {safetensors, safetensors_dcp}, or any non-sharded run)
│   ├── pytorch_model_fsdp_0/  # DCP weight shards (checkpoint_format ∈ {dcp, safetensors_dcp})
│   ├── policy_preprocessor.json  # preprocessor config (when the run has a preprocessor)
│   ├── policy_preprocessor_step_*.safetensors  # state of the stateful preprocessor steps
│   ├── policy_postprocessor.json  # postprocessor config (when the run has a postprocessor)
│   └── policy_postprocessor_step_*.safetensors  # state of the stateful postprocessor steps
└── training_state/
    ├── optimizer_param_groups.json  # optimizer param groups (non-sharded runs)
    ├── optimizer_state.safetensors  # optimizer state (non-sharded runs)
    ├── optimizer_0/  # DCP optimizer shards (sharded runs)
    ├── rng_state.safetensors  # rng states
    ├── scheduler_state.json  # scheduler state (when the run has a scheduler)
    ├── scaler_state.json  # fp16 loss-scaler state (mixed_precision=fp16 only)
    └── training_step.json  # step + dp_world_size/batch_size/grad_accum/precision + topology

أثناء التدريب على وحدة معالجة رسومية واحدة أو باستخدام DDP، يقوم خط الأنابيب بتسلسل كل حالة dict في ملف واحد: model.safetensors للنموذج وoptimizer_state.safetensors لمُحسِّن التدريب.

أثناء التدريب المجزّأ، يُحفظ حالة المُحسِّن على شكل شتات DCP تحت training_state/optimizer_0/، ويمكن تكوين تخطيط النموذج تحت pretrained_model/ من خلال --checkpoint_format:

تخزّن عملية PEFT مُكيّفها (adapter) بدلاً من الأوزان الكاملة: حيث يحلّ adapter_model.safetensors وadapter_config.json محلّ model.safetensors، بينما تحتوي شظايا DCP على المُكيّف فقط. يتم تحميل النموذج الأساسي من المسار المسجّل في adapter_config.json.

شيئان يجب معرفتهما حول نقاط التفتيش المجمّعة (safetensors) من التشغيلات المقسّمة:

• تُخزّن أوزانًا من نوع fp32. في التدريب بالدقة المختلطة، يحتفظ FSDP بنسخة رئيسية من نوع fp32، ويحفظ نقطة التفتيش النسخة الرئيسية لضمان استئناف التدريب بشكل متسق.
• عملية الجمع جماعية (تشارك جميع الرتب) لكن العملية الرئيسية فقط هي التي تكتب.

تحويل نقاط التفتيش DCP

lerobot-convert-dcp يدمج مجلد شريحة DCP في ملف model.safetensors عادي، دون اتصال وبلا وحدات معالجة رسومية:

lerobot-convert-dcp --checkpoint_dir=outputs/train/run/checkpoints/005000
lerobot-convert-dcp --checkpoint_dir=... --delete_dcp=true --push_to_hub=${HF_USER}/my_policy

--push_to_hub ينشر المجلد المحوّل كمستودع نموذج. تندمج شتات تشغيل PEFT في adapter_model.safetensors. وكأي نقطة تحقق dcp، تُحمَّل نقطة تحقق PEFT المحفوظة بواسطة --checkpoint_format=dcp باستخدام --policy.path فقط بعد هذا التحويل.

الاستئناف

استأنف التدريب باستخدام --resume=true --config_path=.../checkpoints/last/pretrained_model/train_config.json. يدعم الاستئناف من نقطة تحقق DCP إعادة تقسيم النموذج وحالة المُحسِّن إلى البنية الحالية، مما يعني أنه يمكنك الاستئناف بتقسيم مختلف لـ dp_replicate/dp_shard. يمكن لمُعيّن البيانات دائمًا الاستئناف عند الحقبة والإزاحة الصحيحين، لكنه يكون دقيقًا على مستوى العينة فقط عندما يتطابق حجم العالم وحجم الدفعة مع الإعدادات الأصلية للتشغيل (يُسجَّل تحذير في حال عدم التطابق).

استخدمت نقاط التفتيش التي كتبتها LeRobot 0.6.x والإصدارات الأقدم تخطيطًا مختلفًا على القرص (حالة مُحسِّن كاملة مجمّعة) ولا يمكن استئنافها.

ملاحظات

• حفظ نقاط التفتيش ونشر نهاية التدريب هما عمليتان جماعيتان (تدخل فيهما كل الرتب). أما الأوزان المجمّعة والملفات الجانبية ورفعها إلى Hub فتُكتب من قبل العملية الرئيسية وحدها.
• تُقلَّص المقاييس عبر الرتب قبل التسجيل: تُحسب متوسطات الخسائر، ويبلغ samples/s عن معدل الإنتاجية على مستوى العنقود بالكامل.
• يتم تحديث جدولة معدل التعلم مرة واحدة في كل خطوة تدريب بغض النظر عن عدد العمليات (حيث أن step_scheduler_with_optimizer=False مدمج مسبقًا).

للحصول على خلفية حول الآلية الأساسية، راجد دليل Accelerate FSDP. وللتعمق أكثر في التدريب على نطاق واسع، اطّلع على Ultrascale Playbook.