کانتکست طولانی و معماری هیبریدی، هر دو نحوهی محاسبهی حافظه در vLLM را تغییر میدهند؛ از طرفی هر دوی آنها ممکن است موقع راهاندازی با خطایی متوقف شوند که دلیل اصلیاش پشت پیام خطا پنهان است.
شاید به کانتکستی طولانیتر از مقدار پیشفرض نیاز دارید، یا میخواهید مدلی را سرو کنید که لایههای اتنشن (Attention) را با لایههای پنجرهی لغزان (Sliding window) یا فضای حالت (State-space) ترکیب میکند. در پایان این بخش، میتوانید طول بیشینه را بهطور هدفمند تعیین کنید و رفتار کش را برای هر نوع لایه بخوانید و بفهمید.
ما برای این راهنما یک مدل کانتکستطولانی یا هیبریدی را اجرا نکردهایم. محتوای این صفحه از مستندات vLLM، سورسکد نسخهی 0.31.0 و یادداشتهای انتشار (Release notes) گرفته شده است.
تعیین هدفمند طول بیشینه
اگر --max-model-len را تنظیم نکنید، vLLM این طول را از کانفیگ مدل میخواند. برای نمونه، در مدل Qwen/Qwen3-8B این عدد 40,960 توکن است. با نرخ 144 کیلوبایت (KiB) به ازای هر توکن، یک درخواست با این طول به 5.6 گیگابایت (GiB) کش کلید-مقدار (KV cache) نیاز دارد. روی یک کارت گرافیک 24 گیگابایتی، پس از اشغال 16.4 گیگابایت برای وزنهای مدل، فضای باقیمانده ممکن است حتی برای پردازش یک درخواست هم کافی نباشد؛ در نتیجه راهاندازی مدل با خطا متوقف میشود.
مقدار --max-model-len را روی مجموع طولانیترین پرامپت و پاسخی که کاربران ارسال میکنند، بگذارید. اندازهی استخر حافظه (Pool size) تغییری نمیکند؛ اما کم کردن این سقف مانع از آن میشود که یک درخواست تمام استخر را تصاحب کند و اجازه میدهد بررسیِ اولیه موقع راهاندازی با موفقیت انجام شود.
بررسی طول کانتکست پس از ارتقا
برخی مدلها کانتکست خود را با روشهای مقیاسبندی مثل YaRN گسترش میدهند. در نسخهی 0.30.0، نحوه برخورد vLLM با YaRN تغییر کرد تا با کتابخانهی Transformers در Hugging Face هماهنگ شود. در نتیجه، برای بعضی مدلها طولی که vLLM از کانفیگ استخراج میکرد کمتر شد. طبق یادداشتهای انتشار، این مقدار در یک مدل از 131,072 به 32,768 توکن رسید.
پس از ارتقا، طول استخراجشده را در لاگ راهاندازی بررسی کنید. اگر تغییر کرده بود، یا خودتان --max-model-len را تعیین کنید، یا مطمئن شوید مدل هنوز از آن طول کانتکست بلندتر پشتیبانی میکند.
سازوکار استفاده از کش در مدلهای هیبریدی
یک مدل هیبریدی بیش از یک نوع لایه دارد. vLLM برای هر نوع لایه یک گروه اختصاصی از کش کلید-مقدار در نظر میگیرد. جدول زیر قواعد هر گروه را نشان میدهد:
| نوع لایه | دادههای نگهداریشده | شرط اصابت پرفیکس کششده (Cache Hit) |
|---|---|---|
| اتنشن کامل (Full attention) | کلیدها و مقادیر برای تمام توکنها | همهی بلوکهای پرفیکس هنوز در کش موجود باشند |
| پنجرهی لغزان (Sliding window) | کلیدها و مقادیر برای آخرین پنجره از توکنها | بلوکهای داخل آخرین پنجره هنوز در کش موجود باشند |
| فضای حالت، مثل Mamba | یک حالت (State) برای هر درخواست، نه یک ورودی به ازای هر توکن | باید یک حالتِ ذخیرهشده برای آن نقطه از پرامپت وجود داشته باشد؛ قواعد ذخیرهی آن بین نسخهها تغییر کرده است |
طراحی گروهی به یک استخر حافظه امکان میدهد به تمام انواع لایهها سرویس بدهد. در عین حال به این معنی است که نرخ اصابت (Hit Rate) پرفیکس کش در یک مدل هیبریدی، برای پرامپتهای یکسان با مدلی که اتنشن کامل دارد متفاوت است.
پرهیز از فلگهای حذفشده و تغییرنامیافته
پشتیبانی از مدلهای هیبریدی بهسرعت دستخوش تغییر میشود. سه تغییر مهم بین نسخههای 0.29 و 0.32 وجود دارد که باید بدانید:
- حالت
allبرای کش Mamba در نسخهی 0.30 منسوخ (Deprecated) شد و vLLM را مجبور میکرد از اجراکنندهی (Runner) قدیمیترِ مدل استفاده کند. در نسخهی 0.32 این گزینه کاملاً حذف شد. - در نسخهی 0.31، نام فلگ
--enable-mamba-fine-grained-prefix-cacheبه--enable-mamba-shared-prefix-checkpointتغییر یافت. - پس از حذف حالت
all، یکی از ایشوهای باز گزارش داده که--mamba-block-sizeعملاً اثری ندارد.
اگر یک مدل هیبریدی پس از ارتقا دیرتر بالا آمد یا حافظهی بیشتری گرفت، اول این فلگها را بررسی کنید. فلگ --disable-hybrid-kv-cache-manager گروهها را غیرفعال میکند و روش خوبی است تا ببینید آیا مشکل از گروهبندی ناشی میشود یا نه.
اعتبارسنجی تنظیمات
سرور را اجرا کنید و خط مربوط به استخر حافظه (Pool line) را بخوانید. این خط بیشترین همزمانی (Concurrency) ممکن را در طول بیشینهی شما نشان میدهد:
grep "GPU KV cache size" server.log
خط مربوط به استخر حافظه تنها در صورتی چاپ میشود که راهاندازی موفقیتآمیز باشد. اگر راهاندازی با خطای مربوط به کش کلید-مقدار و طول بیشینه متوقف شد، مقدار --max-model-len را کم کنید تا این خط چاپ شود. سپس عدد همزمانیاش را بخوانید و با تعداد کاربرانی که میخواهید با کانتکست کامل پوشش دهید مقایسه کنید.
منابع: مستندات vLLM در نسخهی v0.31.0 (فایلهای docs/design/hybrid_kv_cache_manager.md و docs/configuration/optimization.md)، سورسکد vLLM در نسخهی v0.31.0 (فایلهای vllm/config/scheduler.py و vllm/config/cache.py)، یادداشتهای انتشار برای نسخههای v0.30.0 و v0.31.0 و v0.32.0، ایشوی شمارهی 60838 در مخزن vLLM، فایل کانفیگ مدل Qwen/Qwen3-8B.