بخش 7.1 · محیط عملیاتی و آموزش

مدیریت و اجرای SGLang در محیط عملیاتی

Operating SGLang

فهرست مطالب
  1. تگ ایمیج اجرایی را پین کنید
  2. مواردی که pip install در اختیارتان نمی‌گذارد
  3. شروع سرد ترکیبی از وزن‌ها و کامپایلرهاست
  4. بررسی‌های سلامت: ready/، health/، و health_generate/
  5. خاموش‌سازی اصولی: سیگنال را فقط به فرایند اصلی بفرستید
  6. قبل از این‌که به نتایج اندازه‌گیری اعتماد کنید
  7. کرش یا فریز شدن سرور زیر بار شدید آزادسازی کش
  8. ترتیب درست تغییر تنظیمات
  9. گزارش تیم‌های عملیاتی از دنیای واقعی

اجرای SGLang به‌گونه‌ای که راه‌اندازی مجدد فقط چند ثانیه طول بکشد و هیچ درخواستی از دست نرود: تگ ایمیج را پین کنید، کرنل‌های کامپایل‌شده را نگه دارید، سیگنال خاموشی را فقط به فرایند اصلی بفرستید، و تنظیمات را با ترتیبی حساب‌شده اعمال کنید.

اولین حادثه در محیط عملیاتی (Production) با یک موتور سرویس‌دهی جدید، به‌ندرت به نرخ پردازش توکن بر ثانیه مربوط می‌شود. معمولاً یک به‌روزرسانی تدریجی (Rolling update)، ده درخواست را درست در میانه‌ی پاسخ‌دهی قطع می‌کند؛ یک پاد (Pod) جدید چهار دقیقه طول می‌کشد تا آماده شود و به همین دلیل ابزار مقیاس‌بندی خودکار سه پاد دیگر را هم بالا می‌آورد؛ یا یک پروب بررسی زنده‌بودن (Liveness probe) زیر بار کاری تایم‌اوت می‌دهد و شلوغ‌ترین پاد را ریستارت می‌کند. هیچ‌کدام از این موارد در یک بنچمارک ساده دیده نمی‌شوند، اما هزینه‌شان به‌مراتب از یک کرنل کند بیشتر است.

پس از پایان این بخش، می‌توانید تگ ایمیج مناسب را انتخاب کنید و زمان راه‌اندازی را پایین نگه دارید. پروب‌های بررسی سلامت (Health checks) را به اندپوینت‌های درست متصل می‌کنید و یاد می‌گیرید چطور یک سرور را بدون از دست رفتن کار متوقف کنید. همچنین می‌توانید تنظیمات را با ترتیبی که در این راهنما اندازه‌گیری کرده‌ایم تغییر دهید و از سه گزارش عملیاتی واقعی درس بگیرید.

تگ ایمیج اجرایی را پین کنید

تیم SGLang ایمیج‌های داکر را در Docker Hub تحت عنوان lmsysorg/sglang منتشر می‌کند. در نگارش v0.5.22، تگ latest شامل جدیدترین نسخه‌ی پایدار است و latest-runtime ایمیج کم‌حجم‌تری از همان نسخه را ارائه می‌دهد {{docs}}. تگ‌های Nightly نیز تغییرات شاخه‌ی main را دنبال می‌کنند. این ایمیج‌ها فقط شامل CUDA 13 هستند. مستندات مشخص کرده‌اند که lmsysorg/sglang:v0.5.19-cu129 آخرین تگ مبتنی بر CUDA 12 است؛ بنابراین میزبانی که درایور قدیمی‌تری دارد، باید از این تگ استفاده کند یا درایور خود را ارتقا دهد.

دستور رسمی و مستندشده برای شروع، یک بخش حافظه‌ی اشتراکی بزرگ و فضای نام IPC میزبان را در اختیار کانتینر می‌گذارد:

docker run -it --gpus all \
  --shm-size 32g \
  -p 30000:30000 \
  -v "$HF_CACHE_DIR:/root/.cache/huggingface" \
  --ipc=host \
  lmsysorg/sglang:latest bash

دیدگاه ما: هرگز از تگ latest در محیط عملیاتی استفاده نکنید. تیم SGLang نگارش‌های v0.5.20، v0.5.21 و v0.5.22 را در فاصله‌ی زمانی چهار هفته (از 2026-09-18 تا 2026-10-13) منتشر کرد و در هر نسخه، مقادیر پیش‌فرضی که در این راهنما سنجیده‌ایم تغییر کردند. با پین کردن یک تگ مشخص مثل v0.5.22، افت کارایی یا ناسازگاری‌ها نتیجه‌ی تصمیم خودتان خواهد بود؛ اما استفاده از latest باعث می‌شود این اتفاق با یک ریستارت ساده غافلگیرتان کند.

مواردی که pip install در اختیارتان نمی‌گذارد

دلیل اصلی وجود این ایمیج‌ها چیزی است که با یک دستور ساده‌ی pip install پنهان می‌ماند. ما این موضوع را روی سیستمی با دو پردازنده‌ی گرافیکی NVIDIA L4، اوبونتو 24.04، دارای درایور فعال اما فاقد جعبه‌ابزار کامل CUDA (CUDA toolkit) بررسی کردیم. دستور pip install sglang==0.5.22 بدون هیچ خطایی اجرا شد؛ اما اولین اجرای sglang serve شکست خورد و سه تلاش بعدی هم هر بار به دلیلی تازه ناموفق شدند:

