استكشاف الأخطاء

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

التسجيل

يمكن أن يساعدك التسجيل في تحديد مصدر الخطأ. في الإعداد الموزّع الذي يتضمن عمليات متعددة، قد يكون التسجيل تحدياً، لكن Accelerate يوفر أداة logging() لضمان مزامنة السجلات.

لحل مشكلة، استخدم logging() بدلاً من وحدة logging القياسية في Python. اضبط مستوى التفصيل (INFO، DEBUG، WARNING، ERROR، CRITICAL) باستخدام معامل log_level، ثم يمكنك إما:

1. صدّر log_level كمتغير بيئة ACCELERATE_LOG_LEVEL.
2. مرّر log_level مباشرة إلى get_logger.

على سبيل المثال، لضبط log_level="INFO":

from accelerate.logging import get_logger

logger = get_logger(__name__, log_level="DEBUG")

بشكل افتراضي، يُستدعى السجل على العمليات الرئيسية فقط. لاستدعائه على جميع العمليات، مرّر main_process_only=False. إذا كان يجب استدعاء السجل على جميع العمليات وبترتيب، فمرّر أيضًا in_order=True.

from accelerate.logging import get_logger

logger = get_logger(__name__, log_level="DEBUG")
# log all processes
logger.debug("thing_to_log", main_process_only=False)
# log all processes in order
logger.debug("thing_to_log", main_process_only=False, in_order=True)

أخطاء التعليق والتجاوز الزمني

قد يكون هناك أسباب عديدة لتعليق الكود الخاص بك. دعونا نلقي نظرة على كيفية حل بعض أكثر المشكلات شيوعًا التي قد تسبب تعليق الكود.

أشكال متجهات غير متطابقة

عدم تطابق أشكال المصفوفات (Tensor) مشكلة شائعة يمكن أن تُسبب تعليق الكود الخاص بك لفترة طويلة في الإعدادات الموزعة.

عند تشغيل السكربتات في إعداد موزّع، تكون دوال مثل Accelerator.gather() و Accelerator.reduce() ضرورية لجلب المتجهات (tensors) عبر الأجهزة لتنفيذ عمليات عليها بشكل جماعي. تعتمد هذه الدوال (وغيرها) على torch.distributed لتنفيذ عملية gather، والتي تتطلب أن تكون المتجهات ذات الشكل (shape) نفسه تمامًا عبر جميع العمليات. عندما لا تتطابق أشكال المتجهات، يتوقف كودك عن الاستجابة وستواجه في النهاية استثناءً لانتهاء المهلة (timeout exception).

يمكنك استخدام وضع التصحيح التشغيلي في Accelerate للالتقاط هذه المشكلة فورًا. ننصح بتمكين هذا الوضع أثناء إعداد accelerate config، لكن يمكنك أيضًا تمكينه من سطر الأوامر، أو كمتغير بيئة، أو عن طريق تحرير ملف config.yaml يدويًا.

accelerate launch --debug {my_script.py} --arg1 --arg2

ACCELERATE_DEBUG_MODE="1" torchrun {my_script.py} --arg1 --arg2

compute_environment: LOCAL_MACHINE
debug: true

بمجرد تفعيل وضع التصحيح، يجب أن تحصل على أثر استدعاء (traceback) يشير إلى مشكلة عدم تطابق شكل المصفوفة (tensor).

Traceback (most recent call last):
  File "/home/zach_mueller_huggingface_co/test.py", line 18, in <module>
    main()
  File "/home/zach_mueller_huggingface_co/test.py", line 15, in main
    broadcast_tensor = broadcast(tensor)
  File "/home/zach_mueller_huggingface_co/accelerate/src/accelerate/utils/operations.py", line 303, in wrapper
accelerate.utils.operations.DistributedOperationException:

Cannot apply desired operation due to shape mismatches. All shapes across devices must be valid.

Operation: `accelerate.utils.operations.broadcast`
Input shapes:
  - Process 0: [1, 5]
  - Process 1: [1, 2, 5]

الإيقاف المبكر

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

إذا كان لديك شروط لإيقاف مبكر، فاستخدم طريقتي set_trigger وcheck_trigger للتأكد من إنهاء جميع العمليات بشكل صحيح.

# Assume `should_do_breakpoint` is a custom-defined function that returns a conditional, 
# and that conditional might be true only on process 1
if should_do_breakpoint(loss):
    accelerator.set_trigger()

# Later in the training script when we need to check for the breakpoint
if accelerator.check_trigger():
    break

إصدارات منخفضة من النواة في لينكس

على نظام لينكس بإصدار نواة < 5.5، تم الإبلاغ عن عمليات متعثرة. لتجنب هذه المشكلة، قم بترقية نظامك إلى إصدار أحدث من النواة.

MPI

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

في الخطوة التالية، جرّب تنفيذ أمر mpirun كاختبار صحة. على سبيل المثال، يجب أن يطبع الأمر أدناه أسماء مضيفات كل عقدة.

mpirun -f hostfile -n {number of nodes} -ppn 1 hostname

نفاد الذاكرة

One of the most frustrating errors when it comes to running training scripts is hitting “Out-of-Memory” on devices like CUDA, XPU or CPU. The entire script needs to be restarted and any progress is lost.

