سناریوی رخداد

سهم موتور 0.02 و مسیر پیش‌روی شبیه‌سازی‌شده‌ای که شش برابر کندتر شد

An engine share of 0.02 and a rollout six times slower

  • سطح ۲: میانی
  • سناریوی رخداد
  • ۲۰ دقیقه

وضعیت

تیمی مشغول آموزش مدلی با الگوریتم GRPO روی یک پردازنده‌ی گرافیکی GB10 است. هفته‌ی قبل، فرایند آموزش مدل بزرگ‌تری به دلیل خطای کمبود حافظه (Memory Kill) متوقف شد؛ از همان زمان، تیم از پر شدن حافظه‌ی کل نود واهمه دارد. یکی از اعضا برای اجراهای بعدی، سهم حافظه‌ی موتور را با فلگ --sglang-mem-fraction-static روی 0.02 تنظیم می‌کند تا بیشترین فضای ممکن برای بخش آموزش (Trainer) باقی بماند. مقدار پیش‌فرض لانچر 0.4 است.

صبح روز بعد، یک اجرای آزمایشی تک‌مرحله‌ای (One-step check) تمام می‌شود و پاداش (Reward) هم در محدوده‌ی معمول قرار دارد. اما این مرحله بسیار طولانی‌تر از روز قبل زمان برده است. هیچ‌کس خطایی در لاگ‌ها ندیده است. یکی از مهندسان محافظ حرارتی پردازنده را مقصر می‌داند، دیگری کندی دیسک را مطرح می‌کند، و سومی می‌گوید موتور احتمالاً به ناچار سراغ یک کرنل (Kernel) کند رفته است. لاگ این اجرای آزمایشی، لاگ همین بررسی با مقدار 0.25، و لاگ یک اجرای عادی با مقدار 0.4 در اختیارتان قرار می‌گیرد.

نسخه
Miles main 08752a12 with its own SGLang 0.5.22 build
مدل
Qwen/Qwen3-0.6B
سخت‌افزار
one GB10 with 128 GB of unified memory

شواهد

default-run-settings.txt
title: the default run settings of the manual
source: manuals/miles-101/sections/r-3-lab-notes.md
lines: 23-33
lang: text
note: Read the prompts per step, the answers per prompt and the answer limit, then the engine memory fraction.
---
| Setting | Value |
|---|---|
| Prompts per step | 32 (`--rollout-batch-size`) |
| Answers per prompt | 8 (`--n-samples-per-prompt`) |
| Samples per optimizer step | 256 (`--global-batch-size`) |
| Answer limit | 1,024 tokens |
| Temperature | 1 |
| Learning rate | 1e-6, constant |
| Trainer | FSDP on one GPU, colocated with the engine |
| Engine memory fraction | 0.4 |
| Weight update bucket | 536870912 bytes, 512 MiB |
engine-pool-line.txt
title: the KV cache line of the slow run at startup
source: manuals/miles-101/capture/gpu/out-gb10/frac-low-kv.txt
lines: 6-6
lang: text
note: The pool line that the engine prints before the first step.
---
frac-low engine line: KV Cache is allocated. dtype: torch.bfloat16, #tokens: 3082, K size: 0.16 GB, V size: 0.16 GB
how-the-split-works.txt
title: how the engine turns the fraction into a pool
source: manuals/sglang-101/sections/3-2-mem-fraction-static-and-startup-sizing.md
lines: 55-59
lang: text
note: The fraction covers the weights and the KV pool together, and the pool gets what is left after the weights load.
---
**--mem-fraction-static:** the share of memory that SGLang gives to the model weights plus the KV pool. Everything outside that share is for activations, CUDA graphs, and other programs. The flag defaults to `None`, and SGLang computes a value at startup {{code}}.

On a GPU, the automatic value comes from a reserve. SGLang starts with 512 MB and adds 1.5 MB for each token of the prefill chunk {{code}}. Then it adds more for tensor and pipeline parallelism and for CUDA graphs. On a GPU with more than 60 GB, the reserve is at least 10 GiB. The fraction is then the GPU memory minus the reserve, divided by the GPU memory. When SGLang cannot read the device capacity, it uses 0.95.

