بخش 7.1 · اشکال‌زدایی

عیب‌یابی بر اساس نشانه‌ها

Troubleshoot by symptom

فهرست مطالب
  1. کارت گرافیک بی‌کار است و لاگ مدام رشد می‌کند
  2. اجرا پس از خطای ایمپورت پاداش متوقف می‌شود
  3. موتور در همان ابتدا با خطای FlashAttention 3 متوقف می‌شود
  4. جاب با خطای OutOfMemoryError در Ray متوقف می‌شود
  5. ترِینر پیاده‌سازی اتنشن را رد می‌کند
  6. زمان اجرای هر گام از یک اجرا تا اجرای دیگر تغییر می‌کند
  7. شکاف در گام 0 بسیار فراتر از محدوده‌ی مورد انتظار شماست
  8. موتور در همان ابتدای کار دچار کمبود حافظه می‌شود
  9. تابع پاداشی با مقادیر اعشاری، گروهی را جابه‌جا می‌کند که باید بدون تغییر بماند
  10. آموزش پس از تخلیه‌ی حافظه روی FSDP دچار مشکل می‌شود
  11. به‌روزرسانی وزن‌ها روی چند GPU ناموفق است
  12. پیش‌روی شبیه‌سازی‌شده با صدها درخواستِ باز کُند می‌شود
  13. لانچر کلاستر Ray اختصاصی شما را متوقف می‌کند

از چیزی که با چشم می‌بینید شروع کنید؛ در هر مدخل، علت احتمالی، نحوه‌ی بررسی و راهکار رفع مشکل آمده است.

شش مورد اول مشکلاتی هستند که روی یک GB10 با آن‌ها روبه‌رو شدیم: پنج نشانه از اجراهای ناموفق و یک اثر زمانی ناشی از حرارت. مورد هفتم از اجراهای سالم ما به‌عنوان مرجع استفاده می‌کند. مورد هشتم از سورس‌کد و مستندات Miles و SGLang گرفته شده است. بقیه‌ی موارد برگرفته از گزارش‌های ثبت‌شده در بخش پیگیری مسائل (issue tracker) پروژه Miles هستند؛ ما مورد هشتم و بقیه‌ی موارد را بازتولید نکرده‌ایم.

وقتی این بخش را تمام کنید، می‌توانید علت یک اجرای ناموفق یا نادرست را از روی اولین نشانه‌اش پیدا کنید.

از آنچه می‌بینید شروع کنیدهر یک از این پنج نشانه، یک بررسی اولیه و یک راه‌حل دارند.
از آنچه می‌بینید شروع کنید پنج نشانه از اجراهای ما، هرکدام همراه با نخستین بررسی و راه‌حل. بیکار ماندن GPU همراه با رشد مداوم لاگ به‌معنای متوقف شدن موتور است. خطای FlashAttention 3 به این معنی است که معماری GPU از نوع Hopper نیست، زیرا بیلد FA3 در این ایمیج تنها برای Hopper آماده شده است. خطای کمبود حافظه در Ray نشان‌دهنده پر شدن حافظه نود است. تفاوت زمان گام‌ها به‌دلیل توقف‌های ناشی از دمای بالا است. رد شدن نام اتنشن در ترینر نیز به‌معنای عدم پذیرش آن نام توسط کتابخانه نصب‌شده‌ی transformers است. نشانه بررسی اول FIX GPU بیکار، لاگ افزایشی شمارش خطوط 503 خواندن اولین خطا خطای FlashAttention 3 توان پردازشی GPU عدم پشتیبانی FA3 خطای کمبود حافظه Ray حافظه هنگام توقف استفاده از مدل کوچک‌تر تفاوت زمان مراحل افت بر اثر حرارت مقایسه گام‌های عادی رد شدن نام اتنشن فهرست ValueError انتخاب نام مجاز بخش 7.1 تمام نشانه‌های رخ‌داده و شش مورد دیگر از گزارش‌ها را دارد.
پنج مورد از نشانه‌های مشاهده‌شده در اجراهای ما. موارد زیر همچنین اجرای متوقف‌شده به‌دلیل فقدان ماژول پاداش را پوشش می‌دهند. آن‌ها مقایسه‌ای با اجراهای سالم، یک مورد از مستندات، و پنج مورد از گزارش اشکالات را نیز اضافه می‌کنند.

