راهنمای عملی

SGLang 101

سرو مدل‌های زبانی با SGLang، از یک درخواست تا ناوگانی کامل، همراه با تصمیماتی فنی که فهرست پرچم‌ها به شما نمی‌گویند

  • نسخه‌ی سنجیده‌شده: SGLang 0.5.22
  • ۳۶ بخش

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

شروع از بخش ۱٫۱

بعد از این راهنما می‌توانید

  • نصب SGLang، سرو یک مدل و دریافت نخستین پاسخ از هر دو API آن در حدود ده دقیقه.
  • اندازه‌گذاری استخر KV برای GPU خود و رفع مشکل سروری که دچار کمبود حافظه شده است.
  • تنظیم دقیق سرور متناسب با ترافیک شما: پرامپت‌های اشتراکی، اسناد طولانی، کاربران پرتعداد یا فرمت FP8.
  • سنجش کارایی (بنچمارک) سرور خودتان و نظارت بر آن در محیط عملیاتی با استفاده از متریک‌ها.
  • انتخاب نحوه مقیاس‌پذیری روی چندین GPU و ارزیابی بنچمارک‌های منتشرشده پیش از اعتماد به آن‌ها.
یک درخت مبنا روی یک پردازنده L4
One radix tree on one L4 The three SGLang processes run on the host CPU: the TokenizerManager, the Scheduler, and the DetokenizerManager, joined by ZMQ IPC. Below them is one NVIDIA L4 card with its SM array of 58 SMs and its 24 GB of GDDR6 drawn as one memory slab. In that memory the radix tree holds KV prefixes. The system prompt is one shared node of 2,998 tokens, and each repeated request attaches below it. A request with the id at the end attaches there too, with 2,986 of 3,033 tokens cached. A request with the id at the start shares only 6 tokens and starts its own branch. On our L4 the first request waited 2,143.9 ms for its first token, and the repeats waited 82.5 ms. HOST CPU · THREE SGLANG 0.5.22 PROCESSES Qwen3-8B TokenizerManager text to token ids Scheduler match_prefix, batches DetokenizerManager token ids to text ZMQ IPC x86_64 host NVIDIA L4 · GPU MEMORY SM array 58 SMs, Ada 24 GB GDDR6, six packages root system prompt node 2,998 tokens, shared id at the start: 6 of 3,032 cached, own branch match_prefix repeat request, round 3 1 new token, 2,998 of 2,999 cached id at the end: 2,986 of 3,033 ZMQ IPC TIME TO FIRST TOKEN ON OUR L4, SAME 2,999-TOKEN PROMPT first request 2,143.9 ms repeats 82.5 ms, median of 4 first request: 3 cached tokens, the system prompt was not yet in the tree
روی پردازنده L4 ما، پرامپت سیستم یک گره اشتراکی در درخت مبنا است و هر درخواست تکراری زیر آن قرار می‌گیرد. در درخواست‌های تکراری، 2,998 توکن از 2,999 توکن کش شده بودند و نخستین توکن به جای 2,143.9 میلی‌ثانیه، بعد از 82.5 میلی‌ثانیه تحویل داده شد. منبع: capture/gpu/out-l4/cache-experiment.txt و capture/gpu/out-l4/server-default.log.

SGLang را نصب کنید، مدلتان را بالا بیاورید و سپس با تکیه بر اعدادی که با تغییر هر تنظیم ثبت کرده‌ایم، یاد بگیرید کدام گزینه‌های انگشت‌شمار واقعاً روی ترافیک شما اثر می‌گذارند.

این راهنما برای مهندسی نوشته شده است که می‌خواهد همین هفته یک مدل باز را روی GPU خودش اجرا کند. از سروری که پاسخ می‌دهد شروع می‌کنیم و به ناوگانی می‌رسیم که می‌توانید آن را بسنجید و اداره کنید.

با این دستورها محیط را می‌سازید، SGLang را نصب می‌کنید، سرور را راه می‌اندازید و یک درخواست به آن می‌فرستید:

