بخش 2.3 · مسیر درخواست

پذیرش و بازپس‌گیری

Admission and retraction

فهرست مطالب
  1. هزینه: حافظه‌ای که بعداً لازمش دارید
  2. پیش‌بینی
  3. سنجش عملکرد با یک استخر کوچک
  4. بازپس‌گیری: وقتی پیش‌بینی اشتباه از آب درمی‌آید
  5. رخدادها: وقتی بازپس‌گیری به مشکل تبدیل می‌شود
  6. موضع ما

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 است.

چرا پنج درخواست در 4,096 توکن جا می‌شوند و شش درخواست جا نمی‌شوندبا ignore_eos، هر درخواست 256 توکن پرامپت و تمامی 512 توکن خروجی خود را رزرو می‌کند؛ بنابراین پنج درخواست 3,840 توکن مصرف می‌کنند و درخواست ششم به 4,608 توکن نیاز خواهد داشت.
چرا پنج درخواست در 4,096 توکن جا می‌شوند و شش درخواست جا نمی‌شوند دو نوار یک استخر KV با 4,096 توکن را نشان می‌دهند. در نوار اول، پنج درخواست هر کدام 256 توکن پرامپت و 512 توکن خروجی رزرو می‌کنند که در مجموع 3,840 توکن شده و 256 توکن آزاد باقی می‌ماند. در نوار دوم، درخواست ششم به 768 توکن دیگر نیاز دارد و 512 توکن از انتهای استخر فراتر می‌رود، بنابراین اسکژولر آن را در حالت انتظار نگه می‌دارد. پایان استخر پذیرفته‌شده: 5 درخواست each request reserves 256 prompt + 512 output = 768 tokens درخواست ششم نیازمند 4,608 توکن است 0 3,840 4,096 KV پرامپت خروجی رزروشده آزاد جا نمی‌شود
هر نوار نشان‌دهنده استخر KV با 4096 --max-total-tokens است. رنگ سبز KV پرامپتِ رزروشده، رنگ کهربایی خروجی آینده‌ی رزروشده و رنگ خاکستری فضای آزاد است. برگرفته از capture/out/server-small-pool.log و small-pool-bench-long-output-c16.txt.

سنجش عملکرد با یک استخر کوچک

ما سروری را با گزینه‌ی --max-total-tokens 4096 راه‌اندازی کردیم؛ استخری بسیار کوچک‌تر از ظرفیتی که مک ما اجازه می‌داد. سپس بنچمارک را با همروندی (concurrency) 16، پرامپت‌های 256 توکنی و خروجی‌های 512 توکنی اجرا کردیم.

کلاینت بنچمارک به‌طور پیش‌فرض گزینه‌ی ignore_eos را روی true می‌گذارد، بنابراین هر درخواست دقیقاً 512 توکن تولید می‌کند {{code}}. از این رو، هر درخواست 256 به‌اضافه‌ی 512، یعنی 768 توکن رزرو می‌کند. پنج درخواست در مجموع 3840 توکن رزرو می‌کنند و درخواست ششم به 4608 توکن نیاز خواهد داشت. اسکژولر دقیقاً پنج درخواست را پذیرفت.

پنج مورد در حال اجرا، یازده مورد در انتظار capture/out/server-small-pool.log
[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 بالا می‌رود. یازده درخواست دیگر در تمام این مدت در انتظار می‌مانند. وقتی کار آن پنج درخواست تمام می‌شود، پنج درخواست بعدی شروع می‌شوند و این الگو به شکل موج در لاگ تکرار می‌شود.

کلاینت هزینه‌ی این ترتیب پردازش را دید:

آنچه کاربران حس کردند capture/out/small-pool-bench-long-output-c16.txt
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 کل فرایند اجرا را پوشش می‌دهد.

صفر پس‌گیری در اجرای استخر کوچک capture/out/small-pool-metrics.txt
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، حافظه‌ی رزروشده کاملاً دقیق بود. در ترافیک واقعی، درخواست‌ها زودتر متوقف می‌شوند؛ بنابراین این نسبت کاهش می‌یابد، فرایند پذیرش جسورانه‌تر می‌شود و امکان بازپس‌گیری به وجود می‌آید.

نسبت توکن جدید طی 600 گام رمزگشاییاین نسبت از 0.7 شروع می‌شود، پس از 600 گام رمزگشایی به 0.098 کاهش می‌یابد و پس از یک پس‌گیری دوباره جهش می‌کند؛ بنابراین پذیرش جسورانه‌تر می‌شود تا زمانی که شکست بخورد.
نسبت توکن جدید طی 600 گام رمزگشایی نمودار خطی از نسبت 0.7 در گام رمزگشایی 0 شروع شده و به صورت خطی به 0.098 در گام 600 کاهش می‌یابد، سپس ثابت می‌ماند. در گام 700 یک پس‌گیری آن را به 0.714 (مقدار موجود در خط لاگ مربوط به ایشوی 8463) ریست می‌کند و خط مجدداً شروع به کاهش می‌کند. 0 200 400 600 800 گام‌های رمزگشایی 0.7 0.098 پس‌گیری 0.098 to 0.714 پذیرش جسورانه‌تر می‌شود
از چپ به راست در طول گام‌های رمزگشایی خوانده شود. خط کهربایی نسبت پیش‌فرض برای درخواست‌های بدون ignore_eos است. نشانه‌ی گلی‌رنگ نشان‌دهنده‌ی یک پس‌گیری است. ثوابت برگرفته از new_token_ratio_tracker.py در نسخه v0.5.22.

رخدادها: وقتی بازپس‌گیری به مشکل تبدیل می‌شود

سروری که 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.

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