بخش 2.2 · تعیین ابعاد و ظرفیت

رفع خطای کمبود حافظه در زمان راه‌اندازی

Fix out of memory at startup

فهرست مطالب
  1. منابع درخواستی vLLM هنگام راه‌اندازی
  2. یافتن علت خطا در لاگ
  3. رفع خطا در GPU اشتراکی
  4. تنظیم مستقیم اندازه‌ی کش کلید-مقدار
  5. بررسی صحت رفع خطا

یک تنظیم، یعنی سهم حافظه‌ی GPU، عامل بیشتر خطاهای زمان راه‌اندازی است؛ کم کردن طول بیشینه یا کاهش سقف همروندی هم تقریباً بقیه‌ی موارد را حل می‌کند.

سرور پیش از چاپ خط مربوط به اندازه‌ی کش کلید-مقدار (KV cache) متوقف شد. با پایان این بخش، دلیل خطا را از خط‌های پایانی لاگ متوجه می‌شوید و با انتخاب فلگ مناسب، آن را برطرف می‌کنید.

منابع درخواستی vLLM هنگام راه‌اندازی

vLLM پیش از پاسخ‌گویی به درخواست‌ها، چهار مرحله را طی می‌کند:

  1. وزن‌های مدل را بارگذاری می‌کند.
  2. یک دور پروفایل‌گیری (Profile pass) با یک دسته‌ی کامل اجرا می‌کند تا حافظه‌ی اکتیویشن‌ها (Activation memory) را بسنجد.
  3. گراف‌های CUDA را ضبط (Capture) می‌کند.
  4. باقیمانده‌ی سهم تعیین‌شده از 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 بسیار بزرگ است، پس از وزن‌های FP8 یا GPUهای بیشتری استفاده کنید. اگر بررسی حافظه شکست بخورد، برنامه‌های دیگر حافظه را اشغال کرده‌اند، پس نسبت حافظه را کاهش دهید. اگر بررسی KV شکست بخورد، حداکثر طول به کش بیشتری از مقدار آزاد نیاز دارد، پس حداکثر طول را کم کنید. توقف لاگ در بارگذاری وزن‌ها قبل از خط load بررسی حافظه حافظه آزاد کمتر است بررسی KV نیاز حداکثر طول توالی علت وزن‌ها بیش از حد بزرگند برای این GPU حافظه اشتراکی است سایر برنامه‌ها آن را گرفته‌اند کش بیش از حد کوچک است برای یک درخواست کامل این را تغییر دهید وزن‌های FP8 یا tensor-parallel-size-- کاهش نسبت سهم --gpu-memory-utilization زمینه کوتاه‌تر --max-model-len
هر ستون را رو به پایین بخوانید: محل توقف لاگ، علت، و فلگی که باید تغییر کند. برگرفته از سورس vLLM نسخه‌ی 0.31.0 و اجراهای ما روی L4.

رفع خطا در GPU اشتراکی

در یک GPU اشتراکی، نسبت سهم حافظه را خودتان تعیین کنید. ما vLLM 0.31.0 را روی یک کارت L4 اجرا کردیم که تیمی دیگر هم از آن استفاده می‌کرد. فرایندهای آن‌ها بخشی از حافظه را گرفته بود، بنابراین ما --gpu-memory-utilization 0.83 و یک استخر حافظه با ظرفیت 2,928 توکن تنظیم کردیم.

راه‌اندازی اول باز هم ناموفق بود؛ چون طول بیشینه را هم دقیقاً روی 2,928 توکن گذاشته بودیم. یک درخواست با این طول، به کش کلید-مقداری کمی بیشتر از حافظه‌ی خالی نیاز داشت، و خطا نشان داد که ظرفیت واقعی 2,912 توکن است:

خطای حداکثر طول روی GPU اشتراکی L4 capture/gpu/incidents/l4-gpu1-vllm-maxlen-oom.txt
(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.

ترجمه‌ی فارسی Fix out of memory at startup از راهنمای vLLM 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما