رفع خطای CUDA Out of Memory در vLLM؛ آموزش عیب‌یابی و کاهش مصرف GPU Memory

ممکن است مدل به‌درستی داخل VRAM بارگذاری شود، اما vLLM هنگام ساخت KV Cache، اجرای Memory Profiling یا آماده‌سازی CUDA Graph با کمبود حافظه روبه‌رو شود. در شرایط دیگر، سرور بدون مشکل روشن می‌شود و تنها زمانی که چند کاربر هم‌زمان درخواست می‌فرستند، خطای OOM یا افت شدید عملکرد ظاهر می‌شود.

برای رفع اصولی vLLM CUDA OOM باید ابتدا مشخص کنیم خطا در کدام مرحله ایجاد شده و کدام بخش حافظه را مصرف می‌کند: وزن‌های مدل، Activationها، KV Cache، CUDA Graphها یا فرآیندهای دیگر GPU.

در این آموزش، روش عیب‌یابی حافظه GPU در vLLM 0.33.0 را روی سرور Linux بررسی می‌کنیم. با ابزارهایی مانند nvidia-smi، لاگ‌های Startup و Metrics داخلی vLLM، مصرف حافظه را اندازه می‌گیریم و سپس تأثیر Model Size، Dtype، Quantization، max-model-len و Concurrency را جداگانه آزمایش می‌کنیم.

همچنین توضیح می‌دهیم چه زمانی افزایش gpu-memory-utilization مفید است، چرا گاهی کاهش آن بهتر جواب می‌دهد، چگونه Memory Profiling را تحلیل کنیم و چه موقع به GPU با VRAM بیشتر یا معماری چند GPU نیاز داریم.

هدف این مقاله، حل مشکل براساس شواهد است؛ نه اجرای دستورهای تصادفی، حذف Cache مدل یا توقف سایر فرآیندهای سرور بدون بررسی.

CUDA Out of Memory چیست و چرا در vLLM رخ می‌دهد؟

خطای CUDA Out of Memory یا به‌اختصار CUDA OOM زمانی رخ می‌دهد که یک عملیات GPU به حافظه بیشتری نیاز دارد، اما تخصیص حافظه موردنیاز امکان‌پذیر نیست.

برای اجرای مدل زبانی، vLLM علاوه بر ذخیره وزن‌های مدل، به حافظه‌ای برای پردازش درخواست‌ها، Attention، KV Cache، بافرهای Runtime و گاهی CUDA Graph نیاز دارد.

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

آیا OOM یعنی GPU خراب شده است؟

خیر. این خطا معمولاً مربوط به محدودیت ظرفیت یا تخصیص حافظه است؛ نه الزاماً خرابی سخت‌افزار.

البته اگر همراه با OOM خطاهایی مانند GPU Xid، خطای Driver یا قطع ارتباط GPU دیده می‌شود، باید سلامت سخت‌افزار و Driver نیز جداگانه بررسی شود.

آیا داشتن RAM زیاد مشکل CUDA OOM را حل می‌کند؟

RAM معمولی سرور با VRAM کارت گرافیک یکسان نیست.

افزایش RAM ممکن است برای بعضی روش‌های CPU Offloading مفید باشد، اما جایگزین مستقیم حافظه سریع GPU نیست و می‌تواند تأخیر اجرای مدل را افزایش دهد.

پنج مرحله‌ای که خطای OOM در vLLM ممکن است اتفاق بیفتد

قبل از هر تغییر، خطا را براساس مرحله وقوع دسته‌بندی کنید.

چرا تشخیص مرحله اهمیت دارد؟

اگر مدل در مرحله Loading به دلیل اندازه زیاد وزن‌ها اجرا نمی‌شود، کاهش تعداد درخواست‌های هم‌زمان به‌تنهایی مشکل اصلی را حل نمی‌کند.

در مقابل، اگر مدل به‌درستی Load شده و فقط تحت بار هم‌زمان مشکل پیدا می‌کند، تغییر Model Size ممکن است اولین و اقتصادی‌ترین راه‌حل نباشد.

برای هر مرحله باید متغیرهای مربوط به همان بخش را بررسی کنیم.

حافظه GPU در vLLM چگونه تقسیم می‌شود؟

برای تشخیص علت OOM بهتر است یک تصویر ذهنی از مصرف حافظه داشته باشیم.

GPU VRAM
   |
   +-- Model Weights
   |
   +-- Activations / Temporary Buffers
   |
   +-- KV Cache
   |
   +-- CUDA Graph / Compiler Runtime
   |
   +-- CUDA / NCCL / Non-PyTorch Allocations
   |
   +-- Other GPU Processes
   |
   +-- Free Memory / Safety Margin

Model Weights

وزن‌های مدل شامل پارامترهای آموزش‌دیده هستند. این بخش معمولاً به تعداد پارامترها، نوع داده و روش Quantization وابسته است.

Activations

در هنگام پردازش ورودی، Tensorهای موقت تولید می‌شوند. مصرف آن‌ها می‌تواند با اندازه Batch و نوع عملیات تغییر کند.

KV Cache

اطلاعات Attention مربوط به Tokenهای پردازش‌شده را نگهداری می‌کند تا هنگام تولید Token جدید، لازم نباشد تمام محاسبات قبلی دوباره انجام شوند.

CUDA Graph و Runtime

اجرای بهینه مدل ممکن است نیازمند حافظه اضافی برای Capture، بافرها و مدیریت Runtime باشد.

Other Processes

ممکن است سرویس دیگری، Notebook، Container یا یک Instance دیگر vLLM از همان GPU استفاده کند.

این موضوع به‌خصوص در GPU اشتراکی یا محیطی که چند مدل هم‌زمان اجرا می‌شوند اهمیت دارد.

مرحله اول عیب‌یابی: بررسی حافظه GPU با nvidia-smi

قبل از تغییر تنظیمات vLLM، وضعیت واقعی GPU را مشاهده کنید.

بررسی مشخصات GPU

nvidia-smi

