بخش 6.4 · تبدیل یک سرور به یک ناوگان

ابزار sgl-model-gateway و مسیریابی آگاه از کش

sgl-model-gateway and cache-aware routing

فهرست مطالب
  1. دو نقطه‌ای که درخواست‌ها در آن‌ها مسیریابی می‌شوند
  2. شیوه‌ی انتخاب سرور در سیاست cache_aware
  3. درخت فقط یک تخمین است
  4. تنظیمات مهم
  5. توصیه‌ی ما
  6. پین کردن هم‌زمان مسیریاب و موتور پردازش
  7. چه چیزهایی را اندازه بگیریم

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

برای دو برابر کردن ظرفیت، سرور دومی راه می‌اندازید. نرخ پردازش (Throughput) بالا می‌رود، اما زمان تا اولین توکن (TTFT) برای گفت‌وگوهای طولانی بدتر می‌شود. هر سرور کش کلید-مقدار (KV cache) اختصاصی خودش را دارد و نوبت پنجم یک چت به سروری هدایت می‌شود که نوبت‌های 1 تا 4 را اصلاً ندیده است. آن سرور مجبور می‌شود کل تاریخچه را دوباره پیش‌پرکنی (prefill) کند. در بخش 3.4 هزینه‌ی خطای کشِ پیشوند (prefix miss) روی یک سرور را اندازه گرفتیم. مسیریابی که پیشوندها را نادیده بگیرد، عملاً همین خطا را به شکل عمدی تکرار می‌کند.

پس از پایان این بخش، می‌توانید سازوکار انتخاب سرور برای هر درخواست توسط sgl-model-gateway را توضیح دهید. همچنین می‌توانید سیاست مسیریابی مناسبی برای ترافیک کاری‌تان انتخاب کنید و مطمئن شوید که درگاه، نرخ اصابت کش شما را حفظ می‌کند.

دو نقطه‌ای که درخواست‌ها در آن‌ها مسیریابی می‌شوند

در SGLang، درخواست‌ها در دو نقطه‌ی متفاوت و با مقادیر پیش‌فرض مختلف مسیریابی می‌شوند.

درون یک سرور واحد: اگر مقدار --dp-size بیشتر از 1 باشد، کنترل‌کننده‌ی موازی‌سازی داده (data parallel controller) درخواست‌ها را بین نسخه‌ها توزیع می‌کند. روش پیش‌فرض آن، یعنی auto، در حالتی که جداسازی وجود نداشته باشد به round_robin تبدیل می‌شود {{code}}. همان‌طور که در شکل 6.1b می‌بینید، روش نوبت‌گردشی (round robin) پیشوندها را کاملاً نادیده می‌گیرد.

در ورودی سرورها: ابزار sgl-model-gateway یک برنامه‌ی مستقل به زبان Rust است که درخواست‌ها را بین چندین سرور SGLang توزیع می‌کند. این ابزار قبلاً sgl-router نام داشت تا اینکه در تاریخ 2025-12-05 با pull request شماره‌ی #14312 برای «کاهش ابهام» تغییر نام پیدا کرد. سیاست پیش‌فرض آن cache_aware است {{code}}.

یک گزارش میدانی این تفاوت را به‌خوبی نشان می‌دهد. تیم Jarvislabs متوجه شد که مسیریابی پیش‌فرض، هر درخواست را به‌نوبت به پردازنده‌ی گرافیکی بعدی می‌فرستد؛ بدون توجه به این‌که کشِ آن گفت‌وگو کجاست {{field Jarvislabs 2026-08}}.

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

شیوه‌ی انتخاب سرور در سیاست cache_aware

این درگاه برای هر مدل یک درخت مبنای (Radix Tree) تقریبی نگهداری می‌کند. در هر گره‌ی درخت ثبت می‌شود که کدام سرورها آن پیشوند را دیده‌اند. این درخت کاراکترهای متن درخواست را ذخیره می‌کند، نه توکن‌ها را؛ بنابراین درگاه برای مسیریابی هیچ نیازی به اجرای توکنایزر ندارد {{code}}.

نرخ تطابق (Match rate): نسبت تعداد کاراکترهای درخواست جدید که با درخت همخوانی دارند، به طول کل درخواست.

