在 vLLM 里打开约束解码：把工具调用 Schema 准确率从约 92% 拉到 100%

开放权重模型接 agent 时，工具调用一旦写出不合 Schema 的 JSON，错误信息会污染上下文，多轮会话质量会掉。Ubicloud 工程师 Jesse Donkervliet、Junhao Li 在 2026年10月20日的博文里写明：用 vLLM 0.28 服 Kimi K2.6 时，工具调用 Schema 准确率只有约 92%——大约每 25 次就有 2 次失败；打开约束解码后，在 K2VV ToolCall 基准上可到 100%。[1]

问题出在哪

工具声明一般是 JSON Schema（参数类型、必填项等）。推理引擎再包上模型专用特殊 token，让模型按训练格式吐出调用。模型按概率选 token，并不跑编译器；训练里见过的工具名、字段名也可能「串戏」到当前环境，于是出现 search_web 对不上 web_search 这类错。[1]

Moonshot 的 K2VV ToolCall 用约 2000 条请求测两件事：触发时机是否接近官方服务（trigger similarity），以及生成调用是否符合 Schema（schema accuracy）。后者不过关，agent 就得重试、费 token。[1]

约束解码怎么修

约束解码不在事后校验，而是生成时逐步屏蔽非法 token。vLLM 借助 XGrammar 的 structural tags，按「开始调用 → 工具名 → 索引 → 参数起始 → 符合 Schema 的 JSON → 结束」铺合法路径；到索引阶段只允许数字 token，参数段只允许 Schema 允许的结构。[1]

Ubicloud 起初在自有 fork 里打开该能力；上游 vLLM 在 0.25 起加入后，他们改跟上游。后来发现：对未显式开启约束解码的请求，默认行为变了，准确率又掉回约 91%。原因不是实现坏了，而是 vLLM 要服务多模型——部分模型默认强制约束会跑偏，文法翻译与推测解码等也有交互坑——于是默认关闭更安全，改为提供 --tool-strict-level 让部署方自开。[1]

Ubicloud 面向 Kimi、DeepSeek 等要「对齐官方质量」的线路，自行打开约束解码，确认各版本 Schema 准确率 100% 后再上线。[1]

你可以怎么做

1、升到带服务端开关的版本

博文写明约束解码作为服务端 flag 出现在 vLLM 0.31。部署前核对当前版本与发布说明。[1]

确认成功：vllm --help 或文档里能看到 --tool-strict-level（或等价开关）。

2、为 Kimi / DeepSeek 等打开严格工具模式

在服务启动参数中启用 tool strict / constrained decoding（具体枚举值以当版文档为准），保证工具声明 Schema 完整传入。[1]

确认成功：用 K2VV ToolCall 或自建不合规用例集复测，Schema accuracy 接近 100%，且延迟无明显劣化（文中称 XGrammar 预计算 mask，开销可忽略）。[1]

3、按模型决定是否默认开

通用多模型集群可默认关、按模型白名单开，避免 gpt-oss、部分 Qwen/GLM 等已知不适配机型被硬约束带偏。[1]

确认成功：问题机型关闭后请求不再异常失败；目标机型开启后 Schema 合格率稳定。

注意事项

• 约束解码保证的是语法/Schema，不保证工具选对或参数语义正确。

• 与推测解码等特性叠加时留意上游 issue。

• 基准数字来自 Ubicloud 对 Kimi K2.6 等的复现，换模型要自己测。[1]

说明：步骤与版本号据 Ubicloud 2026年10月20日博文；flag 名称以你安装的 vLLM 版本文档为准。

来源

[1] Fixing Tool-Call Accuracy in vLLM，Jesse Donkervliet & Junhao Li，Ubicloud，2026年10月20日。

#vLLM #工具调用 #约束解码 #Kimi #Agent #教程干货