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

اسکژولر همپوشان

The overlap scheduler

فهرست مطالب
  1. هزینه: اتلاف زمان CPU میان گام‌های GPU
  2. نحوهٔ کار روی CUDA
  3. نحوهٔ کار روی Mac
  4. وقتی خاموشش کردیم چه اتفاقی افتاد
  5. رخدادی در GPU با ریشه‌ی یکسان
  6. دیدگاه ما

اسکژولر همپوشان (overlap scheduler) در حالی که GPU مشغول اجرای دسته‌ی N است، دسته‌ی N+1 را روی CPU آماده می‌کند؛ این سازوکار از نسخه‌ی v0.5.22 مسیر پیش‌فرض سیستم است.

اگر یک حلقه‌ی سرویس‌دهی ساده را پروفایل کنید، روی خط زمانی GPU وقفه‌هایی بین گام‌های رمزگشایی (decode) می‌بینید. در هر وقفه، GPU بیکار می‌ماند تا پایتون توکن‌های نمونه‌برداری‌شده را بخواند، رشته‌های توقف را بررسی کند، حافظه را آزاد کند و دسته‌ی بعدی را بسازد. یک گام رمزگشایی در مدلی کوچک فقط چند میلی‌ثانیه طول می‌کشد؛ بنابراین وقفه‌ای یک میلی‌ثانیه‌ای، بخش قابل‌توجهی از کل زمان گام را می‌گیرد.

با مطالعه‌ی این بخش می‌توانید توضیح دهید SGLang چگونه کارهای CPU را میان گام‌ها پنهان می‌کند و چه زمانی همپوشانی خاموش است. همچنین متوجه می‌شوید که آیا پرچم --disable-overlap-schedule اصلاً به کار دستور اجرایی شما می‌آید یا نه.

هزینه: اتلاف زمان CPU میان گام‌های GPU

زمان‌بندی همپوشان (Overlap scheduling): اجرای کارهای CPU برای یک دسته، هم‌زمان با اجرای کارهای GPU برای دسته‌ای دیگر.

تیم SGLang این چالش را در پست وبلاگی انتشار نسخه‌ی v0.4 شرح داد. زمان‌بندی دسته‌ها، تخصیص حافظه و تطابق پیشوند (Prefix match) باعث بیکاری GPU بین گام‌ها می‌شوند {{team 2024-12}}. راهکار آن‌ها اسکژولری است که یک دسته جلوتر حرکت می‌کند و تمام فراداده‌های دسته‌ی بعدی را آماده می‌سازد. آن‌ها از بهبود 1.1 برابری نرخ پردازش (Throughput) با این روش خبر داده‌اند {{team 2024-12}}. البته این رقم ادعای خود آن‌هاست و روی GPUهای خودشان ثبت شده است.

راه‌حل بدیهی، ساخت یک ترد (thread) دوم است تا در حالی که اولی GPU را اجرا می‌کند، دومی دسته‌ها را بسازد. تردهای پایتون مفسر مشترک دارند؛ بنابراین ترد اسکژولر و ترد گذر رو به جلو (forward pass) باید به نوبت کار کنند. SGLang در ابتدا ترد را آزمود، اما از زمان پول‌ریکوئست 11210# در اکتبر 2025، به‌جای آن از دو جریان CUDA در دل یک ترد واحد بهره می‌برد {{code}}.

نحوهٔ کار روی CUDA

این حلقه ابتدا دسته‌ی N+1 را روی GPU لانچ می‌کند و سپس نتایج دسته‌ی N را روی CPU پردازش می‌کند {{code}}. بدین ترتیب، GPU هرگز معطل کارهای دفتریِ گام قبلی نمی‌ماند.

اما یک مشکل وجود دارد: دسته‌ی N+1 به توکن‌های نمونه‌برداری‌شده از دسته‌ی N احتیاج دارد، در حالی که هنگام ساخت N+1، این توکن‌ها هنوز روی GPU هستند. SGLang برای حل این مسئله، دسته‌ی N+1 را با شناسه‌های توکن جایگزین (Placeholder Token) می‌سازد. سپس یک FutureMap روی GPU این توکن‌های جایگزین را با خروجی واقعی دسته‌ی N پر می‌کند؛ بنابراین CPU هرگز پیش از لانچ دسته، نیازی به خواندن توکن‌ها پیدا نمی‌کند {{code}}.

