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

اجرای sglang serve و سه فرایند آن

sglang serve and the three processes

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

SGLang سرور را به سه فرایند توکن‌ساز، اسکژولر و توکن‌زدا تقسیم می‌کند؛ چون پردازش متن در Python نباید هیچ‌وقت حلقه‌ای را که به GPU خوراک می‌رساند معطل کند.

سرور را راه می‌اندازید، یک درخواست می‌فرستید و همه‌چیز کار می‌کند. بعد ترافیک واقعی روی آن می‌اندازید و می‌بینید در حالی که کاربران منتظر مانده‌اند، میزان استفاده از GPU روی 40 درصد درجا می‌زند. بیشتر افراد در وهله‌ی اول کرنل‌ها (kernels) را مقصر می‌دانند. لینکدین (LinkedIn) برای کشف ماجرا دست‌به‌کار شد و مشخص شد که بخش‌های کُند سیستم در واقع توکن‌ساز، پیام‌های بین‌فرایندی، آزادسازی حافظه (garbage collection) در Python و قفل مفسر سراسری (GIL) بوده‌اند {{field LinkedIn 2026-02}}.

پس از پایان این بخش، می‌توانید SGLang را با دستور sglang serve اجرا کنید و هر سه فرایندی را که راه می‌اندازد نام ببرید. همچنین می‌توانید لاگ راه‌اندازی را بخوانید و اعدادی را که بعداً تکلیف همه‌چیز را تعیین می‌کنند متوجه شوید.

هزینه: یک ریسه‌ی Python نمی‌تواند همه‌ی کارها را انجام دهد

سرورِ یک مدل زبانی دو نوع کار انجام می‌دهد. کارِ GPU همان گذر رو به جلو (forward pass) است: یک گام پیش‌پرکنی (prefill) یا رمزگشایی (decode) در هر چند میلی‌ثانیه. کارِ CPU هم همه‌چیزهای دوروبر آن است: تجزیه‌ی HTTP، اِعمال الگوی چت (chat template)، توکن‌سازی (tokenization)، تبدیل دوباره‌ی شناسه‌های توکن به متن، و بررسی رشته‌های توقف.

طراحی بدیهی این است که همه‌چیز درون یک فرایند (process) در Python قرار بگیرد. این طراحی زیر بار ترافیکی شکست می‌خورد. مفسر Python به‌خاطر GIL در هر لحظه فقط یک ریسه (thread) را اجرا می‌کند. وقتی پرامپتی (prompt) با 3,000 توکن در حال توکن‌سازی است، مفسر را درگیر نگه می‌دارد؛ در حالی که همین مفسر باید گام بعدی GPU را اجرا کند. هر میلی‌ثانیه‌ای که صرف کارهای متنی شود، به یک میلی‌ثانیه بیکاری GPU تبدیل می‌شود.

لینکدین این مسئله را روی پردازنده‌های گرافیکی H100 با مدل‌های کوچک رتبه‌بندی اندازه‌گیری کرد. فقط توکن‌سازی دسته‌ای، تاخیر صدک 99 (P99 latency) را در نرخ 500 کوئری در ثانیه، از 4,583 میلی‌ثانیه به 464 میلی‌ثانیه رساند {{field LinkedIn 2026-02}}. مدل هیچ تغییری نکرد؛ تنها چیزی که عوض شد، مسیر پردازش‌های CPU در اطراف آن بود.

فرایندهایی که SGLang راه‌اندازی می‌کند

TokenizerManager: شیئی در فرایند اصلی که هر درخواست را دریافت می‌کند، الگوی چت را اِعمال می‌کند، متن را توکن‌سازی می‌کند و منتظر پاسخ می‌ماند. سرور HTTP و TokenizerManager در یک فرایند مشترک و درون یک حلقه‌ی asyncio اجرا می‌شوند.