After the weights load, SGLang measures free memory again. The KV budget is the free memory minus the `1 - fraction` share of the memory that was free before loading {{code}}. The pool holds that budget divided by the bytes per token from [section 3.1](#s-kv-bytes-per-token-and-the-kv-pool). If the budget is not positive, startup stops and prints the smallest fraction that would work.
manual-entry.txt
title: the troubleshooting entry for the engine memory fraction
source: manuals/miles-101/sections/7-1-troubleshoot-by-symptom.md
lines: 59-63
lang: text
note: Read the Check line for the case of a fraction that is too low.
---
## The engine runs out of memory at start

- **Cause:** `--sglang-mem-fraction-static` does not fit the GPU. With `--colocate`, the trainer can already hold GPU memory when the engine starts. A fraction that is too high leaves no room for activations and CUDA graphs. A fraction that is too low leaves no room for the KV cache.
- **Check:** a CUDA out-of-memory error in the engine lines during startup or on the first batch, and no `Ray OutOfMemoryError`. A fraction that is too low does not always stop the engine. Read `#tokens` in the `KV Cache is allocated` line. In our check at 0.02, the engine started with 3,082 tokens, and the first rollout took 386 s against 61 s at 0.25.
- **Fix:** lower the fraction for the first case, or raise it for the second, by 0.05 or 0.1 at a time. The Miles documentation asks for 0.8 or lower with `--colocate`. Our runs used 0.4. [SGLang 101, section 3.2](https://aiengineeringfromscratch.com/manual-sglang-101.html#s-mem-fraction-static-and-startup-sizing) explains how the engine divides its memory.
three-runs.txt
title: the pool size, the rollout time and the reward of three runs
source: manuals/miles-101/capture/gpu/out-gb10/frac-low-kv.txt
lines: 3-5
lang: text
note: Read the rollout time of the first row against the other two, then the pool size in tokens.
---
frac-low: max_total_num_tokens=3082 perf/rollout_time': 385.5003604888916 rollout/raw_reward': 0.61328125 steps=1
frac-check: max_total_num_tokens=211813 perf/rollout_time': 60.696292877197266 rollout/raw_reward': 0.66015625 steps=1
plain: max_total_num_tokens=347841 perf/rollout_time': 63.839099407196045 rollout/raw_reward': 0.625 steps=12
what-each-run-set.txt
title: the one flag that differed between the runs
source: manuals/miles-101/capture/gpu/out-gb10/frac-low-kv.txt
lines: 1-2
lang: text
note: The second line gives the fraction of each run.
---
# Live check 2026-10-23, Qwen3-0.6B, 1 step, launcher defaults plus one flag.
# frac-low: --sglang-mem-fraction-static 0.02. frac-check: 0.25. plain: launcher default 0.4.

سؤال‌ها

  1. سه زمان مسیر پیش‌روی شبیه‌سازی‌شده (Rollout) و سه اندازه‌ی استخر حافظه داریم. کدام عدد همگام با زمان تغییر کرد و کدام تغییر نکرد؟
  2. پاداش اجرای کند کاملاً عادی است. چرا این موضوع سلامت اجرا را تأیید نمی‌کند؟
  3. خط مربوط به کش کلید-مقدار (KV cache) پیش از اولین گام چاپ می‌شود. کجای این خط نشان می‌دهد که گام کند پیش خواهد رفت، و GPU چقدر کند کار می‌کند؟
  4. تعداد توالی‌هایی را که یک گام باید تولید کند و طول بلندترین پاسخ را بشمارید. استخری با این اندازه چه مقدار داده را می‌تواند هم‌زمان در خود نگه دارد؟
  5. سهم حافظه را در کدام جهت تغییر می‌دهید، در هر تلاش چقدر به آن اضافه یا کم می‌کنید، و بعد از هر تلاش چه مقداری را می‌خوانید؟
  6. حافظه‌ی موتور پر نشد و برنامه کرش نکرد. چرا تشخیص کم بودن بیش‌ازحد این فلگ دشوارتر از زیاد بودن آن است؟

اول شواهد را بخوانید و به سؤال‌ها جواب بدهید، بعد راه‌حل را باز کنید.

راه‌حل گام‌به‌گام
  1. سه اجرا را کنار هم بگذارید. مقدار perf/rollout_time را در هر خط بخوانید. اجرای با سهم حافظه‌ی پایین، برای یک مسیر پیش‌روی شبیه‌سازی‌شده 386 ثانیه زمان برد. اجرا با مقدار 0.25 حدود 61 ثانیه طول کشید و اجرای عادی با مقدار 0.4 نیز حدود یک دقیقه زمان برد. پاداش‌ها به ترتیب 0.61328125، 0.66015625 و 0.625 بودند. پاداش هیچ تغییری متناسب با این تنظیمات نشان نداد؛ اما زمان اجرا دقیقاً تغییر کرد و حدود شش برابر شد.
  2. اندازه‌ی استخر حافظه را در همان خطوط بخوانید. در اجرای کند، مقدار max_total_num_tokens=3082 ثبت شده است. دو اجرای دیگر به ترتیب 211,813 و 347,841 توکن داشتند. استخر (Pool) در واقع تعداد توکن‌هایی است که موتور می‌تواند هم‌زمان در کش کلید-مقدار خود نگه دارد. زمان مسیر پیش‌روی شبیه‌سازی‌شده دقیقاً همگام با اندازه‌ی این استخر جابه‌جا شد و هیچ تفاوت دیگری میان این سه خط دیده نمی‌شد.
  3. خطی را بخوانید که موتور در همان ابتدا چاپ کرده است. هنگام بالا آمدن، موتور کند عبارت KV Cache is allocated را با 3082 توکن و اندازه‌ی K و V هرکدام معادل 0.16 گیگابایت چاپ کرد. این خط قبل از اجرای هرگونه گامی ظاهر می‌شود. کسی که مقدار معمول این پارامتر را برای این دستگاه بداند، دقایقی پیش از پایان اولین گام کند، متوجه مشکل می‌شود.
  4. میزان کارِ یک گام را محاسبه کنید. مقادیر پیش‌فرض راهنما شامل 32 پرامپت (Prompt) در هر گام، 8 پاسخ به ازای هر پرامپت و سقف 1,024 توکن برای هر پاسخ است. یک گام در مجموع 256 پاسخ تولید می‌کند. استخری با ظرفیت 3082 توکن، هم‌زمان فقط گنجایش سه پاسخ با حداکثر طول مجاز را دارد؛ اگر پرامپت‌های آن‌ها را هم حساب کنیم، حتی کمتر از این مقدار جا می‌شود. بنابراین موتور ناچار است کل این مرحله را در قالب رشته‌ای طولانی از دسته‌های (Batch) بسیار کوچک اجرا کند. چیزی خراب نشده است؛ GPU در واقع حین انتظار برای باز شدن فضا، تقریباً بیکار می‌ماند.
  5. تأثیر فلگ بر استخر را دنبال کنید. این سهم در واقع حافظه‌ی مورد نیاز برای وزن‌های مدل به همراه استخر کش کلید-مقدار را با هم مشخص می‌کند. پس از بارگذاری وزن‌ها، موتور دوباره حافظه‌ی آزاد را اندازه می‌گیرد و آنچه را از این سهم باقی مانده باشد، به استخر اختصاص می‌دهد. وقتی سهم حافظه 0.02 تعیین شود، حتی در یک مدل کوچک، وزن‌ها بخش اعظم این سهم را می‌بلعند و جز باقی‌مانده‌ای ناچیز چیزی به استخر نمی‌رسد.
  6. از راهنمای سیستم استفاده کنید. صفحه‌ی عیب‌یابی هر دو حالت خطای این فلگ را فهرست کرده است: اگر سهم حافظه خیلی بالا باشد، فضایی برای محاسبات میانی (Activations) و گراف‌های CUDA باقی نمی‌ماند و در نتیجه CUDA اعلام کمبود حافظه می‌کند. اما اگر این سهم خیلی کم باشد، موتور لزوماً متوقف نمی‌شود؛ راهکار بررسی این است که مقدار #tokens در خط لاگ کش کلید-مقدار خوانده شود. راه‌حل در حالت دوم، افزایش گام‌به‌گام سهم با پله‌های 0.05 یا 0.1 است.
نتیجه

تنظیم سهم موتور روی 0.02، تنها استخری با ظرفیت 3082 توکن باقی گذاشت؛ به همین خاطر، مسیر پیش‌روی شبیه‌سازی‌شده برای یک گام 386 ثانیه طول کشید، در حالی که این زمان با سهم 0.25 حدود 61 ثانیه و با مقدار پیش‌فرض 0.4 تقریباً یک دقیقه بود. مقدار پاداش در محدوده‌ی طبیعی ماند، چون مدل دقیقاً همان کار را انجام می‌داد، منتها در دورهایی بسیار بیشتر. راه‌حل این است که سهم حافظه را به 0.4 برگردانید، یا در صورتی که بخش آموزش واقعاً به فضای بیشتری نیاز دارد آن را روی 0.25 بگذارید؛ اما هیچ‌گاه نباید آن را به حدی کاهش داد که استخر نتواند یک گام کامل را در خود جای دهد.

معیار قطعی اثبات این مسئله، دو مقداری هستند که یکی هنگام بالا آمدن و دیگری بعد از پایان اولین گام ثبت می‌شوند: تعداد توکن‌ها (#tokens) در خط کش کلید-مقدار، و پارامتر perf/rollout_time. با سهم 0.25، استخر گنجایش 211,813 توکن داشت و مسیر پیش‌روی شبیه‌سازی‌شده ظرف 61 ثانیه به پایان رسید. در هر تنظیم جدید برای این فلگ، این دو مقدار را ثبت کنید و سهم را در بازه‌های 0.05 یا 0.1 تغییر دهید. خطای کمبود حافظه‌ی هفته‌ی قبل ناشی از بخش آموزش بود و همان‌طور که حادثه‌ی مربوط به Ray نشان داد، کوچک کردن سهم موتور مانع از وقوع آن نمی‌شد.

مسیرهای اشتباه رایج
  • «پاداش مشکلی ندارد، پس کل اجرا خوب است.» پاداش نشان می‌دهد مدل چه چیزی یاد گرفته است، نه اینکه آن گام چقدر هزینه برداشته است. وقتی زمان مسیر پیش‌روی شبیه‌سازی‌شده شش برابر شود، همان میزان آموزش به شش برابر ساعت استفاده از GPU نیاز خواهد داشت.
  • «محافظ حرارتی سیستم اجرا را متوقف کرده است.» توقف حرارتی زمان واقعی (Wall-clock) را به یک گام اضافه می‌کند، اما ظرفیت 3082 توکنی استخر به تنهایی و بدون نیاز به فرض هیچ مکثی، این زمان را توضیح می‌دهد؛ به‌ویژه که اجرای دیگر با سهم 0.25 در همان روز 61 ثانیه طول کشید.
  • «سقف درخواست‌های هم‌زمان (Running Requests) را بالا ببرید.» موتور تنها تا زمانی درخواست‌های جدید را می‌پذیرد که استخر برای توکن‌های آن‌ها جا داشته باشد. با 3082 توکن، این ظرفیت استخر است که اندازه‌ی دسته را تعیین می‌کند، نه سقف تعداد درخواست‌ها.
  • «سهم را از این هم کمتر کنید، اصل کاری بخش آموزش است.» هفته‌ی قبل فرایند آموزش هم با سهم 0.4 و هم با سهم 0.2 متوقف شد، بنابراین سهم حافظه در آنجا علت اصلی نبود. با تنظیم مقدار کمتر از 0.25، بخش آموزش فضای ناچیزی به دست می‌آورد، اما در عوض کارایی مسیر پیش‌روی شبیه‌سازی‌شده به‌شدت افت می‌کند.
درس کلی

یک تنظیم می‌تواند از هر دو طرف دچار خطا شود و نشانه‌های این دو خطا کاملاً با هم فرق دارند. اختصاص حافظه‌ی بیش‌ازحد به یک بخش باعث کرش کردن آن می‌شود که همه متوجهش می‌شوند؛ اما اختصاص حافظه‌ی ناکافی فقط سیستم را کند می‌کند، و معمولاً تا زمان صدور صورت‌حساب پردازش ابری هیچ‌کس متوجه آن نخواهد شد. مقدار معمول لاگِ تعیین اندازه‌ای را که هر مؤلفه در ابتدای راه‌اندازی چاپ می‌کند بشناسید، آن را پیش از اجرای اولین گام بخوانید، و وقتی سهمی را تغییر می‌دهید، این کار را در پله‌های کوچک انجام دهید و اندازه و زمان حاصل از آن را هم‌زمان ثبت کنید.

کجای دوره آموزش داده می‌شود

راهنمای Miles در جدول نشانه‌های خرابی هر دو حالت خطای سهم موتور را شرح می‌دهد، در صفحه‌ی مربوط به Ray نشان می‌دهد که کم کردن سهم کمکی به نجات بخش آموزش نکرد، در یادداشت‌های آزمایشگاه مقادیر پیش‌فرض اجرا را ارائه می‌دهد، و راهنمای SGLang در صفحه‌ی تخصیص حافظه چگونگی تبدیل این سهم به استخر را توضیح می‌دهد.