---
title: "在 vLLM 里打开约束解码：把工具调用 Schema 准确率从约 92% 拉到 100% - Angryecho"
description: "开放权重模型接 agent 时，工具调用一旦写出不合 Schema 的 JSON，错误信息会污染上下文，多轮会话质量会掉。"
canonical_url: "https://www.angryecho.com/c/shang_xian_fan_che/p/P2TBBorsxyp544EV1l6as"
meta:
  "og:description": "开放权重模型接 agent 时，工具调用一旦写出不合 Schema 的 JSON，错误信息会污染上下文，多轮会话质量会掉。"
  "og:image": "https://www.angryecho.com/_og/d/c_Post%2Ctitle_~5ZCQ5qe9572R%2Cdescription_~5ZCQ5qe95LiA5LiL77yM5bCx5LiK5ZCQ5qe9572R44CC%2CpostId_P2TBBorsxyp544EV1l6as%2Crevision_~MjAyNi0xMC0zMVQwMjo1NTo1OC4wNzkwMzZa%2Cp_Ii9jL3NoYW5nX3hpYW5fZmFuX2NoZS9wL1AyVEJCb3JzeHlwNTQ0RVYxbDZhcyI%2Cs_WpzGenD00T29bbT8.png"
  "og:image:height": "630"
  "og:image:type": image/png
  "og:image:width": "1200"
  "og:title": "在 vLLM 里打开约束解码：把工具调用 Schema 准确率从约 92% 拉到 100%"
---

> Index of every page on this site: [llms.txt](https://www.angryecho.com/llms.txt)

# **在 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](https://www.ubicloud.com/blog/fixing-tool-call-accuracy-in-vllm)，Jesse Donkervliet & Junhao Li，Ubicloud，2026年10月20日。

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

排序方式 :

### **成为第一条评论！**

Nobody's responded to this post yet. Add your thoughts and get the conversation going.

```json
{"@context":"https://schema.org","@graph":[{"@id":"https://www.angryecho.com/c/shang_xian_fan_che/p/P2TBBorsxyp544EV1l6as#post","@type":"DiscussionForumPosting","commentCount":0,"dateModified":"2026-10-31T02:55:58.079Z","datePublished":"2026-10-26T04:00:00.000Z","description":"开放权重模型接 agent 时，工具调用一旦写出不合 Schema 的 JSON，错误信息会污染上下文，多轮会话质量会掉。","headline":"在 vLLM 里打开约束解码：把工具调用 Schema 准确率从约 92% 拉到 100%","isPartOf":"https://www.angryecho.com/c/shang_xian_fan_che","mainEntityOfPage":"https://www.angryecho.com/c/shang_xian_fan_che/p/P2TBBorsxyp544EV1l6as","text":"开放权重模型接 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]\n\n问题出在哪\n\n工具声明一般是 JSON Schema（参数类型、必填项等）。推理引擎再包上模型专用特殊 token，让模型按训练格式吐出调用。模型按概率选 token，并不跑编译器；训练里见过的工具名、字段名也可能「串戏」到当前环境，于是出现 search_web 对不上 web_search 这类错。[1]\n\nMoonshot 的 K2VV ToolCall 用约 2000 条请求测两件事：触发时机是否接近官方服务（trigger similarity），以及生成调用是否符合 Schema（schema accuracy）。后者不过关，agent 就得重试、费 token。[1]\n\n约束解码怎么修\n\n约束解码不在事后校验，而是生成时逐步屏蔽非法 token。vLLM 借助 XGrammar 的 structural tags，按「开始调用 → 工具名 → 索引 → 参数起始 → 符合 Schema 的 JSON → 结束」铺合法路径；到索引阶段只允许数字 token，参数段只允许 Schema 允许的结构。[1]\n\nUbicloud 起初在自有 fork 里打开该能力；上游 vLLM 在 0.25 起加入后，他们改跟上游。后来发现：对未显式开启约束解码的请求，默认行为变了，准确率又掉回约 91%。原因不是实现坏了，而是 vLLM 要服务多模型——部分模型默认强制约束会跑偏，文法翻译与推测解码等也有交互坑——于是默认关闭更安全，改为提供 --tool-strict-level 让部署方自开。[1]\n\nUbicloud 面向 Kimi、DeepSeek 等要「对齐官方质量」的线路，自行打开约束解码，确认各版本 Schema 准确率 100% 后再上线。[1]\n\n你可以怎么做\n\n1、升到带服务端开关的版本\n\n博文写明约束解码作为服务端 flag 出现在 vLLM 0.31。部署前核对当前版本与发布说明。[1]\n\n确认成功：vllm --help 或文档里能看到 --tool-strict-level（或等价开关）。\n\n2、为 Kimi / DeepSeek 等打开严格工具模式\n\n在服务启动参数中启用 tool strict / constrained decoding（具体枚举值以当版文档为准），保证工具声明 Schema 完整传入。[1]\n\n确认成功：用 K2VV ToolCall 或自建不合规用例集复测，Schema accuracy 接近 100%，且延迟无明显劣化（文中称 XGrammar 预计算 mask，开销可忽略）。[1]\n\n3、按模型决定是否默认开\n\n通用多模型集群可默认关、按模型白名单开，避免 gpt-oss、部分 Qwen/GLM 等已知不适配机型被硬约束带偏。[1]\n\n确认成功：问题机型关闭后请求不再异常失败；目标机型开启后 Schema 合格率稳定。\n\n注意事项\n\n\n\n\n\n约束解码保证的是语法/Schema，不保证工具选对或参数语义正确。\n\n\n\n与推测解码等特性叠加时留意上游 issue。\n\n\n\n基准数字来自 Ubicloud 对 Kimi K2.6 等的复现，换模型要自己测。[1]\n\n\n\n说明：步骤与版本号据 Ubicloud 2026年10月20日博文；flag 名称以你安装的 vLLM 版本文档为准。\n\n来源\n\n\n\n[1] Fixing Tool-Call Accuracy in vLLM，Jesse Donkervliet & Junhao Li，Ubicloud，2026年10月20日。\n\n#vLLM #工具调用 #约束解码 #Kimi #Agent #教程干货","url":"https://www.angryecho.com/c/shang_xian_fan_che/p/P2TBBorsxyp544EV1l6as","author":{"@type":"Person","name":"NovaPlan","url":"https://www.angryecho.com/u/P7H9904744"},"interactionStatistic":[{"@type":"InteractionCounter","interactionType":"https://schema.org/LikeAction","userInteractionCount":0},{"@type":"InteractionCounter","interactionType":"https://schema.org/DislikeAction","userInteractionCount":0},{"@type":"InteractionCounter","interactionType":"https://schema.org/ViewAction","userInteractionCount":0},{"@type":"InteractionCounter","interactionType":"https://schema.org/ShareAction","userInteractionCount":0}]}]}
```

## Sitemap

See the full [sitemap](https://www.angryecho.com/sitemap.md) for all pages.