این دستور نام GPU، مصرف حافظه و اطلاعات مربوط به فرآیندهای شناخته‌شده را نمایش می‌دهد.

مشاهده مقدار دقیق VRAM

nvidia-smi \
--query-gpu=index,name,memory.total,memory.used,memory.free \
--format=csv

بررسی فرآیندهای فعال GPU

nvidia-smi --query-compute-apps=pid,process_name,used_gpu_memory \
--format=csv

در بعضی محیط‌های Container، MIG یا Driverهای خاص ممکن است اطلاعات فرآیندها ناقص باشد.

پایش تغییرات حافظه هنگام Startup

nvidia-smi \
--query-gpu=timestamp,index,memory.used,memory.free,utilization.gpu \
--format=csv \
-l 2

این دستور وضعیت GPU را هر دو ثانیه نمایش می‌دهد. برای پایان مشاهده، Ctrl+C بزنید.

اگر مدل قبل از Startup مقدار زیادی VRAM اشغال کرده است، ابتدا مالکیت فرآیندهای موجود را بررسی کنید.

هشدار: بدون شناخت فرآیندها از دستورهای kill، GPU Reset یا توقف سرویس‌های دیگر استفاده نکنید؛ ممکن است پردازش مهم دیگری روی GPU فعال باشد.

مرحله دوم: پیام CUDA OOM و لاگ‌های vLLM را چگونه بخوانیم؟

به‌جای تمرکز صرف بر آخرین خط خطا، قسمت‌های قبل از آن را نیز بررسی کنید.

معمولاً اطلاعات مهم در لاگ‌های Startup شامل مراحل Loading، Profiling، تخصیص KV Cache و آماده‌سازی CUDA Graph است.

ثبت لاگ در محیط آزمایشی

اگر مدل را از Terminal اجرا می‌کنید، می‌توانید خروجی جدید را در فایل مخصوص عیب‌یابی ذخیره کنید:

vllm serve Qwen/Qwen3-0.6B \
--host 127.0.0.1 \
--port 8000 \
--max-model-len 2048 \
--gpu-memory-utilization 0.80 \
2>&1 | tee vllm-startup.log

این فرمان برای محیط تست است. در Production، مدیریت لاگ باید مطابق سرویس فعلی انجام شود و نباید یک Instance جدید را بدون توجه به GPU و پورت فعال اجرا کرد.

جست‌وجوی عبارت‌های مرتبط

grep -inE \
'out of memory|cuda|profil|cache|graph|preempt|free memory|weight' \
vllm-startup.log

اگر سرویس با systemd اجرا می‌شود

sudo journalctl -u vllm.service \
-n 200 --no-pager

نام Unit ممکن است در سرور شما متفاوت باشد. این فرمان فقط لاگ سرویس را می‌خواند.

به دنبال چه پیام‌هایی باشیم؟

• مدل با چه Dtype بارگذاری شده است؟
• چقدر حافظه برای وزن‌ها مصرف شده است؟
• چه مقدار حافظه برای KV Cache در دسترس بوده است؟
• آیا خطا هنگام Profile Run اتفاق افتاده است؟
• آیا پیام CUDA Graph Capture وجود دارد؟
• آیا Preemption یا Recompute گزارش شده است؟
• آیا GPU توسط فرآیند دیگری اشغال شده است؟

همین اطلاعات معمولاً مسیر بررسی را مشخص‌تر می‌کنند.

مرحله سوم: آیا اندازه مدل از VRAM بیشتر است؟

یکی از رایج‌ترین علت‌های OOM در Startup، بزرگ بودن وزن‌های مدل نسبت به حافظه GPU است.

برای یک مدل Dense، تخمین اولیه حافظه وزن‌ها با این رابطه انجام می‌شود:

حجم نظری وزن‌ها = تعداد پارامترها × تعداد بایت هر پارامتر

این مقادیر ده‌دهی و مربوط به وزن‌ها هستند؛ نه مقدار واقعی حافظه موردنیاز برای اجرای کامل مدل.

چرا مدل ۷B با FP16 روی GPU دارای ۱۶GB ممکن است اجرا نشود؟

زیرا وزن‌ها به‌تنهایی حدود ۱۴GB حافظه نظری مصرف می‌کنند و برای KV Cache، Activationها و Runtime نیز حافظه لازم است.

همچنین حجم واقعی به ساختار مدل، نوع بارگذاری و ویژگی‌های معماری آن بستگی دارد.

اگر مدل MoE باشد چه تفاوتی دارد؟

در Mixture-of-Experts ممکن است فقط بخشی از پارامترها در هر Token فعال شوند، اما این به معنی آن نیست که فقط همان وزن‌های فعال به حافظه نیاز دارند.

نحوه بارگذاری و تقسیم Expertها روی GPU می‌تواند مقدار حافظه موردنیاز را تغییر دهد.

اولین راه‌حل برای وزن‌های بیش‌ازحد بزرگ

اگر مدل از همان ابتدا در حافظه جا نمی‌شود، گزینه‌ها شامل استفاده از مدل کوچک‌تر، نسخه Quantized سازگار یا تقسیم مدل روی چند GPU هستند.

کاهش max-num-seqs مشکل وزن‌هایی را که به‌تنهایی بیش از VRAM ظرفیت دارند حل نخواهد کرد.

نقش Dtype در مصرف حافظه vLLM

Dtype مشخص می‌کند وزن‌ها یا بعضی محاسبات با چه نوع داده‌ای انجام شوند.

تنظیم dtype در vLLM

vllm serve MODEL_ID \
--dtype auto \
--host 127.0.0.1 \
--port 8000

برای شروع بهتر است از Dtype سازگار با مدل استفاده کنید و خروجی Log را بررسی کنید.

در صورت نیاز می‌توان Dtype را به‌صورت صریح تعیین کرد، اما تغییر Precision باید با سازگاری سخت‌افزار و کیفیت مدل بررسی شود.

آیا dtype=float16 همیشه نصف حافظه مصرف می‌کند؟

