وضعیت
یک تیم پلتفرم، پادهای (pods) مربوط به SGLang را روی Kubernetes اجرا میکند. پروب زنده بودن (liveness probe) هر چند ثانیه یک بار با مهلت زمانی کوتاهی اندپوینت /health را فراخوانی میکند و اگر پاسخی نگیرد، پاد ریاستارت میشود. هنگام جهش ناگهانی ترافیک (traffic spike)، شلوغترین پادها وارد چرخهی مدام ریاستارت میشوند: مهلت پاسخ پروب تمام میشود، پاد درست وسط پاسخدهی به درخواستها متوقف (kill) میشود، کاربران آن به پادهای دیگر منتقل میشوند و در نتیجه پروب شلوغترین پاد بعدی هم با خطا روبهرو میشود. سرویس فقط وقتی به حالت عادی برمیگردد که این موج ترافیک فروکش کند.
لاگ اسکژولر (scheduler) پاد ریاستارتشده رد خودِ پروبها را نشان میدهد: دستههای پیشپرکنی (prefill batches) با یک توکن، لابهلای درخواستهای کاربران. در تیکت دو تغییر پیشنهاد شده است: افزایش مهلت پروب و بالا بردن محدودیت حافظهی پاد.
- نسخه
- SGLang 0.5.22 against vLLM 0.31.0
- مدل
- Qwen/Qwen3-8B
- سختافزار
- one L4 with 24 GB of memory
شواهد
probe-in-the-log.txt
title: the health probe around the ready line of our L4 server
source: manuals/sglang-101/capture/gpu/out-l4/server-default.log
lines: 36-43
lang: text
note: Read the line before the last one, and ask what sent that batch.
---
[2026-10-17 14:43:37] INFO: 127.0.0.1:58250 - "GET /health HTTP/1.1" 503 Service Unavailable
[2026-10-17 14:43:38] INFO: 127.0.0.1:58266 - "GET /model_info HTTP/1.1" 200 OK
[2026-10-17 14:43:38] Prefill batch, #new-seq: 1, #new-token: 6, #cached-token: 0, token usage: 0.00, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: True, input throughput (token/s): 3.37
[2026-10-17 14:43:38] INFO: 127.0.0.1:58272 - "POST /generate HTTP/1.1" 200 OK
[2026-10-17 14:43:38] INFO: 127.0.0.1:58288 - "POST /freeze_gc HTTP/1.1" 200 OK
[2026-10-17 14:43:38] The server is fired up and ready to roll!
[2026-10-17 14:43:40] Prefill batch, #new-seq: 1, #new-token: 1, #cached-token: 0, token usage: 0.00, #running-req: 0, #queue-req: 0, #pending-token: 0, cuda graph: False, input throughput (token/s): 0.58
[2026-10-17 14:43:40] INFO: 127.0.0.1:58298 - "GET /health HTTP/1.1" 200 OK
the-docstring-and-the-incident.txt
title: what the code claims and what two incidents showed
source: manuals/sglang-101/sections/7-1-operating-sglang.md
lines: 92-92
lang: text
note: Separate the claim about the work from the claim about the timing.
---
The docstring says that the probe request costs nothing when the server is busy, because any output from the scheduler counts as proof of life. That is true for the work, and false for the timing. **A real incident:** issue #22511 reports "health check failed. server could not get a response from detokenizer for last 20 seconds" on GLM-5 with 2 H800 GPUs under high load, on v0.5.10 {{issue #22511}}. A related issue, #35884, found that a timed-out probe left its request in the scheduler, so failed probes accumulated {{issue #35884}}.
the-other-engine.txt
title: the routes of a vLLM server with an API key, with and without the key
source: manuals/vllm-101/capture/gpu/out-l4/livecheck-2026-10-22.txt
lines: 52-62
lang: text
note: Find the routes that answer without a key, and think about which of them touch the model.
---
/v1/models nokey=401 key=200
/health nokey=200 key=200
/metrics nokey=200 key=200
/invocations nokey=405 key=405
/version nokey=200 key=200
/tokenize nokey=405 key=405
/v2/x nokey=401 key=404
/inference/x nokey=401 key=404
/cohere/x nokey=401 key=404
/ping nokey=200 key=200
/load nokey=200 key=200
three-endpoints.txt
title: the three health endpoints and the two settings behind them
source: manuals/sglang-101/sections/7-1-operating-sglang.md
lines: 86-90
lang: text
note: Find the endpoint that sends no request to the model, and the default of the generation setting.
---
- `/ready` returns 200 when the tokenizer manager is ready and 503 before that.
- `/health` and `/health_generate` share one handler. They return 503 while the server starts and while it shuts down.
- Otherwise the handler sends a one-token request with `max_new_tokens` 1 and waits for any output from the detokenizer.
- `SGLANG_ENABLE_HEALTH_ENDPOINT_GENERATION` defaults to true, so a plain `/health` also generates that token.
- The wait is `SGLANG_HEALTH_CHECK_TIMEOUT`, 20 s by default. With no output in that time, the handler marks the server `UnHealthy` and returns 503.
vllm-health-semantics.txt
title: the first health check of a vLLM server after startup
source: manuals/vllm-101/sections/1-2-check-that-the-server-is-healthy.md
lines: 23-25
lang: text
note: No prefill batch follows the health request on this engine.
---
INFO: Application startup complete.
INFO: 127.0.0.1:35152 - "GET /health HTTP/1.1" 200 OK
INFO: 127.0.0.1:34616 - "GET /v1/models HTTP/1.1" 200 OK
سؤالها
- لاگ را در حوالی خط اعلام آمادگی بخوانید. سرور هنگام درخواست بررسی سلامت از سوی پروب چه کرد و این کار زیر بار سنگین چه هزینهای دارد؟
- نام سه اندپوینت و پرسشی را که هر کدام پاسخ میدهند بنویسید.
- در متن کد آمده که این پروب هنگام شلوغی سرور هیچ هزینهای ندارد. چرا این ادعا از نظر حجم پردازش درست اما از نظر زمانبندی نادرست است؟
- پروبها را طراحی کنید: پروب آمادگی (readiness)، پروب زنده بودن (liveness) و بررسی عمیق (deep check). برای هر کدام اندپوینت، تنظیمات، مهلت زمانی و پیامد شکست را مشخص کنید.
- موتور دیگر به مسیر سلامت خود بدون تولید توکن پاسخ میدهد. این تفاوت چه تغییری در بررسی عمیق آن موتور ایجاد میکند؟
- ریاستارت در میانهی تولید پاسخها نیازمند توقف تمیز (clean stop) است. کدام سیگنال، به کدام فرایند ارسال شود و چقدر باید منتظر بمانید؟
اول شواهد را بخوانید و به سؤالها جواب بدهید، بعد راهحل را باز کنید.
راهحل گامبهگام
هشت خط لاگ را به ترتیب بخوانید. در ساعت 14:43:37 پروب اندپوینت /health را فراخوانی کرد و خطای 503 گرفت، چون سرور هنوز در حال راهاندازی بود. سرور سپس یک درخواست از سوی خودش به /generate فرستاد، زبالهروب (garbage collector) را متوقف کرد و خط اعلام آمادگی را نوشت. دو ثانیه بعد، اسکژولر لاگ یک دستهی پیشپرکنی با یک توکن جدید را ثبت کرد و بلافاصله پس از آن، پروب کد 200 گرفت. در آن لحظه هیچ کار دیگری در حال اجرا نبود. آن دستهی تکتوکنی، در واقع همان درخواست پروب بود. به صورت پیشفرض، /health فقط پاسخ خالی برنمیگرداند؛ بلکه یک درخواست را به مدل میفرستد و منتظر نتیجه میماند.
فهرست دوم نام سه اندپوینت را مشخص میکند. اندپوینت /ready وقتی مدیر توکنساز (tokenizer manager) آماده باشد کد 200 برمیگرداند و چیزی به مدل نمیفرستد. اندپوینتهای /health و /health_generate از یک کنترلکننده (handler) مشترک استفاده میکنند: تا زمانی که سرور در حال راهاندازی یا خاموش شدن باشد، خطای 503 میدهند؛ در غیر این صورت یک درخواست تکتوکنی با max_new_tokens برابر 1 میفرستند و منتظر هرگونه خروجی از دیتوکنساز (detokenizer) میمانند. متغیر SGLANG_ENABLE_HEALTH_ENDPOINT_GENERATION به طور پیشفرض روی true تنظیم شده است؛ بنابراین یک فراخوانی ساده به /health نیز به تولید توکن میانجامد. مدتزمان انتظار برابر با مقدار SGLANG_HEALTH_CHECK_TIMEOUT است که به طور پیشفرض 20 ثانیه در نظر گرفته شده و پس از آن، کنترلکننده سرور را ناسالم علامت زده و خطای 503 برمیگرداند.
فهرست سوم بخش ظریف ماجرا را نشان میدهد. توضیحات داخل کد (docstring) دربارهی حجم پردازش درست میگوید: هر خروجی از سوی اسکژولر اثبات حیات (proof of life) تلقی میشود؛ بنابراین نیازی نیست یک سرور شلوغ حتماً تولید توکن پروب را به پایان برساند. اما دربارهی زمانبندی اشتباه میکند. درخواست پروب در همان صف درخواستهای کاربران منتظر میماند؛ در نتیجه اگر تولید اولین توکن هر یک از کاربران بیشتر از مهلت پروب طول بکشد، پروب با شکست مواجه میشود. دو حادثهی ثبتشده هر دو روی سکه را نشان میدهند. یک گزارش نشان داد که بررسی سلامت روی مدلی بزرگ و زیر بار سنگین، به دلیل عدم دریافت پاسخ از دیتوکنساز ظرف 20 ثانیه شکست خورده است. گزارش دوم نشان داد پروبی که با اتمام مهلت زمانی روبهرو شده، درخواستش در اسکژولر باقی مانده و پروبهای ناموفق روی هم انباشته شدهاند. هنگام هجوم ترافیک، پروب مثل کاربری عمل میکند که پس از 20 ثانیه ناامید میشود و به هماهنگکننده (orchestrator) دستور میدهد سرور را بکشد.
دو فهرست آخر مربوط به موتور دیگر هستند. مسیرهای /health، /ping و /load آن بدون کلید API کد 200 میدهند و اولین بررسی سلامت پس از بالا آمدن سرور با فهرست مدلها دنبال میشود، نه با یک دستهی پیشپرکنی. مستندات علت را توضیح میدهد: آن مسیر سلامت وقتی موتور در حال اجرا باشد کد 200 برمیگرداند و توکنی تولید نمیکند؛ بنابراین دریافت کد 200 اثبات نمیکند که درخواستی تا انتها تکمیل میشود. در آن موتور، مسیر سلامت طبق طراحی یک بررسی زنده بودن است و بررسی عمیق به معنای ارسال یک درخواست کوتاه خواهد بود.
نتیجه
خود پروبها عامل حادثه بودند. پروب زنده بودن در هر فراخوانی یک توکن تولید میکرد، در صف کاربران معطل میماند، زیر بار ترافیک با اتمام مهلت مواجه میشد و شلوغترین پاد را متوقف میکرد؛ امری که بار آن پاد را به دوش پاد بعدی میانداخت.
مسیر /ready را به عنوان پروب آمادگی تعیین کنید تا پاد فقط زمانی به چرخهی سرویسدهی اضافه شود که بتواند درخواست بپذیرد. برای پروب زنده بودن، متغیر SGLANG_ENABLE_HEALTH_ENDPOINT_GENERATION=false را تنظیم کنید تا /health بدون ارسال درخواست به اسکژولر کد 200 برگرداند، و همین پروب را روی پاد نگه دارید. مسیر /health_generate را به یک بررسی عمیق با بازهی طولانیتر منتقل کنید که فقط به یک نفر هشدار دهد و چیزی را ریاستارت نکند. با این کار، مهلت زمانی پروب زیر بار سنگین دیگر اهمیتی ندارد؛ محدودیت حافظه هم که از ابتدا مشکلی نداشت. روی آن موتور دیگر، از همان /health بدون تغییر برای پروب زنده بودن استفاده کنید و بررسی عمیق را به یک درخواست کوتاه اختصاص دهید.
سپس فرایند خاموش کردن پاد را اصلاح کنید. تنها ارسال SIGTERM به فرایند اصلی است که باعث تخلیهی کامل (drain) درخواستهای در حال اجرا میشود: سرور در زمان تخلیه روی /health خطای 503 برمیگرداند، هر 5 ثانیه تعداد درخواستهای باقیمانده را لاگ میکند و وقتی هیچ درخواستی نماند خارج میشود. ارسال سیگنال به کل گروه فرایندی (process group) یا خروج اجباری، کارهای در حال انجام را نیمهکاره متوقف میکند. مهلت توقف پاد (termination grace period) را بیشتر از طولانیترین درخواست ممکن در سقف توکن خروجی تعیین کنید و حتماً ابتدا برای max_tokens سقف بگذارید؛ وگرنه تخلیهی سرور هرگز سر وقت تمام نمیشود.
مسیرهای اشتباه رایج
- «افزایش مهلت پروب به یک دقیقه.» پروب همچنان در صف کاربران منتظر میماند؛ علاوه بر این، طبق یکی از گزارشها درخواست پروب بعد از اتمام مهلت هم در اسکژولر باقی میماند. مهلت طولانیتر بار بیشازحد را برای مدت بیشتری پنهان میکند و در نهایت باز هم پاد را میکشد.
- «افزایش محدودیت حافظهی پاد.» پادها با کمبود حافظه روبهرو نشدند، بلکه هماهنگکننده بعد از معطلیِ طولانی پروب آنها را متوقف کرد.
- «استفاده از اندپوینتِ تولیدکننده برای پروب زنده بودن، چون کارکردن مدل را اثبات میکند.» بررسی عمیقی که زیر بار سنگین شلوغترین پاد را ریاستارت کند، خودش عامل حادثه است. بررسی عمیق باید به یک انسان هشدار دهد.
- «پاد را سریع بکشیم تا بقیه کار را بر عهده بگیرند.» ارسال سیگنال به کل گروه فرایندی ابتدا فرایند فرزندِ اسکژولر را متوقف کرد و باعث شکست همهی درخواستهای در حال اجرا شد. تنها ارسال SIGTERM به فرایند اصلی عملیات تخلیه را به درستی انجام میدهد.
درس کلی
پروب در واقع یک کلاینت است؛ و کلاینتی که در همان صف کاربران منتظر بماند دقیقاً وقتی با شکست روبهرو میشود که کاربران معطل شدهاند، یعنی درست در لحظهای که ریاستارت بیشترین ضربه را میزند. این پرسشها را از هم تفکیک کنید: آیا فرایند میتواند درخواست بپذیرد، آیا فرایند زنده است، و آیا مدل میتواند توکن تولید کند. به هر پرسش اندپوینت، زمانبندی و پیامد ویژهی خودش را اختصاص دهید، و هرگز نگذارید پرسشهای کُند باعث ریاستارت شوند.
کجای دوره آموزش داده میشود
مستندات SGLang رد پای پروب در لاگ را در صفحهی بررسی سلامت آورده و تنظیمات پروب، حوادث و تخلیهی سرور را در صفحهی عملیات شرح داده است. راهنمای vLLM نیز مسیر سلامت خود را در صفحهی بررسی سلامت vLLM و پروبهای محیط عملیاتی (production) را در صفحهی اجرای vLLM در محیط عملیاتی توضیح میدهد. همچنین درس SRE برای هوش مصنوعی رانبوکهای مختص این دست از چرخههای خرابی را پوشش داده است.