升级 vLLM 从 0.4 到 0.6，真正需要处理的不是安装过程，而是对外暴露的 API 契约变化。0.6 对 OpenAI 兼容接口的字段校验和默认值管理更严格，响应中的 usage、finish_reason、choices 等字段在部分场景下会和 0.4 不一致。如果你的业务代码直接读取这些字段，建议先把升级后的响应实际结构拿出来核对，再决定改客户端还是改启动参数。
建议先做一次最小请求对比：同环境、同模型、同一段 prompt，分别记录 0.4 和 0.6 的响应 JSON。不要依赖记忆或旧文档，以 /openapi.json 实际声明为准。处理顺序：先确认 model 名称，再核对 usage 和 finish_reason 的字段路径，最后把采样参数全部显式传入。若代码依赖旧字段，先做 key 容错，再逐步调整参数。
先核对实际暴露的接口形态
升级完成后，先不要急着改业务代码。用下面命令确认服务当前暴露的模型名：
curl -s http://localhost:8000/v1/models | jq确认 model 字段是否与之前一致。0.6 对请求中的 model 名匹配更严格，如果客户端传的 model 名称和启动参数不一致，会直接返回 404 或 400。
再拉取 openapi.json 看看服务端实际声明的请求和响应结构。这个 JSON 是自动生成的，比任何外部文档都更接近当前实例的真实行为：
curl -s http://localhost:8000/openapi.json | jq '.components.schemas.ChatCompletionResponse'重点看 usage、choices、finish_reason 的字段类型和嵌套层级。如果你用的是 openai 官方 Python 库，建议同步升级到与 0.6 兼容的版本，因为 SDK 会按自己的类型定义解析响应，版本不匹配时可能正常请求也会在高版本 SDK 中报验证错误。
响应格式差异的核对点
响应格式变化的常见点是 usage 和 finish_reason。0.6 对 OpenAI 兼容端点的实现更贴近官方 schema，但和 0.4 相比，usage 中的 prompt_tokens 口径可能变化，例如是否包含 chat 模板追加的 token。这个会直接影响基于 token 数的限流和计费统计，建议升级后对同一 prompt 做一次对比记录。
finish_reason 的处理也要调整。如果原来代码只判断 choices[0].finish_reason == 'stop'，当请求因 max_tokens 到达被截断时，0.6 可能返回 'length'，若没有单独处理，会把不完整回答当成正常结果。
logprobs 结构如果被用到，最好单独验证。用一条带 logprobs 的请求实际打印返回 JSON，确认 top_logprobs 的字段名和位置。
采样参数调整要点
0.4 到 0.6 之间，采样参数的默认值和校验规则可能有调整。最稳妥的做法是不依赖默认值，在每次请求里显式声明 temperature、top_p、max_tokens、stop。这样做也能让升级后的生成行为更接近旧版本。
对于 vLLM 扩展参数，比如 top_k、repetition_penalty，需要确认请求字段是否直接被接受，还是要在 extra_body 里传。如果你用的是 openai SDK，这些扩展参数通常放在 extra_body；如果直接传，可能因为字段不在 schema 上而被拒绝。
如果升级后报错信息中出现 'extra fields not permitted' 或 'additional properties'，说明请求携带了当前 schema 不接受的字段。此时以错误对象中给出的字段名为准，移除 0.4 允许但在 0.6 已不再兼容的字段。
另一个容易忽略的是 stop 参数。0.6 对 stop 的校验可能更严格，比如要求字符串长度限制或数组类型必须一致。建议在请求里显式传 stop 并确认类型与 0.4 一致。
兼容性处理建议
如果业务代码一时改不完，先按以下顺序处理。第一，在客户端对所有响应字段做存在性判断，不要直接取深层路径；第二，对生成结果建立固定 prompt 回归集，升级后跑一遍，用文本 diff 确认输出是否仍可接受；第三，查看 vLLM 启动参数 `--help`，看是否有旧版行为兼容开关。注意，这类开关是为了过渡，不是长期依赖。
不要试图通过固定随机种子来保证输出完全一致。vLLM 升级后采样内核、并行策略和 kernel 实现都可能变化，即使参数完全一致，输出也可能有差异。回归测试应以语义和长度约束为准，而不是逐字一致。
常见问题
升级后同一个请求的 usage 和以前不一样，是正常现象吗？
通常属于正常现象，usage 由服务端按当前版本统计逻辑生成，不同版本口径可能不同。需要先对比实际 JSON，确认是普通统计差异还是字段缺失，再决定是否调整依赖逻辑。
max_tokens 参数在 0.6 还能用吗？
通常能用，但要以实例的 /openapi.json 为准。如果 schema 中有 max_tokens，则直接在请求传；如果 schema 中是 max_completion_tokens，则需要改名。使用 openai 新 SDK 时，按 schema 调整最稳妥。