کارت گرافیک بی‌کار است و لاگ مدام رشد می‌کند

  • علت: موتور مسیر پیش‌روی شبیه‌سازی‌شده (rollout) از کار افتاده و ترِینر همچنان برایش درخواست می‌فرستد.
  • بررسی: تعداد خطاهای 503 Service Unavailable را در تک‌تک دقایق آخر لاگ بشمارید. در اجرای ناموفق ما، در هر دقیقه‌ی کامل به‌مدت یک ساعت بیش از 2600 خطا ثبت شده بود. در یک اجرای سالم با 16 پاسخ به‌ازای هر پرامپت (prompt)، رگبارهای کوتاهی تا حداکثر یک دقیقه خطا ثبت شد و پس از آن هیچ خطایی نیامد.
  • راهکار: اجرا را متوقف کنید، سپس خطوط مربوط به موتور را درست قبل از اولین خطای 503 بخوانید. هر اجرای بدون نظارتی را حتماً با دیده‌بان (watchdog) معرفی‌شده در بخش 1.2 شروع کنید.

اجرا پس از خطای ایمپورت پاداش متوقف می‌شود

  • علت: Miles نمی‌تواند ماژولی را که با --custom-rm-path مشخص شده ایمپورت کند؛ معمولاً به این دلیل که PYTHONPATH به پوشه‌ی آزمایش نمی‌رسد.
  • بررسی: در لاگ دنبال خطای ModuleNotFoundError با نام ماژول پاداش خود بگردید. بعد از آن هیچ خطی شامل rollout 0 ثبت نشده است.
  • راهکار: اجرا به‌خودی‌خود متوقف نمی‌شود و دیده‌بان هم جلوی آن را نمی‌گیرد، چون موتور فقط چند خطای 503 ثبت می‌کند. در آزمایش ما این جاب دو ساعت فعال ماند. کانتینر را متوقف کنید، PYTHONPATH را طبق بخش 3.5 اصلاح کنید و اجرا را دوباره راه بیندازید.

موتور در همان ابتدا با خطای FlashAttention 3 متوقف می‌شود

  • علت: اجرا تقاضای FlashAttention 3 داشته است (معمولاً از طریق حالت هم‌سیاست (on-policy) واقعی)، آن هم روی پردازنده‌ی گرافیکی خارج از محدوده‌ی پشتیبانی آن.
  • بررسی: در لاگ موتور دنبال پیام FlashAttention v3 Backend requires SM>=80 and SM<=90 بگردید.
  • راهکار: روی پردازنده‌های گرافیکی غیر از معماری Hopper، حالت هم‌سیاست واقعی را غیرفعال کنید و از بک‌اند پیش‌فرض بهره ببرید. در بخش 4.6 این محدودیت توضیح داده شده است.

جاب با خطای OutOfMemoryError در Ray متوقف می‌شود

  • علت: در حافظه‌ی یکپارچه (Unified Memory)، ابزار Ray برای کل نود فقط یک میزان حافظه را می‌خواند و ظرفیت نود تقریباً پر است. Ray هر ورکر فراتر از آستانه (threshold) را متوقف می‌کند.
  • بررسی: ثبت خط Memory on the node ... was 115.86GB / 121.69GB یا مشابه آن، بدون هیچ خطای کمبود حافظه‌ی CUDA.
  • راهکار: از مدل کوچک‌تر یا حجم کار کمتر در هر گام استفاده کنید و آستانه‌ی Ray را روی همان مقدار پیش‌فرض بگذارید. در اجرای مدل 4B ما، پایین آوردن سهم حافظه‌ی موتور کمکی نکرد. جزئیات بیشتر در بخش 2.3 آمده است.

ترِینر پیاده‌سازی اتنشن را رد می‌کند

  • علت: نام پیاده‌سازی اتنشن (attention) در ترِینر برای نسخه‌ی نصب‌شده‌ی کتابخانه‌ی transformers ناشناخته است؛ مانند triton.
  • بررسی: ثبت خطای ValueError که فهرست پیاده‌سازی‌های مورد قبول transformers را نمایش می‌دهد.
  • راهکار: یکی از گزینه‌های همان فهرست را انتخاب کنید. ما روی GB10 تنظیمات ترِینر را روی حالت پیش‌فرض گذاشتیم.