سه گام رمزگشایی یکسان بدون همپوشانی و با همپوشانیبدون همپوشانی، GPU پس از هر گام منتظر کارهای دفتری CPU می‌ماند؛ با همپوشانی، در حالی که GPU گام N+1 را اجرا می‌کند، CPU مشغول پردازش گام N است.
سه گام رمزگشایی یکسان بدون همپوشانی و با همپوشانی دو خط زمانی با یک لاین GPU و یک لاین CPU. بدون همپوشانی، بعد از هر گام GPU یک فاصله هاشورخورده وجود دارد که طی آن CPU نتایج را پردازش می‌کند و سه گام در زمان 500 پایان می‌یابند. با همپوشانی، GPU گام‌ها را پشت‌سرهم اجرا می‌کند در حالی که CPU گام قبلی را همزمان با اجرای گام بعدی پردازش می‌کند، و هر دو لاین سه گام را در زمان 420 به پایان می‌رسانند. WITHOUT OVERLAP: EVENT_LOOP_NORMAL GPU CPU WITH OVERLAP: EVENT_LOOP_OVERLAP GPU CPU t گام 1 گام 2 گام 3 سه گام تا 500 GPU منتظر CPU می‌ماند گام 1 گام 2 گام 3 سه گام تا 420 CPU گام N را همزمان با اجرای گام N+1 پردازش می‌کند
نمودار را از چپ به راست در محور زمان بخوانید. میله‌های بنفش گذر رو به جلو GPU، میله‌های آبی کارهای CPU، و میله‌های هاشورخورده خاکستری زمان بیکاری GPU هستند. شکل شماتیک است؛ ترتیب حلقه بر اساس event_loop_overlap در نسخه v0.5.22 است.

نحوهٔ کار روی Mac

بک‌اند MLX حلقه‌ی همپوشان ویژه‌ی خود را دارد: event_loop_overlap_mlx {{code}}. از آنجا که ارزیابی در MLX به‌صورت تنبل (lazy) انجام می‌شود، این حلقه با کمک mx.async_eval همواره دو گراف رمزگشایی را در صف نگه می‌دارد. طبق توضیحات داک‌استرینگ، GPU گام بعدی را دقیقاً بلافاصله پس از گام فعلی اجرا می‌کند و هیچ فاصله‌ای ناشی از زمان‌بندی روی تراشه ایجاد نمی‌شود. این زنجیره زمانی پاره می‌شود که یک درخواست پیش‌پرکنی (prefill) وارد شود، پردازش درخواستی خاتمه یابد، یا در صف انتظار کار جدیدی قرار گیرد. در این حالت، حلقه از نو یک گام تازه می‌سازد.

اسکژولر پایتون در CUDA و MLX کاملاً یکسان است؛ منطق دسته‌بندی، مدیریت درخت مبنا (Radix Tree) و خطوط لاگ در بخش 2.2 تغییری نمی‌کنند. تنها تفاوت در گذر رو به جلو و سازوکار همپوشانی است.

وقتی خاموشش کردیم چه اتفاقی افتاد

صفحه‌ی Apple silicon در مستندات SGLang، پارامتر --disable-overlap-schedule را یکی از گزینه‌های کلیدی بک‌اند MLX معرفی کرده است. ما این پرچم را به دستور اجرای سرور اضافه کردیم و بنچمارک را با هم‌زمانی 8 اجرا کردیم. سرور مراحل گرم‌کردن (warm-up) خود و بنچمارک را به‌درستی پشت سر گذاشت، اما اسکژولر دقیقاً روی اولین دسته‌ی اجرای واقعی کرش کرد.

کرش کردن اسکژولر با گزینه --disable-overlap-schedule در MLX capture/out/server-no-overlap.log
[2026-10-16 14:07:15] Prefill batch, #new-seq: 1, #new-token: 1, #cached-token: 511, token usage: 0.00, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: False, input throughput (token/s): 0.39
[2026-10-16 14:07:16] Scheduler hit an exception: Traceback (most recent call last):
…
    scheduler.event_loop_normal()
