بخش 1.1 · شروع

نصب SGLang و سرو اولین مدل

Install SGLang and serve your first model

فهرست مطالب
  1. پیش‌نیازها
  2. بررسی کارت گرافیک
  3. نصب SGLang
  4. با Docker
  5. با uv
  6. راه‌اندازی سرور
  7. اگر سرور اجرا نشد
  8. ارسال درخواست با curl
  9. ارسال همان پرسش از طریق API سازگار با OpenAI
  10. متوقف کردن سرور
  11. روی مک‌های مجهز به اپل سیلیکون

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

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

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

پیش‌نیازها

  • لینوکس با یک کارت گرافیک انویدیا و درایور سازگار با CUDA 13. نسخه‌ی SGLang 0.5.22 چرخ‌ها (wheels) و ایمیج‌های خود را فقط برای CUDA 13 منتشر می‌کند {{docs}}.
  • 24 گیگابایت حافظه‌ی گرافیکی (VRAM) برای مدلی که در این بخش استفاده می‌کنیم، یعنی Qwen/Qwen3-8B. اگر حافظه‌ی کمتری دارید، از Qwen/Qwen3-0.6B استفاده کنید؛ مراحل کار تغییری نمی‌کند و فقط عددهای خروجی تفاوت خواهند داشت.
  • حدود 16 گیگابایت فضای خالی روی دیسک برای وزن‌های Qwen/Qwen3-8B.
  • ابزار Docker به‌همراه NVIDIA Container Toolkit، یا پایتون 3.11 یا بالاتر به‌همراه uv.

تمام خروجی‌های این بخش را روی یک کارت گرافیک NVIDIA L4 با حافظه‌ی 24 گیگابایت ثبت کرده‌ایم. در کنار هر خروجی، نام فایل ضبط‌شده آمده است تا بتوانید اجرای خود را خط‌به‌خط با مال ما مقایسه کنید.

بررسی کارت گرافیک

ابتدا بررسی کنید که درایور کارت گرافیک را شناسایی می‌کند:

nvidia-smi

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

نصب SGLang

یکی از این دو مسیر را انتخاب کنید: اگر روی ماشین فقط درایور گرافیک نصب است، از Docker استفاده کنید؛ اما اگر ماشین از پیش به مجموعه‌ی کامل ابزارهای CUDA (از جمله nvcc) مجهز است، سراغ uv بروید.

روی یک ماشین با گرافیک L4 که فقط درایور داشت، دستور pip install sglang==0.5.22 بدون خطا اجرا شد؛ اما سرور در چهار تلاش اول برای راه‌اندازی با شکست روبه‌رو شد که هر بار به‌دلیل نبود یکی از بخش‌های جعبه‌ابزار CUDA بود. در بخش 7.1 این چهار خطا و راه رفع هرکدام را آورده‌ایم.

با Docker

ایمیج مربوط به نسخه‌ای را که در این راهنما تست شده است دریافت (pull) کنید:

docker pull lmsysorg/sglang:v0.5.22

ما تگ نسخه را قفل (pin) کرده‌ایم. تگ latest با انتشار هر نسخه‌ی جدید جابه‌جا می‌شود و نسخه‌های تازه ممکن است پیش‌فرض‌ها را تغییر دهند.

با uv

یک محیط مجازی بسازید و SGLang را با نسخه‌ی مشخص نصب کنید:

uv venv --python 3.12
source .venv/bin/activate
uv pip install --prerelease=allow "sglang==0.5.22"

فلگ --prerelease=allow را دست‌نخورده باقی بگذارید. برخی از وابستگی‌های SGLang فقط نسخه‌های پیش‌انتشار دارند و بدون این فلگ، نسخه‌های قدیمی‌تر uv بدون هیچ هشداری SGLang 0.5.9 را نصب می‌کنند {{docs}}.

اکنون نسخه را بررسی کنید:

sglang version
نسخه نصب‌شده capture/gpu/out-gb10/sglang-version.txt
$ sglang version
sglang version: 0.5.22
git revision: N/A

اگر نسخه‌ی متفاوتی می‌بینید، فرایند نصب نسخه‌ی دیگری را انتخاب کرده است. دستور نصب را دوباره همراه با قفل کردن نسخه اجرا کنید.

راه‌اندازی سرور

سرور را در همان محیطی که SGLang را نصب کرده‌اید بالا بیاورید. این همان دستوری است که ما در اجرای ثبت‌شده‌ی خود روی کارت L4 به کار برده‌ایم:

sglang serve --model-path Qwen/Qwen3-8B --host 127.0.0.1 --port 30000 \
  --enable-cache-report --enable-metrics --mem-fraction-static 0.85

اگر از Docker استفاده می‌کنید، همین سرور را داخل کانتینر اجرا کنید. کشِ Hugging Face را هم مانت کنید تا وزن‌ها فقط یک بار دانلود شوند:

docker run --rm --gpus all --ipc=host --shm-size 32g -p 127.0.0.1:30000:30000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  lmsysorg/sglang:v0.5.22 \
  sglang serve --model-path Qwen/Qwen3-8B --host 0.0.0.0 --port 30000 \
  --enable-cache-report --enable-metrics --mem-fraction-static 0.85

ما از مسیر uv پیش رفتیم. دستور Docker مطابق با راهنمای رسمی نصب SGLang تنظیم شده است {{docs}}. گزینه‌ی --host 0.0.0.0 به این دلیل استفاده شده که پورت باید خارج از کانتینر در دسترس باشد؛ اما پیشوند 127.0.0.1: در آرگومان -p این پورت را فقط به ماشین خودتان محدود می‌کند. از آنجا که سرور هیچ کلید API ندارد، آن را روی اینترفیس شبکه‌ی عمومی منتشر نکنید.

سه فلگ در این دستور به انتخاب ما اضافه شده‌اند:

  • --enable-cache-report فیلد cached_tokens را به تمام پاسخ‌ها اضافه می‌کند. بدون آن، کلاینت نمی‌تواند موارد اصابت به کش (cache hits) مربوط به درخواست خود را ببیند.
  • --enable-metrics اندپوینت /metrics را فعال می‌کند که در بخش 1.2 بررسی‌اش می‌کنیم.
  • --mem-fraction-static 0.85 تعیین می‌کند چه مقدار از حافظه‌ی گرافیکی در اختیار SGLang قرار گیرد. بخش 3.2 نشان می‌دهد چطور این مقدار را تعیین کنید.

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

خطوط راه‌اندازی سرور L4 ما capture/gpu/out-l4/server-default.log
[2026-10-17 14:42:45] KV Cache is allocated. dtype: torch.bfloat16, #tokens: 22939, K size: 1.58 GB, V size: 1.58 GB
…
[2026-10-17 14:43:36] max_total_num_tokens=22939, chunked_prefill_size=4096, max_prefill_tokens=16384, max_running_requests=2048, context_len=40960, available_gpu_mem=1.31 GB
…
[2026-10-17 14:43:36] Tree cache initialized: source=default impl=UnifiedRadixCache hybrid_swa=False hybrid_ssm=False hicache_attached=False
[2026-10-17 14:43:37] Engine startup timings (s): load_weight=3.73, kv_cache_allocation=0.40, scheduler_e2e=59.11, cuda_graph={prefill=48.33, decode=2.61, target_verify=0.00, draft_prefill=0.00, draft_decode=0.00, draft_extend=0.00}, tokenizer_e2e=69.10
…
[2026-10-17 14:43:38] The server is fired up and ready to roll!

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

وزن‌های مدل از قبل روی دیسک ما ذخیره بودند، بنابراین بارگذاری آن‌ها 3.73 ثانیه طول کشید. با این حال راه‌اندازی کامل حدود یک دقیقه زمان برد که بخش عمده‌ی آن، یعنی 48.33 ثانیه، صرف ثبت گراف‌های CUDA (یا CUDA graphs) برای فاز پیش‌پرکنی (prefill) شد. در اجراهای بعدی روی همین ماشین، کرنل‌های کامپایل‌شده از مسیر ~/.cache/sglang بازاستفاده خواهند شد.