اگر در حال مقایسه وزن‌های FP32 و FP16 یک مدل Dense معمولی باشید، حجم نظری وزن‌ها تقریباً نصف می‌شود؛ اما مصرف کل VRAM الزاماً نصف نخواهد شد.

برای مثال، بافرهای Runtime یا حافظه‌ای که با Precision دیگری ذخیره می‌شود می‌توانند رفتار متفاوتی داشته باشند.

آیا Quantization بهترین راه کاهش مصرف GPU Memory است؟

Quantization می‌تواند وزن‌های مدل را با Precision پایین‌تر ذخیره یا محاسبه کند و در نتیجه مصرف حافظه کاهش یابد.

روش‌هایی مانند AWQ، GPTQ و FP8 بسته به مدل و GPU ممکن است قابل استفاده باشند.

چه زمانی Quantization مناسب است؟

وقتی وزن‌های مدل بخش اصلی مصرف حافظه هستند و مدل اصلی روی GPU جا نمی‌شود یا فضای کافی برای KV Cache باقی نمی‌گذارد.

چه زمانی Quantization مشکل را حل نمی‌کند؟

اگر عامل اصلی OOM، تعداد بسیار زیاد Sequenceهای هم‌زمان، CUDA Graph Capture یا یک فرآیند رقیب باشد، کاهش حجم وزن‌ها ممکن است فقط بخشی از مشکل را کاهش دهد.

آیا هر مدل را می‌توان با یک Flag به نسخه ۴ بیتی تبدیل کرد؟

خیر. روش Quantization باید با فرمت وزن‌ها، Backend و سخت‌افزار سازگار باشد.

برای مثال، صرف افزودن --quantization awq به یک مدل معمولی، به این معنی نیست که وزن‌های آن به‌طور خودکار به یک Checkpoint مناسب AWQ تبدیل می‌شوند.

روش درست استفاده

ابتدا یک مدل از قبل Quantized و سازگار انتخاب کنید و راهنمای همان مدل را بررسی کنید. سپس کیفیت خروجی و میزان مصرف GPU را در مقایسه با نسخه اصلی اندازه بگیرید.

برای بررسی روش‌ها و GPUهای پشتیبانی‌شده به مستندات رسمی Quantization مراجعه کنید.

max-model-len چه تأثیری روی خطای CUDA OOM دارد؟

پارامتر --max-model-len حداکثر طول Sequence را مشخص می‌کند؛ یعنی مجموع Context ورودی و خروجی که مدل در این تنظیم می‌تواند پردازش کند.

مثال تنظیم طول Context

vllm serve Qwen/Qwen3-0.6B \
--host 127.0.0.1 \
--port 8000 \
--max-model-len 2048

آیا کاهش max-model-len حافظه وزن‌های مدل را کم می‌کند؟

خیر. تعداد پارامترهای مدل تغییر نمی‌کند.

اما کاهش حداکثر طول Sequence می‌تواند ظرفیت KV Cache موردنیاز برای هر درخواست بلند و بعضی محدودیت‌های Startup را کاهش دهد.

نکته مهم در vLLM جدید

در نسخه‌های جدید، KV Cache ممکن است به‌صورت قابل‌گسترش تخصیص داده شود و رفتار آن با روش‌های قدیمی رزرو حافظه متفاوت باشد.

بنابراین کاهش max-model-len همیشه به معنی کاهش مستقیم و هم‌اندازه VRAM رزروشده در Startup نیست.

بااین‌حال این تغییر همچنان برای محدود کردن طول درخواست‌های ورودی و کاهش فشار احتمالی Cache مفید است.

استفاده از Auto

در نسخه فعلی می‌توان مقدار auto یا -1 را برای انتخاب طولی که با ظرفیت مدل و حافظه سازگار است بررسی کرد.

vllm serve MODEL_ID \
--max-model-len auto \
--host 127.0.0.1

این قابلیت جایگزین تست با بار واقعی و تعیین محدودیت درخواست کاربران نیست.

KV Cache چگونه باعث OOM می‌شود؟

مدل هنگام تولید متن، اطلاعات Attention مراحل قبلی را داخل KV Cache نگهداری می‌کند.

با افزایش طول Prompt و خروجی یا تعداد Sequenceهای فعال، مصرف KV Cache می‌تواند بیشتر شود.

فرمول تقریبی برای مدل‌های Attention معمولی

برای یک Transformer با ساختار KV متراکم:

KV Bytes ≈ 2 × Layers × KV Heads × Head Dimension × Cached Tokens × Bytes per Element

این رابطه برای معماری‌های دارای MLA، Sliding Window یا KV Cacheهای خاص ممکن است مناسب نباشد.

چرا دو مدل با پارامتر تقریباً یکسان مصرف KV متفاوت دارند؟

زیرا تعداد لایه‌ها، KV Headها، اندازه Head و معماری Attention ممکن است متفاوت باشد.

برای مثال، مدل دارای Grouped-Query Attention می‌تواند نسبت به مدلی با تعداد بیشتر KV Head، به حافظه KV متفاوتی نیاز داشته باشد.

تفاوت کمبود KV Cache و CUDA OOM

وقتی ظرفیت KV Cache تحت بار محدود می‌شود، vLLM ممکن است بعضی درخواست‌ها را Preempt و بعداً Recompute کند.

این رفتار الزاماً خطای CUDA OOM نیست، اما می‌تواند تأخیر پاسخ را افزایش دهد.

اگر Allocator واقعاً نتواند حافظه لازم را تخصیص دهد، ممکن است خطای حافظه نیز رخ دهد.

gpu-memory-utilization را افزایش دهیم یا کاهش؟

این یکی از مهم‌ترین سؤال‌ها در عیب‌یابی vLLM است.

گزینه --gpu-memory-utilization سهم هدف حافظه GPU را برای موتور vLLM مشخص می‌کند.

اما اثر آن به مرحله خطا، نسخه و تنظیمات Cache بستگی دارد.

سناریو اول: GPU قبل از اجرا پر است