uv venv --python 3.12
source .venv/bin/activate
uv pip install --prerelease=allow "sglang==0.5.22"
sglang serve --model-path Qwen/Qwen3-8B --host 127.0.0.1 --port 30000 \
  --enable-cache-report --enable-metrics --mem-fraction-static 0.85
curl -s http://127.0.0.1:30000/generate -H 'Content-Type: application/json' \
  -d '{"text": "The capital of France is", "sampling_params": {"max_new_tokens": 12, "temperature": 0}}'

در بخش 1.1، این مراحل را گام‌به‌گام پیش می‌بریم، خروجی مورد انتظار بعد از هر دستور را نشان می‌دهیم و خطاهای رایج را برطرف می‌کنیم. ما نصب با uv و اجرای سرور را روی یک کارت گرافیک NVIDIA L4 با SGLang 0.5.22 تست کرده‌ایم. مراحل مربوط به تراشه‌های Apple silicon از تست‌های ما روی Mac آمده‌اند و دستور Docker نیز از صفحه‌ی نصب SGLang پیروی می‌کند. منبع تک‌تک اعداد سنجیده‌شده در این راهنما شفاف است و ماشینی که از آن به دست آمده‌اند مشخص شده: یک NVIDIA L4، یک NVIDIA DGX Spark یا Mac.

کارهایی که پس از خواندن این راهنما می‌توانید انجام دهید

  • SGLang را نصب کنید، یک مدل بالا بیاورید و ظرف حدود 10 دقیقه اولین پاسخ را از هر دو API آن بگیرید.
  • اندازه‌ی استخر KV را برای GPU خود مشخص کنید و سروری را که با کمبود حافظه مواجه می‌شود نجات دهید.
  • سرور را متناسب با ترافیک خود تنظیم کنید: پرامپت‌های مشترک، اسناد طولانی، کاربران پرتعداد یا FP8.
  • سرور خود را بنچمارک کنید و با متریک‌هایش، آن را در محیط عملیاتی (Production) زیر نظر بگیرید.
  • نحوه‌ی توزیع مدل روی چندین GPU را انتخاب کنید و نتایج بنچمارک‌های منتشرشده را قبل از آنکه به آن‌ها اعتماد کنید، بسنجید.

مخاطبان این راهنما

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

دستور sglang serve --help در نسخه‌ی 0.5.22 فهرستی از 535 گزینه را ارائه می‌دهد. مستندات SGLang تک‌تک آن‌ها را توضیح داده است؛ اما این راهنما به شما می‌گوید در روز اول کار سراغ کدام گزینه‌ها بروید و کدام مقادیر پیش‌فرض ماشینی را فرض گرفته‌اند که شما ندارید. علاوه بر این، نشان می‌دهد که هر تغییر روی GPUهای ما چه نتیجه‌ای داشته است.

ترتیب بخش‌ها

بخش 1 سرور را راه می‌اندازد و آن را بررسی می‌کند. بخش 2 مسیر یک درخواست را در میان فرایندها (Processes) و اسکژولر (Scheduler) دنبال می‌کند. بخش 3 به کش کلید-مقدار (KV cache) می‌پردازد؛ همان چیزی که تعیین می‌کند یک GPU می‌تواند به چند کاربر سرویس دهد.

بخش 4 سرعت هر گذر رو به جلو (forward pass) را بالا می‌برد و بخش 5 سرور را می‌سنجد. بخش 6 یک مدل را روی چند GPU پخش می‌کند. بخش 7 به مدیریت و اجرای SGLang اختصاص دارد و کار را با یادگیری تقویتی (Reinforcement Learning) می‌بندد. در بخش مرجع هم جدول‌های جستجو (Lookup Tables) و نحوه‌ی تهیه‌ی این راهنما آمده است:

پایان هر بخش، قسمتی با عنوان «دیدگاه ما» دارد که می‌گوید چه کاری باید انجام دهید و فهرستی کوتاه از اقدامات عملی ارائه می‌دهد. اگر امروز به جواب نیاز دارید، اول همان قسمت را بخوانید؛ اگر به دنبال دلیل تصمیم‌ها هستید، بقیه‌ی متن را بخوانید.

