بخش 3.6 · کش KV

مدل‌های ترکیبی و کش

Hybrid models and the cache

فهرست مطالب
  1. سه نوع وضعیت لایه
  2. نحوه‌ی مدیریت هر نوع وضعیت در SGLang
  3. ریشه‌ی خطاها در ایشوها
  4. دیدگاه ما: پیش از اعتماد به کش در مدل ترکیبی، آن را بسنجید

لایه‌های پنجره‌ی لغزان و Mamba وضعیتی را نگه می‌دارند که درخت در سطح توکن نمی‌تواند آن را در هر موقعیت دلخواهی بشکند؛ به همین دلیل در نسخه‌ی v0.5.22، ریشه‌ی بسیاری از خرابی‌های گزارش‌شده‌ی کش به مدل‌های ترکیبی (hybrid models) برمی‌گردد.

تیمی مدلی ترکیبی را سرویس‌دهی می‌کند که لایه‌های اتنشن خطی (linear-attention) را با لایه‌های اتنشن کامل (full-attention) ترکیب کرده است. آن‌ها HiCache را فعال می‌کنند و 20 درخواست می‌فرستند که همگی به لایه‌ی میزبان (host tier) اصابت می‌کنند. هر 20 پاسخ کاملاً روان و مرتبط هستند، اما برای پرامپتی دیگر! بخش آمار مصرف، تمام توکن‌ها را کش‌شده گزارش می‌دهد و هیچ هشداری هم در لاگ‌ها ثبت نمی‌شود.

پس از پایان این بخش، می‌توانید توضیح دهید که چرا مدل‌های ترکیبی تصویر ساده‌ی ما از درخت مبنا را بر هم می‌زنند. همچنین می‌توانید پیش از آنکه کاربران کش مدلتان را تست کنند، خودتان آن را بیازمایید.

سه نوع وضعیت لایه

درخت مبنا در بخش 3.3 به این دلیل کار می‌کند که اتنشن کامل، به ازای هر توکن یک کلید و یک مقدار ذخیره می‌کند. هر پیشوند کش‌شده با هر طولی معتبر است؛ بنابراین درخت می‌تواند یک گره را روی هر توکنی بشکند. اما دو نوع لایه‌ی دیگر این قاعده را نقض می‌کنند.

اتنشن پنجره‌ی لغزان (Sliding-window attention یا SWA): اتنشنی که فقط چند هزار توکن آخر را می‌خواند. یک لایه‌ی SWA تنها به همین پنجره نیاز دارد؛ بنابراین SGLang استخر کوچک‌تری را برای لایه‌های SWA نگه می‌دارد و مقادیر KV خارج‌شده از پنجره را دور می‌ریزد. پیشوند کش‌شده فقط تا جایی کاربرد دارد که KV آن پنجره هنوز وجود داشته باشد.

لایه‌ی Mamba: یک لایه‌ی فضای حالت (state-space) یا اتنشن خطی که به ازای هر توالی، یک وضعیت بازگشتی با اندازه‌ی ثابت نگه می‌دارد و توکن‌به‌توکن به‌روزش می‌کند. وضعیت در توکن 2,000، خلاصه‌ی تمام 2,000 توکن است و نمی‌توان آن را تا توکن 1,500 عقب کشید. ادامه‌ی کار از روی یک پیشوند تنها در صورتی ممکن است که SGLang در آن نقطه اسنپ‌شاتی از وضعیت ذخیره کرده باشد.

مدل ثبت‌شده‌ی ما هیچ‌کدام را ندارد؛ لاگ راه‌اندازی هم همین را می‌گوید.

مدلی با تنها لایه‌های تمام‌اتنشن capture/out/server-default.log
[2026-10-16 13:58:06] Tree cache initialized: source=default impl=UnifiedRadixCache hybrid_swa=False hybrid_ssm=False hicache_attached=False
…
[2026-10-16 13:58:08] Attention KV pool initialized: pool_size=181574 (buffer size 181575 incl. padding slot 0), 28 full-attention layers (0 sliding-window layers stay per-request), 8 kv_heads, 128 head_dim

دو خط از لاگ راه‌اندازی با پیکربندی پیش‌فرض.

ابتدا این دو خط را روی مدل خودتان بررسی کنید. hybrid_swa=True یا hybrid_ssm=True یعنی تمام مباحث این بخش برای شما صدق می‌کند.

نحوه‌ی مدیریت هر نوع وضعیت در SGLang