اگر فرآیندهای دیگر GPU را اشغال کرده‌اند یا vLLM به‌علت محدودیت بودجه حافظه در Startup شکست می‌خورد، افزایش درصد معمولاً راه‌حل مطمئنی نیست.

ابتدا حافظه آزاد واقعی و سایر مصرف‌کننده‌ها را بررسی کنید.

سناریو دوم: CUDA Graph یا Runtime حافظه اضافی می‌خواهد

ممکن است تنظیم تهاجمی حافظه فضای اطمینان کافی برای بعضی عملیات‌ها باقی نگذارد.

در این حالت، کاهش مقدار هدف یا استفاده موقت از enforce-eager می‌تواند به تشخیص کمک کند.

سناریو سوم: KV Cache ظرفیت کافی ندارد

در بعضی پیکربندی‌ها افزایش سهم حافظه موتور می‌تواند فضای بیشتری برای KV Cache فراهم کند و تعداد Preemptionها را کاهش دهد.

البته باید مطمئن باشید GPU واقعاً فضای آزاد کافی دارد و تنظیم جدید باعث OOM در مرحله دیگر نمی‌شود.

سناریو چهارم: kv-cache-memory-bytes فعال است

اگر این گزینه به‌صورت صریح تعیین شده باشد، اندازه KV Cache از مقدار آن تبعیت می‌کند و تنظیم gpu-memory-utilization برای اندازه آن نادیده گرفته می‌شود.

جدول تصمیم‌گیری

قاعده اصلی: هیچ عدد جادویی مانند 0.80 یا 0.95 برای تمام GPUها وجود ندارد. باید مقدار مناسب را از روی مصرف واقعی و تست پایداری تعیین کرد.

Memory Profiling در vLLM چگونه انجام می‌شود؟

vLLM هنگام آماده‌سازی موتور می‌تواند مصرف حافظه قسمت‌های مختلف مدل را اندازه‌گیری کند تا مشخص شود چه مقدار حافظه برای KV Cache در دسترس خواهد بود.

در این محاسبات ممکن است حافظه وزن‌ها، بیشینه مصرف Activationها، سربار بخش‌های غیر PyTorch و CUDA Graph در نظر گرفته شود.

چرا Memory Profiling مهم است؟

زیرا مصرف حافظه در زمان اجرای یک Batch آزمایشی ممکن است بیشتر از حالتی باشد که فقط وزن مدل بارگذاری شده است.

اگر تنها به خروجی nvidia-smi بعد از Model Loading نگاه کنیم، ممکن است مصرف Peak را نبینیم.

تفاوت مصرف فعلی و مصرف Peak

ممکن است یک GPU هنگام Idle مقدار قابل قبولی VRAM آزاد داشته باشد، اما هنگام پردازش Prompt طولانی، حافظه موقت بیشتری نیاز پیدا کند.

بنابراین عدد Memory Used در یک لحظه برای ظرفیت‌سنجی کافی نیست.

Memory Profiling شامل چه مؤلفه‌هایی است؟

• حافظه مصرف‌شده برای وزن‌ها.
• بیشینه حافظه Activation در اجرای آزمایشی.
• سربار CUDA و بعضی کتابخانه‌های خارج از PyTorch.
• در پیکربندی‌های مربوطه، حافظه CUDA Graph.
• حافظه باقی‌مانده قابل اختصاص به KV Cache.

تفاوت تخصیص سنتی و Extensible KV Cache

در نسخه‌های جدید vLLM، برای Backendهای سازگار می‌توان از Extensible KV Cache استفاده کرد؛ به‌طوری که فضای آدرس مجازی Cache رزرو و صفحات حافظه فیزیکی مطابق نیاز مدیریت شوند.

این روش در بعضی پیکربندی‌ها به تخمین دقیق‌تر حافظه قابل استفاده بعد از Warm-up کمک می‌کند.

اما نباید فرض کرد همه GPUها و تمام مسیرهای اجرایی از رفتار یکسانی استفاده می‌کنند.

آیا باید مقدار kv-cache-memory-bytes را دستی تنظیم کنیم؟

معمولاً بهتر است ابتدا اندازه‌گیری خودکار vLLM را آزمایش کنیم.

تنظیم دستی زمانی مفید است که محدودیت حافظه را دقیق می‌شناسید و می‌خواهید مقدار مشخص و قابل بازتولیدی برای Cache انتخاب کنید.

اما مقدار بیش‌ازحد خوش‌بینانه می‌تواند در تخصیص حافظه شکست بخورد و مقدار بسیار کم نیز Concurrency و Throughput را محدود کند.

آیا CUDA Graph باعث خطای Out of Memory شده است؟

CUDA Graphها می‌توانند سربار اجرای عملیات تکراری GPU را کاهش دهند؛ اما Capture و نگهداری ساختارهای موردنیاز آن‌ها ممکن است حافظه اضافی مصرف کند.

اگر مدل بعد از Load و هنگام CUDA Graph Capture با خطا روبه‌رو می‌شود، می‌توان برای تشخیص، این قابلیت را موقتاً غیرفعال کرد.

تست با enforce-eager

vllm serve Qwen/Qwen3-0.6B \
--host 127.0.0.1 \
--port 8000 \
--max-model-len 2048 \
--gpu-memory-utilization 0.80 \
--enforce-eager

در نسخه جدید، enforce-eager علاوه بر CUDA Graph، مسیر Compile مربوط به آن را نیز غیرفعال می‌کند.

چگونه نتیجه را تفسیر کنیم؟

اگر همان مدل با تنظیمات مشابه در حالت Eager اجرا شود اما در حالت عادی OOM بدهد، سربار Compile یا CUDA Graph یکی از عوامل محتمل است.

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

آیا enforce-eager را همیشه فعال نگه داریم؟

نه لزوماً. ممکن است مصرف حافظه را در شرایطی کاهش دهد، اما توان پردازشی و Latency حالت عادی را نیز تحت تأثیر قرار دهد.

بهتر است از آن برای تشخیص استفاده کنید و سپس با محدودیت‌های مناسب Graph یا Batch، تنظیم نهایی را Benchmark کنید.