هفت درس دیگر، مفاهیمی را که در این راهنما به کار گرفته‌ایم عمیق‌تر بررسی می‌کنند: درس سازوکار داخلی سرو مدل به اتنشن صفحه‌بندی‌شده (Paged Attention) و دسته‌بندی پیوسته (Continuous Batching) می‌پردازد؛ درس نرخ پردازش موثر متریک‌ها را تعریف می‌کند؛ درس دیکودینگ حدسی ساخت EAGLE-3 را آموزش می‌دهد و درس کوانتیزه‌سازی قالب‌ها را پوشش می‌دهد. درس انتخاب بستر سرو خودمیزبان، درس بهینه‌سازی استنتاج و درس کش کردن پرامپت این مجموعه را کامل می‌کنند. تمرکز این راهنما منحصراً روی SGLang باقی می‌ماند.

رنگ‌ها در نمودارها

هر طیف رنگی در تمام نمودارها معنای ثابتی دارد:

در شکل 0.1 با استفاده از تبادلات ثبت‌شده در تست‌هایمان، سبک‌های مختلف فلش‌ها آموزش داده شده است.

راهنمای خواندن نمودار توالی در این مستندهر سبک فلش نمایانگر یک نوع تبادل است و هر برچسب، یک نام، پیام یا عدد واقعی از اجراهای ثبت‌شده‌ی ماست.
راهنمای خواندن نمودار توالی در این مستند شش خط عمر (Lifeline): اسکریپت کلاینت، مدیر توکنایزر، اسکژولر، مدل روی MLX، مدیر دی‌توکنایزر، و macOS. نه ردیف شماره‌دار از هشت سبک فلش استفاده می‌کنند: POST /v1/chat/completions به‌صورت فراخوانی پیوسته تیره، TokenizedGenerateReqInput به‌صورت پیام ZMQ با نقطه‌چین نیلی، تغییر حالت waiting به running به‌صورت خط‌چین کهربایی، پیش‌پرکنی 1 توکن نو با 2998 توکن کش‌شده به‌صورت فراخوانی مدل با خط پیوسته آلبالویی، محدودیت حافظه Metal به میزان 51.8 GB به‌صورت اثر بیرونی خط‌چین زیتونی، فایل‌های مدل در کش Hugging Face به‌صورت نوشتن پایدار پیوسته فیروزه‌ای، BatchTokenIDOutput به‌صورت پیام نقطه‌چین نیلی، 200 OK با cached_tokens 2998 به‌صورت پاسخ خط‌چین تیره، و Insufficient Memory در همروندی 32 به‌صورت شکست با خط‌چین سرخ. کلاینت اسکریپت پایتون توکنایزر مدیر اسکژولر حلقه رویداد مدل MLX, Qwen3 دی‌توکنایزر مدیر macOS Metal، دیسک 1 POST /v1/chat/completions فراخوانی · خط پیوسته تیره 2 TokenizedGenerateReqInput پیام ZMQ · نقطه‌چین نیلی 3 تغییر وضعیت از انتظار به اجرا تغییر وضعیت · خط‌چین کهربایی 4 پیش‌پرکنی 1 توکن نو، 2998 در حافظه محاسبه مدل · خط پیوسته آلبالویی 5 سقف حافظه Metal برابر 51.8 GB اثر بیرونی · خط‌چین زیتونی 6 9 فایل مدل در کش HF نوشتن پایدار · خط پیوسته فیروزه‌ای 7 BatchTokenIDOutput پیام ZMQ · نقطه‌چین نیلی 8 200 OK, cached_tokens 2998 پاسخ · خط‌چین تیره 9 Insufficient Memory at c=32 شکست · خط‌چین سرخ
هر ردیف شماره‌دار را از انتهای فلش تا نوک آن بخوانید؛ یادداشت زیر هر برچسب، نام آن سبک را مشخص می‌کند. برگرفته از capture/out/cache-experiment.txt، server-default.log و اجرای با خطای کمبود حافظه در بخش 3.2.

منابع: manual.json؛ capture/gpu/out-l4/server-default.command.txt، capture/gpu/out-l4/generate.txt؛ capture/out/serve-help.txt، cache-experiment.txt، server-default.log؛ docs/docs/get-started/install.mdx در v0.5.22.

