vLLM 怎样为在线服务设置请求最大 Token 数

我在把 vLLM 接到在线问答接口时，最先遇到的不是模型速度，而是回答长度不可控：同一条业务请求，有时只返回几百个 token，有时一直生成到上下文边界。要限制单次生成，优先在请求体中设置 max_tokens；服务启动参数 --max-model-len 管的是总上下文容量，两者不是同一个开关。

官方地址：https://docs.vllm.ai/en/stable/serving/openai_compatible_server/

请求级 max_tokens 应该放在哪里

vLLM 的 OpenAI 兼容 Chat Completions 接口把生成控制项放在 JSON 请求体内。下面的值只影响这一条请求，适合按业务类型动态分配预算：

# 用 curl 发送一次聊天请求，并限制本次最多生成 512 个 token
curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer dev-token' \
  -d '{
    "model": "your-model",
    "messages": [{"role": "user", "content": "用三点说明缓存击穿。"}],
    "max_tokens": 512,
    "temperature": 0.2
  }'

这里的 512 是“最多生成多少”，不是“必须生成多少”。模型遇到结束标记、请求中的停止条件或自身生成策略时，可能更早结束。Completions 接口同样把 max_tokens 放在请求体中，只是输入字段换成 prompt。

总上下文上限决定了 max_tokens 的天花板

实际可用的输出预算要先扣掉输入。一个简单的估算是：

可用输出上限 = min(请求 max_tokens，服务端可用上下文 - 输入 token 数)

启动服务时可以用 --max-model-len 约束总上下文长度：

# 设置服务端总上下文上限；它同时约束输入和输出的合计长度
vllm serve /models/your-model --max-model-len 8192

# 长上下文请求仍需在请求体中单独给出生成预算
curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"your-model","messages":[{"role":"user","content":"总结这段文本"}],"max_tokens":1024}'

不要把服务端参数当成每次请求的输出长度开关。若提示词已经占用 7600 个 token，再传入 1024 的 max_tokens，就可能触碰上下文边界；生产环境应在网关或客户端先做 token 估算，并为模板、工具调用和特殊 token 留余量。

用返回字段判断是否真的撞到了上限

只看回答字数不够可靠。兼容接口的响应通常会在选择结果中返回 finish_reason，结合输出 token 统计，可以把“达到上限”和“自然结束”分开：

在线服务可以把请求的 max_tokens、实际 completion token 数和 finish_reason 放进同一条日志。这样才能知道是预算不足、提示词过长，还是模型本来就已经完成任务。

在线服务中更稳妥的参数策略

我更倾向于按接口用途设三档预算：短分类或改写使用较小上限，普通问答给中等上限，报告生成才允许较长输出。默认值不要直接取模型上下文长度，而应减去系统提示词、历史消息、工具参数和安全余量。

如果客户端同时提供 max_completion_tokens，先确认它与当前 vLLM 版本及接口实现的兼容性；跨客户端时，统一在网关层转换成服务端实际接受的字段。修复“回答被截断”时，先看 finish_reason 和输入长度，再决定加预算，避免用无上限请求掩盖提示词膨胀。

常见问题

max_tokens 设置 512，为什么实际只有几十个 token？

它只是上限。模型可能自然结束，或命中了 stop 条件；先看 finish_reason，不要把上限当成目标长度。

max_tokens 越大，回答一定越好吗？

不一定。上限变大只扩大可生成空间，也会增加延迟和 KV Cache 压力；应按任务结果和成本设定。

--max-model-len 能代替 max_tokens 吗？

不能。前者约束输入与输出的总上下文，后者约束一次请求最多生成多少 token，实际请求需要同时考虑。

把请求级预算、服务端上下文和返回原因分开记录，vLLM 的输出长度就从“凭感觉调参”变成了可解释的在线策略。