زمان اجرای هر گام از یک اجرا تا اجرای دیگر تغییر می‌کند

  • علت: مکث‌های حرارتی یا کاهش فرکانس کلاک روی GPU داغ. انتظار داریم خروجی نمونه‌ها و پاداش‌ها ثابت بماند، اما این فرضیه را آزمایش نکرده‌ایم.
  • بررسی: لاگ مکث‌های محافظ حرارتی از بخش 1.2 و کلاک GPU را حین اجرا بررسی کنید.
  • راهکار: فقط گام‌های بدون وقفه را زمان‌گیری کنید و مقایسه‌ی زمان‌ها را تنها در یک نشست (session) انجام دهید. قاعده‌ی آن در بخش 5.3 آمده است.

شکاف در گام 0 بسیار فراتر از محدوده‌ی مورد انتظار شماست

  • علت: موتور و ترِینر کار را با وزن‌های یکسان شروع نمی‌کنند، یا وزن‌های یکسان را با فرمت‌های متفاوتی می‌خوانند.
  • بررسی: مقدار train/train_rollout_logprob_abs_diff را در گام 0 با اجراهای سالم خود مقایسه کنید. مقادیر ما برای Qwen3-0.6B بین 0.0148 تا 0.0157 بود.
  • راهکار: پیش از آنکه مدل بر پایه‌ی اعداد غلط آموزش ببیند، اجرا را متوقف کنید. مسیرهای چک‌پوینت (checkpoint) را در هر دو سمت بازبینی کنید.

موتور در همان ابتدای کار دچار کمبود حافظه می‌شود

  • علت: مقدار --sglang-mem-fraction-static متناسب با حافظه‌ی GPU نیست. با فعال بودن --colocate، ممکن است ترِینر در لحظه‌ی شروع موتور از قبل بخشی از حافظه‌ی GPU را اشغال کرده باشد. نسبت بیش از حد بالا جایی برای اکتیویشن‌ها و نمودارهای CUDA باقی نمی‌گذارد؛ نسبت بیش از حد پایین هم فضایی برای کش کلید-مقدار (KV cache) خالی نمی‌گذارد.
  • بررسی: خطای کمبود حافظه‌ی CUDA در خطوط مربوط به موتور حین راه‌اندازی یا روی اولین دسته (batch)، بدون ثبت خطای Ray OutOfMemoryError. کسر خیلی پایین همیشه باعث توقف موتور نمی‌شود. مقدار #tokens را در خط KV Cache is allocated بخوانید. در بررسی ما با مقدار 0.02، موتور با 3082 توکن (token) بالا آمد و اولین مسیر پیش‌روی شبیه‌سازی‌شده به‌جای 61 ثانیه (در حالت 0.25)، حدود 386 ثانیه طول کشید.
  • راهکار: در حالت اول این کسر را کم، و در حالت دوم آن را زیاد کنید؛ هر بار با گام‌های 0.05 یا 0.1. مستندات Miles پیشنهاد می‌کند در صورت استفاده از --colocate مقدار 0.8 یا کمتر را در نظر بگیرید. اجراهای ما از 0.4 استفاده کردند. بخش 3.2 راهنمای SGLang 101 توضیح می‌دهد که موتور چطور حافظه‌اش را تقسیم‌بندی می‌کند.

تابع پاداشی با مقادیر اعشاری، گروهی را جابه‌جا می‌کند که باید بدون تغییر بماند

  • علت: گزارشی در بخش پیگیری مسائل نشان می‌دهد گروهی متشکل از 16 پاسخ، که به هر کدام نمره‌ی 0.3 اختصاص داده شده بود، به‌دلیل خطای گرد کردن float32 مقادیر مزیت (advantage) کوچک و غیرصفر دریافت کرده‌اند. پاداش‌های دودویی 0 و 1 با این مشکل مواجه نمی‌شوند.
  • بررسی: گروهی که در آن همه‌ی پاسخ‌ها پاداش یکسانی گرفته‌اند اما مقادیر مزیت آن‌ها 0 نیست.
  • راهکار: از پاداش‌هایی استفاده کنید که در قالب float32 به‌طور دقیق ذخیره شوند، یا مزیت‌های چنین گروه‌هایی را خودتان کنترل کنید.