Concurrency و max-num-seqs چه تأثیری روی GPU Memory دارند؟

وقتی چند کاربر هم‌زمان از API مدل درخواست می‌فرستند، موتور باید حافظه مربوط به درخواست‌های فعال و داده‌های Attention آن‌ها را مدیریت کند.

بنابراین ممکن است یک مدل با یک درخواست بدون مشکل اجرا شود، اما زیر بار هم‌زمان دچار فشار حافظه شود.

max-num-seqs

این پارامتر سقف تعداد Sequenceهایی را مشخص می‌کند که در یک Iteration موتور پردازش می‌شوند.

در برخی مسیرهای جدید، اندازه این پارامتر روی بافرهای Model Runner و CUDA Graph نیز اثر دارد.

max-num-batched-tokens

این پارامتر تعداد Tokenهای قابل پردازش در یک Iteration را کنترل می‌کند.

افزایش آن ممکن است Throughput بعضی Workloadها را بهبود دهد، اما همچنین می‌تواند فشار حافظه و مصرف Activation را تغییر دهد.

max-num-active-seqs در نسخه‌های جدید

نسخه فعلی vLLM گزینه‌ای برای محدود کردن تعداد درخواست‌هایی دارد که به وضعیت Running وارد می‌شوند، بدون آنکه الزاماً ظرفیت اندازه‌گیری و ساختار Runner به همان نسبت کوچک شود.

این تفاوت هنگام عیب‌یابی مهم است؛ چون کاهش Admission Limit لزوماً همان اثر کاهش max-num-seqs را روی حافظه Startup ندارد.

مثال تنظیم محدودتر برای تست

vllm serve Qwen/Qwen3-0.6B \
--host 127.0.0.1 \
--port 8000 \
--max-model-len 2048 \
--gpu-memory-utilization 0.80 \
--max-num-seqs 4 \
--max-num-batched-tokens 2048

این مقادیر برای تست محافظه‌کارانه هستند و تنظیم پیشنهادی نهایی برای تمام مدل‌ها محسوب نمی‌شوند.

چرا بهتر است فقط یک متغیر را تغییر دهیم؟

اگر هم‌زمان مدل، Dtype، Context و Batch را تغییر دهید، مشخص نخواهد شد کدام عامل باعث رفع OOM شده است.

برای عیب‌یابی دقیق، ابتدا یک Baseline ثبت کنید و در هر آزمایش فقط یک پارامتر مهم را تغییر دهید.

Preemption در vLLM چیست و آیا همان CUDA OOM است؟

خیر. Preemption و CUDA OOM یکسان نیستند.

وقتی ظرفیت KV Cache برای نگهداری همه درخواست‌های فعال کافی نباشد، vLLM می‌تواند بعضی درخواست‌ها را موقتاً کنار بگذارد و در ادامه بخشی از محاسبات آن‌ها را دوباره انجام دهد.

این رفتار به ادامه کار سیستم کمک می‌کند، اما ممکن است Latency افزایش پیدا کند.

نشانه‌های Preemption

• افزایش زمان پاسخ زیر بار.
• وجود پیام Preemption یا Recompute در Log.
• افزایش شمارنده Preemption در Metrics.
• کاهش بهره‌وری به دلیل اجرای دوباره بعضی محاسبات.

راهکارهای قابل بررسی

در صورت وجود حافظه آزاد واقعی، افزایش فضای KV Cache می‌تواند مفید باشد.

همچنین کاهش max-num-seqs یا max-num-batched-tokens، محدود کردن تعداد درخواست‌ها و استفاده از GPU بیشتر ممکن است فشار Cache را کاهش دهد.

اما این تغییرات باید با توجه به نوع خطا و نسخه vLLM انتخاب شوند.

مانیتورینگ Preemption

در نسخه‌های جدید، شمارنده‌ای مانند vllm:num_preemptions برای بررسی تعداد Preemptionها وجود دارد.

مقدار آن را بهتر است به‌صورت نرخ در بازه زمانی مناسب بررسی کنید، نه فقط یک عدد تجمعی از شروع فرآیند.

چه زمانی باید از چند GPU یا CPU Offloading استفاده کنیم؟

اگر بعد از بهینه‌سازی‌های منطقی هنوز وزن مدل یا KV Cache در یک GPU جا نمی‌شود، ممکن است واقعاً به سخت‌افزار بیشتری نیاز داشته باشید.

Tensor Parallelism

در این روش، بخش‌هایی از محاسبات و وزن‌های مدل روی چند GPU تقسیم می‌شوند.

vllm serve MODEL_ID \
--tensor-parallel-size 2 \
--host 127.0.0.1 \
--port 8000

این دستور فقط زمانی مناسب است که دو GPU سازگار و مدل قابل تقسیم در اختیار داشته باشید.

آیا مجموع VRAM دو GPU دقیقاً قابل استفاده است؟

خیر. سربار Runtime، حافظه جداگانه هر GPU و هزینه ارتباط بین کارت‌ها همچنان وجود دارد.

برای مدل‌های بزرگ بهتر است مصرف هر GPU را جداگانه بررسی کنید.

CPU Offloading

در بعضی پیکربندی‌ها می‌توان بخشی از وزن‌های مدل را از حافظه CPU در زمان اجرا استفاده کرد.

این روش ممکن است امکان اجرای مدل بزرگ‌تر را فراهم کند، اما انتقال داده میان CPU و GPU می‌تواند هزینه تأخیر و پهنای باند ایجاد کند.

KV Cache Offloading

نسخه‌های جدید vLLM قابلیت‌هایی برای Offloading حافظه KV نیز دارند که بسته به Backend و معماری ممکن است قابل استفاده باشند.

اما Offloading جایگزین رایگان افزایش VRAM نیست؛ باید تأثیر آن بر TTFT، TPOT و Throughput اندازه‌گیری شود.

چرا مقدار حافظه PyTorch با nvidia-smi فرق دارد؟

PyTorch برای مدیریت تخصیص‌ها از Caching Allocator استفاده می‌کند.

