وضعیت
یک حامی توسعهدهندگان (Developer Advocate) در حال آمادهسازی دموی یک کارگاه روی لپتاپ خود است. سرور یک مدل کوانتیزهشدهی کوچک را روی بکاند MLX اجرا میکند؛ فرمانی که برای راهاندازی استفاده شده فقط مسیر مدل را دارد و هیچ تنظیمی برای حافظه در آن مشخص نشده است. درخواستهای تکی و همزمانی چند کاربر بدون مشکل پاسخ داده میشوند. برای نمایش توان پردازشی لپتاپ، او کلاینت بنچمارک را با 32 درخواست همزمان فعال اجرا میکند.
کل سرور از کار میافتد. انتهای لاگ خطای Metal با پیام Insufficient Memory دیده میشود و درخت فرایندها (process tree) بهکل ناپدید میشود. خطوط لاگ رمزگشایی (decode) درست قبل از کرش، 32 درخواست در حال اجرا را با نرخ مصرف توکن 0.05 نشان میدهند. او نتیجه میگیرد لپتاپ توانایی پاسخگویی به 32 کاربر را ندارد و تصمیم میگیرد دمو را با 4 کاربر همزمان نشان دهد.
- نسخه
- SGLang 0.5.22 with the MLX backend
- مدل
- mlx-community/Qwen3-0.6B-4bit
- سختافزار
- a laptop with unified memory, shared with the other programs of a desktop session
شواهد
how-to-read-the-crash.txt
title: how the manual reads the crash
source: manuals/sglang-101/sections/3-2-mem-fraction-static-and-startup-sizing.md
lines: 43-43
lang: text
note: Start with token usage.
---
Read `token usage: 0.05` first. Thirty-two requests held 16,095 tokens, which is 5 percent of a 312,581-token pool. The pool reserved 33 GB and used under 2 GB of it. The activations of the next forward pass needed memory outside the pool, and the operating system had none left. One failed command buffer took down the scheduler, and the server killed its whole process tree.
run-1-startup.txt
title: the pool line of the first start
source: manuals/sglang-101/capture/out/oom-exploratory.log
lines: 3-4
lang: text
note: Read sys_available, kv_budget and pool_size.
---
# run 1 startup
[2026-10-16 13:30:31] Auto-sized attention KV pool: sys_available=27.81 GB, mlx_limit=51.8 GB, mlx_used=0.31 GB, kv_budget=24.25 GB, bytes_per_slot=114688, pool_size=227022
run-2-startup.txt
title: the pool lines of the second start, minutes later
source: manuals/sglang-101/capture/out/oom-exploratory.log
lines: 5-10
lang: text
note: Compare sys_available and kv_budget with the first start, and read the resolved fraction.
---
# run 2 startup
'mem_fraction_static': 0.872
[2026-10-16 13:38:58] Auto-sized attention KV pool: sys_available=38.29 GB, mlx_limit=51.8 GB, mlx_used=0.31 GB, kv_budget=33.39 GB, bytes_per_slot=114688, pool_size=312581
[2026-10-16 13:38:58] MLX stub: initialized minimal pools (max_total_num_tokens=312581, max_running_requests=4096, zero GPU KV cache allocation)
[2026-10-16 13:39:00] max_total_num_tokens=312581, chunked_prefill_size=4096, max_prefill_tokens=16384, max_running_requests=4096, context_len=40960, available_gpu_mem=37.92 GB
[2026-10-16 13:39:02] MlxAttentionKVPool: 312582 slots x 28 layers x 8 heads x 128 dim, dtype=mlx.core.bfloat16, ~34188.7 MB
the-benchmark-that-finished.txt
title: the same benchmark against the kit's server
source: manuals/sglang-101/capture/out/bench-random-c32.txt
lines: 14-16
lang: text
note: Read the concurrency and the count of successful requests.
---
Max request concurrency: 32
Successful requests: 128
Benchmark duration (s): 64.83
the-crash.txt
title: the benchmark at a concurrency of 32, and the crash
source: manuals/sglang-101/capture/out/oom-exploratory.log
lines: 11-20
lang: text
note: Read token usage in the decode lines before you read the RuntimeError.
---
# run 2, benchmark at --max-concurrency 32
[2026-10-16 13:42:51] Decode batch, #running-req: 32, #token: 16095, token usage: 0.05, cuda graph: False, gen throughput (token/s): 579.49, #queue-req: 0
[2026-10-16 13:42:53] Decode batch, #running-req: 32, #token: 16095, token usage: 0.05, cuda graph: False, gen throughput (token/s): 564.55, #queue-req: 0
[2026-10-16 13:42:55] Prefill batch, #new-seq: 1, #new-token: 511, #cached-token: 0, token usage: 0.00, #running-req: 0, #queue-req: 9, #pending-token: 0, cuda graph: False, input throughput (token/s): 66.85
RuntimeError: [METAL] Command buffer execution failed: Insufficient Memory (00000008:kIOGPUCommandBufferCallbackErrorOutOfMemory).
[2026-10-16 13:42:57] SIGQUIT received. signum=None, frame=None. It usually means one child failed.
[2026-10-16 13:42:57] Sleeping 5 seconds before crash diagnostics to let GPU activity settle.
[2026-10-16 13:43:02] No live scheduler processes found; skipping py-spy and CUDA coredump.
[2026-10-16 13:43:02] kill_process_tree called: parent_pid=81559, include_parent=True, pid=81559
the-kit-start.txt
title: the pool line of the kit's server, with an explicit fraction
source: manuals/sglang-101/capture/out/server-default.log
lines: 61-61
lang: text
note: Divide kv_budget by sys_available.
---
[2026-10-16 13:58:03] Auto-sized attention KV pool: sys_available=48.49 GB, mlx_limit=51.8 GB, mlx_used=0.31 GB, kv_budget=19.39 GB, bytes_per_slot=114688, pool_size=181574
why-the-two-starts-differ.txt
title: why the two starts sized the pool differently
source: manuals/sglang-101/sections/3-2-mem-fraction-static-and-startup-sizing.md
lines: 26-26
lang: text
note: One paragraph from the manual.
---
Nothing changed in SGLang between the runs. Other programs on the Mac used less memory at the second start, so `sys_available` grew from 27.81 GB to 38.29 GB. The pool grew with it, from 24.25 GB to 33.39 GB. Both budgets are 87.2 percent of the free memory, because the automatic `mem_fraction_static` resolved to 0.872.
سؤالها
- استخر هنگام مرگ سرور تقریباً خالی بود. حافظه اگر در استخر نبود، کجا رفته بود؟
- دو بار اجرای یک فرمان یکسان، دو اندازهی استخر متفاوت به بار آورد. در این فاصله چه چیزی تغییر کرده بود؟
- چه قاعدهای این کسر را محاسبه کرد و این قاعده چه فرضی دربارهی سیستم دارد؟
- کدام فلگ این مشکل را حل میکند، کیت بررسی چه مقداری برای آن استفاده کرد و استخر پس از آن چه وضعیتی پیدا کرد؟
- اثبات این راهحل با چیست: خط لاگ راهاندازی یا نتیجهی بنچمارک؟
اول شواهد را بخوانید و به سؤالها جواب بدهید، بعد راهحل را باز کنید.
راهحل گامبهگام
- خطوط رمزگشایی را قبل از خطا بخوانید. 32 درخواست در مجموع 16,095 توکن نگه داشته بودند که تنها 5 درصد از یک استخر 312,581 توکنی است. استخر 33 گیگابایت فضا رزرو کرده بود اما زیر 2 گیگابایت آن را مصرف میکرد. پیشپرکنی (prefill) بعدی به حافظهی اکتیویشن (activation memory) در خارج از استخر نیاز داشت، اما سیستمعامل دیگر حافظهای برای اختصاص دادن نداشت. با شکست یک بافر فرمان، اسکژولر (scheduler) از کار افتاد، والد سیگنال SIGQUIT دریافت کرد و کل درخت فرایند را بست. کش کلید-مقدار (KV cache) سرور تمام نشده بود؛ تمام منابع دیگر سیستم ته کشیده بود.
- دو خط راهاندازی را با هم مقایسه کنید. در بار اول، سیستم 27.81 گیگابایت حافظهی آزاد دید و بودجهی استخر را 24.25 گیگابایت (معادل 227,022 توکن) تعیین کرد. بار دوم، دقایقی بعد، سیستم 38.29 گیگابایت دید و 33.39 گیگابایت (معادل 312,581 توکن) به استخر داد. هیچ تنظیمی در SGLang تغییر نکرده بود. برنامههای دیگر روی لپتاپ هنگام راهاندازی دوم حافظهی کمتری مصرف میکردند؛ بنابراین اسنپشات (snapshot) حافظهی آزاد بزرگتر بود و استخر هم متناسب با آن رشد کرد.
- قاعده را بررسی کنید. هر دو بودجه دقیقاً 87.2 درصد از حافظهی آزاد بودند، چرا که کسر خودکار روی 0.872 محاسبه شده بود. در این بکاند، قاعده مقدار کمتر بین دو رقم را مبنا قرار میدهد: کسری از مجموعهی کاری Metal و کسری از حافظهی در دسترس سیستم در همان لحظه؛ و رقم دوم همان اسنپشاتی است که مدام تغییر میکرد. این قاعده فرض میکند کل سیستم در طول زمان اجرای سرور منحصراً متعلق به SGLang است. لپتاپی با مرورگر باز و ویرایشگر در حال اجرا چنین سیستمی نیست.
- راهحل را در راهاندازی کیت بخوانید. کیت بررسی آرگومان
--mem-fraction-static 0.4را ارسال میکند. خط راهاندازی آن یک اسنپشات 48.49 گیگابایتی و بودجهی 19.39 گیگابایتی را نشان میدهد که دقیقاً 0.4 اسنپشات است، یعنی استخری معادل 181,574 توکن. این استخر باز هم بسیار بیشتر از نیاز 32 درخواستِ 640 توکنی ظرفیت دارد؛ بنابراین کوچکتر شدن استخر برای این بار کاری هیچ هزینهای نداشت. - درستی آن را با همان بار پردازشی ثابت کنید. روی سرور کیت، بنچمارک با همزمانی 32 تمام 128 درخواست را در 64.83 ثانیه به پایان رساند. خط راهاندازی نحوهی تقسیم فضا را نشان میدهد، و نتیجهی بنچمارک اثبات میکند سرور زیر همان باری که قبلاً آن را از پا درآورده بود، زنده مانده است.
نتیجه
لپتاپ هیچوقت گلوگاه نبود. کسر خودکار 87 درصد از حافظهی آزاد را به استخری اختصاص داده بود که بار کاری تنها 5 درصد آن را مصرف میکرد، و عملاً هیچ فضایی برای اکتیویشنهای پیشپرکنی بعدی باقی نگذاشته بود. با تنظیم --mem-fraction-static 0.4 حجم استخر به 181,574 توکن کاهش یافت و همان بنچمارک توانست 128 درخواست از 128 درخواست را در همزمانی 32 با موفقیت پردازش کند.
اکنون این دمو با تعیین صریح کسر اجرا میشود و حامی توسعهدهندگان پس از هر تغییر دو خط را بررسی میکند: مقدار kv_budget در خط استخر و مقدار max_total_num_tokens در خط تنظیمات. در این بکاند، سنجهی حافظهی کش مقدار 0.0 را نشان میدهد، چون استخر MLX بیرون از سازوکار حسابرسی این سنجه تخصیص مییابد؛ بنابراین عددی که باید به آن اتکا کرد همان خط لاگ استخر است.
مسیرهای اشتباه رایج
- «لپتاپ نمیتواند به 32 کاربر سرویس بدهد.» استخر ظرفیت 312,581 توکن داشت و 32 درخواست تنها 5 درصد آن را پر کرده بودند. کمبود حافظه در خارج از استخر رخ داد، جایی که کسر خودکار فضای بسیار کمی برایش باقی گذاشته بود.
- «کسر را بالاتر ببرید تا استخر بزرگتر شود.» استخر خودش دلیل مشکل بود. 87 درصد از حافظهی آزاد را بلعید و اکتیویشنها را از گرسنگی کشت. باید آن را پایین بیاورید.
- «سرور را ریاستارت کنید، در بار دوم حافظهی بیشتری آزاد بود.» این اسنپشات با سایر برنامههای سیستم تغییر میکند و ممکن است در راهاندازی بعدی حافظهی کمتری پیدا کند. کسر را دستی تنظیم کنید تا اندازهی استخر وابسته به اسنپشات لحظهای نباشد.
- «کسر را روی 0.95 بگذارید تا خیالتان راحت باشد.» کسر 0.95 تنها 5 درصد برای اکتیویشنها باقی میگذارد و ایشوی شمارهی 39675 در مستندات دقیقاً همین خرابی را در همان اولین پیشپرکنی گزارش کرده است.
درس کلی
استخری که هنگام مرگ فرایند تقریباً خالی است، نشان میدهد حافظه در جایی مصرف شده که در محاسبات استخر نیامده است. روی سیستمی که همزمان کارهای دیگری هم انجام میدهد، محاسبهی کسر بر اساس اسنپشات حافظهی آزاد، در واقع قماری روی رفتار سایر برنامهها در طول زمان فعالیت سرور است. سهم را خودتان دستی مشخص کنید، دو خط لاگ راهاندازی را بخوانید تا نتیجه را ببینید، و راهحل حافظه را با همان باری اثبات کنید که سرور را از پا درآورده بود، نه صرفاً با بالا آمدن موفق سرور.
کجای دوره آموزش داده میشود
صفحهی حافظه در SGLang 101 این کرش و راهحل آن را مستند کرده است: کرشی که ثبت کردیم و دیدگاه ما: تعیین دستی کسر حافظه روی هر سیستم اشتراکی.