مرجع R.7

نحوه‌ی تهیه‌ی این راهنما

How this manual was made

فهرست مطالب
  1. نسخه
  2. رتبه‌بندی منابع
  3. چهار نوع شواهد
  4. ابزار ثبت روی Mac
  5. ابزار ثبت روی GPU
  6. قواعد نگارشی و علائم

این صفحه نسخه، منابع، ماشین‌ها و ابزارهای ثبت نتایج را که پشت تک‌تک فکت‌ها و اعداد این راهنما قرار دارند، مستند می‌کند.

نسخه

این راهنما بر پایه‌ی نسخه‌ی SGLang 0.5.22 نوشته شده که در تاریخ 2026-10-13 با تگ commit به شناسه‌ی baa9befa381511cd4d56f83980951e5a45fffc6d منتشر شد. فکت‌ها در تاریخ 2026-10-16 اعتبارسنجی شده‌اند. نسخه‌های جدید SGLang تقریباً هر سه هفته یک‌بار منتشر می‌شوند و چندین مقدار پیش‌فرض بین 0.5.20 و 0.5.22 تغییر کرده‌اند. دستورالعملی که برای نسخه‌ای قدیمی‌تر نوشته شده باشد ممکن است در این نسخه اشتباه باشد، و بخش‌های مختلف راهنما مشخص کرده‌اند که این تفاوت‌ها کجاست.

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

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

رتبه منبع آنچه راهنما از آن می‌گیرد شیوه‌ی ارجاع
1 کد منبع SGLang در تگ مربوطه، baa9befa تمام مقادیر پیش‌فرض و سازوکارها فهرست فایل‌ها در خط Sources در پایان هر بخش
2 اجراهای ثبت‌شده روی Mac و روی پردازنده‌های گرافیکی تمام قطعه‌کدها و اعدادی که با عنوان سنجیده‌شده مشخص شده‌اند نام فایل ثبت نتایج
3 ایشوها و پول‌ریکوئست‌های SGLang رخدادها و تاریخچه‌ی طراحی هر قابلیت واژه‌ی issue به همراه شماره‌ی آن
4 مقاله‌های علمی طراحی اولیه‌ی توجه رادیکس (RadixAttention) و روش‌هایی که SGLang پیاده‌سازی کرده است واژه‌ی paper به همراه عنوان مقاله
5 مستندات SGLang در تگ مربوطه رفتارهای مستندشده، پس از تطبیق با کد منبع واژه‌ی docs به همراه عنوان سرفصل
6 گزارش‌های میدانی مستقل پیکربندی‌های مبتنی بر چند GPU که امکان اجرای آن‌ها را نداشتیم، مانند چندین پردازنده‌ی گرافیکی در یک سرور واژه‌ی field، نام نویسنده و ماه
7 گزارش‌های تیم SGLang و ارائه‌دهندگان سخت‌افزار ادعاها، که همیشه با برچسب ادعای نویسنده مشخص می‌شوند واژه‌ی team یا نام ارائه‌دهنده و ماه

اینکه مستندات رتبه‌ای پایین‌تر از کد منبع دارند، تصمیمی آگاهانه است. در نسخه‌ی 0.5.22، مستندات رسمی هنوز دو بک‌اند اتنشن (Attention) را فهرست می‌کنند که از کد منبع حذف شده‌اند. همچنین مهلت‌های زمانی پیش‌واکشی HiCache در مستندات با مقادیر مورد استفاده در کد متفاوت است. هر جا واژه‌ی پیش‌فرض را به کار می‌بریم، منظور مقداری است که در کد منبع تنظیم شده است.

چهار نوع شواهد

تمام اعدادی که در این راهنما می‌بینید، با یکی از این چهار برچسب در متن مشخص شده‌اند:

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

کد منبع: این پیش‌فرض یا سازوکار مستقیماً از سورس‌کد SGLang در تگ اعلام‌شده استخراج شده است. خط Sources نام فایل‌ها را مشخص می‌کند.

گزارش میدانی: مهندس یا شرکتی خارج از تیم SGLang برنامه‌اش را اجرا کرده و نتایج را منتشر کرده است. در متن نام آن‌ها، ماه، شماره‌ی نسخه در زمان آزمایش، و مواردی که دستکاری و تنظیم کرده‌اند ذکر شده است.