به همین دلیل بخشی از حافظه‌ای که در nvidia-smi مصرف‌شده دیده می‌شود، ممکن است در حال حاضر توسط Tensor فعال استفاده نشود، اما همچنان توسط Allocator رزرو شده باشد.

memory_allocated چیست؟

مقدار حافظه‌ای است که PyTorch برای Tensorهای فعال تخصیص داده است.

memory_reserved چیست؟

حافظه‌ای است که Allocator مربوط به PyTorch مدیریت یا رزرو کرده است.

مثال بررسی با PyTorch

import torch

if torch.cuda.is_available():
    print(
        "Allocated:",
        torch.cuda.memory_allocated() / 1024**3,
        "GiB",
    )

    print(
        "Reserved:",
        torch.cuda.memory_reserved() / 1024**3,
        "GiB",
    )

    print(
        "Peak allocated:",
        torch.cuda.max_memory_allocated() / 1024**3,
        "GiB",
    )

این اطلاعات مربوط به همان فرآیند Python است که کد در آن اجرا می‌شود. اگر آن را در یک فرآیند جدا از vLLM اجرا کنید، مصرف داخلی موتور اصلی را مشاهده نخواهید کرد.

آیا torch.cuda.empty_cache مشکل OOM را حل می‌کند؟

این دستور می‌تواند حافظه Cache بلااستفاده PyTorch را آزاد کند تا برای بخش‌های دیگر قابل استفاده باشد.

اما حافظه مربوط به Tensorهای فعال یا وزن‌های مدل را آزاد نمی‌کند و به همین دلیل راه‌حل عمومی برای OOM نیست.

همچنین اجرای این دستور در یک فرآیند دیگر، Cache داخلی فرآیند vLLM را پاک نمی‌کند.

مرجع: مستندات رسمی PyTorch CUDA Memory Management.

مرحله چهارم: اجرای ابزار Read-only بررسی GPU Memory

برای ثبت یک Snapshot قابل مقایسه از وضعیت GPU، ابزار Python همراه مقاله آماده شده است.

این ابزار هیچ کتابخانه خارجی نیاز ندارد و فقط اطلاعات حافظه و میزان استفاده از GPU را از nvidia-smi می‌خواند.

اجرای ابزار

python3 gpu_snapshot.py \
--output snapshot.json

اجرای آفلاین بدون GPU

python3 gpu_snapshot.py \
--from-csv sample-nvidia-smi.csv

نمونه خروجی

{
  "source": "offline_csv",
  "gpus": [
    {
      "index": "0",
      "total_mib": 24564,
      "used_mib": 18100,
      "free_mib": 6464,
      "used_percent": 73.69
    }
  ]
}

این نمونه خلاصه‌شده است و اطلاعات زمان و مشخصات GPU در خروجی واقعی نیز وجود دارد.

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

چه زمانی Snapshot بگیریم؟

بهتر است از یک GPU اختصاصی آزمایشی، در وضعیت Idle، هنگام Startup و پس از آماده شدن مدل Snapshot بگیرید.

همچنین برای بررسی Peak مصرف حافظه، پایش دوره‌ای و لاگ‌های داخلی vLLM ضروری هستند.

مرحله پنجم: راه‌اندازی vLLM با تنظیمات محافظه‌کارانه

پس از ثبت وضعیت GPU و بررسی لاگ، می‌توان با یک مدل کوچک و تنظیمات محدود، سلامت محیط را آزمایش کرد.

برای مثال:

vllm serve Qwen/Qwen3-0.6B \
--host 127.0.0.1 \
--port 8000 \
--served-model-name oom-test \
--dtype auto \
--max-model-len 2048 \
--gpu-memory-utilization 0.75 \
--max-num-seqs 4 \
--max-num-batched-tokens 2048 \
--enforce-eager

این دستور برای یک GPU سازگار، محیط تست مجزا و بدون Instance رقیب در نظر گرفته شده است.

اگر GPU یا Driver مناسب نباشد یا فرآیند دیگری حافظه را اشغال کرده باشد، حتی این نمونه کوچک نیز ممکن است اجرا نشود.

ترتیب پیشنهادی عیب‌یابی

1. مصرف GPU و فرآیندهای فعال را ثبت کنید.
2. مدل کوچک را با تنظیمات محافظه‌کارانه اجرا کنید.
3. اگر اجرا موفق بود، Dtype و اندازه مدل اصلی را بررسی کنید.
4. سپس max-model-len را متناسب با نیاز واقعی افزایش دهید.
5. پس از آن محدودیت Batch و Concurrency را تنظیم کنید.
6. در صورت نیاز CUDA Graph را دوباره فعال و تست کنید.
7. در پایان روی Workload واقعی Benchmark بگیرید.

هر تغییر بهتر است جداگانه ثبت شود تا مشخص باشد کدام پارامتر واقعاً روی OOM تأثیر داشته است.

چگونه مطمئن شویم مشکل OOM واقعاً برطرف شده است؟

موفقیت Startup به‌تنهایی کافی نیست. ممکن است مدل بدون خطا بارگذاری شود، اما زیر بار واقعی دوباره با فشار حافظه مواجه شود.

تست اول: یک درخواست کوتاه

یک درخواست با Context کوتاه ارسال کنید و صحت پاسخ API را بررسی کنید.

تست دوم: Context بلندتر

درخواست‌هایی با طول Context نزدیک به نیاز واقعی برنامه اجرا کنید و مصرف KV Cache را بررسی کنید.

تست سوم: Concurrency تدریجی

تعداد درخواست‌های هم‌زمان را به‌تدریج افزایش دهید؛ مثلاً از یک درخواست شروع کنید و سپس مقادیر ۲، ۴ و ۸ را در صورت پشتیبانی محیط آزمایش کنید.

تست چهارم: بار پایدار

به‌جای یک Burst کوتاه، مدت مشخصی درخواست واقعی‌نما ارسال کنید تا پایداری حافظه و Queue بررسی شود.

تست پنجم: راه‌اندازی مجدد کنترل‌شده

در محیط آزمایشی بررسی کنید آیا سرویس پس از Startup مجدد نیز با همان پیکربندی و شرایط حافظه، رفتار مشابهی دارد.

چه معیارهایی ثبت کنیم؟

برای اجرای تست رسمی می‌توانید از vllm bench serve استفاده کنید.

مقایسه باید با مدل، نسخه، Dtype، طول Prompt و تعداد درخواست‌های یکسان انجام شود.

چگونه از بازگشت خطای CUDA OOM جلوگیری کنیم؟

اگر vLLM در Production اجرا می‌شود، بهتر است مصرف حافظه و ظرفیت درخواست‌ها به‌صورت مستمر مانیتور شوند.

مهم‌ترین شاخص‌ها

• VRAM آزاد و مصرف‌شده برای هر GPU.
• میزان استفاده از KV Cache.
• تعداد Preemptionها و نرخ افزایش آن‌ها.
• تعداد درخواست‌های در صف.
• تأخیر پاسخ به تفکیک TTFT و TPOT.
• تعداد خطاهای API و شکست Workerها.
• تغییر مصرف GPU هنگام Deploy یا اجرای سرویس‌های دیگر.

مشاهده Metrics داخلی vLLM

curl --fail --silent \
http://127.0.0.1:8000/metrics

در سرویس عمومی، Endpointهای Metrics باید پشت کنترل دسترسی مناسب قرار بگیرند.

چرا مانیتورینگ vLLM را از خود مدل جدا کنیم؟

اگر خود موتور vLLM با OOM متوقف شود، سیستم هشداردهی نباید به همان فرآیند وابسته باشد.

می‌توانید از ابزارهای مستقل مانند Prometheus، GPU Exporter و Alertmanager برای پایش سلامت استفاده کنید.

برای ساخت یک گردش کار تحلیل هشدار با هوش مصنوعی، مقاله ساخت AI Server Monitoring Agent نیز مرتبط است.

۱۴ اشتباه رایج هنگام رفع CUDA Out of Memory در vLLM

۱. افزایش gpu-memory-utilization بدون بررسی علت

اگر GPU از قبل پر است، افزایش بودجه حافظه می‌تواند باعث شکست Startup شود. ابتدا میزان VRAM آزاد را اندازه بگیرید.

۲. کاهش max-model-len برای مدلی که وزن آن جا نمی‌شود

کاهش Context وزن مدل را کوچک نمی‌کند. ابتدا حجم وزن‌ها را بررسی کنید.

۳. تغییر هم‌زمان چند پارامتر

با تغییر هم‌زمان Model Size، Dtype و Batch، علت واقعی بهبود مشخص نمی‌شود.

۴. اعتماد به عدد فایل مدل در Hugging Face

حجم فایل تنها بخشی از مصرف حافظه است. Runtime، KV Cache و Activationها نیز به VRAM نیاز دارند.

۵. فرض اینکه مدل Quantized همیشه سریع‌تر است

Quantization ممکن است حافظه را کاهش دهد، اما عملکرد نهایی به Kernel، Backend و GPU وابسته است.

۶. پاک کردن Cache مدل بدون دلیل

حذف Cache دانلود مدل معمولاً حافظه GPU فرآیند فعال را آزاد نمی‌کند و فقط باعث دانلود دوباره می‌شود.

۷. اجرای torch.cuda.empty_cache در فرآیند اشتباه

Cache مربوط به یک فرآیند دیگر با این کار پاک نمی‌شود و حافظه Tensorهای فعال نیز آزاد نخواهد شد.

۸. نادیده گرفتن مصرف سایر فرآیندها

یک Instance دیگر یا Notebook فعال ممکن است بخش قابل توجهی از VRAM را اشغال کرده باشد.

۹. اشتباه گرفتن Preemption با OOM

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

۱۰. استفاده دائمی از enforce-eager بدون Benchmark

این تنظیم برای تشخیص مفید است، اما ممکن است کارایی موتور را کاهش دهد.

۱۱. تنظیم دستی KV Cache بدون اندازه‌گیری

مقدار بزرگ می‌تواند تخصیص حافظه را ناموفق کند و مقدار کوچک می‌تواند Throughput را کاهش دهد.

۱۲. فرض اینکه چند GPU دقیقاً VRAM قابل جمع دارند

سربار هر GPU و هزینه ارتباط میان کارت‌ها باید در ظرفیت‌سنجی لحاظ شود.

۱۳. تست فقط با یک درخواست کوتاه

مدل ممکن است برای یک درخواست کوچک پایدار باشد، اما با Context طولانی یا Concurrency بالا دچار مشکل شود.

۱۴. توقف فرآیندهای GPU بدون بررسی مالکیت

این کار ممکن است پردازش کاربران یا سرویس‌های دیگر را مختل کند. تغییرات باید کنترل‌شده و با مجوز انجام شوند.

سؤالات متداول درباره vLLM CUDA OOM

خطای CUDA Out of Memory در vLLM چیست؟

خطایی است که هنگام ناتوانی در تخصیص حافظه موردنیاز روی GPU رخ می‌دهد.

چرا vLLM هنگام Load مدل OOM می‌دهد؟

ممکن است وزن مدل، نوع داده یا حافظه آزاد GPU برای بارگذاری کافی نباشد.

چرا مدل اجرا می‌شود ولی هنگام درخواست OOM می‌دهد؟

ممکن است حافظه موردنیاز برای KV Cache، پردازش Batch یا فعالیت هم‌زمان از ظرفیت موجود بیشتر شود.

gpu-memory-utilization را چند بگذاریم؟

مقدار ثابتی برای تمام GPUها وجود ندارد. باید براساس مصرف واقعی، نوع Cache و تست پایداری تنظیم شود.

آیا افزایش gpu-memory-utilization خطای OOM را رفع می‌کند؟

گاهی برای افزایش ظرفیت KV Cache مفید است، اما ممکن است OOM هنگام Startup را بدتر کند.

آیا کاهش max-model-len مشکل را حل می‌کند؟

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

