SGLang تنها زمانی درخواست جدید را میپذیرد که پیشبینی توکنهای آیندهاش در استخر کش کلید-مقدار (KV cache) جا شود؛ به این ترتیب، وقتی سرور پر است، بهجای خرابکردن پردازشهای در حال اجرا، کاربران جدید را در صف میگذارد.
داشبوردتان میگوید پردازندهی گرافیکی حافظهی خالی دارد، با این حال درخواستهای جدید 28 ثانیه منتظر نخستین توکن خود میمانند. نه برنامهای کرش کرده، نه درخواستی رد شده، و سرعت تولید هر توکن هم مناسب است؛ ولی کاربران حس میکنند سرویس قطع شده است. کنترل پذیرش (admission control) وقتی وظیفهاش را درست انجام میدهد، دقیقاً چنین رفتاری دارد؛ و شما باید بدانید چرا تصمیم گرفته آنها را منتظر بگذارد.
پس از پایان این بخش، میتوانید سهمیهی توکن (Token Budget) را که مبنای تصمیمگیری برای پذیرش است توضیح دهید و حساب کنید چه تعداد درخواست در یک استخر جا میگیرد. علاوه بر این، میتوانید تفاوت یک صف سالم را با مشکل بازپسگیری (retraction) در لاگها تشخیص دهید.
هزینه: حافظهای که بعداً لازمش دارید
هر درخواست به کش کلید-مقدار نیاز دارد: در حال حاضر برای پرامپت خود، و در ادامه برای تکتک توکنهایی که تولید میکند. اسکژولر (Scheduler) نمیداند هر درخواست در نهایت چند توکن تولید خواهد کرد؛ فقط max_new_tokens، یعنی همان سقف بالایی را میداند.
دو راهحل بهظاهر بدیهی وجود دارد که هر دو شکست میخورند: اگر کل max_new_tokens را برای همه رزرو کنید، بیشتر فضای استخر خالی و دستنخورده میماند، چون اغلب درخواستها با رسیدن به توکن پایان توالی زودتر متوقف میشوند. اگر هم هیچ فضایی رزرو نکنید، استخر حین رمزگشایی (decode) پر میشود و سرور ناچار است پردازشهای انجامشده را دور بریزد.
پیشبینی
سیستم SGLang از یک پیشبینی همراه با اصلاح استفاده میکند. دو قانون تکلیف پذیرش را مشخص میکنند {{code}}:
- درخواست جدید باید توکنهای پرامپتِ کشنشده به اضافهی باقیماندهی
max_new_tokensخود را در حافظه جا دهد؛ مقداری که باSGLANG_CLIP_MAX_NEW_TOKENS_ESTIMATIONحداکثر روی 4096 محدود میشود. - هر درخواست در حال اجرا باقیماندهی
max_new_tokensخود را ضربدر نسبت توکن جدید میکند و این فضا را نگه میدارد.
نسبت توکن جدید (New token ratio): سهمی از خروجی باقیمانده است که اسکژولر انتظار دارد درخواستِ در حال اجرا مصرف کند. این نسبت از 0.7 ضربدر --schedule-conservativeness (بهطور پیشفرض 1.0) شروع میشود و در طول 600 گام رمزگشایی، بهصورت خطی تا 0.14 مقدار اولیهاش (یعنی 0.098 در حالت پیشفرض) پایین میآید {{code}}.
علت کاهش این نسبت آن است که بیشتر درخواستها زودتر متوقف میشوند؛ بنابراین هرچه اوضاع مدت طولانیتری خوب پیش برود، اسکژولر جسورانهتر عمل میکند. درخواستی که گزینهی ignore_eos برایش فعال باشد نمیتواند زودتر تمام شود، در نتیجه نسبت آن همیشه 1.0 است.
سنجش عملکرد با یک استخر کوچک
ما سروری را با گزینهی --max-total-tokens 4096 راهاندازی کردیم؛ استخری بسیار کوچکتر از ظرفیتی که مک ما اجازه میداد. سپس بنچمارک را با همروندی (concurrency) 16، پرامپتهای 256 توکنی و خروجیهای 512 توکنی اجرا کردیم.
کلاینت بنچمارک بهطور پیشفرض گزینهی ignore_eos را روی true میگذارد، بنابراین هر درخواست دقیقاً 512 توکن تولید میکند {{code}}. از این رو، هر درخواست 256 بهاضافهی 512، یعنی 768 توکن رزرو میکند. پنج درخواست در مجموع 3840 توکن رزرو میکنند و درخواست ششم به 4608 توکن نیاز خواهد داشت. اسکژولر دقیقاً پنج درخواست را پذیرفت.
[2026-10-16 14:08:02] Prefill batch, #new-seq: 1, #new-token: 1, #cached-token: 255, token usage: 0.06, #running-req: 0, #queue-req: 15, #pending-token: 0, cuda graph: False, input throughput (token/s): 0.80
[2026-10-16 14:08:02] Prefill batch, #new-seq: 4, #new-token: 896, #cached-token: 0, token usage: 0.28, #running-req: 1, #queue-req: 11, #pending-token: 2808, cuda graph: False, input throughput (token/s): 3889.60
…
[2026-10-16 14:08:14] Decode batch, #running-req: 5, #token: 1517, token usage: 0.37, cuda graph: False, gen throughput (token/s): 170.33, #queue-req: 11
[2026-10-16 14:08:17] Decode batch, #running-req: 5, #token: 2117, token usage: 0.52, cuda graph: False, gen throughput (token/s): 205.04, #queue-req: 11
…
[2026-10-16 14:08:26] Decode batch, #running-req: 5, #token: 3717, token usage: 0.91, cuda graph: False, gen throughput (token/s): 139.02, #queue-req: 11خطوط جداشده از دقیقه اول اجرا. خط اول همان پرامپت warm-up کَششده است.
به مقدار token usage دقت کنید. همزمان با اینکه آن پنج درخواست در فضای رزروشدهشان شروع به تولید توکن میکنند، این رقم از 0.28 تا 0.91 بالا میرود. یازده درخواست دیگر در تمام این مدت در انتظار میمانند. وقتی کار آن پنج درخواست تمام میشود، پنج درخواست بعدی شروع میشوند و این الگو به شکل موج در لاگ تکرار میشود.
کلاینت هزینهی این ترتیب پردازش را دید:
Successful requests: 32
…
Concurrency: 13.06
…
Median TTFT (ms): 27943.11
…
Mean TPOT (ms): 24.26 خطوط جداشده از بلوک خلاصهی نتایج.
همهی درخواستها با موفقیت به پایان رسیدند. بهمحض شروع هر درخواست، تولید هر توکن 24 میلیثانیه زمان برد؛ اما میانهی زمان انتظار کاربران برای اولین توکن 27.9 ثانیه بود. مقدار Concurrency برابر با 13.06 میانگین تعداد درخواستهای باز کلاینت را نشان میدهد؛ در حالی که در هر لحظه فقط پنجتای آنها روی پردازندهی گرافیکی در حال پردازش بودند.
بازپسگیری: وقتی پیشبینی اشتباه از آب درمیآید
پیشبینی میتواند بیش از حد جسورانه باشد، چون نسبت پیشبینی تا 0.098 افت میکند. در نتیجه، درخواستهایی که طولانی میشوند به جایگاههای (slot) بیشتری از ظرفیت استخر نیاز پیدا خواهند کرد. اسکژولر قبل از هر گام رمزگشایی بررسی میکند که آیا به هر یک از درخواستهای در حال اجرا میتوان یک جایگاه دیگر داد یا خیر {{code}}.
بازپسگیری (Retraction): خارجکردن درخواستهای در حال اجرا از دستهی (batch) رمزگشایی برای آزادکردن جایگاههای کش کلید-مقدار، و بازگرداندن آنها به صف انتظار. این درخواستها بعداً دوباره پیشپرکنی (prefill) میشوند.
وقتی این بررسی شکست بخورد، SGLang عبارت KV cache pool is full. Retract requests. را لاگ میکند. سیستم ابتدا درخواستهایی را که کمترین توکن خروجی را تولید کردهاند بازپس میگیرد، و در میان آنها اولویت را به طولانیترین پرامپتها میدهد، زیرا کار پردازشی کمتری روی آنها هدر رفته است {{code}}. سپس این نسبت را با تخمینی تازه بازتنظیم میکند: توکنهای رمزگشاییشده تا این لحظه بهاضافهی 20 توکن بهازای هر درخواست، تقسیم بر کل max_new_tokens. در نسخهی v0.5.22، اگر حتی آخرین درخواست هم جا نشود، سیستم بهجای افتادن در حلقه، آن درخواست را با خطای "Out of memory even after retracting all other requests" لغو میکند.
اجرای آزمایشی ما با استخر کوچک هیچ بازپسگیری نداشت؛ در لاگ سرور خبری از خط Retract requests نیست. اندپوینت (endpoint) متریکها نیز این موضوع را تأیید میکند، البته با یک محدودیت: مقدار num_retracted_reqs مقداری لحظهای است که اسکژولر بعد از هر بازهی لاگگیری آن را صفر میکند؛ پس عدد 0 فقط مربوط به آخرین بازه است. اما شمارندهی num_retracted_requests_total کل فرایند اجرا را پوشش میدهد.
sglang:num_retracted_reqs{engine_type="unified",model_name="mlx-community/Qwen3-0.6B-4bit",moe_ep_rank="0",pid="38678",pp_rank="0",tp_rank="0"} 0.0پیشبینی هیچ خطایی نداشت که نیاز به اصلاح باشد. با وجود ignore_eos، حافظهی رزروشده کاملاً دقیق بود. در ترافیک واقعی، درخواستها زودتر متوقف میشوند؛ بنابراین این نسبت کاهش مییابد، فرایند پذیرش جسورانهتر میشود و امکان بازپسگیری به وجود میآید.
رخدادها: وقتی بازپسگیری به مشکل تبدیل میشود
سروری که DeepSeek-R1 را روی هشت پردازندهی گرافیکی H20 اجرا میکرد، روی تکتک رتبهها (Rank) بارها و بارها خطای KV cache pool is full. Retract requests. را لاگ کرد و سپس پاسخدهی به بررسی سلامت (Health Check) را متوقف کرد {{issue #8463}}. یکی از کاربران با ردگیری محاسبات (Trace) متوجه شد بازپسگیری نمیتوانست حافظهی کافی آزاد کند و در چرخهای بیپایان تکرار میشد. این مشکل بدون راهحل بسته شد. در نسخهی v0.5.22، اگر اسکژولر حتی بعد از بازپسگیری همهی درخواستها باز هم با کمبود حافظه مواجه شود، آخرین درخواست را متوقف میکند؛ این سازوکار برای پایاندادن به همین حلقه طراحی شده است. ما نتوانستیم این مشکل را بازتولید کنیم.
کاربر دیگری متوجه شد که پس از یک بازپسگیری، نرخ پردازش (Throughput) رمزگشایی از حدود 429 به رقمی بین 20 تا 38 توکن در ثانیه سقوط کرد و در همان حد باقی ماند {{issue #26248}}. آن گزارش نیز به دلیل عدم فعالیت (Activity) و بدون مشخصشدن علت بسته شد. درس ما به قوت خود باقی است: دیدن بازپسگیری در لاگ، هشداری برای افت عملکرد است.
موضع ما
صفبندی، شکستِ صادقانه است. تشکیل صف باعث میشود سرعت تکتک درخواستهای در حال اجرا بالا بماند و بار اضافه در #queue-req و مدتزمان انتظار تا نخستین توکن نمایان شود. اما بازپسگیری، بار اضافه را در قالب پیشپرکنیهای هدررفته پنهان میکند.
مستندات بهینهسازی SGLang میگویند بازپسگیریِ گاهبهگاه—حدود یک بار در دقیقه—مشکلی ندارد. هر مقداری بیش از این را یک باگ در تنظیمات تلقی کنید. گزینهی --schedule-conservativeness را بالا ببرید—مثلاً تا 1.3—تا پیشبینی از عدد بزرگتری شروع شود؛ یا --max-running-requests را کم کنید. این مشکل را فقط با افزایش --mem-fraction-static حل نکنید، زیرا در بخش 3.2 هزینههای این کار را نشان دادهایم.
در کلاینتهای خود مقادیر واقعبینانهای برای max_new_tokens تعیین کنید. کلاینتی که 4096 توکن درخواست میکند اما 200 توکن مصرف میکند، باعث میشود فضای رزروشده برای خروجی هر درخواست جدید حدود 20 برابر بزرگتر از حد واقعی تخمین زده شود.
منابع: python/sglang/srt/managers/schedule_policy.py (PrefillAdder.add_one_req, _get_running_request_total_token_offset, CLIP_MAX_NEW_TOKENS)، python/sglang/srt/managers/scheduler_components/new_token_ratio_tracker.py، python/sglang/srt/managers/schedule_batch.py (check_decode_mem, retract_decode, _get_decode_retraction_order)، python/sglang/srt/managers/scheduler.py (update_running_batch)، python/sglang/srt/environ.py، python/sglang/benchmark/serving.py (ignore_eos default) در نسخهی v0.5.22؛ docs/docs/advanced_features/hyperparameter_tuning.mdx در نسخهی v0.5.22؛ capture/out/server-small-pool.command.txt، server-small-pool.log، small-pool-bench-long-output-c16.txt، small-pool-metrics.txt؛ گزارشهای باگ https://github.com/sgl-project/sglang/issues/8463 و https://github.com/sgl-project/sglang/issues/26248.