نحوه انتخاب سرور توسط cache_awareدرگاه ابتدا تعادل بار را بررسی می‌کند، سپس درخواست را تنها در صورتی به سروری با طولانی‌ترین تطابق می‌فرستد که بیش از 30 درصد متن آن منطبق باشد.
نحوه انتخاب سرور توسط cache_aware جریان تصمیم‌گیری. ابتدا درگاه بررسی می‌کند که آیا بارها نامتعادل هستند یا خیر: اختلاف شلوغ‌ترین و خلوت‌ترین سرور بیش از 64 باشد و بار شلوغ‌ترین بیش از 1.5 برابر خلوت‌ترین باشد. در صورت بله، درخواست به کم‌بارترین سرور هدایت می‌شود. در صورت خیر، درگاه نرخ تطابق را در برابر درخت کاراکتری خود محاسبه می‌کند. بالاتر از 0.3، درخواست به سروری با بیشترین تطابق ارسال می‌شود. در 0.3 یا کمتر، به کم‌بارترین سرور می‌رود. در هر صورت، متن درخواست داخل درخت درج می‌شود. متن درخواست نامتعادل است؟ max - min > 64 و max > 1.5 x min نرخ تطابق > 0.3؟ کاراکترهای منطبق / کاراکترهای درخواست کم‌بارترین سرور بیشترین تطابق سرور در درخت کم‌بارترین انتخاب تصادفی در برابری بله no بله no گام 1 گام 2 گام 3 هر خروجی متن درخواست را زیر سرور انتخاب‌شده درج می‌کند
از بالا به پایین بخوانید. کادرهای کهربایی آزمون‌ها، کادرهای آبی خروجی‌ها هستند و هر دو خروجی متن درخواست را در درخت درج می‌کنند. مقادیر پیش‌فرض از خط فرمان درگاه در نسخه v0.5.22 گرفته شده است.

برای هر درخواست، تابع select_worker سه مرحله را طی می‌کند {{code}}:

  1. بررسی تعادل بار: اگر دو شرط برقرار باشد، سیستم نامتعادل شناخته می‌شود: بار شلوغ‌ترین سرور بیش از 64 واحد بیشتر از خلوت‌ترین سرور باشد، و در عین حال بار آن بیش از 1.5 برابر خلوت‌ترین سرور باشد. در این حالت، درخواست مستقیماً به خلوت‌ترین سرور می‌رود.
  2. در غیر این صورت، نرخ تطابق را محاسبه می‌کند. اگر این نرخ بالاتر از 0.3 باشد، درخواست به سروری می‌رود که طولانی‌ترین تطابق را دارد.
  3. اگر نرخ تطابق کمتر از 0.3 باشد، درخواست به خلوت‌ترین سرور فرستاده می‌شود و در صورت برابری، یکی از آن‌ها به‌تصادف انتخاب می‌گردد.

سپس درگاه متن درخواست را ذیل سرورِ انتخاب‌شده وارد درخت می‌کند. هر 120 ثانیه یک‌بار، وظیفه‌ای در پس‌زمینه برگ‌هایی را که کمتر از بقیه اخیراً استفاده شده‌اند (LRU) حذف می‌کند تا حجم هر درخت حداکثر 67,108,864 گره بماند {{code}}.

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

درخت فقط یک تخمین است

درگاه هرگز از سرورها نمی‌پرسد چه چیزی را در کش نگه داشته‌اند. درختِ آن فقط مقصد متن‌های قبلی را ثبت می‌کند، در حالی که ممکن است سرور بعداً آن پیشوند را از حافظه‌اش پاک کرده باشد. بنابراین احتمال دارد درگاه درخواستی را به سروری بفرستد که دیگر پیشوند را ندارد؛ در نتیجه این درخواست مثل هر خطای کش دیگری از نو پیش‌پرکنی می‌شود. پس علاوه‌بر تصمیم‌های مسیریابی، حتماً نرخ اصابت را روی خود سرورها و با معیار sglang:cache_hit_rate (معرفی‌شده در بخش 5.2) زیر نظر بگیرید.

تنظیمات مهم

فلگ مقدار پیش‌فرض عملکرد
--policy cache_aware گزینه‌های دیگر: random، round_robin، power_of_two، prefix_hash، manual
--cache-threshold 0.3 آستانه‌ی نرخ تطابق که از آن به بعد ترجیحِ پیشوند برنده می‌شود
--balance-abs-threshold 64 اختلاف باری که سیستم را نامتعادل نشان می‌دهد
--balance-rel-threshold 1.5 نسبت باری که سیستم را نامتعادل نشان می‌دهد
--eviction-interval 120 فاصله‌ی زمانی پاک‌سازی درخت (بر حسب ثانیه)
--max-tree-size 67108864 سقف تعداد گره‌های نگهداری‌شده به‌ازای هر مدل
--prometheus-port 29000 متریک‌های اختصاصی خود درگاه
--request-timeout-secs 1800 حداکثر زمانی (ثانیه) که درگاه منتظر یک درخواست می‌ماند

تمامی مقادیر پیش‌فرض از سورس درگاه در نگارش v0.5.22 برداشته شده‌اند {{code}}. در آن سورس، نگارش 0.3.2 ذکر شده است. جدیدترین برچسب درگاه در مخزن، gateway-v0.3.1، به یک commit در تاریخ 2026-01-08 اشاره دارد. نگارش درگاه را بر اساس همان commit اجرایی خود پین کنید، نه با آن برچسب.