اگر سرور اجرا نشد

آخرین خط خطای لاگ را بخوانید و علت را در میان موارد زیر بیابید:

  • لاگ به Python.h، nvcc یا -lcudart اشاره می‌کند. جعبه‌ابزار کامل CUDA روی سیستم میزبان وجود ندارد. سراغ مسیر Docker بروید یا چهار راهکار بخش 7.1 را پیاده کنید.
  • لاگ می‌گوید حافظه‌ی گرافیکی پر شده است (out of memory). مدل و کش آن در حافظه جا نمی‌شوند. مقدار --mem-fraction-static را کم کنید یا سراغ مدل کوچک‌تری بروید. در بخش 3.2 این کرش و نحوه‌ی حل آن را نشان داده‌ایم.
  • دانلود با خطا مواجه می‌شود. وضعیت شبکه و نام مدل را بررسی کنید. اگر متغیر HF_HUB_OFFLINE=1 تنظیم شده باشد، مدل باید حتماً از قبل داخل کش موجود باشد.
  • برنامه‌ی دیگری در حال استفاده از پورت 30000 است. سرور را با --port 30001 اجرا کنید و در تمام درخواست‌های بعدی نیز همین پورت را به کار ببرید.

ارسال درخواست با curl

یک ترمینال دوم باز کنید و به API بومیِ SGLang درخواستی بفرستید:

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}}'

سرور L4 ما چنین پاسخی داد:

پاسخ از API بومی capture/gpu/out-l4/generate.txt
  "text": " Paris. The capital of Italy is Rome. The capital of",