گزارش تیم توسعه یا گزارش ارائه‌دهنده‌ی سخت‌افزار: این عدد توسط تیم SGLang، شرکت RadixArk یا یکی از تولیدکنندگان سخت‌افزار منتشر شده است. ما آن را به عنوان ادعای خود آن‌ها بازگو می‌کنیم و در صورت وجود نتایج مستقل، در کنار آن‌ها قرار می‌دهیم.

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

ابزار ثبت روی Mac

ابزار ثبت نتایج سرور واقعی SGLang را روی پردازنده‌ی Apple silicon از طریق بک‌اند MLX اجرا می‌کند؛ سپس درخواست‌ها را می‌فرستد، بنچمارک رسمی را اجرا می‌کند، و هر چه را که دریافت کرده در پوشه‌ی خروجی خود می‌نویسد. دستور python3 capture/run.py تمام اطلاعات را ثبت می‌کند. دستور python3 capture/run.py --check فرآیند را دوباره در یک دایرکتوری موقت تکرار می‌کند و فکت‌هایی را که نباید تغییر کنند می‌سنجد. این فکت‌ها شامل متن تولیدشده با دمای 0، تعداد کل توکن‌ها، توکن‌های کش‌شده، و تعداد کل درخواست‌ها است. حجم بایت‌های KV به ازای هر توکن و نام سنجه‌ها هم جزو این فکت‌ها به شمار می‌روند.

از آنجا که زمان‌بندی‌ها در هر بار اجرا تغییر می‌کنند، فرآیند بررسی آن‌ها را با هم مقایسه نمی‌کند.

این ابزار برای اجرا به SGLang 0.5.22 به همراه اکسترای MLX روی پردازنده‌های Apple silicon نیاز دارد؛ بنابراین امکان اجرای آن در CI مخزن وجود ندارد. بدون این پیکربندی، فلگ --check عبارت skipped را همراه با دلیل چاپ می‌کند و با کد 0 خارج می‌شود. تمامی فایل‌های مربوط به اجراهای Mac روی یک دستگاه ثبت شده‌اند:

مورد مقدار
میزبان لپ‌تاپ مجهز به پردازنده‌ی Apple silicon، سیستم‌عامل macOS 26.2، بیلد 25C56، معماری arm64
SGLang نسخه‌ی 0.5.22، نصب‌شده از تگ با اکسترای srt_mps
فریم‌ورک‌ها PyTorch 2.13.0، MLX 0.32.4، Python 3.12.12
مدل mlx-community/Qwen3-0.6B-4bit
فلگ‌های سرور SGLANG_USE_MLX=1، --disable-cuda-graph، --enable-cache-report، --enable-metrics، --mem-fraction-static 0.4
تاریخ ثبت 2026-10-16

این ابزار چهار سرور را راه‌اندازی می‌کند: پیکربندی پیش‌فرض، یک سرور بدون کش رادیکس، یک سرور بدون اسکژولر همپوشانی (overlap scheduler)، و سروری دیگر با استخر 4,096 توکنی. سرور بدون اسکژولر همپوشانی در نسخه‌ی 0.5.22 در اولین دسته‌ی واقعی خود کرش کرد، و این ابزار با هدف مستندسازی آن را ثبت کرده است. بخش 2.4 این مورد را بررسی می‌کند.

ابزار ثبت روی GPU

ابزار ثبت روی GPU همین ایده را روی پردازنده‌ی گرافیکی NVIDIA پیاده می‌کند. اسکریپت اجرای آن هشت پیکربندی مختلف از سرور را اجرا کرده و لاگ‌های اجرای GB10 را می‌نویسد. اسکریپت سوییپ هر نقطه‌ی بنچمارک را با سه سید مختلف تکرار می‌کند و فرکانس کاری و دمای GPU را در تمام اجراها ثبت می‌نماید. اسکریپت خلاصه‌سازی برای هر دستگاه یک فایل خلاصه می‌نویسد: داده‌های خلاصه‌ی GB10، داده‌های خلاصه‌ی L4، و داده‌های خلاصه‌ی L4 در وضعیت کاهش فرکانس. اسکریپت خلاصه‌سازی Miles نیز داده‌های خلاصه‌ی Miles را می‌نویسد. نمودارها اطلاعات خود را از این چهار فایل می‌خوانند.

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

