PR #40775: [Bugfix] Don't reserve max_tokens strictly for chat completions

• Repository: vllm-project/vllm
• Author: hoobnn
• State: open | merged: False
• Link: https://github.com/vllm-project/vllm/pull/40775

Description (problem / solution / changelog)

Summary

Chat completions hard-failed validation when the chat template prepended tokens the caller could not easily predict. The most reproducible case is Qwen3.5 with enable_thinking=False, where the template injects <think>\n\n</think>\n\n (2 extra tokens vs. the default <think>\n). With a prompt sized to fit max_model_len - max_tokens, the post-template prompt overshoots by a token or two and the renderer raises VLLMValidationError, even though get_max_tokens would have auto-capped the generation budget moments later.

This PR introduces TokenizeParams.reserve_max_output_tokens (default True, preserving the completion / pooling / tokenize / responses behavior) and opts chat completions out of the strict reservation. The renderer still fails when the prompt alone exceeds max_model_len, and truncation/padding semantics tied to max_input_tokens (e.g. truncate_prompt_tokens=-1) are unchanged.

Fixes #40689.

Why this is not a duplicate

• gh pr list --repo vllm-project/vllm --state open --search "40689 in:body" → no matches
• gh pr list --repo vllm-project/vllm --state open --search "nothink enable_thinking" → no matches
• gh pr list --repo vllm-project/vllm --state all --search "max_tokens nothink" → no matches

The closest related change is #36197 (misleading error message wording), which only adjusts the error text and does not address the strict reservation.

What changed

• vllm/renderers/params.py
  • Add reserve_max_output_tokens: bool = True and _length_check_limit property
  • _text_len_check, _token_len_check, get_encode_kwargs use the new limit; error messages adapt when reservation is disabled
  • with_kwargs propagates the new flag
• vllm/entrypoints/openai/chat_completion/protocol.py
  • ChatCompletionRequest.build_tok_params sets reserve_max_output_tokens=False (with rationale comment)
• tests/renderers/test_completions.py
  • Add two regression tests: overshoot is allowed when opted out; prompts above max_model_len still error

Test plan

• pytest tests/renderers/test_completions.py -q → 24 passed
• pre-commit run --files vllm/renderers/params.py vllm/entrypoints/openai/chat_completion/protocol.py tests/renderers/test_completions.py → all hooks pass (ruff, ruff format, typos, mypy, SPDX, …)
• Local repro using Qwen3.5-4B + enable_thinking=False with max_model_len=8192 and max_tokens=7000: pre-fix the request raises VLLMValidationError; post-fix it succeeds. A prompt > max_model_len still raises with an updated message ("the prompt alone exceeds the model's context window"). The default completion path keeps the strict reservation.

Changed files

• tests/renderers/test_completions.py (modified, +47/-0)
• vllm/entrypoints/openai/chat_completion/protocol.py (modified, +7/-0)
• vllm/renderers/params.py (modified, +64/-20)