…
  "meta_info": {
…
    "finish_reason": {
      "type": "length",
      "length": 12
…
    "prompt_tokens": 5,
…
    "completion_tokens": 12,
    "cached_tokens": 2,
…
    "e2e_latency": 0.7252887019421905,

برش‌خورده از پاسخ generate/. شناسه‌های توکن، شناسه درخواست و فیلدهای زمانی به‌جز e2e_latency حذف شده‌اند.

با ضریب دمای (temperature) صفر، متن خروجی شما با مدل Qwen/Qwen3-8B کلمه‌به‌کلمه با خروجی ما برابر خواهد بود. پاسخ دقیقاً پس از 12 توکن متوقف شده است، چون ما 12 توکن خواسته بودیم و فیلد finish_reason نیز مقدار length را نشان می‌دهد.

دو توکن از پنج توکنِ پرامپت از قبل داخل کش بودند. سرور هنگام بالا آمدن، پرامپت «The capital city of France is» را برای خودش ارسال کرده تا گرم شود؛ و چون دو توکن اول پرامپت ما با آن پرامپتِ گرم‌سازی یکی بود، سیستم کش پیشوند از پردازش مجدد آن‌ها صرف‌نظر کرد.

ارسال همان پرسش از طریق API سازگار با OpenAI

بیشتر کلاینت‌ها از API چت OpenAI استفاده می‌کنند و SGLang نیز آن را روی همان پورت ارائه می‌دهد. ابتدا با curl یک درخواست چت بفرستید:

curl -s http://127.0.0.1:30000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model": "default", "messages": [{"role": "user", "content": "Name one planet. Answer in one word."}], "max_tokens": 64, "temperature": 0, "chat_template_kwargs": {"enable_thinking": false}}'
پاسخ از API چت OpenAI capture/gpu/out-l4/generate.txt
  "model": "default",
…
      "message": {
        "role": "assistant",
        "content": "Earth",
…
      "finish_reason": "stop",
…
  "usage": {
    "prompt_tokens": 21,
    "total_tokens": 23,
    "completion_tokens": 2,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "reasoning_tokens": 0

برش‌خورده از پاسخ v1/chat/completions/. شناسه، برچسب زمانی و بلوک متادیتا حذف شده‌اند.

پرسش هفت کلمه دارد و به 21 توکنِ پرامپت تبدیل شده است. الگوی چت (chat template) نشانگرهای نقش را دور پیام اضافه می‌کند، بنابراین هنگام برنامه‌ریزی برای طول زمینه (context length) این توکن‌ها را به حساب بیاورید. گزینه‌ی "enable_thinking": false حالت تفکر مدل Qwen3 را خاموش می‌کند؛ به همین دلیل پاسخ تک‌کلمه‌ای است و فیلد reasoning_tokens عدد 0 را نشان می‌دهد.

اکنون همین درخواست را از داخل پایتون و با کلاینت OpenAI ارسال کنید:

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:30000/v1", api_key="none")
response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "Name one planet. Answer in one word."}],
    max_tokens=64,
    temperature=0,
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)
print(response.choices[0].message.content)

این اسکریپت فیلد content پاسخ را چاپ می‌کند. در تستی که ثبت کردیم، همین بدنه‌ی JSON را با کتابخانه‌ی استاندارد پایتون فرستادیم و کلمه‌ی Earth را تحویل گرفتیم. از آنجا که فلگ --api-key روی سرور تنظیم نشده است، SGLang کلید را بررسی نمی‌کند و هر مقداری کار می‌کند.

متوقف کردن سرور

برای توقف سرور، در ترمینال آن کلیدهای Ctrl+C را فشار دهید {{docs}}. در محیط عملیاتی (production)، سیگنال توقف را تنها به فرایند اصلی بفرستید. در بخش 7.1 علت این موضوع را توضیح داده‌ایم.

روی مک‌های مجهز به اپل سیلیکون

SGLang با تکیه بر بک‌اند MLX روی تراشه‌های اپل سیلیکون نیز اجرا می‌شود. برای این کار به macOS 14 یا بالاتر و حدود 8 گیگابایت فضای خالی دیسک نیاز دارید. SGLang را همراه با اکستراهای MLX از روی تگ نسخه نصب کنید:

git clone --branch v0.5.22 --depth 1 https://github.com/sgl-project/sglang.git
cd sglang
uv venv -p 3.12 .venv && source .venv/bin/activate
cp python/pyproject_other.toml python/pyproject.toml
uv pip install -e "python[srt_mps]"

روی مک ما فرایند نصب 3 دقیقه و 15 ثانیه طول کشید. سرور را با یک مدل کوچک 4 بیتی راه بیندازید:

SGLANG_USE_MLX=1 sglang serve --model-path mlx-community/Qwen3-0.6B-4bit \
  --disable-cuda-graph --enable-cache-report --mem-fraction-static 0.4

سپس همان درخواست /generate بالا را ارسال کنید. مک ما چنین پاسخی داد: « Paris, and the capital of Germany is Berlin. The capital». مدل کوچک‌تر متن متفاوتی تولید می‌کند، اما تعداد توکن‌ها تغییری نخواهد کرد. اگر از مک خود همزمان برای کارهای دیگر هم استفاده می‌کنید، حتماً فلگ --mem-fraction-static را تنظیم کنید. در بخش 3.2 خطایی را که بدون تنظیم این مقدار رخ داد نشان داده‌ایم.

منابع: capture/gpu/out-gb10/sglang-version.txt، capture/gpu/out-l4/server-default.command.txt، capture/gpu/out-l4/server-default.log، capture/gpu/out-l4/generate.txt، capture/gpu/out-l4/environment.json، capture/one_request.py، capture/gpu/incidents/l4-toolchain-failures.txt، capture/out/generate.txt؛ docs/docs/get-started/install.mdx و docs/docs/get-started/quickstart.mdx در نسخه‌ی v0.5.22؛ docs/docs/hardware-platforms/apple_metal.mdx و python/pyproject_other.toml در نسخه‌ی v0.5.22.

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