کلاس UnifiedRadixCache یک درخت واحد نگه می‌دارد که برای هر نوع وضعیت، مولفه‌ای اختصاصی دارد {{code}}. هر گره داده‌های مربوط به مولفه‌ی اتنشن کامل و در صورت نیاز، داده‌های مولفه‌های SWA و Mamba را در خود نگه می‌دارد. انطباق تنها تا جایی پیش می‌رود که همه‌ی مولفه‌ها بر سر معتبر بودن وضعیت در آن موقعیت توافق داشته باشند.

برای SWA، درخت نشانگری را در نقطه‌ی حذف KV پنجره نگه می‌دارد و انطباق درست در محل این نشانگر متوقف می‌شود. آرگومان --swa-full-tokens-ratio نسبت اندازه‌ی استخر SWA به استخر کامل را تعیین می‌کند. مقدار پیش‌فرض آن None است و بازنویسی‌های اختصاصی هر مدل (overrides) آن را تنظیم می‌کنند. بازنویسی DeepSeek-V4 آن را روی 0.1 می‌گذارد {{code}}.

برای Mamba، درخت روی برخی گره‌ها اسنپ‌شات وضعیت را ذخیره می‌کند و وقتی درخواستی دوباره از آن استفاده کند، اسنپ‌شات کپی می‌شود. گزینه‌ی --mamba-radix-cache-strategy نحوه‌ی نگهداری اسنپ‌شات‌ها را در SGLang مشخص می‌کند: حالت پیش‌فرض auto، و حالت‌های no_buffer، extra_buffer یا extra_buffer_lazy {{code}}. آرگومان --mamba-track-interval نیز مشخص می‌کند که در فاز رمزگشایی هر چند وقت یک‌بار اسنپ‌شات گرفته شود؛ به طور پیش‌فرض هر 256 توکن.

پیشوند Mamba فقط از یک اسنپ‌شات ازسرگرفته می‌شودیک درخواست جدید که با 1,800 توکن از مدل Mamba هم‌خوانی دارد، از آخرین اسنپ‌شات در 1,792 توکن ادامه می‌یابد و 8 توکن را مجدداً پیش‌پرکنی می‌کند.
پیشوند Mamba فقط از یک اسنپ‌شات ازسرگرفته می‌شود یک گفتگوی کش‌شده که به‌صورت نواری از 0 تا 2,048 توکن رسم شده، به همراه اسنپ‌شات‌های حالت Mamba در هر 256 توکن. یک درخواست جدید با 1,800 توکن اول مطابقت دارد. کش KV تمام‌اتنشن برای همه‌ی 1,800 توکن موجود است، اما حالت بازگشتی تنها در اسنپ‌شات‌ها وجود دارد؛ بنابراین، درخواست از اسنپ‌شاتِ توکن 1,792 ادامه می‌یابد و توکن‌های 1,792 تا 1,800 دوباره پیش‌پرکنی می‌شوند. گفتگوی کش‌شده · 2,048 توکن 0 512 1,024 1,536 2,048 خطوط سبزآبی: اسنپ‌شات‌های حالت Mamba، هر 256 توکن درخواست جدید · تطابق 1,800 توکن استفاده‌ی مجدد: 1,792 توکن، تا آخرین اسنپ‌شات پیش‌پرکنی دوباره: 8 توکن از 1,792 تا 1,800 مقدار KV تمام‌اتنشن برای همه‌ی توکن‌ها موجود است. حالت بازگشتی فقط در نقاط ذخیره‌ی اسنپ‌شات موجود است.
نمودار را از ریشه به پایین بخوانید. اسنپ‌شات‌ها در هر 256 توکن رمزگشایی مطابق با پیش‌فرض mamba-track-interval-- ثبت می‌شوند. تعداد توکن‌ها صرفاً یک مثال است، نه یک گزارش واقعی.

ریشه‌ی خطاها در ایشوها