Scheduler: فرایند مجزایی که کنترل GPU را در دست دارد. این بخش تصمیم می‌گیرد کدام توکن‌ها در نوبت بعدی اجرا شوند، دسته (batch) را می‌سازد، گذر رو به جلو را اجرا می‌کند و نمونه‌برداری را انجام می‌دهد. در حالت موازی‌سازی تنسور (Tensor Parallelism)، به‌ازای هر GPU یک فرایند اسکژولر وجود دارد.

DetokenizerManager: فرایند سوم که شناسه‌های توکنِ خروجی را تکه‌تکه به متن تبدیل می‌کند و متن خروجی را برای TokenizerManager پس می‌فرستد.

این فرایندها از طریق سوکت‌های ZMQ با هم ارتباط دارند. بخش TokenizerManager یک شیء TokenizedGenerateReqInput به اسکژولر می‌فرستد. اسکژولر خروجی BatchTokenIDOutput را برای توکن‌زدا ارسال می‌کند. توکن‌زدا هم خروجی BatchStrOutput را برمی‌گرداند. در نسخه‌ی v0.5.22 این پیام‌ها به‌صورت پیش‌فرض پیکل (pickle) می‌شوند، چون مقدار SGLANG_USE_PICKLE_IPC فعال است {{code}}.

سه فرایند یک سرور SGLangیک درخواست از طریق ZMQ از سه فرایند عبور می‌کند و فقط اسکژولر با مدل در ارتباط است، بنابراین کارهای متنی هرگز روی نخی که گام‌های GPU را اجرا می‌کند اجرا نمی‌شوند.
سه فرایند یک سرور SGLang یک کلاینت درخواست POST /generate را به فرایند اصلی با pid 5782 ارسال می‌کند که سرور HTTP و TokenizerManager را در بر دارد. سپس یک TokenizedGenerateReqInput از طریق ZMQ به scheduler_0 با pid 5909 فرستاده می‌شود که مدل MLX را اجرا می‌کند. خروجی BatchTokenIDOutput به دی‌توکنایزر ارسال می‌شود که BatchStrOutput را به فرایند اصلی بازمی‌گرداند، و فرایند اصلی به کلاینت پاسخ می‌دهد. کلاینت curl یا بنچمارک main · pid 5782 سرور HTTP TokenizerManager scheduler_0 · pid 5909 صف و دسته‌ها استخر KV و درخت مبنا دی‌توکنایزر شناسه توکن به متن مدل MLX Qwen3-0.6B-4bit 1 2 3 4 5 6 مراحل شماره‌گذاری‌شده 1 POST /generate روی HTTP 2 TokenizedGenerateReqInput روی ZMQ 3 گذر رو به جلو و نمونه‌برداری 4 BatchTokenIDOutput روی ZMQ 5 BatchStrOutput روی ZMQ 6 پاسخ HTTP همراه با متن
فلش‌های شماره‌گذاری‌شده را به ترتیب بخوانید. جعبه‌های آبی فرایندهای SGLang هستند و جعبه زیتونی کلاینت است. شناسه‌های فرایند 5782 و 5909 از لاگ پیش‌فرض سرور در اجرای Mac ما گرفته شده‌اند.

هنگام موازی‌سازی تنسور، فقط رتبه‌ی 0 (rank 0) از اسکژولر سوکت‌های ZMQ را باز می‌کند. این رتبه هر درخواست را به سایر رتبه‌ها همه‌پخشی (broadcast) می‌کند تا همه‌ی GPUها دقیقاً همان دسته را بسازند {{code}}. هیچ رتبه‌ای برای خودش و مستقل تصمیم نمی‌گیرد.

دستوری که اجرا کردیم

ما سرور را روی یک مک با پردازنده‌ی Apple silicon، بک‌اند MLX و مدل 4-بیتی Qwen3 0.6B اجرا کردیم. در نسخه‌ی v0.5.22، دستور پیشنهادی sglang serve است. دستور قدیمی‌تر python -m sglang.launch_server هنوز کار می‌کند، ولی هشداری چاپ می‌کند که sglang serve را به‌عنوان اندپوینت (endpoint) ورودیِ پیشنهادی معرفی می‌کند {{code}}.