…
  File "/private/tmp/sglang-research/sglang-v0.5.22/python/sglang/srt/managers/scheduler.py", line 4746, in run_batch
    self._relay_forward_payload(
  File "/private/tmp/sglang-research/sglang-v0.5.22/python/sglang/srt/managers/scheduler.py", line 4852, in _relay_forward_payload
    self.future_map.stash(future_indices, payload)
  File "/private/tmp/sglang-research/sglang-v0.5.22/python/sglang/srt/managers/overlap_utils.py", line 639, in stash
    self.output_tokens_buf[indices] = payload.bonus_tokens.to(
…
RuntimeError: Expected all tensors to be on the same device, but found at least two devices, mps:0 and cpu!

ردگیری خطا (traceback) میان حلقه رویداد و run_batch بریده شده است. مسیرهای فایل مربوط به نسخه v0.5.22 هستند.

اگر رد پشته (stack trace) را از پایین بخوانید، می‌بینید که با خاموش بودن همپوشانی، توزیع‌کننده‌ی وظایف (Dispatcher) به سراغ event_loop_normal (حلقه‌ی عمومی) می‌رود. این حلقه تابع run_batch را صدا می‌زند که همچنان توکن‌های نمونه‌برداری‌شده را از طریق FutureMap سازوکار همپوشانی منتقل می‌کند. در MLX بافر روی دستگاه Metal قرار دارد و توکن‌های نمونه‌برداری‌شده به CPU می‌رسند؛ در نتیجه PyTorch از ترکیب آن‌ها جلوگیری می‌کند. حلقه‌ی همپوشان MLX اصلاً وارد این مسیر نمی‌شود، بنابراین سرور در حالت پیش‌فرض هرگز به آن نمی‌رسد.

به دنبال این اتفاق، فرایند (Process) اصلی همه‌چیز را خاموش کرد. تک‌تک 32 درخواست بنچمارک شکست خوردند: پاسخ 8 تای آن‌ها در میانه قطع شد و 24 تای دیگر پس از خاموشی سرور اصلاً نتوانستند متصل شوند.

سمت کلاینتِ کرش capture/out/no-overlap-bench-random-c8.txt
Warmup completed with 1 sequences. Starting main benchmark run...
…
requests.exceptions.ConnectionError: HTTPConnectionPool(host='0.0.0.0', port=30000): Max retries exceeded with url: /server_info (Caused by NewConnectionError("HTTPConnection(host='0.0.0.0', port=30000): Failed to establish a new connection: [Errno 61] Connection refused"))

کاراکترهای ابتدایی دو خط از 32 خط خطا، به‌همراه خط پایانی. هر سطر خطا شامل یک traceback کامل است.

این خرابی در یک دور آزمایش ثبت‌شده‌ی ما روی MLX رقم خورد. گزارش ما دقیقاً انعکاس واقعیت است: پرچمی که مستندات خود پلتفرم پیشنهاد داده بود، روی نسخه‌ی قفل‌شده‌ی سیستم کل پلتفرم را از کار انداخت.

همین پیکربندی روی CUDA در دو کارت L4 و GB10 بدون هیچ خطایی اجرا شد و به تمام 64 درخواست پاسخ داد. هر کارت یک بار با همپوشانی روشن و یک بار با همپوشانی خاموش، با 8 کاربر آزمایش شد. این دو نتیجه با هم هم‌راستا نیستند:

کارت، مدل توکن خروجی بر ثانیه (روشن / خاموش) میانه‌ی TPOT (روشن / خاموش)
L4, Qwen3-8B 73.71 / 84.17 91.24 / 69.38 ms
GB10, Qwen3-30B-A3B 78.92 / 73.59 97.30 / 103.21 ms

روی L4 سرور بدون همپوشانی 14 درصد سریع‌تر شد و روی GB10 حدود 7 درصد کندتر عمل کرد. این‌ها حاصل یک بار اجرا بدون ثبت فرکانس کلاک هستند و داغ شدن کارت می‌تواند دلیل هر دوی آن‌ها باشد. این نتایج نه ادعای بهبود 1.1 برابری تیم SGLang را نشان می‌دهند و نه آن را رد می‌کنند.

رخدادی در GPU با ریشه‌ی یکسان

روی CUDA، کاربری در حال اجرا با همپوشانی روشن بود که درست پس از پیام KV cache pool is full در مصرف 94 درصدی توکن‌ها، با خطای تخصیص حافظه روبه‌رو شد {{issue #14972}}. در سازوکار همپوشانی، دسته‌ی بعدی زمانی برنامه‌ریزی می‌شود که توکن‌های دسته‌ی قبلی هنوز در حال محاسبه هستند. سازوکار پس‌گیری (retraction) باید وضعیت درخواست‌هایی را که یک گام بعد خاتمه می‌یافتند تحلیل می‌کرد. پچ (Patch) پیشنهادی در پول‌ریکوئست 15626# بدون مرج (merge) بسته شد. در نسخه‌ی v0.5.22، اسکژولر درخواست‌هایی را که بر اساس طول به پایان می‌رسند از دسته‌ی رمزگشایی بعدی حذف می‌کند. همچنین اگر در گامی درخواست‌های رو‌به‌پایان قرار باشد فضای کش کلید-مقدار (KV cache) را آزاد کنند، از پس‌گیری صرف‌نظر می‌کند {{code}}.

هر دو ماجرا یک درس دارند: همپوشانی یعنی نسخه‌ی دومی از خط زمانی در هد (Head) اسکژولر، و تمام قابلیت‌ها باید کاملاً با آن هماهنگ باشند.

دیدگاه ما

همپوشانی را روشن بگذارید، مگر اینکه سنجش روی کارت خودتان خلاف آن را نشان دهد. این حالت پیش‌فرض است و دقیقاً برای پنهان کردن زمان CPU طراحی شده که در غیر این صورت باید در هر گام بپردازید. از آنجا که دو تست تک‌مرحله‌ای ما روی CUDA نتایج متفاوتی داشتند، پیش از هر تغییری هر دو وضعیت را با ثبت دقیق کلاک بسنجید.

خاموش کردن آن فقط یک دلیل موجه دارد: وقتی خروجی نادرست می‌گیرید یا سیستم قفل می‌کند، برای عیب‌یابی و رد دخالت همپوشانی آن را کنار بگذارید. انتظار داشته باشید که مسیر خاموش کمتر تست شده باشد و پیش از تکیه بر آن، حتماً روی سخت‌افزار خود آزمایشش کنید. خود SGLang نیز در جاهایی که همپوشانی کارایی ندارد آن را خاموش می‌کند؛ مثلاً روی Apple MPS بدون MLX و برای دیکودینگ حدسی (Speculative Decoding) روی CPU {{code}}.

منابع: بخش‌های مختلف مخزن در نسخه‌ی v0.5.22 شامل python/sglang/srt/managers/scheduler.py (توابع event_loop_overlap، event_loop_normal، _dispatch_event_loop_once، run_batch، _relay_forward_payload، update_running_batch)؛ فایل python/sglang/srt/managers/overlap_utils.py (متد FutureMap.stash)؛ فایل python/sglang/srt/hardware_backend/mlx/scheduler_mixin.py (تابع event_loop_overlap_mlx)؛ مستندات docs/docs/hardware-platforms/apple_metal.mdx در نسخه‌ی v0.5.22؛ پست وبلاگی LMSYS با عنوان «SGLang v0.4: Zero-Overhead Batch Scheduler» مورخ 2024-12-04 در نشانی https://lmsys.org/blog/2024-12-04-sglang-v0-4/؛ پول‌ریکوئست https://github.com/sgl-project/sglang/pull/11210؛ ایشوی https://github.com/sgl-project/sglang/issues/14972 و پول‌ریکوئست https://github.com/sgl-project/sglang/pull/15626؛ لاگ‌ها و داده‌های بنچمارک در مسیرهای capture/out/server-no-overlap.command.txt، server-no-overlap.log، no-overlap-bench-random-c8.txt، capture/gpu/out-l4/bench-random-c8.txt، capture/gpu/out-l4/no-overlap-bench-random-c8.txt، capture/gpu/out-gb10/bench-random-c8.txt و capture/gpu/out-gb10/no-overlap-bench-random-c8.txt.

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