执行摘要

• 一句话：拒绝无效 thinking_token_budget 并标准化 -1
• 推荐动作：值得精读，尤其是 BeforeValidator 的 Pydantic 验证模式，适合作为 vLLM 中其他参数输入验证的参考。

功能与动机

修复 invalid thinking_token_budget 值在 API 中被错误接受并导致静默错误的问题，应与 logprobs 等参数一样拒绝无效输入。文档中 -1 表示 unlimited 但实际仍触发预算跟踪，需要对齐。

实现拆解

1. 定义验证函数与类型：在 vllm/sampling_params.py 新增 validate_thinking_token_budget 函数，拒绝 None 以外的非整数、负数、布尔和浮点值，-1 转换为 None。并使用 Annotated[int | None, BeforeValidator(validate_thinking_token_budget)] 定义 ThinkingTokenBudget 类型。
2. 集成到 SamplingParams：在 SamplingParams.__post_init__ 中调用 validate_thinking_token_budget 对字段进行验证和标准化。
3. 应用至请求模型：将 ChatCompletionRequest 和 CompletionRequest 的 thinking_token_budget 字段类型从 int | None 改为 ThinkingTokenBudget，使 Pydantic 在解析请求时自动调用验证。
4. 添加单元测试：新建 tests/entrypoints/openai/chat_completion/test_thinking_token_budget_validation.py 测试请求层验证，并在 tests/v1/logits_processors/test_correctness.py 中添加对 validate_thinking_token_budget 函数和 SamplingParams 的单元测试。

关键文件：

• vllm/sampling_params.py（模块 采样参数；类别 source；类型 core-logic；符号 validate_thinking_token_budget, ThinkingTokenBudget）: 核心验证函数和 BeforeValidator 类型定义，所有入口点的验证基础
• tests/entrypoints/openai/chat_completion/test_thinking_token_budget_validation.py（模块 预算验证；类别 test；类型 test-coverage；符号 test_chat_completion_request_rejects_invalid_thinking_token_budget, test_chat_completion_request_accepts_valid_thinking_token_budget, test_chat_completion_request_accepts_minus_one_as_unlimited, test_completion_request_rejects_invalid_thinking_token_budget）: 新增文件，覆盖请求层验证，确保 ChatCompletionRequest 和 CompletionRequest 正确验证预算值
• tests/v1/logits_processors/test_correctness.py（模块 正确性测试；类别 test；类型 test-coverage；符号 test_validate_thinking_token_budget, test_sampling_params_minus_one_normalizes_to_none, test_validate_thinking_token_budget_rejects_invalid, test_thinking_budget_invalid_budget_rejected）: 扩展现有测试，验证 validate_thinking_token_budget 函数和 SamplingParams 处理
• vllm/entrypoints/openai/completion/protocol.py（模块 补全接口；类别 source；类型 core-logic）: 将 thinking_token_budget 字段类型改为 ThinkingTokenBudget，使其在请求解析时自动验证
• vllm/entrypoints/openai/chat_completion/protocol.py（模块 聊天接口；类别 source；类型 core-logic）: 同样的类型修改，应用于聊天接口

关键符号：validate_thinking_token_budget, test_validate_thinking_token_budget, test_sampling_params_minus_one_normalizes_to_none, test_validate_thinking_token_budget_rejects_invalid, test_thinking_budget_invalid_budget_rejected, test_chat_completion_request_rejects_invalid_thinking_token_budget, test_chat_completion_request_accepts_valid_thinking_token_budget, test_chat_completion_request_accepts_minus_one_as_unlimited, test_completion_request_rejects_invalid_thinking_token_budget, test_completion_request_accepts_valid_thinking_token_budget, test_completion_request_accepts_minus_one_as_unlimited

评论区精华

讨论1：无效值应拒绝还是静默忽略

• gemini-code-assist[bot] 建议放宽类型，允许字符串和整数浮点数转换。
• DarkLight1337 认为应拒绝请求而非静默忽略，与已有参数验证方式一致。
• 作者 linzm1007 同意并修改为拒绝。

讨论2：-1 值标准化

• DarkLight1337 指出应保持 -1 文档语义（unlimited），作者同意并在 CompletionRequest 中实现标准化。

• 无效值处理方式：拒绝 vs 静默忽略 (correctness): 确定为拒绝请求并返回 VLLMValidationError

• -1 值应标准化为 None 保持 unlimited 语义 (correctness): 实现 -1 标准化为 None

风险与影响

• 风险：向后兼容性：之前接受 -2 等无效值的客户端将收到 HTTP 400 错误，需要更新。但这是合理的 bug 修复，影响可控。功能影响：-1 标准化为 None 后，内部 ThinkingBudgetStateHolder 不再创建，行为与文档一致。测试覆盖：新增测试覆盖了边界情况，风险低。
• 影响：用户影响：使用 reasoning 模型并设置 thinking_token_budget 的请求现在获得更严格的输入验证，错误立即返回而非产生空 reasoning 块。系统影响：无性能影响，验证仅发生在请求解析时。团队影响：为后续类似参数验证提供了可复用的 BeforeValidator 模式。
• 风险标记：向后兼容性影响, 无效值处理行为变更

关联脉络

• 暂无明显关联 PR