فهرست راهنما

بخش ۱: شروع

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

  1. 1.1نصب SGLang و سرو اولین مدل
  2. 1.2بررسی سلامت سرور
  3. 1.3سرور با درخواست شما چه می‌کند؟

بخش ۲: مسیر درخواست

یک درخواست از سه فرایند عبور می‌کند و اسکژولر میان آن‌ها تعیین می‌کند چه کسی اجرا شود، چه کسی منتظر بماند و چه کسی بیرون انداخته شود.

  1. 2.1اجرای sglang serve و سه فرایند آن
  2. 2.2حلقه‌ی اسکژولر و ‎--schedule-policy
  3. 2.3پذیرش و بازپس‌گیری
  4. 2.4اسکژولر همپوشان
  5. 2.5استریمینگ، رشته‌های توقف و OpenAI API

بخش ۳: کش KV

حافظه—نه توان محاسباتی—مشخص می‌کند یک GPU به چند کاربر سرویس می‌دهد، و درخت مبنا تعیین می‌کند چقدر از این حافظه را دو بار هزینه می‌کنید.

  1. 3.1استخر KV و بایت به ازای هر توکن
  2. 3.2پرچم mem-fraction-static-- و تعیین اندازه در زمان راه‌اندازی
  3. 3.3حافظه‌ی رادیکس (RadixCache)
  4. 3.4پرامپت‌های سازگار با کش پیشوند
  5. 3.5سیاست‌های تخلیه و HiCache
  6. 3.6مدل‌های ترکیبی و کش

بخش ۴: هر گذر رو به جلو

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

  1. 4.1حالت گذر رو به جلو (ForwardMode) و گراف‌های CUDA
  2. 4.2‎--attention-backend
  3. 4.3پرچم‌های ‎--quantization‎ و ‎--kv-cache-dtype‎
  4. 4.4الگوریتم‌های حدسی (--speculative-algorithm)
  5. 4.5آرگومان ‎--grammar-backend‎ و خروجی‌های ساختاریافته
  6. 4.6پرچم ‎--enable-deterministic-inference‎ و مقادیر logprobs

بخش ۵: اندازه‌گیری عملکرد سرور

عدد نرخ پردازش بدون مشخص بودن حد تاخیر بی‌معناست؛ پس پیش از هرگونه تنظیم دقیق، نقطه شکست کارایی را اندازه بگیرید.

  1. 5.1sglang.benchmark.serving
  2. 5.2اندپوینت /metrics
  3. 5.3خواندن بنچمارک‌های دیگران درباره‌ی SGLang

بخش ۶: تبدیل یک سرور به یک ناوگان

مدل را تنها پس از اشباع کامل یک GPU بین چند پردازنده خرد کنید، و پیش‌پرکنی را از رمزگشایی تنها پس از اندازه‌گیری و اثبات تداخل پرهزینه جدا سازید.

  1. 6.1پارامترهای ‎--tp-size‎، ‏‎--dp-size‎ و ‎--attn-dp-size‎
  2. 6.2سرویس‌دهی MoE: فلگ‌های moe-a2a-backend--، DeepEP و EPLB
  3. 6.3تفکیک پیش‌پرکنی و رمزگشایی: ‎--disaggregation-mode‎
  4. 6.4ابزار sgl-model-gateway و مسیریابی آگاه از کش

بخش ۷: محیط عملیاتی و آموزش

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

  1. 7.1مدیریت و اجرای SGLang در محیط عملیاتی
  2. 7.2استفاده از SGLang به‌عنوان موتور پیش‌روی در یادگیری تقویتی

مرجع: مراجع و واژه‌نامه

پرچم‌ها، متریک‌ها، رخدادها، اصطلاحات و منابع به‌کاررفته در این راهنما، همگی در یک‌جا.

  1. R.1فلگ‌ها و مقادیر پیش‌فرض
  2. R.2متریک‌ها
  3. R.3نمایه رخدادها
  4. R.4واژه‌نامه
  5. R.5منابع
  6. R.6فهرست شکل‌ها
  7. R.7نحوه‌ی تهیه‌ی این راهنما