دستور سرور برای هر ثبت پیش‌فرض capture/out/server-default.command.txt
SGLANG_USE_MLX=1 sglang serve --model-path mlx-community/Qwen3-0.6B-4bit --disable-cuda-graph --host 127.0.0.1 --port 30000 --enable-cache-report --enable-metrics --mem-fraction-static 0.4

سه تا از فلگ‌ها مقدار پیش‌فرض نیستند و استفاده از هر سه کاملاً حساب‌شده بوده است. فلگ --enable-cache-report تعداد توکن‌های کش‌شده را در تمام پاسخ‌های شبیه به OpenAI درج می‌کند تا بتوانیم در بخش 2.5 آن را نشان دهیم. فلگ --enable-metrics اندپوینت /metrics را فعال می‌کند که در بخش 5.2 سراغش می‌رویم. فلگ --mem-fraction-static 0.4 استخر KV را محدود می‌کند و در بخش 3.2 توضیح می‌دهیم که چطور بدون آن سیستم کرش کرد.

لاگ خروجی به یکی از فلگ‌ها ایراد می‌گیرد. در مستندات Apple silicon در SGLang آمده است که باید فلگ --disable-cuda-graph را بدهید. اما خط دوم لاگ ما می‌گوید این فلگ «منسوخ شده است و در نسخه‌های آینده حذف خواهد شد» و گزینه‌ی جایگزین را --cuda-graph-backend-{decode,prefill}=disabled معرفی می‌کند.

اینجا مستندات و کد با هم نمی‌خوانند و حق با کد است. این فلگ در نسخه‌ی v0.5.22 هنوز کار می‌کند، ولی قبل از اینکه در نسخه‌ی بعدی حذف شود، برای تغییرش برنامه‌ریزی کنید.

اول از همه، لاگ راه‌اندازی را بخوانید

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