لمعالجة هذه المشكلة، يوفر Accelerate أداة find_executable_batch_size() التي تعتمد بشكل كبير على toma. تعيد هذه الأداة تشغيل الكود الذي يفشل بسبب حالات نفاد الذاكرة (OOM) وتخفض أحجام الدفعات تلقائياً. ففي كل حالة نفاد للذاكرة، يقلل الخوارزمية حجم الدفعة إلى النصف ويعيد تشغيل الكود حتى ينجح.

لاستخدام find_executable_batch_size()، أعد هيكلة دالة التدريب الخاصة بك لتشمل دالة داخلية تحتوي على find_executable_batch_size، وأنشئ مُحمِّلات البيانات (dataloaders) داخلها. وبحدٍّ أدنى، يتطلب هذا الأمر إضافة 4 أسطر جديدة فقط من الكود.

يجب أن يستقبل الدالة الداخلية حجم الدفعة كعامل أول، لكننا لا نمرره إليها عند استدعائها. سيتولى الغلاف معالجة ذلك نيابةً عنك. أي كائن (نماذج، محسّنات) يستهلك ذاكرة الجهاز ويُمرَّر إلى Accelerator يجب أن يُعلن داخل الدالة الداخلية.

def training_function(args):
    accelerator = Accelerator()

+   @find_executable_batch_size(starting_batch_size=args.batch_size)
+   def inner_training_loop(batch_size):
+       nonlocal accelerator # Ensure they can be used in our context
+       accelerator.free_memory() # Free all lingering references
        model = get_model()
        model.to(accelerator.device)
        optimizer = get_optimizer()
        train_dataloader, eval_dataloader = get_dataloaders(accelerator, batch_size)
        lr_scheduler = get_scheduler(
            optimizer, 
            num_training_steps=len(train_dataloader)*num_epochs
        )
        model, optimizer, train_dataloader, eval_dataloader, lr_scheduler = accelerator.prepare(
            model, optimizer, train_dataloader, eval_dataloader, lr_scheduler
        )
        train(model, optimizer, train_dataloader, lr_scheduler)
        validate(model, eval_dataloader)
+   inner_training_loop()

نتائج غير قابلة للتكرار بين إعدادات الأجهزة

إذا قمت بتغيير إعداد الجهاز وتلاحظ أداءً مختلفًا للنموذج، فمن المرجح أنك لم تحدّث سكربتك عند الانتقال من إعداد إلى آخر. حتى لو كنت تستخدم نفس السكربت مع نفس حجم الدفعة، فإن النتائج ستظل مختلفة على TPU، وعلى عدة وحدات GPU، وعلى وحدة GPU واحدة.

على سبيل المثال، إذا كنت تدرب على وحدة معالجة رسومية واحدة بحجم دفعة 16 ثم انتقلت إلى إعداد يتضمن وحدتي معالجة رسومية، فستحتاج إلى تغيير حجم الدفعة إلى 8 للحصول على حجم دفعة فعال متساوٍ. والسبب في ذلك هو أنه عند التدريب باستخدام Accelerate، يكون حجم الدفعة المُمرَّر إلى مُحمِّل البيانات هو حجم الدفعة لكل وحدة معالجة رسومية.

لضمان إمكانية إعادة إنتاج النتائج بين الإعدادات المختلفة، تأكد من استخدام البذرة (seed) نفسها، وضبط حجم الدفعة (batch size) وفقاً لذلك، مع مراعاة مقياس معدل التعلم (learning rate).

لمزيد من التفاصيل ومرجع سريع لحجم الدفعة، راجع دليل مقارنة الأداء بين تكوينات الأجهزة المختلفة.

مشاكل الأداء على وحدات معالجة الرسوميات المختلفة

إذا كانت بيئة العمل متعددة وحدات معالجة الرسوميات لديك تتكون من وحدات معالجة رسوميات مختلفة، فقد تواجه بعض مشاكل الأداء:

• قد يوجد اختلال في ذاكرة وحدة معالجة الرسوميات بين وحدات المعالجة. في هذه الحالة، ستحدد وحدة المعالجة ذات الذاكرة الأصغر حجم الدفعة أو حجم النموذج الذي يمكن تحميله على وحدات المعالجة.
• إذا كنت تستخدم وحدات معالجة رسومية (GPUs) بمواصفات أداء مختلفة، فإن الأداء العام سيُحدده أبطأ وحدة معالجة رسومية تستخدمها، لأن الوحدات الأخرى ستضطر إلى الانتظار حتى تُنهي عملها.

يمكن أن تؤدي بطاقات الرسوميات المختلفة بشكل كبير ضمن نفس الإعداد إلى اختناقات في الأداء.

اطلب المساعدة

إذا لم تساعدك أي من الحلول والنصائح الواردة هنا في حل مشكلتك، يمكنك دائمًا التواصل مع المجتمع وفريق Accelerate للحصول على المساعدة.

• اطلب المساعدة في منتديات Hugging Face من خلال نشر سؤالك في فئة Accelerate. تأكد من كتابة منشور وصفي يتضمن سياقًا ذا صلة بإعدادك ورمزًا قابلًا لإعادة الإنتاج لتعظيم احتمالية حل مشكلتك!

• انشر سؤالك على Discord ودع الفريق والمجتمع يساعدانك.

• أنشئ مشكلة (Issue) في مستودع GitHub الخاص بـ Accelerate إذا كنت تعتقد أنك اكتشفت خطأً برمجيًا يتعلق بالمكتبة. تضمّن سياقًا حول الخطأ وتفاصيل عن إعدادك الموزّع لمساعدتنا على فهم المشكلة بشكل أفضل وكيفية إصلاحها.