چهار راه‌اندازی، چهار بخش مفقود capture/gpu/incidents/l4-toolchain-failures.txt
=== attempt: out-l4-nopyheaders/server-default.log
<site-packages>/triton/backends/nvidia/driver.c:9:10: fatal error: Python.h: No such file or directory
…
=== attempt: out-l4-nonvcc/server-default.log
[2026-10-16 14:21:19] RuntimeError: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist
…
=== attempt: out-l4-jitmismatch/server-default.log
…
<site-packages>/flashinfer/data/cccl/libcudacxx/include/cuda/std/__cccl/cuda_toolkit.h:41:8: error: #error "CUDA compiler and CUDA toolkit headers are incompatible, please check your include paths"
…
=== attempt: out-l4-nolibcudart/server-default.log
/usr/bin/ld: cannot find -lcudart: No such file or directory

اولین سطر خطای هر تلاش. خطوط تکراری و نوارهای پیشرفت حذف شده‌اند.

ریشه‌ی هر چهار خطا به یک موضوع برمی‌گردد: کتابخانه‌های SGLang، Triton و FlashInfer هنگام شروع به کار کرنل‌ها را روی ماشین مقصد کامپایل می‌کنند، و کامپایلر به یک زنجیره‌ی ابزار (Toolchain) کامل نیاز دارد.

  1. ابزار Triton یک فایل کمکی کوچک به زبان C را در برابر هدرهای پایتون کامپایل می‌کند؛ اما پایتون پیش‌فرض اوبونتو فایل Python.h را ندارد. ما پایتون را به توزیعی تغییر دادیم که هدرها را همراه داشت (از طریق uv).
  2. کتابخانه‌ی SGLang به دنبال کامپایلر nvcc در مسیر /usr/local/cuda می‌گردد. بسته‌های Wheel در pip شامل نسخه‌ی 13.4 از nvcc در مسیر nvidia/cu13 پوشه‌ی site-packages هستند، اما هیچ متغیری به آن اشاره نمی‌کند. ما CUDA_HOME را روی آن دایرکتوری تنظیم کردیم.
  3. سپس FlashInfer کرنل‌های اتنشن (Attention) خود را با همان nvcc در برابر هدرهای داخلی خودش کامپایل کرد، اما نسخه‌ها همخوانی نداشتند. ما flashinfer-jit-cache را نصب کردیم که کرنل‌های از‌پیش‌کامپایل‌شده را برای معماری SM 8.9 در خود دارد.
  4. کرنل‌های JIT در SGLang با -lcudart از مسیر $CUDA_HOME/lib64 لینک می‌شوند؛ اما بسته‌ی Wheel فقط فایل lib/libcudart.so.13 را داشت. ما یک پوشه‌ی CUDA_HOME با دایرکتوری lib64 ساختیم که حاوی libcudart.so بود.

سرور در پنجمین تلاش بالا آمد و به درخواست‌ها پاسخ داد. سیستم GB10 ما هرگز این مشکل را نداشت، چون سیستم‌عامل DGX آن تول‌کیت کامل را در /usr/local/cuda دارد.

کلاینت بنچمارک یک وابستگی دیگر هم دارد که فایروال دستش را رو می‌کند. مجموعه‌داده‌ی random متن‌های خود را از ShareGPT می‌گیرد و آن فایل را از Hugging Face Hub دانلود می‌کند {{code}}. با تنظیم HF_HUB_OFFLINE=1، اولین بنچمارک GPU ما شکست خورد، هرچند همه‌ی مدل‌ها روی دیسک ذخیره شده بودند. گزارش آن را نگه نداشتیم. روی سیستمی که دسترسی به شبکه ندارد از --dataset-name random-ids استفاده کنید، یا فایل محلی ShareGPT را با آرگومان --dataset-path بفرستید.

دیدگاه ما: SGLang را از طریق ایمیج پین‌شده یا روی میزبانی اجرا کنید که تول‌کیت کامل CUDA را دارد. نصب با pip روی سیستمی که فقط درایور دارد، پس از این چهار دستکاری راه می‌افتد؛ اما با هر بار ارتقای SGLang ممکن است دوباره به آن‌ها نیاز پیدا کنید.

شروع سرد ترکیبی از وزن‌ها و کامپایلرهاست

یک فرایند جدید SGLang وزن‌های مدل را بارگذاری می‌کند، کرنل‌ها را کامپایل یا لود می‌نماید، اندازه‌ی مخزن کش کلید-مقدار (KV cache) را تعیین می‌کند و گراف‌ها را ثبت (Capture) می‌سازد. لاگ‌های ما هر مرحله را در یک خط جداگانه ثبت کرده‌اند. این آزمایش با مدلی انجام شد که از قبل روی دیسک قرار داشت:

مراحل راه‌اندازی سرور پیش‌فرض capture/out/server-default.log
[2026-10-16 13:58:06] Engine startup timings (s): load_weight=0.00, kv_cache_allocation=0.00, scheduler_e2e=7.01, cuda_graph={prefill=0.00, decode=0.00, target_verify=0.00, draft_prefill=0.00, draft_decode=0.00, draft_extend=0.00}, tokenizer_e2e=11.92

یک سطر از لاگ راه‌اندازی. فیلدهای گراف CUDA همگی 0.00 هستند زیرا مسیر MLX هیچ گراف CUDA ثبت نمی‌کند.