آموزش پس از تخلیه‌ی حافظه روی FSDP دچار مشکل می‌شود

  • علت: گزارشی در بخش پیگیری مسائل نشان می‌دهد که تخلیه‌ی وضعیت ترِینر با FSDP2 روی دو یا چند GPU می‌تواند شاردهای (shard) با اندازه‌ی نابرابر را خراب کند.
  • بررسی: مشاهده‌ی مقادیر نامعتبر، پرش در تابع زیان (loss) یا نُرم گرادیان (gradient norm)، یا خطای مهلت زمانی عمل اشتراکی (collective timeout) پس از نخستین تخلیه‌ی حافظه. این مسئله وقتی رخ می‌دهد که لایه‌های مدل به‌طور یکنواخت میان رتبه‌ها (rank) تقسیم نشده باشند.
  • راهکار: یک‌بار با آرگومان --no-offload-train اجرا و نتایج را مقایسه کنید. برای اعمال اصلاحیه‌ی کد، موضوع را در ایشوی مربوطه دنبال کنید.

به‌روزرسانی وزن‌ها روی چند GPU ناموفق است

  • علت: دو گزارش در سیستم پیگیری مسائل؛ اول اینکه یک به‌روزرسانی هم‌مکان با مراحل پایپ‌لاین (pipeline) در NCCL 2.29 و 2.30 با وجود پلاگین تیونر کرش می‌کرد که این نقص در NCCL 2.31 برطرف شد. دوم اینکه سروینگ قطعی (deterministic) روی دو GPU تعداد کانال‌های NCCL متفاوتی را در مقایسه با ترِینر تنظیم می‌کرد و درنتیجه انتقال با خطای عدم تطابق اندازه شکست می‌خورد.
  • بررسی: بروز خطای segmentation fault یا پیام Message truncated هنگام به‌روزرسانی وزن‌ها.
  • راهکار: برای حالت اول، NCCL را به نسخه‌ی 2.31 یا بالاتر ارتقا دهید. برای حالت دوم، تا زمان انتشار اصلاحیه، سروینگ قطعی را روی موتورهای مجهز به چند GPU غیرفعال کنید.

پیش‌روی شبیه‌سازی‌شده با صدها درخواستِ باز کُند می‌شود

  • علت: گزارشی در سیستم پیگیری مسائل نشان می‌دهد که بار پردازشی سمت کلاینت همگام با افزایش تعداد درخواست‌های باز بالا می‌رود؛ این مقدار با 256 درخواستِ باز برابر 4.8 ثانیه و با 1536 درخواست به 43.7 ثانیه رسید.
  • بررسی: افزایش مدت‌زمان rollout با سرعتی بیشتر از نرخ رشد تعداد نمونه‌ها.
  • راهکار: تعداد درخواست‌های باز به‌ازای هر موتور را کمتر نگه دارید، یا اصلاحات کلاینت را در ایشوی مربوطه دنبال کنید.

لانچر کلاستر Ray اختصاصی شما را متوقف می‌کند

  • علت: گزارشی در سیستم پیگیری مسائل نشان می‌دهد لانچرهای مربوط به شش نمونه‌ی ایجنت (agent)، هر فرایندی (process) را که عبارت sglang در خط فرمان آن باشد متوقف می‌کنند. اگر متغیر MILES_SCRIPT_EXTERNAL_RAY=1 تنظیم شده باشد، این کار کلاستر Ray خود شما را هم خاموش می‌کند.
  • بررسی: توقف سایر جاب‌های Ray شما هم‌زمان با پایان یافتن اجرای Miles.
  • راهکار: دستورات پاک‌سازی را از داخل آن لانچرها حذف کنید، یا تا زمان برطرف شدن مشکل، یک کلاستر Ray جداگانه به Miles اختصاص دهید.

منابع: مستندات بک‌اند آموزش Miles در برنچ main کامیِت 08752a12؛ کد تعیین اندازه‌ی حافظه در SGLang در نسخه‌ی ایمیج 0.5.22.dev46؛ فایل capture/gpu/out-gb10/engine-died-503.log؛ فایل capture/gpu/out-gb10/engine-died-count.txt؛ فایل capture/gpu/out-gb10/503-bursts.txt؛ فایل capture/gpu/out-gb10/ray-oom-4b.log؛ فایل capture/gpu/out-gb10/thermostat.log؛ فایل capture/gpu/summary/miles-gb10-lab.json؛ فایل manuals/sglang-101/capture/gpu/out-miles/true-on-policy-error.log؛ ایشوهای 3649، 3714، 4003، 4019، 4134 و 4238 در Miles؛ فایل capture/gpu/out-gb10/custom-rm-noenv-hang.txt (بررسی زنده، 2026-10-23)؛ فایل capture/gpu/out-gb10/frac-low-kv.txt (بررسی زنده، 2026-10-23).

ترجمه‌ی فارسی Troubleshoot by symptom از راهنمای Miles 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما