وضعیت
مهندس نوبت پاسخگویی (آنکال)، مدل Qwen/Qwen3-8B را با vLLM روی دومین کارت L4 یک نود مستقر میکند. تیم دیگری نیز پادهایش را روی همان GPU اجرا میکند و بخشی از حافظهی آن را در اختیار دارد. سرور پیش از چاپ خط مربوط به اندازهی کش کلید-مقدار (KV cache) متوقف میشود و لاگ با یک ValueError به پایان میرسد که در آن به حداکثر 40,960 توکن اشاره شده است.
یکی از همکاران که قبلاً این خطا را دیده است، دو فلگ را تنظیم میکند: --gpu-memory-utilization 0.83 تا مصرف، زیر سقف حافظهی مورد استفادهی تیم دیگر باقی بماند، و --max-model-len 2928 که با استخرِ (pool) 2,928 توکنی مدنظرشان برای تست همخوانی دارد. سرور دوباره و تقریباً با همان پیام قبلی با شکست مواجه میشود. اکنون مهندس قصد دارد نسبت حافظه را به 0.95 افزایش دهد و یک بار دیگر تلاش کند.
- نسخه
- vLLM 0.31.0
- مدل
- Qwen/Qwen3-8B
- سختافزار
- the shared second L4 of a two-GPU node, with another team's processes on it
شواهد
a-start-that-works.txt
title: a start on the same shared GPU that reached the pool line
source: manuals/vllm-101/capture/gpu/out-l4/livecheck-2026-10-22.txt
lines: 6-13
lang: text
note: Read the memory fraction in the first line, then the two memory lines near the end.
---
== c01 startup lines
(APIServer pid=2812801) INFO 10-22 21:24:23 [api_utils.py:286] non-default args: {'model_tag': 'Qwen/Qwen3-0.6B', 'port': 8010, 'reasoning_parser': 'qwen3', 'gpu_memory_utilization': 0.5}
(EngineCore pid=2813854) INFO 10-22 21:24:39 [gpu_worker.py:479] Using V2 Model Runner
(EngineCore pid=2813854) INFO 10-22 21:24:41 [cuda.py:526] Using FLASH_ATTN attention backend out of potential backends: ['FLASH_ATTN', 'FLASHINFER', 'TRITON_ATTN', 'FLEX_ATTENTION'].
(EngineCore pid=2813854) INFO 10-22 21:24:43 [model_runner.py:407] Model loading took 1.12 GiB memory and 3.909338 seconds
(EngineCore pid=2813854) INFO 10-22 21:25:26 [gpu_worker.py:692] Available KV cache memory: 9.02 GiB
(EngineCore pid=2813854) INFO 10-22 21:25:26 [kv_cache_utils.py:2464] GPU KV cache size: 84,480 tokens, Maximum concurrency for 40,960 tokens per request: 2.06x
INFO: Application startup complete.
default-length-fails.txt
title: the first start, with the default maximum model length
source: manuals/vllm-101/capture/gpu/out-l4/livecheck-2026-10-22.txt
lines: 105-110
lang: text
note: Read the three sizes in the error: the length, the cache it needs and the cache that is free.
---
== c18 Qwen3-8B BF16, no max-model-len
rc=1
(EngineCore pid=2870799) ERROR 10-22 21:45:27 [core.py:1433] raise ValueError(
(EngineCore pid=2870799) ERROR 10-22 21:45:27 [core.py:1433] ValueError: To serve at least one request with the model's max seq len (40960), (5.62 GiB KV cache is needed, which is larger than the available KV cache memory (1.01 GiB). Based on the available memory, the estimated maximum model length is 7360. Try increasing `gpu_m
raise ValueError(
ValueError: To serve at least one request with the model's max seq len (40960), (5.62 GiB KV cache is needed, which is larger than the available KV cache memory (1.01 GiB). Based on the available memory, the estimated maximum model length is 7360. Try increasing `gpu_memory_utilization` (which also controls CPU memory on the CPU
three-cases.txt
title: the three startup failures and the flag for each
source: manuals/vllm-101/sections/2-2-fix-out-of-memory-at-startup.md
lines: 22-26
lang: text
note: Match the error text of each failed start with a row.
---
| What the log says | Cause | Fix |
|---|---|---|
| The KV cache needed for one request at the maximum length is larger than the available KV cache memory | The weights and the profile leave too little for one full-length request | Lower `--max-model-len`. The error gives the largest length that fits. |
| The free memory on the device is less than the desired GPU memory utilization | Another process holds GPU memory | Lower `--gpu-memory-utilization` below the free share, or stop the other process |
| CUDA out of memory during the profile run or the graph capture | The batch in the profile pass or the graphs need more memory than is left | Lower `--max-num-seqs` or `--max-num-batched-tokens`, or lower `--max-cudagraph-capture-size` |
tight-length-fails.txt
title: the second start, with the maximum length set to the pool size
source: manuals/vllm-101/capture/gpu/incidents/l4-gpu1-vllm-maxlen-oom.txt
lines: 1-2
lang: text
note: The first line gives the three settings, the second line gives the length that would fit.
---
(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
سؤالها
- در پیام خطا به 40,960 توکن اشاره شده است. این عدد از کجا میآید و چرا وجود حتی یک درخواست با این طول، تعیین میکند که سرور راهاندازی شود یا خیر؟
- در تلاش دوم، حداکثر طول برابر با اندازهی استخر حافظه تنظیم شد اما با اختلاف 16 توکن شکست خورد. محاسباتی را که در خط خطا نمایش داده شده است توضیح دهید.
- روی یک GPU اشتراکی، نسبت حافظه بیانگر چیست و چرا افزایش آن به عنوان حرکت اول اشتباه است؟
- کدام خط هنگام راهاندازی اثبات میکند که راهکار جواب داده است، و آن را با چه چیزی مقایسه میکنید؟
- این سه فلگ را به ترتیبی که باید تغییرشان دهید مرتب کنید و متن لاگی را که به هر یک اشاره دارد نام ببرید.
اول شواهد را بخوانید و به سؤالها جواب بدهید، بعد راهحل را باز کنید.
راهحل گامبهگام
خطای اول را از انتها بخوانید. vLLM باید بتواند حداقل به یک درخواست با حداکثر طول توالی مدل پاسخ دهد. برای این مدل، طول مذکور برابر با 40,960 توکن است که اگر کسی --max-model-len را تنظیم نکرده باشد، از پیکربندی مدل خوانده میشود. یک درخواست با این طول به 5.62 گیبیبایت (GiB) کش کلید-مقدار نیاز دارد، و پس از بارگذاری وزنها و پروفایلینگ راهاندازی، تنها 1.01 گیبیبایت روی این کارت اشتراکی آزاد مانده بود. پیام خطا حتی پاسخ را هم محاسبه کرده است: حداکثر طول تخمینی مدل 7,360 توکن است. سرور به این دلیل که GPU برای مدل خیلی کوچک است شکست نخورد؛ بلکه علتش این بود که طول پیشفرض بسیار بیشتر از هر درخواستی است که این سرویس در عمل ارسال خواهد کرد.
خطای دوم همان بررسی را با اختلافی ناچیز نشان میدهد. خط تنظیمات، مقدار max_model_len را روی 2,928، نسبت حافظه را روی 0.83 و بلوک سفارشی را 183 بلوکِ 16 توکنی (یعنی 2,928 توکن) نشان میدهد. این بررسی، یک درخواست با حداکثر طول را با حافظهی کش کلید-مقداری که پس از پروفایلینگ باقی مانده مقایسه میکند، و آن حافظه فقط گنجایش 2,912 توکن را دارد. هر دو طرف مقایسه به صورت 0.4 گیبیبایت چاپ میشوند، بنابراین بررسی با اختلافی مویی شکست خورده است. وقتی حافظهی باقیمانده پس از پروفایلینگ کمتر از استخر مورد نظر شما باشد، تنظیم طول مدل دقیقاً برابر با آن استخر گرهی از کار باز نمیکند.
خروجی سوم نشان میدهد که یک اجرای موفق روی همان کارت به چه شکل است. مدلی کوچکتر با نسبت 0.5 راهاندازی شد، 1.12 گیبیبایت وزن را بارگذاری کرد و دو خط حیاتی را چاپ نمود: Available KV cache memory: 9.02 GiB و GPU KV cache size: 84,480 tokens، که در آن حداکثر همزمانی برای طول پیشفرض 2.06 برابر است. این دو خط، اثبات این هستند که راهاندازی به استخر حافظه رسیده است. خروجی آخر، این سه خطا را به سه فلگ نگاشت میکند. خطایی دربارهی حداکثر طول توالی به --max-model-len اشاره دارد. خطایی مبنی بر اینکه حافظهی آزاد کمتر از میزان بهرهبرداری مورد نظر است، به --gpu-memory-utilization یا به پردازهی (process) دیگر اشاره میکند. خطای کمبود حافظهی CUDA حین پروفایلینگ یا ثبت گراف (graph capture) نیز به محدودیتهای دسته (batch) یا اندازهی ثبت گراف برمیگردد.
نتیجه
راهکار تنها با تغییر یک فلگ انجام شد که مقدار آن از خود خطا خوانده شده بود. مقدار --max-model-len 2048 را تنظیم کردیم که درخواستهای 640 توکنی ما را پوشش میدهد، و سرور راهاندازی شد. بعداً آن را به 2,304 توکن افزایش دادیم تا تستهای دارای پیشوندهای 2,048 توکنی هم در آن جا شوند. روی یک GPU اشتراکی، نسبت حافظه و حداکثر طول در تعامل با یکدیگر کار میکنند، و اولین موردی که باید کاهش یابد حداکثر طول است؛ یعنی باید آن را تا اندازهی طولانیترین درخواستی که سرویس واقعاً ارسال میکند پایین آورد.
افزایش نسبت حافظه به 0.95 از دو جهت اشتباه بود. این نسبت، محدودیتی برای یک نمونهی vLLM روی کل حافظهی GPU است، نه سهمی از حافظهی آزاد در زمان راهاندازی سرور؛ بنابراین انتخاب نسبتی بالاتر روی یک کارت اشتراکی، ادعای مالکیت روی حافظهای است که یک مستأجر (tenant) دیگر قبلاً در اختیار گرفته است. علاوهبر این، خطای اول برای طولی درخواست حافظهی 5.62 گیبیبایتی کرده بود که هیچ درخواستی اصلاً به آن نیاز ندارد. زمانی که دو نمونه ناچارند یک GPU را با استخر حافظهی مشخص برای هر کدام به اشتراک بگذارند، کش را بر حسب بایت و با استفاده از فلگ --kv-cache-memory-bytes مشخص کنید. پس از هر تغییر، سرور را همراه با دستور tee روی لاگ اجرا کنید و عبارت GPU KV cache size را گرپ (grep) نمایید؛ سپس استخر حافظه را با مقدار بهدستآمده از صفحهی حافظه تطبیق دهید.
مسیرهای اشتباه رایج
- «افزایش نسبت حافظه تا جایی که سرور بالا بیاید.» این نسبت کسری از کل GPU است، نه از حافظهی آزاد. روی یک کارت اشتراکی، نسبت بالاتر دست روی حافظهای میگذارد که در اختیار پردازهی دیگری است؛ در نتیجه راهاندازی ممکن است کمی بعد در مرحلهی پروفایلینگ متوقف شود یا تسکِ تیم دیگر با خطا بخوابد.
- «این GPU برای یک مدل 8B خیلی کوچک است.» وزنها بارگذاری شدند. بررسیای که شکست خورد برای یک درخواست 40,960 توکنی بود، و در پیام خطا آمده بود که 7,360 توکن جا میشود.
- «تنظیم حداکثر طول دقیقاً برابر با اندازهی استخر حافظه.» در تلاش دوم این کار انجام شد و با اختلاف 16 توکن شکست خورد. استخر در قالب بلوکهای 16تایی شمرده میشود و بررسی طول به کمی حاشیهی امن نیاز دارد.
- «استفاده از بازنویسی دستی بلوکها (block override) در محیط عملیاتی (production) برای تحمیل اندازهی استخر.» این بازنویسی بررسی نمیکند که حافظه واقعاً وجود دارد یا نه. این یک فلگ آزمایشی است و روی یک کارت اشتراکی، در نخستین درخواستی که به حافظه نیاز پیدا کند خطا میدهد.
درس کلی
بررسیای در زمان راهاندازی که روی یک حد آستانه شکست میخورد، در اصل سؤالی دربارهی ترافیک ورودی شماست، نه سختافزارتان. عددی را که در خطا آمده بخوانید، بررسی کنید کدام تنظیمات باعث ایجاد آن شده و درخواستهای واقعی چه نیازی دارند، و ابتدا همان تنظیمات را تغییر دهید. روی هر سیستم اشتراکی، در نظر گرفتن کسری از کل حافظه قولی است که سایر مستأجران ندادهاند؛ بنابراین به سراغ محدودیتهایی بروید که بایتهای دقیق مورد نظرتان را مشخص میکنند.
کجای دوره آموزش داده میشود
راهنمای vLLM هر خطای راهاندازی را با یک فلگ در صفحهی خطای کمبود حافظه هنگام راهاندازی تطبیق میدهد، استخر را در صفحهی حافظه محاسبه میکند و خطوط راهاندازی را در صفحهی بررسی سلامت تحلیل میکند؛ همچنین راهنمای SGLang همین روش تعیین ابعاد راهاندازی را در صفحهی نسبت حافظه نشان میدهد.