اندازه‌گیری‌های ما نشان داد که برای یک مدل 0.6B روی مک، از اولین خط لاگ تا پیام «The server is fired up and ready to roll!» حدود 18 ثانیه طول کشید. یک مدل بزرگ روی پردازنده‌های گرافیکی داستان کاملاً متفاوتی دارد. یک گزارش میدانی از Doubleword (یک وبلاگ مهندسی در تاریخ 2026-04)، زمان SGLang v0.5.10 را با مدل Qwen3.5-122B-A10B-FP8 روی هشت GPU مدل B200 سنجیده است {{field Doubleword 2026-04}}. یک شروع سرد (Cold start) حدود 695 ثانیه زمان برد که 531 ثانیه‌ی آن صرف بارگذاری وزن‌ها شد. با حفظ کش کرنل‌ها بین دفعات اجرا، شروع گرم (Warm start) به 88 ثانیه رسید؛ و با استفاده از چک‌پوینت (Checkpoint) فرایند و نگهداری وزن‌ها در حافظه‌ی رم سیستم میزبان، این زمان به 9.6 ثانیه کاهش یافت.

ساختار کد در بخش کم‌هزینه‌تر این فرایند به کمکتان می‌آید. زمانی که پایتون بسته‌ی sglang را ایمپورت می‌کند، کش‌های Triton، TorchInductor، CUDA، TileLang و FlashInfer همگی به یک مسیر واحد یعنی SGLANG_CACHE_DIR هدایت می‌شوند که پیش‌فرض آن ~/.cache/sglang است {{code}}. این پوشه و پوشه‌ی کش Hugging Face را روی ولوم‌هایی مانت کنید که با از بین رفتن پاد پاک نشوند. با این کار، ریستارت‌ها از همان کرنل‌های کامپایل‌شده و وزن‌های دانلودشده استفاده‌ی مجدد می‌کنند.

همان گزارش میدانی از کندی شروع سرد دفاع می‌کند. از نظر آن‌ها، 10 درصد نرخ پردازش بالاتر توکن ارزش این را دارد که زمان راه‌اندازی 10 ثانیه بیشتر شود {{field Doubleword 2026-04}}. این نگاه برای زیرساختی که روزها مداوم کار می‌کند درست است؛ اما برای محیطی که هر شب تعداد نمونه‌هایش صفر می‌شود، زمان راه‌اندازی یک هزینه‌ی واقعی است و کش‌های ماندگار نخستین راهکار آن هستند.

بررسی‌های سلامت: ready/، health/، و health_generate/

سیستم SGLang دو نوع اندپوینت (Endpoint) برای بررسی سلامت دارد {{code}}:

  • اندپوینت /ready زمانی که مدیر توکن‌ساز آماده باشد کد 200 و پیش از آن کد 503 برمی‌گرداند.
  • اندپوینت‌های /health و /health_generate یک کنترل‌کننده (Handler) مشترک دارند. آن‌ها در حین راه‌اندازی و همچنین هنگام خاموش شدن سرور، کد 503 را برمی‌گردانند.
  • در غیر این صورت، این کنترل‌کننده یک درخواست تک‌توکنی با max_new_tokens برابر با 1 ارسال می‌کند و منتظر هرگونه خروجی از دیتوکن‌ساز می‌ماند.
  • متغیر SGLANG_ENABLE_HEALTH_ENDPOINT_GENERATION به‌طور پیش‌فرض true است؛ بنابراین حتی فراخوانی ساده‌ی /health نیز آن یک توکن را تولید می‌کند.
  • زمان انتظار برابر با SGLANG_HEALTH_CHECK_TIMEOUT و پیش‌فرض آن 20 ثانیه است. اگر در این مدت خروجی دریافت نشود، کنترل‌کننده وضعیت سرور را UnHealthy علامت می‌زند و کد 503 برمی‌گرداند.

در مستندات کد (Docstring) آمده که پروب تولید توکن وقتی سرور شلوغ است هزینه‌ای ندارد، زیرا هر خروجی از اسکژولر (Scheduler) اثبات زنده‌بودن سیستم به‌شمار می‌رود. این موضوع از نظر حجم کار درست است، اما از نظر زمان‌بندی واقعیت ندارد. یک نمونه‌ی واقعی: در تیکت شماره‌ی #22511 گزارش شده که روی مدل GLM-5 با دو GPU مدل H800 در بار کاری سنگین و روی نگارش v0.5.10، خطای «health check failed. server could not get a response from detokenizer for last 20 seconds» رخ داده است {{issue #22511}}. در تیکت مرتبط دیگر (#35884) مشخص شد که پروب‌های تایم‌اوت‌خورده درخواست خود را در اسکژولر باقی می‌گذارند و این باعث تجمع پروب‌های ناموفق می‌شود {{issue #35884}}.

دیدگاه ما: از /ready برای آزمون ارزیابی آمادگی (Readiness probe) استفاده کنید. جلوی تولید توکن در پروب زنده‌بودن را بگیرید؛ مقدار SGLANG_ENABLE_HEALTH_ENDPOINT_GENERATION=false را تنظیم کنید تا /health بدون ارسال درخواست به اسکژولر، کد 200 را برگرداند {{code}}. از اندپوینت /health_generate برای بررسی‌های عمیق‌تر استفاده کنید تا به یک انسان هشدار دهد، نه این‌که سیستم را ریستارت کند. به این ترتیب، سرور شلوغ پادهای فعال خود را فقط به این خاطر که یک پروب در صف معطل مانده، از دست نمی‌دهد.

خاموش‌سازی اصولی: سیگنال را فقط به فرایند اصلی بفرستید

