سناریوی رخداد

خطای 400 برای پاسخ‌های طولانی

A 400 for long answers

  • سطح ۱: غربالگری
  • سناریوی رخداد
  • ۱۵ دقیقه

وضعیت

یک تیم محصول، مدل Qwen/Qwen3-0.6B را روی یک سرور vLLM برای ابزار نگارش داخلی شرکت اجرا می‌کند. یک تیکت پشتیبانی ثبت می‌شود: «API پاسخ‌های طولانی را رد می‌کند». کلاینت مقدار max_tokens را روی 50000 تنظیم کرده تا مدل هیچ‌وقت پاسخی را نصفه‌کاره رها نکند؛ اما تک‌تک این درخواست‌ها فوراً و قبل از استریم شدن حتی یک توکن، با خطای HTTP 400 برمی‌گردند. درخواست‌های کوتاه‌تر بدون مشکل کار می‌کنند.

در تیکت از تیم پلتفرم خواسته شده که «این محدودیت را غیرفعال کند». شما بررسی مسئله را با نگاه به متن خطا، لاگ راه‌اندازی سرور و مستندات آغاز می‌کنید.

نسخه
vLLM 0.31.0
مدل
Qwen/Qwen3-0.6B
سخت‌افزار
the shared second L4 of a two-GPU node, with another user's processes on it

شواهد

a-cut-answer.txt
title: a request that the server cut at its own cap
source: manuals/vllm-101/capture/gpu/out-l4/livecheck-2026-10-22.txt
lines: 19-22
lang: text
note: With max_tokens of 64 the finish reason is length, and the reasoning field holds the start of the answer.
---
== c03 thinking on, 64 tokens
finish length
content None
reasoning "\nOkay, the user asked me to name three prime numbers. Let me think. First, what's a prime number? A prime number is a nu"
four-ways-to-fit-more.txt
title: the four choices when the pool holds too few users, in order of cost
source: manuals/vllm-101/sections/2-1-count-the-memory-before-you-pick-a-gpu.md
lines: 83-90
lang: text
note: The first choice is the one that this ticket is about.
---
## Decide what to change

If the count is too small for your traffic, you have four choices. They are in order of cost:

1. Lower `--max-model-len` to the longest context that your users send. The pool stays the same size, and one long request can no longer take all of it.
2. Use an FP8 KV cache. It halves the bytes per token. [The FP8 KV page](#s-fit-more-users-with-an-fp8-kv-cache) shows the cost.
3. Use FP8 weights. They free memory for the cache. [The FP8 weights page](#s-fit-a-bigger-model-with-fp8-weights) shows when this pays.
4. Use a GPU with more memory, or split the model across GPUs. [The parallelism page](#s-choose-tensor-pipeline-or-data-parallelism) covers this.
the-error.txt
title: the 400 answer to a request with max_tokens of 50000
source: manuals/vllm-101/capture/gpu/out-l4/livecheck-2026-10-22.txt
lines: 46-48
lang: text
note: Read the two numbers in the message and the parameter that it names.
---
== c44 max_tokens above max model len
HTTP/1.1 400 Bad Request
{"error":{"message":"max_tokens=50000 cannot be greater than max_model_len=40960. Please request fewer output tokens. (parameter=max_tokens, value=50000)","type":"BadRequestError","param":"max_tokens","code":400}}
the-pool-at-startup.txt
title: the pool and the maximum length of that server at startup
source: manuals/vllm-101/capture/gpu/out-l4/livecheck-2026-10-22.txt
lines: 11-12
lang: text
note: The second line gives the longest request the server accepts and how many such requests fit in the pool.
---
(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
the-troubleshooting-entry.txt
title: the troubleshooting entry for this status code
source: manuals/vllm-101/sections/7-1-troubleshoot-by-symptom.md
lines: 99-103
lang: text
note: Two shapes of the same error, and the fix for each side.
---
### A request returns HTTP 400 about the maximum context length

- **Cause:** the prompt tokens plus `max_tokens` are more than `--max-model-len`.
- **Check:** the error says `This model's maximum context length is` and gives the counts. When `max_tokens` alone is above the limit, the error says that `max_tokens` cannot be greater than `max_model_len`, as it did on our L4.
- **Fix:** send a shorter prompt or a smaller `max_tokens`, or start the server with a larger maximum length if the pool allows it.

سؤال‌ها

  1. متن خطا را بخوانید. این پیام کدام دو عدد را با هم مقایسه می‌کند و نام کدام پارامتر در آن آمده است؟
  2. سرور عدد دوم را از کجا می‌آورد و این عدد چه ارتباطی با استخر حافظه‌ی KV دارد؟
  3. در تیکت خواسته شده محدودیت برداشته شود. دو راهکار اصولی برای حل مشکل چیست و هر تغییر را چه کسی باید انجام دهد؟
  4. تیکت دیگری همین کد وضعیت را گزارش می‌کند، اما این بار در پیام خطا به طول پرامپت (Prompt) اشاره شده است. تفاوت در چیست و راه حل چیست؟

اول شواهد را بخوانید و به سؤال‌ها جواب بدهید، بعد راه‌حل را باز کنید.

راه‌حل گام‌به‌گام
  1. متن خطا را بررسی کنید. پیام می‌گوید مقدار max_tokens=50000 نمی‌تواند از max_model_len=40960 بیشتر باشد، و در فیلد param به max_tokens اشاره شده است. سرور ارقام درخواست را قبل از زمان‌بندی بررسی می‌کند؛ بنابراین خطای 400 فوراً بازگردانده می‌شود و هیچ توکنی تولید نمی‌شود. کلاینت خروجی بیشتری از گنجایش مجاز یک درخواست خواسته است.
  2. خطوط لاگ راه‌اندازی را بخوانید. سرور طولانی‌ترین درخواست مجاز را بر اساس پیکربندی مدل 40960 توکن در نظر گرفته، و ظرفیت استخر حافظه را با تکیه بر 9.02 GiB حافظه‌ی کش کلید-مقدار (KV cache) روی 84480 توکن تنظیم کرده است. خط دوم نشان می‌دهد که سرور هم‌زمان فقط گنجایش 2.06 درخواست با حداکثر طول را دارد. حداکثر طول، سهمیه‌ی یک درخواست است و استخر حافظه، سهمیه‌ی کل کاربران. درخواست برای 50000 توکن خروجی، حتی روی یک سرور کاملاً خلوت هم از سهمیه‌ی اول فراتر می‌رود.
  3. ببینید پاسخ کوتاه شده چه شکلی است. در همان نشستِ (Session) بررسی، درخواستی با max_tokens برابر با 64 اجرا شد و سرور ادامه‌ی آن را با دلیل خاتمه‌ی length متوقف کرد. کلاینت از همین طریق متوجه می‌شود که پاسخ ناقص مانده است: استریم به جای stop با length پایان می‌یابد. راه‌حل جلوگیری از قطع شدن پاسخ، گذاشتن یک عدد نجومی برای max_tokens نیست؛ بلکه راه درست این است که دلیل خاتمه را بررسی کنید.
  4. دو حالت مختلف خطا را بررسی کنید. در بخش عیب‌یابی هر دو حالت آمده است. وقتی مجموع توکن‌های پرامپت و max_tokens از حد مجاز بگذرد، پیام خطا به حداکثر طول زمینه (context length) مدل اشاره می‌کند و تعداد توکن‌ها را نشان می‌دهد. وقتی فقط خود max_tokens از حد مجاز بالاتر باشد، همان پیامی صادر می‌شود که در این تیکت دیدیم. راهکار در هر دو حالت یکسان است: کاهش طول پرامپت یا مقدار max_tokens در سمت کلاینت، یا در صورت اجازه‌ی ظرفیت استخر، افزایش حداکثر طول مجاز در سمت سرور.
  5. اولویت گزینه‌های سمت سرور را مرور کنید. مستندات چهار اقدام را برای مواقعی که استخر کاربران کمی را نگه می‌دارد، به ترتیب هزینه فهرست کرده است؛ اولین راهکار، کاهش حداکثر طول به اندازه‌ی طولانی‌ترین زمینه‌ای است که کاربران واقعاً می‌فرستند. خواسته‌ی این تیکت دقیقاً عکس این مسیر است: بالا بردن محدودیت باعث می‌شود یک درخواست، سهم بزرگ‌تری از استخر را ببلعد. لاگ راه‌اندازی قبلاً نشان داد که این فضا تقریباً برای دو درخواست کامل کافی است. افزایش محدودیت به معنی سرویس‌دهی به کاربران هم‌زمانِ کمتر است؛ پس این یک تصمیم مهندسی و سنجیده است، نه صرفاً بستن یک تیکت.
نتیجه

این محدودیت یک سهمیه‌بندی حساب‌شده است، نه یک باگ. کلاینت 50000 توکن خروجی روی سروری خواسته که طولانی‌ترین درخواست مجازش 40960 توکن است، و سرور پیش از شروع هر کاری درخواست را رد کرده است. راه‌حل کلاینت این است که مقدار max_tokens را متناسب با نیاز واقعی محصول و بسیار کمتر از سقف مجاز بگذارد، و دلیل خاتمه را بررسی کند تا اگر پاسخی قطع شد، برای کاربر مشخص باشد. آزمایش با 64 توکن دقیقاً همین را نشان می‌دهد: وقتی سرور پاسخ را نصفه می‌گذارد، مقدار length را گزارش می‌دهد.

تغییر سمت سرور هم ممکن است، ولی شرط دارد. پارامتر --max-model-len را فقط زمانی افزایش دهید که طولانی‌ترین مجموع پرامپت و پاسخ ارسالی کاربران را اندازه گرفته باشید، و مطمئن شوید که یک درخواست در آن ابعاد، در کنار سایر کاربران همچنان در استخر حافظه جا می‌شود. در استخری با ظرفیت 84480 توکن، هر پله افزایش محدودیت، تعداد درخواست‌های کاملی را که هم‌زمان جا می‌شوند از عدد 2.06 لاگ راه‌اندازی کمتر می‌کند. بررسی‌های زمان راه‌اندازی، همین قاعده را از طرف دیگر هم اعمال می‌کنند: سروری که نتواند حتی یک درخواست با طول کامل را در خود جا دهد اصلاً بالا نمی‌آید؛ درست مثل نمونه‌ی راه‌اندازی روی GPU اشتراکی در مستندات که وقتی فقط 2912 توکن جا داشت، روی 2928 توکن از اجرا انصراف داد.

مسیرهای اشتباه رایج
  • «غیرفعال کردن محدودیت روی سرور.» حداکثر طول، سقف کش کلید-مقداری است که یک درخواست می‌تواند مصرف کند و استخر حافظه ظرفیت آن را تعیین می‌کند. بدون این سقف، یک درخواست می‌تواند بیشترِ استخر را تصاحب کند و سایر کاربران را در محرومیت منابع (Starvation) بگذارد.
  • «تنظیم max_tokens دقیقاً روی سقف مجاز سرور.» در این حالت، مجموع پرامپت و پاسخ از طول زمینه بیشتر می‌شود و سرور شکل دیگر همان خطای 400 را برمی‌گرداند؛ همان خطایی که نام توکن‌های پرامپت در آن می‌آید.
  • «افزایش مداوم حداکثر طول تا زمانی که تیکت‌ها متوقف شوند.» سقف طولانی‌تر یعنی درخواست‌های هم‌زمانِ کمتر. اول طولانی‌ترین درخواست واقعی را اندازه بگیرید و مطمئن شوید که در استخر حافظه جا می‌شود.
  • «تلاش مجدد برای ارسال همان درخواست.» خطای 400 حاصل بررسی مقادیر خودِ درخواست است؛ ارسال دوباره‌ی همان درخواست، همان نتیجه را دارد.
درس کلی

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

کجای دوره آموزش داده می‌شود

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