KV Cache چیست؟

بخشی از حافظه است که اطلاعات Attention Tokenهای قبلی را برای تولید Tokenهای بعدی نگهداری می‌کند.

آیا KV Cache با تعداد کاربران افزایش می‌یابد؟

با افزایش تعداد و طول Sequenceهای فعال، تقاضا برای KV Cache معمولاً بیشتر می‌شود.

Preemption با CUDA OOM چه تفاوتی دارد؟

Preemption مکانیزم مدیریت فشار Cache است؛ CUDA OOM خطای واقعی تخصیص حافظه GPU است.

آیا FP16 حافظه کمتری از FP32 مصرف می‌کند؟

برای وزن‌های مشابه، حجم نظری FP16 تقریباً نصف FP32 است؛ اما مصرف کل GPU الزاماً نصف نمی‌شود.

آیا BF16 بهتر از FP16 است؟

هر دو معمولاً دو بایت برای هر مقدار استفاده می‌کنند. انتخاب به نیاز مدل و سازگاری سخت‌افزار بستگی دارد.

آیا Quantization مشکل OOM را برطرف می‌کند؟

اگر بخش اصلی مصرف مربوط به وزن‌ها باشد، می‌تواند کمک کند؛ اما همه مشکلات Cache و Runtime را حل نمی‌کند.

آیا مدل ۷B روی GPU با VRAM هشت گیگابایت اجرا می‌شود؟

به نوع Precision، Quantization، معماری مدل، Context و Backend بستگی دارد. نسخه FP16 معمولی آن معمولاً بیش از این مقدار را فقط برای وزن‌ها نیاز دارد.

Memory Profiling در vLLM چیست؟

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

آیا CUDA Graph حافظه اضافی مصرف می‌کند؟

در بعضی پیکربندی‌ها بله. می‌توان برای تشخیص، حالت Eager را مقایسه کرد.

enforce-eager چه کاری انجام می‌دهد؟

در نسخه فعلی مسیر CUDA Graph و Compile مربوطه را برای اجرای Eager غیرفعال می‌کند.

آیا enforce-eager همیشه بهتر است؟

خیر. ممکن است OOM را در بعضی شرایط کاهش دهد، اما عملکرد را نیز تحت تأثیر قرار دهد.

max-num-seqs چیست؟

سقف تعداد Sequenceهایی است که موتور در یک Iteration پردازش می‌کند و می‌تواند روی ظرفیت Runner و حافظه اثر بگذارد.

max-num-batched-tokens چه کاربردی دارد؟

تعداد Tokenهای قابل پردازش در یک Iteration را محدود می‌کند.

آیا کاهش Concurrency مصرف حافظه را کم می‌کند؟

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

چرا nvidia-smi و PyTorch مصرف متفاوت نشان می‌دهند؟

به دلیل تفاوت دامنه اندازه‌گیری، Caching Allocator و مصرف بخش‌هایی خارج از PyTorch.

آیا torch.cuda.empty_cache مدل را از VRAM حذف می‌کند؟

خیر. حافظه Tensorهای فعال و وزن‌های در حال استفاده را آزاد نمی‌کند.

آیا CPU Offloading جایگزین GPU با VRAM بالاتر است؟

ممکن است اجرای بعضی مدل‌ها را ممکن کند، اما هزینه انتقال حافظه و افت عملکرد باید بررسی شود.

آیا دو GPU مشکل OOM را حل می‌کنند؟

برای مدل‌های قابل تقسیم می‌توانند کمک کنند، اما سربار و سازگاری Multi-GPU باید بررسی شود.

چگونه بفهمیم مشکل کاملاً رفع شده است؟

با تست Startup، Context طولانی، Concurrency تدریجی، بار پایدار و بررسی Metrics و خطاها.

آیا خطای CUDA OOM همیشه به معنی نیاز به سرور قوی‌تر است؟

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

آیا این روش‌ها برای نسخه 0.33.0 مناسب‌اند؟

بله، مفاهیم و گزینه‌های اصلی مقاله براساس مستندات فعلی این نسخه بررسی شده‌اند. رفتار نهایی همچنان به Model Runner، GPU و Backend انتخابی وابسته است.

جمع‌بندی

برای رفع اصولی vLLM CUDA OOM ابتدا باید مشخص کنید خطا هنگام Loading، Profiling، ساخت KV Cache، CUDA Graph Capture یا پردازش درخواست‌های هم‌زمان رخ می‌دهد.

اگر وزن مدل در GPU جا نمی‌شود، بررسی Model Size، Dtype، Quantization و Multi-GPU اولویت دارد. اگر مدل بارگذاری می‌شود اما در بار هم‌زمان مشکل پیدا می‌کند، باید KV Cache، Concurrency و Batch Scheduling را بررسی کنید.

همچنین یاد گرفتیم که gpu-memory-utilization همیشه نباید افزایش پیدا کند؛ چون تأثیر آن به وضعیت حافظه و نوع Cache بستگی دارد. در نسخه‌های جدید vLLM، سازوکارهای KV Cache و Profiling نسبت به بعضی نسخه‌های قدیمی تغییر کرده‌اند.

برای تشخیص بهتر باید از nvidia-smi، لاگ‌های داخلی vLLM، Memory Profiling و معیارهایی مانند KV Cache Usage، Preemption، TTFT و Throughput استفاده شود.

نتیجه اصلی: OOM را با حدس و تغییر تصادفی پارامترها رفع نکنید. ابتدا مصرف واقعی حافظه را اندازه بگیرید، مرحله شکست را مشخص کنید و هر تنظیم را جداگانه آزمایش کنید. اگر سخت‌افزار واقعاً ظرفیت کافی ندارد، ارتقای VRAM یا تقسیم مدل روی چند GPU راه‌حل پایدار‌تری خواهد بود.

اگر هنوز با مبانی اجرای مدل آشنا نیستید، ابتدا راهنمای vLLM چیست و چگونه API مدل زبانی روی GPU بسازیم؟ را مطالعه کنید.