با دریافت سیگنال SIGTERM، وب‌سرور HTTP فلگ gracefully_exit را فعال می‌کند و اندپوینت /health شروع به بازگرداندن کد 503 می‌کند. ناظر پردازشی (Watchdog) در بخش مدیریت توکن‌ساز هر 5 ثانیه یک‌بار این متغیر را چک می‌کند {{code}}. سپس تعداد درخواست‌های باقی‌مانده را هر 5 ثانیه یک‌بار لاگ می‌اندازد تا به صفر برسد. بعد از اتمام درخواست‌ها، پیام ShutdownReq را برای اسکژولرها ارسال می‌کند و 15 ثانیه به آن‌ها مهلت می‌دهد تا خارج شوند، سپس آن‌ها را متوقف می‌سازد. شکل 7.1 این فرایند و دو مسیر دیگری را که مرحله‌ی تخلیه (Drain) را رد می‌کنند نشان می‌دهد.

سه روش توقف سرور SGLangتنها سیگنال SIGTERM به فرایند اصلی درخواست‌های در حال اجرا را تخلیه می‌کند، و خروج اجباری یا سیگنال به گروه فرایندی کارهای در حال اجرا را متوقف می‌سازد.
سه روش توقف سرور SGLang یک سرور فعال SGLang که SIGTERM را در فرایند اصلی خود دریافت می‌کند، درخواست‌ها را تخلیه کرده، ShutdownReq می‌فرستد و با کد 0 خارج می‌شود. همین سرور در صورت خروج اجباری، تخلیه را نادیده می‌گیرد و اگر SIGTERM به کل گروه فرایندی فرستاده شود، فرزند اسکژولر زودتر کشته شده و در نتیجه والد مسیر کرش را در پیش گرفته و درخت فرایند را از بین می‌برد. مسیر ایمن سرویس‌دهی /health 200 در حال تخلیه /health 503 تخلیه هر 5 ثانیه ShutdownReq 15 ثانیه تا خروج کد خروج 0 تخلیه در 13 ثانیه 1 2 3 اجباری force_exit_handler قطع کارهای جاری 4 سیگنال ارسالی به گروه scheduler_0 exit -15 فرزند اول می‌میرد SIGQUIT kill_process_tree 5 6 1 سیگنال SIGTERM به فرایند اصلی: مسیر /health خطای 503 برمی‌گرداند و حلقه تخلیه آغاز می‌شود 2 درخواست‌های باقی‌مانده به 0 می‌رسند، هر 5 ثانیه طی اجرای تخلیه لاگ می‌شود 3 پیام ShutdownReq به اسکژولرها ارسال می‌شود که 15 ثانیه برای خروج فرصت دارند 4 force exit when the server is UnHealthy or SGL_FORCE_SHUTDOWN is set 5 SIGTERM to the whole process group: scheduler_0 exits first with -15 6 والد فروپاشی فرزند را می‌خواند و کل درخت را بدون تخلیه متوقف می‌کند
از چپ به راست در بالا مسیر ایمن (graceful) را دنبال کنید، سپس برای دو مسیر دیگر به سمت پایین بروید. اعداد با راهنما مطابقت دارند. برگرفته از capture/out/shutdown-exploratory.log، capture/out/server-default.log و کد خاتمه در نسخه v0.5.22.

ما هر دو حالت را روی مک اندازه گرفتیم. ابزار لاگ‌گیری ما سرورها را با ارسال سیگنال SIGTERM به کل گروه فرایندی (Process group) متوقف کرد. فرایند فرزند مربوط به اسکژولر نیز سیگنال را دریافت کرد و زودتر بسته شد:

ارسال SIGTERM به گروه فرایندی capture/out/server-default.log
[2026-10-16 14:01:45] SIGTERM received. signum=None frame=None. Draining requests and shutting down...
[2026-10-16 14:01:45] Subprocess scheduler_0 (pid=5909) crashed with exit code -15. Triggering SIGQUIT for cleanup...
[2026-10-16 14:01:45] SIGQUIT received. signum=None, frame=None. It usually means one child failed.
[2026-10-16 14:01:46] Sleeping 5 seconds before crash diagnostics to let GPU activity settle.

چهار سطر متوالی از انتهای اجرای پیش‌فرض.

فرایند والد متوجه کرش فرزند شد، مسیر مدیریت کرش را در پیش گرفت و تمام درخت فرایندها را به اجبار قطع کرد. در آن لحظه درخواستی در حال اجرا نبود، بنابراین چیزی آسیب ندید؛ اما زیر بار ترافیکی، تمام درخواست‌های جاری با خطا مواجه می‌شدند. سپس سروری را بالا آوردیم، درخواستی برای تولید 3,000 توکن خروجی فرستادیم و سیگنال SIGTERM را فقط به فرایند اصلی فرستادیم:

ارسال SIGTERM به فرایند اصلی، هم‌زمان با یک درخواست در حال اجرا capture/out/shutdown-exploratory.log
[2026-10-16 14:13:54] SIGTERM received. signum=None frame=None. Draining requests and shutting down...
…
[2026-10-16 14:13:55] INFO:     127.0.0.1:53237 - "GET /health HTTP/1.1" 503 Service Unavailable
…
[2026-10-16 14:13:57] Gracefully exiting... Remaining number of requests 1. Remaining requests remaining_rids=['ef12359aaaaf40d78fedb4e7f7aaed25'].
…
[2026-10-16 14:14:04] INFO:     127.0.0.1:53209 - "POST /generate HTTP/1.1" 200 OK
[2026-10-16 14:14:07] Gracefully exiting... Remaining number of requests 0. Remaining requests remaining_rids=[].
…
[2026-10-16 14:14:07] INFO:     Finished server process [53853]

سطرهای برش‌خورده از لاگ یک اجرای مجزا. سطرهای دسته رمزگشایی میان آن‌ها حذف شده‌اند.

آنچه کلاینت مشاهده کرد capture/out/shutdown-exploratory.txt
health before SIGTERM: 200
sent SIGTERM to the server process only
health during drain: 503
in-flight request: {"status": 200, "completion_tokens": 3000, "finish_reason": {"type": "length", "length": 3000}, "seconds": 14.2}
server exit code: 0

خروجی کامل اسکریپت آزمون ارزیابی.

درخواست با هر 3,000 توکن کامل شد و اندپوینت /health در طول زمان تخلیه، کد 503 برگرداند. سرور سیزده ثانیه پس از سیگنال با کد 0 بسته شد. دستور docker stop و کوبرنتیز سیگنال SIGTERM را به فرایند اصلی کانتینر می‌فرستند. این حالت زمانی درست کار می‌کند که sglang serve فرایند اصلی سیستم باشد؛ بنابراین آن را با دستور exec یا مستقیماً به عنوان Entrypoint اجرا کنید. اجرای تعاملی در دستورهای بالا باعث می‌شود bash فرایند اصلی شود، و شل bash این سیگنال را به فرایندهای زیرین منتقل نمی‌کند. اگر از یک اسکریپت واسط برای ارسال سیگنال به کل گروه فرایندی استفاده کنید، یا از یک سرپرست (Supervisor) که کل گروه را می‌بندد، با همان لاگ خروجی اول روبه‌رو خواهید شد.

کد دارای دو حالت خروج است که مرحله‌ی تخلیه را رد می‌کنند. اگر سرور از قبل در وضعیت UnHealthy باشد، سیستم بدون معطلی متوقف می‌شود. همچنین اگر متغیر محیطی SGL_FORCE_SHUTDOWN برابر true باشد، سرور درجا بسته می‌شود. در نگارش v0.5.22 ناظر سیستم هنوز نام قدیمی این متغیر را مستقیماً می‌خواند {{code}}.

ماژول محیطی، متغیر جدید با نام SGLANG_FORCE_SHUTDOWN را معرفی کرده است. بخش سازگاری کد، متغیرهای _SGL را به نام‌های _SGLANG کپی می‌کند، اما هرگز عکس این کار را انجام نمی‌دهد. بررسی کد نشان می‌دهد که مقداردهی به SGLANG_FORCE_SHUTDOWN به بخش ناظر نمی‌رسد. این موضوع را در متن کد دیده‌ایم و آن را اجرا نکردیم، بنابراین آن را یک باگ محتمل می‌دانیم. اگر به خاموشی اجباری نیاز دارید، مقدار SGL_FORCE_SHUTDOWN=1 را تنظیم کنید.

دیدگاه ما: زمان مهلت خاتمه‌ی فرایند (Termination grace period) را بیشتر از مدت‌زمان طولانی‌ترین درخواست با حداکثر سقف توکن خروجی تعیین کنید. پاسخ 32K توکنی با سرعت 30 توکن بر ثانیه، به بیش از 18 دقیقه زمان نیاز دارد. قبل از تعیین مهلت خاتمه، پارامتر max_tokens را سقف بگذارید؛ در غیر این صورت زمان کافی برای تخلیه وجود نخواهد داشت.

قبل از این‌که به نتایج اندازه‌گیری اعتماد کنید

سه بررسی جلوی بیشتر نتایج غلطی را که در ماشین‌های خود با آن‌ها مواجه شدیم می‌گیرند:

  1. کش پیشوند (Prefix cache) را پیش از هر دور مقایسه پاک کنید و تعداد توکن‌های کش‌شده را ثبت نمایید؛ مشابه روش بخش 5.1. در ابزار ما، کش گرم باعث می‌شد تستی با بار بیشتر سریع‌تر به نظر برسد. در آزمایشی دیگر با مدل Qwen/Qwen3-0.6B و سقف 16، تکرار آزمایش بدون پاک‌سازی کش، میانه‌ی TTFT (زمان تا اولین توکن) را حدود 4.8 برابر کمتر نشان داد.
  2. فرکانس کلاک SM و دمای پردازنده را در هر دور ثبت کنید، مطابق روش بخش 5.1. یک پردازنده‌ی داغ L4 تا 28 درصد نرخ پردازش (Throughput) کمتری نشان داد.
  3. روی یک سرور اشتراکی GB10، ابزار SGLang را درون کانتینری با محدودیت حافظه اجرا کنید و مقدار حافظه‌ی آزاد در زمان راه‌اندازی را لاگ بگیرید؛ مطابق روش بخش 3.2.

وقتی خروجی حریصانه (Greedy output) بین دو اجرای یکسان تغییر می‌کند، ابتدا وضعیت کش را بررسی کنید. درخواستی که پرامپت (Prompt) خود را در کش پیدا می‌کند مسیر متفاوتی را در مرحله‌ی پیش‌پرکنی (prefill) طی خواهد کرد، همان‌طور که در بخش 4.6 می‌بینید. در پردازش تک‌درخواستی، یک کش گرم باعث شد خروجی حریصانه‌ی 21 مورد از 32 درخواست ما تغییر کند؛ اما با پاک‌سازی کش، نتایج تکرارپذیر و عیناً مشابه شدند. این دو آزمایش روی یک GPU اشتراکی L4 بدون قفل فرکانس اجرا شدند، بنابراین به نسبت‌ها و تعداد توجه کنید، نه به زمان‌ها.

