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 با استفاده از تبادلات ثبتشده در تستهایمان، سبکهای مختلف فلشها آموزش داده شده است.
منابع: 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.