تمامی لاگ‌های اجرای GB10 و فایل خلاصه‌ی داده‌های آن روی یک دستگاه ثبت شده‌اند:

مورد مقدار
میزبان سرور NVIDIA DGX Spark، سیستم‌عامل Ubuntu 24.04، معماری aarch64
پردازنده‌ی گرافیکی NVIDIA GB10 با قابلیت رایانش 12.1 و حافظه‌ی مشترک 121.7 GiB با پردازنده‌ی اصلی
SGLang نسخه‌ی 0.5.22 از مخزن PyPI، پکیج sglang-kernel 0.4.9، پکیج flashinfer 0.7.1
فریم‌ورک‌ها PyTorch 2.14.1+cu130، پلتفرم CUDA 13.0، درایور 580.159.03، پایتون 3.12.3
مدل‌ها Qwen/Qwen3-30B-A3B-Instruct-2507، چک‌پوینت FP8 آن، و مدل پیش‌نویس EAGLE-3 با شناسه‌ی lmsys/SGLang-EAGLE3-Qwen3-30B-A3B-Instruct-2507-SpecForge-Nex
فلگ‌های سرور --enable-cache-report، --enable-metrics، --mem-fraction-static 0.7
تاریخ ثبت 2026-10-16

این ابزار همچنین یک پروفایل l4 برای مدل Qwen3-8B روی کارت NVIDIA L4 دارد که لاگ‌های اجرای L4 و داده‌های خلاصه‌ی L4 حاصل اجرای آن هستند. بخش 1 برای قطعه‌کدهای خود از این سرور L4 استفاده می‌کند. در اولین اجرای سوییپ ما روی L4، کارت بیش از حد داغ شد و فرکانس کاری‌اش کاهش یافت (throttling رخ داد)، و بخش 5.1 این ماجرا را به عنوان یک رخداد شرح می‌دهد. پس از آن، بنچمارک L4 را دوباره و با خنک‌سازی کارت تا دمای 72 درجه‌ی سانتی‌گراد قبل از هر بار اجرا تکرار کردیم. بخش 4.3، بخش 4.4 و بخش 5.1 از این سری جدید اجراها استفاده می‌کنند؛ همچنین بخش 5.1 نشان می‌دهد که کارت حتی با وجود خنک‌سازی اولیه، باز هم زیر بار کاری طولانی فرکانس خود را پایین آورده است.

قواعد نگارشی و علائم

در تمام دستورها، سرور با sglang serve اجرا می‌شود. دستور قدیمی‌تر python -m sglang.launch_server هنوز در نسخه‌ی 0.5.22 کار می‌کند، اما یک هشدار منسوخ‌شدن چاپ خواهد کرد. پورت‌های پیش‌فرض برابر با 30000 هستند. در خروجی‌های ثبت‌شده، علامت ~ نشان‌دهنده‌ی پوشه‌ی خانگی است.

ارجاع‌ها مشخص می‌کنند که موضوع دقیقاً کجا ثبت شده است. عبارت {{issue #35129}} به یک ایشو در مخزن SGLang اشاره دارد. عبارت {{field Jarvislabs 2026-05}} به یک گزارش میدانی با ذکر نام نویسنده و ماه آن ارجاع می‌دهد و در متن لینک شده است. فایل‌های منبع SGLang که هر بخش بر اساس آن‌ها تدوین شده، یک‌بار در خط Sources در انتهای همان بخش فهرست شده‌اند. قطعه‌کدها خطوط فایل‌های ثبت را عیناً کپی کرده‌اند و علامت … نشان‌دهنده‌ی بخش‌های حذف‌شده‌ای است که در یادداشت توضیح داده شده است.

تصاویر روی وب متحرک هستند، و کلید بازپخش مراحل را دوباره نشان می‌دهد. در نسخه‌ی چاپی و در صورت فعال بودن گزینه‌ی کاهش حرکت (reduced motion)، فریم نهایی نمایش داده می‌شود.

منابع: manual.json؛ capture/README.md؛ capture/run.py؛ capture/gpu/run.py، capture/gpu/sweep.py، capture/gpu/summarize.py، capture/gpu/summarize_miles.py، capture/gpu/out-gb10/environment.json، capture/gpu/out-l4/environment.json؛ capture/out/environment.json، server-no-overlap.log.

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