کرش یا فریز شدن سرور زیر بار شدید آزادسازی کش

نشانه‌ها: در میانه‌ی اجرای یک بار کاری با نوبت‌های گفت‌وگو‌ی (Turn) متعدد، سرور با خطای CUDA error: an illegal memory access was encountered متوقف می‌شود؛ یا لاگ بدون هیچ خطایی متوقف می‌ماند درحالی‌که مصرف GPU روی 100 درصد می‌ماند.

ما این حالت را در SGLang 0.5.22 با مدل Qwen/Qwen3-0.6B، مخزن حافظه‌ی 8,192 توکنی، و اجرای ردگیری محاسبات (Trace) مربوط به بخش 3.5 مشاهده کردیم. از نوبت چهارم به بعد، مخزن تقریباً در هر گام مجبور به آزادسازی (Eviction) پیشوندها می‌شد. گراف‌های CUDA و اسکژولر همپوشان (Overlap scheduler) فعال بودند که حالت پیش‌فرض است. تست‌ها روی پردازنده‌ی گرافیکی دوم سیستم L4 ما در تاریخ 2026-10-23 انجام شد که مالکش آن را به اشتراک می‌گذارد و قفل فرکانس نداشت.

لغوها و قفل‌شدگی‌ها بر حسب نگارش، سرور و ردگیری یکسان capture/gpu/out-l4/small-pool-crash.txt
variant                                          runs   aborts   hangs   clean
lru, CUDA graph and overlap on (default)         6      1        3       2
lru, CUDA_LAUNCH_BLOCKING=1                      3      0        0       3
lru, --disable-cuda-graph                        4      0        0       4
lru, --enable-hierarchical-cache                 3      1        0       2
lru, HiCache, CUDA_LAUNCH_BLOCKING=1             2      0        0       2

شمارش ارائه‌شده از خلاصه. قفل‌شدگی لاگی است که 5 دقیقه هیچ سطر جدیدی نداشته باشد، یا اجرایی که بیش از 15 دقیقه طول بکشد.

در تنظیمات پیش‌فرض، 4 مورد از 6 اجرا با خطا روبه‌رو شدند. استفاده از HiCache هم نتوانست مانع آن شود و 1 مورد از 3 تلاش آن هم کرش کرد. همه‌ی قطعی‌ها و فریزها در یک نقطه‌ی مشابه رخ دادند: اسکژولر منتظر پایان کپی نتایج مرحله‌ی رمزگشایی (decode) می‌ماند. با خاموش کردن گراف‌های CUDA، در هیچ‌کدام از 4 اجرا خطایی دیده نشد. با فعال‌سازی CUDA_LAUNCH_BLOCKING=1 نیز در 3 اجرا هیچ خطایی رخ نداد.

ما کرنلی را که خطا می‌دهد پیدا نکردیم، زیرا با لانچ‌های مسدودکننده (Blocking launches)، خطا دیگر اتفاق نمی‌افتاد. این موضوع به مخزن اصلی گزارش نشد.

راهکار موقت: فلگ --disable-cuda-graph را اضافه کنید. در سیستم L4 ما با یک مدل 8B، گراف‌ها حدود 1 درصد از زمان هر مرحله‌ی رمزگشایی را کم می‌کردند، همان‌طور که در بخش 4.1 توضیح داده شد. یک مدل کوچک سهم بیشتری از هر مرحله را صرف ارسال دستورات اجرایی می‌کند، بنابراین باید هزینه‌ی آن را روی مدل خودتان اندازه بگیرید. استفاده از CUDA_LAUNCH_BLOCKING=1 نیز خطا را پنهان کرد، اما فراخوانی هر کرنل را معطل کرنل قبلی می‌گذارد. از این گزینه فقط برای دیباگ استفاده کنید، هرگز در محیط عملیاتی به کار نبرید.

آزمایش تکمیلی: مخزن حافظه‌ی بزرگ‌تر. با مخزنی معادل 16,384 توکن یا بیشتر، همان ردگیری محاسبات دیگر با مشکل کوبیدگی حافظه (Thrashing) روبه‌رو نشد؛ همان‌طور که در بخش 3.5 اشاره شد. البته ما در اندازه‌های بزرگ‌تر تعداد کرش‌ها را نشمردیم، بنابراین این یک راه‌حل قطعی نیست.

ترتیب درست تغییر تنظیمات

بیشتر راهنماها فهرستی از فلگ‌ها را پیشنهاد می‌دهند. ترتیب این کار بسیار مهم‌تر از خود فهرست است، چرا که هر مرحله نحوه‌ی سنجش مرحله‌ی بعد را تغییر می‌دهد. شکل 7.1b ترتیب مورد استفاده در این راهنما را نشان می‌دهد که هر ردیف به بخش مربوط به آن متصل است.

