用 vLLM 的 --tool-strict-level 把自托管模型的工具调用成功率从 92% 拉到 100%：约束解码实操

开工之前先做一件事：把「工具调用解析失败」单独统计出来。多数团队只在 Agent 明显报错时才去翻日志，而解析失败往往表现为一次静默重试——看起来任务还是做成了，代价是错误信息被回灌进上下文，后面好几轮都被污染，并且每次重试都要重新付一遍 token。统计必须按工具名分开：92% 的平均值完全可以掩盖某个关键工具 70% 的失败率，而真正会在半夜把你叫醒的恰恰是后者。

统计思路：在调用侧包一层，把「结构不合格」与「选错了工具」分开记

fail_schema = Counter()   # 不合 schema：字段名错、必填缺失、JSON 截断
fail_choice = Counter()   # 结构合法但选错工具，或参数值明显不合理

try:
    call = parse_tool_call(resp)          # 服务端解析器的输出
    validate(call.arguments, TOOL_SCHEMA[call.name])
except SchemaError:
    fail_schema[call.name if call else 'unparsed'] += 1
    retry(...)                            # 重试会再烧一轮 token

另一个值得借用的口径来自模型厂商自己。Moonshot 公开了 K2VV ToolCall 基准，用 2000 条请求测两件互不替代的事：触发相似度，衡量服务方决定「什么时候该调工具」与官方服务有多接近；schema 准确率，衡量生成的调用能不能真的被执行。把这两个数字分开看很重要——后面会看到，约束解码只解决后者，前者它一点忙都帮不上。

vLLM 0.31 加了一个服务端参数 --tool-strict-level（PR #56268），它规定的是约束的地板，一共有三档。理解这张表比记住命令更重要，因为它决定了你的部署究竟被约束到了哪一层。

有三条边界容易被误解。其一，它是下限而非上限：永远不会放宽调用方已经要求的约束，也不会反过来强迫模型去调工具——语法只在模型自己打开工具调用外壳之后才介入。其二，默认值是分解析器的：glm47 的解析器默认 function，其余全部是 auto，Kimi 也包含在内，所以只服务 Kimi 的部署要显式写 parameter。其三，环境变量 VLLM_ENFORCE_STRICT_TOOL_CALLING=false 会彻底关掉结构标签，并且覆盖这个参数；如果很久以前有人为了排查别的问题把它写进了启动脚本，你加什么参数都不会生效。

做法是启动服务时把三件事配齐：打开自动工具选择、指定与模型匹配的解析器、给出严格等级。解析器名必须与你服务的模型家族一致，例如 Kimi K2 系列对应 kimi_k2；具体可用名以你安装的 vLLM 版本文档为准，写错的表现通常是工具调用完全解析不出来，而不是报错。

pip install --upgrade "vllm>=0.31"

vllm serve <你的模型路径> \
  --enable-auto-tool-choice \
  --tool-call-parser kimi_k2 \
  --tool-strict-level parameter

还不到 0.31 的部署也有一条路：在发给服务端的每一个函数定义里显式带上 strict 标记。在 tool_choice 取 auto 的常规写法下，这会打开同样的结构标签，不需要动服务端。代价是它散落在调用方代码里，任何一个工具漏写就退回自由生成，所以只适合当过渡方案。

tools = [{
  "type": "function",
  "function": {
    "name": "search_orders",
    "description": "按订单号或日期区间查询订单，只读",
    "parameters": {
      "type": "object",
      "properties": {"order_id": {"type": "string"},
                     "date_from": {"type": "string"}},
      "required": ["order_id"],
      "additionalProperties": False
    },
    "strict": True     # 低于 0.31 时靠这个打开结构标签
  }
}]

关于开销，公开的材料给出的说法是「可忽略」：掩码在 GPU 上预先算好，稳态几乎不增加成本；但生成新语法的那一次请求会有一次编译抖动，之后被缓存。极端 batch 下应当自己测 p99，而不是照抄宣传口径。另外，参数约束与推测解码曾经出过冲突，见 Step 5。

打开开关之后要做两类验证，缺一不可。一类是结构验证：反复跑同一批请求，确认 schema 失败率降到零，并且 No 之类必填参数不再缺失。另一类是语义验证：故意构造「两个工具名字相近、参数形状相似」的场景，看模型是否仍然选对。约束解码保证的只是前者——一个格式完美、却调错工具或传错 URL 的调用，依然会顺利通过所有检查。

验收脚本的两个计数器，缺一不可

1) schema_fail_rate  = 结构不合格次数 / 总调用次数   目标：接近 0
2) wrong_tool_rate   = 结构合法但选错工具 / 总调用次数  约束解码不改善它

固定随机种子重跑同一批请求，两次结果应当一致；
若不一致，说明还有别的非确定性来源（批处理调度、并发路径）没被控住。

把这两条做成持续指标，比做一次性验收有用得多。前者可以用来验证部署配置没被改回去，后者才是真正反映模型与提示词质量的数字。团队里常见的一句话「我们开了约束解码，工具调用没问题了」，通常只验证了前者。

这个功能带着几个已经公开的坑，动手之前值得知道。其一是嵌套在结构标签里的 JSON schema 会跳过 XGrammar 的不支持特性检查，像 multipleOf 这类约束会被静默忽略（issue #58930，当时仍在开放状态，已有修复提案）；其二，严格工具调用叠加 MTP 推测解码曾经抛出 FSM 推进失败并伴随 500（issue #44006，已被修复，但后来仍有版本报告出现同类报错而不伴 500）；其三，guidance 后端会拒绝新的结构标签格式并抛 KeyError（issue #55152，维护者回应说工具调用结构标签本就是为 xgrammar 建的，在 guidance 上预计都会失败）。

上线前的排障顺序

1) 解析器是否匹配模型家族
2) 会话模板是否是带工具意识的较新版本
3) 生成是否在中途被截断（max_tokens 太小会伪装成结构错误）
4) 是否开着推测解码，且未重新验证
5) 客户端传入的历史消息 id 是否规范

还有一类情况应当主动放弃或降档：当模型本身就与它文档里的工具标记格式偏差很大时，强约束反而会拖垮输出——早期报告点名了 Qwen、GLM 与 gpt-oss 的某些变体；另外在约束解码曾经默认开启的那段时间里，gpt-oss-20b、Qwen 3.6 与 GLM 5.1 的用户都报告过问题。判断方法很朴素：用你真实的 schema，把开关开着和关着各跑一遍，比哪一个在你的任务上更好，而不是相信任何通用基准。

最后一件事是把这件事固化成流程：在监控里加两个按工具名分组的计数器，一个记结构失败，一个记重试次数；给结构失败率设一条告警线，超过就先怀疑部署配置被改；每次升级 vLLM 之后，用同一批固定种子的请求重跑基线并把数字写进变更记录。默认值是会变的，而一次静默退化在聚合指标上可能只是从 100% 掉到 97%。

监控面板建议保留的四列

tool_name        schema_fail_rate    retry_rate    wrong_tool_rate
search_orders    0.0%                0.0%          1.2%
update_order     0.0%                0.4%          0.0%
refund           8.3%                9.1%          0.0%   <- 该查这个工具了

上表最后一行就是这套监控的意义：聚合数字看起来很好，但退订单这一个工具的失败率是 8.3%，而它恰恰是那个错了就要赔钱的工具。把指标按工具拆开，是这类治理能起作用的全部前提。