بسیاری از باگ‌های گزارش‌شده‌ی کش در نسخه‌ی v0.5.22 به مدل‌های ترکیبی مربوط می‌شوند. ما خودمان مدل ترکیبی اجرا نکردیم، اما این چهار ایشو دامنه‌ی مشکل را نشان می‌دهند:

  1. پاسخ اشتباه ناشی از اصابت به لایه‌ی میزبان. ایشوی شماره‌ی #39830 همان داستان ابتدای این بخش است {{issue #39830}}. یک مدل ترکیبی با اتنشن خطی و فعال بودن HiCache، در 20 بار از 20 اصابت به لایه‌ی میزبان، پاسخ‌هایی روان اما مربوط به پرامپتی دیگر داد. درخواست‌های سرد (cold) و اصابت‌ها به GPU خروجی کاملاً درستی داشتند.
  2. عدم استفاده‌ی مجدد برای پرامپت یکسان. در ایشوی شماره‌ی #22935، انطباقِ یک پرامپت تکراری درون یک یال تمام می‌شود و شکستن گره، گرهی جدید بدون وضعیت Mamba می‌سازد {{issue #22935}}. انطباق روی آخرین گرهِ دارای وضعیت متوقف می‌شود؛ در نتیجه هیچ بخشی از پرامپتِ یکسان مجدداً استفاده نمی‌شود.
  3. استراتژی خاصی که توکن اول را 4.7 برابر کندتر کرد. در ایشوی شماره‌ی #37834، یک گزینه استراتژی no_buffer را تحمیل کرده بود {{issue #37834}}. اسنپ‌شات در عمقی قرار گرفته بود که درخواست‌های بعدی به آن دسترسی نداشتند. در یک بار کاریِ بازیابی، نرخ اصابت از 88.2 به 65.9 درصد سقوط کرد. میانگین زمان تا اولین توکن از 226 میلی‌ثانیه به 1,063 میلی‌ثانیه افزایش یافت.
  4. رفتار پیش‌فرضی که رمزگشایی را کند کرد. ایشوی شماره‌ی #36131 رفتار پیش‌فرض جدیدی را گزارش می‌دهد که جایگاه‌های SWA بیرون از پنجره را آزاد می‌کند {{issue #36131}}. این کار نرخ پردازش رمزگشایی تک‌جریانی (single-stream) را برای مدل‌های ترکیبی SWA روی DGX Spark و Thor کاهش داد.

دیدگاه ما: پیش از اعتماد به کش در مدل ترکیبی، آن را بسنجید

در یک مدل مبتنی بر اتنشن کامل، اصابت اشتباه به کش آن‌قدر نادر است که کش را روشن می‌گذاریم و رد می‌شویم. اما در یک مدل ترکیبی، پیش از ورود به محیط عملیاتی سه بررسی زیر را انجام دهید؛ هر کدام تنها چند دقیقه زمان می‌برد:

  1. صحت. پرامپت‌های یکسانی را در سه حالت بفرستید: سرد، با اصابت به GPU و در صورت استفاده از HiCache، با اصابت به لایه‌ی میزبان. خروجی‌ها را در دمای صفر با هم مقایسه کنید. هنگام آزمایش، آرگومان --kv-canary log را اجرا کنید؛ این گزینه جایگاه‌های KV را برای جلوگیری از خرابی داده بررسی می‌کند و سرور را در حال اجرا نگه می‌دارد {{code}}.
  2. استفاده‌ی مجدد. یک پرامپت را تکرار کنید و مقدار #cached-token را بخوانید. اگر برای پرامپتی یکسان عدد پایینی دیدید، به مشکل شکستن گره در ایشوی شماره‌ی #22935 برخورد کرده‌اید.
  3. تاخیر. زمان تا اولین توکن را یک بار با --mamba-radix-cache-strategy auto و بار دیگر با استراتژی پیشنهادی در راهنمای استقرار خود اندازه بگیرید. تنها در صورتی گزینه‌ی سریع‌تر را نگه دارید که نرخ اصابت افت نکرده باشد.

سپس پیش از هر بار ارتقا، ایشوهای باز مربوط به خانواده‌ی مدل خود را بخوانید. بین تاریخ 2026-09-01 تا تگ v0.5.22، حدود 330 commit کد کش را در python/sglang/srt/mem_cache تغییر داده‌اند. در مدل‌های ترکیبی، یک نسخه‌ی جدید می‌تواند یکی از این باگ‌ها را برطرف کند و باگی تازه بسازد.

منابع: python/sglang/srt/mem_cache/unified_radix_cache.py، python/sglang/srt/mem_cache/unified_cache/components/README.md، python/sglang/srt/arg_groups/fields/exec_.py (mamba_radix_cache_strategy، mamba_track_interval)، python/sglang/srt/arg_groups/fields/schedule.py (swa_full_tokens_ratio)، python/sglang/srt/arg_groups/model_overrides/deepseek_v4.py، python/sglang/srt/arg_groups/fields/observability.py (kv_canary) در نسخه‌ی v0.5.22، capture/out/server-default.log، ایشوهای #39830، #22935، #37834 و #36131؛ فهرست commitهای گیت‌هاب برای مسیر python/sglang/srt/mem_cache از تاریخ 2026-09-01 در تگ v0.5.22 (333 کامیت، سرشماری در 2026-10-22)

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