ترتیب تغییر تنظیمات SGLangابتدا اندازه‌گیری کنید، سپس حافظه، پرامپت‌ها و هم‌زمانی را تنظیم نمایید، و تنها پس از آن به سراغ کرنل‌ها، موازی‌سازی و جداسازی بروید.
ترتیب تغییر تنظیمات SGLang هفت تنظیم به ترتیبی که این راهنما تغییر می‌دهد: اندازه‌گیری با sglang.benchmark.serving، تعیین اندازه استخر KV، مرتب‌سازی پرامپت، محدود کردن هم‌زمانی در نقطه زانو، سپس گراف‌های CUDA و بک‌اندهای اتنشن، سپس موازی‌سازی و در آخر تفکیک معماری. هر ردیف به بخشی اشاره دارد که آن را اندازه می‌گیرد. 1 اندازه‌گیری با sglang.benchmark.serving معیارهای TTFT ،TPOT و توکن خروجی/ثانیه در 3 سطح هم‌زمانی · 5.1 2 --mem-fraction-static تعیین اندازه استخر KV متناسب با سیستم اشتراکی · 3.2 3 ترتیب پرامپت shared text first, per-request text last, read cached_tokens · 3.4 4 --max-running-requests محدود کردن هم‌زمانی در نقطه شکست اندازه‌گیری‌شده · 5.1 5 --cuda-graph-backend-decode, --attention-backend یک تغییر در هر اجرا، پس از مراحل 1 تا 4 · 4.1، 4.2 6 --tp-size, --dp-size, --attn-dp-size تنها زمانی که یک رپلیکا اشباع شده باشد · 6.1 7 --disaggregation-mode تنها زمانی که پیش‌پرکنی به شکل محسوس رمزگشایی را به تعویق اندازد · 6.3
از بالا به پایین بخوانید. هر ردیف یک تنظیم یا اقدام است، همراه با اندازه‌گیری‌ای که آن را توجیه می‌کند و بخشی که آن اندازه‌گیری را نشان می‌دهد.
  1. کارایی را با دستور sglang.benchmark.serving در سه سطح همروندی بسنجید، مشابه بخش 5.1. بدون داشتن خط مبنا (Baseline)، هیچ تغییر بعدی عدد و معیاری نخواهد داشت.
  2. مقدار --mem-fraction-static را متناسب با ظرفیت سیستم اشتراکی تعیین کنید؛ مشابه بخش 3.2. روی سیستم مک ما، مقدار خودکار این گزینه باعث کرش سرور در همروندی 32 شد.
  3. بخش‌های متنی مشترک را در ابتدای هر پرامپت بگذارید؛ مشابه بخش 3.4. قرار دادن یک شناسه‌ی درخواست در ابتدای پرامپت سیستمی، زمان تا اولین توکن را برای ما حدود 14 برابر کرد.
  4. پارامتر --max-running-requests را روی نقطه‌ی زانویی (Knee) نمودار که اندازه‌گیری کرده‌اید محدود کنید. پس از عبور از این نقطه در سیستم L4 ما، نرخ پردازش افت کرد درحالی‌که زمان تا اولین توکن افزایش یافت. سیستم GB10 ما تا 64 کاربر هم به صعود ادامه داد و خود سقف را اندازه نگرفتیم.
  5. تازه حالا به سراغ تغییر تنظیمات گراف‌های CUDA و --attention-backend بروید و در هر اجرا فقط یک تغییر اعمال کنید؛ مطابق بخش 4.1 و بخش 4.2. در نگارش v0.5.22 گزینه‌ی --disable-cuda-graph منسوخ شده و جایش را به --cuda-graph-backend-decode و --cuda-graph-backend-prefill داده است.
  6. وقتی یک نمونه (Replica) به اشباع رسید، موازی‌سازی تنسور (Tensor)، موازی‌سازی داده (Data Parallelism)، یا موازی‌سازی اتنشن-داده را اضافه کنید؛ مطابق بخش 6.1.
  7. تفکیک مرحله‌ی پیش‌پرکنی از رمزگشایی را در آخر انجام دهید، و آن هم فقط بعد از اینکه اندازه گرفتید پیش‌پرکنی باعث تاخیر (Latency) در رمزگشایی می‌شود؛ مطابق بخش 6.3.

گزارش تیم‌های عملیاتی از دنیای واقعی

سه گزارش توسط تیم‌های خارج از مجموعه‌ی SGLang به ما نشان می‌دهند که انرژی عملیاتی صرف چه بخش‌هایی می‌شود.

لینکدین (LinkedIn) در یک وبلاگ فنی در تاریخ 2026-02-20، نحوه‌ی اجرای مدل‌های رتبه‌بندی با اندازه بین 375M تا 0.6B پارامتر را روی پردازنده‌های H100 شرح داد {{field LinkedIn 2026-02}}. این بار کاری فقط به پیش‌پرکنی و لاجیت‌های (Logits) آخرین توکن نیاز دارد. گلوگاه‌های اصلی آن‌ها بخش توکن‌سازی (Tokenization)، پیام‌های ZMQ، بازیافت حافظه (Garbage collection) پایتون، قفل سراسری مفسر (GIL)، و اسکژولر بودند؛ و هیچ‌کدام به کرنل‌های GPU مربوط نمی‌شدند.

توکن‌سازی دسته‌ای (Batch tokenization) تاخیر صدک 99 (P99) را از 4,583 میلی‌ثانیه به 464 میلی‌ثانیه رساند. مسیری اختصاصی برای امتیازدهی که فاز رمزگشایی را دور می‌زد، تاخیر P99 را از 6,220 میلی‌ثانیه به 454 میلی‌ثانیه رساند. توقف‌های ناشی از Garbage collection که بین 100 تا 300 میلی‌ثانیه طول می‌کشیدند، با یک گرم‌کردن اولیه و دستور gc.freeze() ناپدید شدند. خروجی مدل رتبه‌بندی 375M نیز از 750 به 2,200 آیتم در ثانیه به ازای هر پردازنده جهش کرد. بیشتر پول‌ریکوئست‌های مربوط به این تغییرات را خود لینکدین نوشت، بنابراین وضعیت قبلی آن‌ها روی نسخه‌ی قدیمی‌تری از SGLang بوده است.

