مرجع R.1

فلگ‌ها و مقادیر پیش‌فرض

Flags and defaults

فهرست مطالب
  1. حافظه و پذیرش درخواست
  2. زمان‌بندی
  3. کش
  4. اجرا
  5. موازی‌سازی و عملیات سرور

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

دستور sglang serve --help در نسخه‌ی 0.5.22 شامل 535 گزینه‌ی مختلف است (خروجی ذخیره‌شده‌ی help). بیشتر این گزینه‌ها هرگز به کارتان نمی‌آیند. جدول زیر مهم‌ترین مواردی را نشان می‌دهد که در این راهنما استفاده شده‌اند. در بخش‌های مختلف، به چند فلگ دیگر هم بر اساس نیاز اشاره می‌کنیم.

مقدار پیش‌فرض بسیاری از این فلگ‌ها در کد None است. یک هوک راه‌اندازی (startup hook) بر اساس GPU، مدل و حافظه‌ی آزاد سیستم، مقدار مناسبی جایگزین آن‌ها می‌کند. ستون «روی مک ما» مقدار تعیین‌شده را از خط server_args در لاگ سرور پیش‌فرض نشان می‌دهد.

حافظه و پذیرش درخواست

فلگ پیش‌فرض در کد روی مک ما چه زمانی تغییرش دهیم؟ بخش
--mem-fraction-static None، هنگام راه‌اندازی بر اساس ظرفیت GPU محاسبه می‌شود 0.4، تنظیم‌شده توسط کیت برنامه‌های دیگری هم‌زمان روی ماشین اجرا می‌شوند، یا سرور در دسته‌های (batch) بزرگ کرش می‌کند 3.2
--max-total-tokens None، بر اساس بودجه‌ی حافظه محاسبه می‌شود 181,574 توکن در استخر حافظه اندازه‌ی ثابتی برای استخر حافظه در سناریوی تست می‌خواهید 2.3
--max-running-requests None، بر اساس استخر حافظه و طول زمینه (context length) محاسبه می‌شود 4,096 سقف همروندی را می‌دانید، یا دیکودینگ حدسی (speculative decoding) را فعال می‌کنید 2.3
--chunked-prefill-size None، بر اساس حافظه‌ی GPU محاسبه می‌شود 4,096 پرامپت‌های طولانی فاز رمزگشایی (decode) را متوقف می‌کنند، یا پیش‌پرکنی (prefill) بیش از حد کند است 2.2
--max-prefill-tokens 16,384 16,384 به‌ندرت 2.2
--schedule-conservativeness 1.0 1.0 در لاگ‌ها ابطال (retraction) می‌بینید؛ در این حالت مقدار را افزایش دهید 2.3
--page-size None، بر اساس بک‌اند اتنشن تعیین می‌شود 1 بک‌اند اتنشن (attention) به ساختار صفحه‌بندی‌شده نیاز دارد 3.1

زمان‌بندی

فلگ پیش‌فرض در کد روی مک ما چه زمانی تغییرش دهیم؟ بخش
--schedule-policy fcfs fcfs درخواست‌های زیادی در صف پیشوندهای طولانی مشترک دارند؛ در این صورت lpm را امتحان کنید 2.2
--disable-overlap-schedule False False فقط برای خطایابی، و هرگز روی MLX در نسخه‌ی 0.5.22 که باعث کرش می‌شد 2.4
--stream-interval 1 1 خروجی را برای کلاینت‌های متعددی استریم می‌کنید و می‌خواهید تعداد پیام‌ها کمتر باشد 2.5

کش

فلگ پیش‌فرض در کد روی مک ما چه زمانی تغییرش دهیم؟ بخش
--disable-radix-cache False False فقط برای سنجش عملکرد کش، مثل کاری که در کیت انجام دادیم 3.3
--radix-eviction-policy lru lru تعداد کمی از پیشوندها بسیار پرکاربرد و بیشتر آن‌ها کم‌کاربرد هستند 3.5
--enable-hierarchical-cache off off مجموعه‌ی پیشوندهای فعال از حافظه‌ی GPU بزرگ‌تر است 3.5
--kv-cache-dtype auto auto به زمینه‌ی طولانی‌تری روی هر GPU نیاز دارید و می‌توانید کیفیت خروجی را بسنجید 4.3
--enable-cache-report False True، تنظیم‌شده توسط کیت همیشه؛ تا کلاینت‌ها مقدار cached_tokens را ببینند 3.4

اجرا

فلگ پیش‌فرض در کد روی مک ما چه زمانی تغییرش دهیم؟ بخش
--attention-backend None، متناسب با هر GPU و مدل انتخاب می‌شود torch_native، که MLX از آن استفاده نمی‌کند بک‌اند بهینه‌تری را برای مدل خود ارزیابی و پیدا کرده‌اید 4.2
--grammar-backend None، که به xgrammar تبدیل می‌شود xgrammar کامپایل یک گرامر ناموفق است 4.5
--disable-cuda-graph (منسوخ‌شده) False True، همان‌طور که دستورالعمل‌های اپل می‌گویند روی تراشه‌های اختصاصی اپل (Apple silicon) که گراف‌های CUDA وجود ندارند. ترجیحاً از --cuda-graph-backend-decode disabled و --cuda-graph-backend-prefill disabled استفاده کنید 4.1
--speculative-algorithm None None تاخیر (latency) فاز رمزگشایی در همروندی‌های پایین بیشترین اهمیت را دارد 4.4
--enable-deterministic-inference False False برای ورودی یکسان در هر دسته‌ای به خروجی قطعی (deterministic) نیاز دارید 4.6

فلگ --disable-cuda-graph در نسخه‌ی 0.5.22 هنوز کار می‌کند، ولی فلگ‌های تفکیک‌شده‌ی فازها یعنی --cuda-graph-backend-decode و --cuda-graph-backend-prefill جایگزین آن شده‌اند.

موازی‌سازی و عملیات سرور

فلگ پیش‌فرض در کد روی مک ما چه زمانی تغییرش دهیم؟ بخش
--tp-size 1 1 وزن‌های مدل در یک GPU جا نمی‌شوند 6.1
--dp-size 1 1 ظرفیت یک نسخه از مدل اشباع شده و GPU کافی برای اجرای یک نسخه‌ی دیگر دارید 6.1
--attn-dp-size 1 1 یک مدل مبتنی بر MLA (مثل DeepSeek) را روی چندین GPU اجرا می‌کنید 6.1
--ep-size 1 1 یک مدل بزرگ MoE را سرو می‌کنید 6.2
--enable-metrics False True، تنظیم‌شده توسط کیت همیشه در محیط عملیاتی (production) 5.2
--watchdog-timeout 300 s 300 s یک گذر رو به جلو (forward pass) ممکن است بیش از پنج دقیقه طول بکشد 7.1

منابع: فایل‌های python/sglang/srt/arg_groups/fields/schedule.py، memory.py، exec_.py، model.py، parallel.py، spec.py، serving.py، observability.py و device.py در نسخه‌ی v0.5.22؛ فایل‌های capture/out/serve-help.txt، server-default.log و server-small-pool.log.

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