محدودیت‌های محاسبه‌شده توسط SGLang هنگام راه‌اندازی capture/out/server-default.log
[2026-10-16 13:58:05] max_total_num_tokens=181574, chunked_prefill_size=4096, max_prefill_tokens=16384, max_running_requests=4096, context_len=40960, available_gpu_mem=47.96 GB
…
[2026-10-16 13:58:06] Using the Python TreeCore: the Rust TreeCore supports Linux only
[2026-10-16 13:58:06] Tree cache initialized: source=default impl=UnifiedRadixCache hybrid_swa=False hybrid_ssm=False hicache_attached=False
[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

خطوط حذف‌شده از بخش راه‌اندازی. همین خطوط در هر ثبت با اعداد حافظه متفاوتی ظاهر می‌شوند.

خط اول را فیلد به فیلد بخوانید:

  • مقدار max_total_num_tokens=181574 اندازه‌ی استخر KV بر حسب توکن است. بخش 3 نشان می‌دهد این عدد از کجا می‌آید.
  • مقدار chunked_prefill_size=4096 بزرگ‌ترین تکه از یک پرامپت است که در یک گام اجرا می‌شود. پرامپت طولانی‌تر در چند تکه اجرا می‌شود.
  • مقدار max_running_requests=4096 مشخص می‌کند چه تعداد درخواست می‌توانند هم‌زمان در مرحله‌ی رمزگشایی باشند. این یک مقدارِ محاسبه‌شده است، نه تضمینی برای تاخیر مناسب.
  • مقدار context_len=40960 طولانی‌ترین دنباله‌ای است که مدل می‌پذیرد.

خط‌های مربوط به کش درختی (tree cache) هم مهم هستند. در Linux درخت مبنا (radix tree) از نسخه‌ی v0.5.21 به‌صورت پیش‌فرض در Rust اجرا می‌شود. روی مک ما، این بخش با Python اجرا می‌شود و لاگ هم صراحتاً همین را می‌گوید.

گرم‌کردن اولیه و آزادسازی حافظه

قبل از اینکه سرور اعلام آمادگی کند، یک درخواست به خودش می‌فرستد. سپس اندپوینت /freeze_gc خودش را فرامی‌خواند.

درخواست گرم کردن و زباله‌روب منجمدشده capture/out/server-default.log
[2026-10-16 13:58:08] 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: False, input throughput (token/s): 3.85
[2026-10-16 13:58:08] INFO:     127.0.0.1:63781 - "POST /generate HTTP/1.1" 200 OK
[2026-10-16 13:58:08] INFO:     127.0.0.1:63785 - "POST /freeze_gc HTTP/1.1" 200 OK
[2026-10-16 13:58:08] The server is fired up and ready to roll!

فراخوانی /freeze_gc پیشینه‌ای دارد. لینکدین متوجه توقف‌های 100 تا 300 میلی‌ثانیه‌ای در هر چند ثانیه به‌خاطر garbage collection شد و این مشکل را با گرم‌کردن اولیه (warm-up) و gc.freeze() برطرف کرد {{field LinkedIn 2026-02}}. در نسخه‌ی v0.5.22 سرور بعد از گرم‌کردن اولیه، همین کار را برای شما انجام می‌دهد؛ برای اسکژولر و توکن‌زدا هم همین‌طور {{code}}.

فرایندها در لاگ خاموش‌شدن

روشن‌ترین اثبات (proof) برای تفکیک فرایندها، موقع خاموش‌شدن سرور دیده می‌شود. ابزار ثبت لاگ ما هر سرور را با 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...

فرایند اصلی دارای pid 5782 و اسکژولر دارای pid 5909 است. کد خروج 15- ناشی از SIGTERM خود ماست؛ بنابراین واژه‌ی «crashed» گمراه‌کننده است. کرش واقعی اسکژولر شکل دیگری دارد: یک ردگیری محاسبات (traceback) چاپ می‌کند و بعد پیام «SIGQUIT received ... It usually means one child failed» در لاگ می‌آید، همان‌طور که در بخش 2.4 می‌بینیم.

موضع ما

مسیر پردازش در CPU را بخشی از سرور مدل بدانید. وقتی زمان تا اولین توکن بالا رفت و دیدید GPU سرش شلوغ نیست، قبل از اینکه سراغ کرنل‌ها بروید فرایند توکن‌ساز را بررسی کنید. SGLang به شما امکان می‌دهد تعداد ورکرها را در هر دو سمت افزایش دهید: فلگ‌های --tokenizer-worker-num و --detokenizer-worker-num که مقدار پیش‌فرض هر دو 1 است {{code}}.

تمام آزمایش‌هایتان را بر اساس مقادیر پیش‌فرضی که لاگ راه‌اندازی گزارش می‌دهد جلو نبرید. محدودیت‌های محاسبه‌شده را یادداشت کنید و سپس تصمیم بگیرید کدام‌ها را خودتان مقداردهی کنید. در بخش 7.1 ترتیب اولویت این تنظیمات را آورده‌ایم.

منابع: فایل‌های python/sglang/srt/entrypoints/engine.py (توضیحات داک‌استرینگ Engine و اجرای فرایندها)، python/sglang/srt/managers/io_struct.py، python/sglang/srt/environ.py (متغیر SGLANG_USE_PICKLE_IPC)، python/sglang/srt/managers/scheduler_components/request_receiver.py، python/sglang/launch_server.py، python/sglang/srt/entrypoints/http_server.py (گرم‌کردن اولیه و freeze_gc/)، python/sglang/srt/arg_groups/fields/serving.py در نسخه‌ی v0.5.22؛ مستندات docs/docs/hardware-platforms/apple_metal.mdx در نسخه‌ی v0.5.22؛ فایل‌های capture/out/server-default.command.txt و capture/out/server-default.log؛ مقاله‌ی وبلاگ مهندسی لینکدین با عنوان «Scaling LLM-based ranking systems with SGLang at LinkedIn» به‌تاریخ 2026-02-20، در آدرس https://www.linkedin.com/blog/engineering/ai/scaling-llm-based-ranking-systems-with-sglang-at-linkedin.

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