مرکز CERIT-SC، یک مجموعه‌ی دانشگاهی در جمهوری چک، در سال 2025 از vLLM به SGLang مهاجرت کرد و تا تاریخ 2026-04 ارائه‌ی 100 میلیارد توکن را گزارش داد {{field CERIT-SC 2026-04}}. الگوی ترافیک آن‌ها همان درسی است که باید گرفت. برای مدل Kimi K2.6، طول میانه‌ی پرامپت 2,179 توکن و صدک 95 آن 99,746 توکن بود که آن را به ابزارهای کدنویسی ایجنتی (Agentic coding) نسبت می‌دهند. چالش‌های آن‌ها با SGLang شامل مواردی مثل نشت فراخوانی ابزار (Tool call) به خروجی استدلال مدل، هنگی‌های گاه‌به‌گاه، و حلقه‌های مدل بود که کش کلید-مقدار را نگه می‌داشت. راه‌حل آن‌ها رویکردی عملیاتی بود: محدود کردن خروجی به 32K توکن و افزودن جریمه‌ی حضور (Presence penalty) برای بارهای کاری که در حلقه می‌افتند. آن‌ها همچنان بسته به هر مدل، هر دو موتور را اجرا می‌کنند.

گروه Ant Group جزییات پیاده‌سازی DeepSeek-R1 روی پردازنده‌های H20 با نگارش v0.5.2 از SGLang را در وبلاگ LMSYS در تاریخ 2025-09-26 منتشر کرد {{field Ant Group 2025-09}}. آن‌ها موازی‌سازی متخصصان (Expert parallelism) را روی مقدار 16 به جای 32 انتخاب کردند، چون در دسته‌ی (Batch) 32 تایی، تنظیم EP16 نرخ 675 توکن در ثانیه داد، درحالی‌که این رقم برای EP32 معادل 585 بود. تولید توکن‌های حدسی بیشتر (Speculative draft tokens) در دسته‌ی 1 تایی کارایی را 21% بالا برد و در دسته‌ی 32 تایی حدود 18% افت کرد. آن‌ها سه سطح تاخیر می‌فروشند و سخت‌گیرانه‌ترین سطح (تاخیر کمتر از 30 میلی‌ثانیه برای هر توکن خروجی یا TPOT)، در دسته‌ی 12 تایی اجرا می‌شود. جدول سطوح اندازه‌گیری‌شده یک تصمیم محصولی است، و نکته‌ی اصلی هم دقیقاً همین است.

دیدگاه ما: گزارش‌های محیط عملیاتی را برای دیدن الگوی ترافیک و ترتیب رفع ایرادات بخوانید، هرگز برای رقم نرخ پردازش نخوانید. لینکدین کارهای مربوط به CPU را قبل از بهینه‌سازی GPU حل کرد. CERIT-SC سقف خروجی توکن را قبل از دست زدن به هر تنظیمی بست. مجموعه‌ی Ant Group نیز گروه متخصصی کوچک‌تر را انتخاب کرد، چرا که شعاع خرابی و اندازه‌ی دسته‌ای که برای سرویس تجاری‌اش می‌فروشد، از حداکثر نرخ پردازش مهم‌تر بود.

منابع: فایل‌های python/sglang/srt/entrypoints/http_server.py (برای ready، health_generate، HEALTH_CHECK_TIMEOUT)، python/sglang/srt/managers/tokenizer_manager.py (برای sigterm_watchdog، _SCHEDULER_EXIT_TIMEOUT_SECS)، python/sglang/srt/environ.py (برای SGLANG_FORCE_SHUTDOWN، SGLANG_ENABLE_HEALTH_ENDPOINT_GENERATION، SGLANG_CACHE_DIR، redirect_third_party_caches، _handle_deprecated_envs) و python/sglang/init.py در نگارش v0.5.22؛ مستندات docs/docs/get-started/install.mdx در نگارش v0.5.22؛ گزارش‌های خروجی در capture/out/server-default.log، capture/out/server-default.command.txt، capture/out/shutdown-exploratory.log، capture/out/shutdown-exploratory.txt، اسکریپت capture/shutdown_probe.py، و capture/gpu/incidents/l4-toolchain-failures.txt؛ فایل python/sglang/benchmark/datasets/random.py در نگارش v0.5.22؛ تیکت‌های گیت‌هاب #22511 و #35884؛ گزارش‌های میدانی: Doubleword در fergusfinn.com/blog/fast-sglang-starts (2026-04-06)، وبلاگ مهندسی لینکدین در linkedin.com/blog/engineering/ai/scaling-llm-based-ranking-systems-with-sglang-at-linkedin (2026-02-20)، مرکز CERIT-SC در blog.cerit.io/blog/run-llm2 (2025-10-19) و blog-dev.cerit.io/blog/llm3 (2026-04-27)، گزارش Ant Group در وبلاگ LMSYS در lmsys.org/blog/2025-09-26-sglang-ant-group (2025-09-26)، لاگ capture/gpu/out-l4/os-release.txt، بخش‌های 3.2، 4.6 و 5.1 همین راهنما (بررسی کش، کلاک و حافظه)، capture/gpu/out-l4/prefix-cache-flush.txt، capture/gpu/out-l4/greedy-output-cache-batch-dtype.txt، capture/gpu/out-l4/small-pool-crash.txt، capture/gpu/out-l4/eviction-multiturn.txt، و بخش 4.1 همین راهنما (هزینه‌ی گراف‌های CUDA روی پردازنده‌ی L4).

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