سورس برنامه شامل سیاست‌های bucket و consistent_hashing نیز هست، اما خط فرمان در نگارش v0.5.22 آن‌ها را قبول نمی‌کند. برای دو سرور ساده، دستور راه‌اندازی به این صورت است: python -m sglang_router.launch_router --worker-urls http://127.0.0.1:30000 http://127.0.0.1:30001 --policy cache_aware.

توصیه‌ی ما

برای ترافیک چت و ایجنت که نوبت‌های گفت‌وگو در آن‌ها پیشوندهای طولانی مشترک دارند، از cache_aware استفاده کنید. برای ترافیک‌های دسته‌ای (batch) با پرامپت‌های یکتا، سیاست power_of_two یا round_robin را برگزینید؛ زیرا وقتی نرخ تطابق زیر 0.3 باشد، چسبندگی پیشوند عملاً اعمال نمی‌شود. ترافیک‌های چندنوبتی را پشت فلگ --dp-size درون سرور که رفتار پیش‌فرض نوبت‌گردشی دارد قرار ندهید. در عوض سرورهای جداگانه پشت درگاه راه بیندازید، یا مقدار متفاوتی برای --load-balance-method تنظیم کنید.

تیم SGLang مسیریاب آگاه از کش را در نگارش v0.4 اضافه کرد {{team 2024-12}}. آن‌ها از 1.9 برابر بهبود نرخ پردازش و 3.8 برابر ارتقای نرخ اصابت خبر دادند. این اعداد مربوط به الگوی ترافیکی خودشان است؛ بنابراین حتماً نرخ اصابت سامانه‌ی خود را قبل و بعد از تغییر اندازه بگیرید.

پین کردن هم‌زمان مسیریاب و موتور پردازش

کاربری از افت دوبرابری نرخ پردازش در SGLang روی شتاب‌دهنده‌ی GB200 NVL72 هنگام اجرای DeepSeek-R1 خبر داد (ایشوی شماره‌ی 22095). ریشه‌ی این افت در مسیریاب خارج از SGLang بود: روی یک بیلد یکسان از SGLang، مسیریاب Dynamo نگارش 0.8.1 خروجی 132,140 توکن بر ثانیه می‌داد، در حالی که Dynamo نگارش 1.0.0 به 69,767 توکن بر ثانیه می‌رسید. همیشه کارایی مسیریاب و موتور پردازش را در کنار هم و به‌عنوان یک سامانه‌ی یکپارچه ارزیابی کنید و نگارش هر دو را پین نمایید.

حادثه‌ی دیگری نشان داد که مسیریابی و سازوکار شناسایی سرویس (service discovery) روی یکدیگر اثر می‌گذارند. در حالت جداسازی و استفاده از شناسایی سرویس کوبرنتیز، سیاست cache_aware با خطای «Failed to select prefill/decode worker» متوقف شد و کاربران ناچار به بازگشت به نوبت‌گردشی شدند (ایشوی شماره‌ی 10608). این ایشو بسته شد، اما اصلاحیه‌ای که باعث رفع آن شده باشد را پیدا نکردیم. بنابراین قبل از آنکه به سیاستی متکی شوید، آن را دقیقاً در بستر عملیاتی خود تست کنید.

چه چیزهایی را اندازه بگیریم

قبل و بعد از تغییر سیاست، مقدار sglang:cache_hit_rate را روی تک‌تک سرورها بسنجید. متریک‌های درگاه روی پورت 29000 را برای بررسی تلاش‌های مجدد (retries) و مدارهای باز (open circuits) پیگیری کنید. این درگاه به‌طور پیش‌فرض تا 5 بار برای درخواست ناموفق تلاش مجدد می‌کند و بعد از 10 شکست متوالی، مدار ارتباط با آن سرور را باز می‌نماید {{code}}. افزایش TTFT هم‌زمان با افت نرخ اصابت نشان می‌دهد درخواست‌ها دیگر به سروری که پیشوندشان را دارد نمی‌رسند. برای دیدی جامع‌تر درباره‌ی درگاه‌ها در محیط عملیاتی، درس درگاه‌های هوش مصنوعی را مطالعه کنید.

منابع: sgl-model-gateway/src/main.rs، sgl-model-gateway/src/policies/cache_aware.rs، sgl-model-gateway/Cargo.toml، python/sglang/srt/arg_groups/serving_hook.py (تابع handle_load_balance_method) و python/sglang/srt/managers/data_parallel_controller.py همگی در نگارش v0.5.22. پول‌ریکوئست 14312، ایشوهای 22095 و 10608. گزارش Jarvislabs تحت عنوان «Managed Endpoints» در تاریخ 2026-08-26. مستند LMSYS با عنوان «SGLang v0.4» در تاریخ 2024-12-04.

ترجمه‌ی فارسی sgl-model-gateway and cache-aware routing از راهنمای SGLang 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما