یک تنظیم، یعنی سهم حافظهی GPU، عامل بیشتر خطاهای زمان راهاندازی است؛ کم کردن طول بیشینه یا کاهش سقف همروندی هم تقریباً بقیهی موارد را حل میکند.
سرور پیش از چاپ خط مربوط به اندازهی کش کلید-مقدار (KV cache) متوقف شد. با پایان این بخش، دلیل خطا را از خطهای پایانی لاگ متوجه میشوید و با انتخاب فلگ مناسب، آن را برطرف میکنید.
منابع درخواستی vLLM هنگام راهاندازی
vLLM پیش از پاسخگویی به درخواستها، چهار مرحله را طی میکند:
- وزنهای مدل را بارگذاری میکند.
- یک دور پروفایلگیری (Profile pass) با یک دستهی کامل اجرا میکند تا حافظهی اکتیویشنها (Activation memory) را بسنجد.
- گرافهای CUDA را ضبط (Capture) میکند.
- باقیماندهی سهم تعیینشده از GPU را به کش کلید-مقدار اختصاص میدهد.
این سهم را فلگ --gpu-memory-utilization مشخص میکند. مقدار پیشفرض 0.92 است؛ یعنی vLLM معادل 92 درصد از کل حافظهی GPU را برای خود برمیدارد. این عدد سقفی برای یک نمونهی vLLM است، نه درصدی از حافظهی خالی در زمان راهاندازی سرور. همانطور که در صفحهی DGX Spark توضیح داده شده، روی حافظهی یکپارچه (Unified Memory) مثل سامانهی DGX Spark، این مقدار همیشه یک سقف قطعی و سختگیرانه نیست.
یافتن علت خطا در لاگ
30 خط آخر لاگ سرور را بخوانید. بیشتر خطاهای راهاندازی به یکی از این سه حالت مربوط میشوند:
| متن لاگ | علت | راهکار |
|---|---|---|
| The KV cache needed for one request at the maximum length is larger than the available KV cache memory | با احتساب وزنها و مرحلهی پروفایل، حافظهی باقیمانده حتی برای یک درخواست با طول کامل هم کافی نیست | مقدار --max-model-len را کم کنید. متن خطا حداکثر طول مجاز را اعلام میکند. |
| The free memory on the device is less than the desired GPU memory utilization | فرایند دیگری بخشی از حافظهی GPU را اشغال کرده است | مقدار --gpu-memory-utilization را کمتر از سهم حافظهی خالی بگذارید، یا فرایند دیگر را متوقف کنید |
| CUDA out of memory during the profile run or the graph capture | دستهی داده در دور پروفایلگیری یا گرافها به حافظهای بیشتر از مقدار باقیمانده نیاز دارند | مقادیر --max-num-seqs یا --max-num-batched-tokens را کم کنید، یا --max-cudagraph-capture-size را کاهش دهید |
رفع خطا در GPU اشتراکی
در یک GPU اشتراکی، نسبت سهم حافظه را خودتان تعیین کنید. ما vLLM 0.31.0 را روی یک کارت L4 اجرا کردیم که تیمی دیگر هم از آن استفاده میکرد. فرایندهای آنها بخشی از حافظه را گرفته بود، بنابراین ما --gpu-memory-utilization 0.83 و یک استخر حافظه با ظرفیت 2,928 توکن تنظیم کردیم.
راهاندازی اول باز هم ناموفق بود؛ چون طول بیشینه را هم دقیقاً روی 2,928 توکن گذاشته بودیم. یک درخواست با این طول، به کش کلید-مقداری کمی بیشتر از حافظهی خالی نیاز داشت، و خطا نشان داد که ظرفیت واقعی 2,912 توکن است:
(APIServer pid=3681321) INFO 10-22 00:35:04 [api_utils.py:286] non-default args: {'model_tag': 'Qwen/Qwen3-8B', 'host': '127.0.0.1', 'port': 30100, 'model': 'Qwen/Qwen3-8B', 'max_model_len': 2928, 'gpu_memory_utilization': 0.83, 'num_gpu_blocks_override': 183}
(EngineCore pid=3682071) ERROR 10-22 00:36:18 [core.py:1433] ValueError: To serve at least one request with the model's max seq len (2928), (0.4 GiB KV cache is needed, which is larger than the available KV cache memory (0.4 GiB). Based on the available memory, the estimated maximum model length is 2912. Try increasing `gpu_memory_utilization` (which also controls CPU memory on the CPU backend) or decreasing `max_modخط اول تنظیمات را نشان میدهد. خط دوم خطا و طولی که جا میشود را مشخص میکند. خروجی ثبتشده ما خط دوم را در 420 کاراکتر قطع کرده است. در vLLM 0.31.0، ادامه پیام به شما میگوید نسبت سهم حافظه را افزایش دهید یا حداکثر طول را کاهش دهید.
ما مقدار --max-model-len 2048 را تعیین کردیم که برای درخواستهای 640 توکنی ما کاملاً کافی بود و سرور اجرا شد. بعداً آن را به 2,304 توکن رساندیم تا تستهای ما با پیشوندهای 2,048 توکنی هم جا شوند.
بنابراین در یک GPU اشتراکی، سهم حافظه و طول بیشینه در کنار هم کار میکنند. پیش از کم کردن سهم حافظه، ابتدا طول بیشینه را متناسب با طولانیترین درخواست ارسالی کاهش دهید.
تنظیم مستقیم اندازهی کش کلید-مقدار
اگر اندازهی دقیق کش کلید-مقدار مورد نیازتان را میدانید، آن را بر حسب بایت با --kv-cache-memory-bytes مشخص کنید. در این حالت vLLM برای تخصیص کش، فلگ --gpu-memory-utilization را نادیده میگیرد. این گزینه زمانی کاربرد دارد که دو نمونهی vLLM از یک GPU مشترک استفاده میکنند و هر کدام به یک استخر حافظهی مشخص نیاز دارند.
گزینهی --num-gpu-blocks-override تعداد بلاکهای 16 توکنی را برای تست تعیین میکند؛ درست مثل استخر ثابت ما. از این گزینه در محیط عملیاتی استفاده نکنید، چون وجود واقعی حافظه را بررسی نمیکند.
بررسی صحت رفع خطا
سرور را دوباره با دستور tee server.log اجرا کنید (مانند راهاندازی نخست) و منتظر خط مربوط به استخر حافظه بمانید:
grep "GPU KV cache size" server.log
اگر این خط دیده شد، یعنی سرور استخر حافظه را ایجاد کرده است. اندازهی آن را با محاسبات قبلی خود مقایسه کنید.
منابع: capture/gpu/incidents/l4-gpu1-vllm-maxlen-oom.txt، مستندات vLLM نسخهی v0.31.0 (مسیر docs/configuration/optimization.md)، سورسکد vLLM نسخهی v0.31.0 (مسیرهای vllm/config/cache.py و vllm/config/scheduler.py)، تست ما روی GPU اشتراکی L4 در تاریخ 2026-10-22.