vLLM 约束解码将 Kimi 和 DeepSeek 的工具调用准确率修复至 100%

要点

启用 vLLM 0.31 中引入的约束解码标志，可确保 Kimi K2.6 和 DeepSeek V4 Flash 的工具调用模式 100% 符合规范，消除了此前将准确率降至 92% 的错误调用。

为什么工具调用模式准确性很重要

  • 工具调用必须遵循向模型公布的 JSON 模式；任何偏差都会导致调用失败并污染上下文窗口。
  • 在多轮智能体工作负载中，一次错误的调用会迫使重试，增加延迟，并降低整体模型质量。
  • Moonshot AI 的 K2VV ToolCall 基准测试衡量两个关键指标：
    • 触发相似度 – 服务决定调用工具的频率与参考实现的对比。
    • 模式准确率 – 生成的调用中符合声明模式的比例。50% 的模式准确率意味着一半的调用不可用。
  • 当 Ubicloud 使用 vLLM 0.28 服务 Kimi K2.6 时，模式准确率仅为 92%（每 25 次调用中有 2 次失败），这对于生产环境中的智能体来说是不可接受的。

约束解码：工作原理

  • 标准解码 允许模型根据概率采样任何 token，这可能会产生语法无效的 JSON。
  • 约束解码 在每一步生成时，将 token 集合限制为仅那些能保持输出符合工具 JSON 模式的 token。
  • vLLM 使用 XGrammar 结构标签 实现这一点。语法定义了一个确定性序列：
    1. <|tool_call_begin|>{function.name}:{index}
    2. <|tool_call_argument_begin|>
    3. JSONSchemaFormat – 生成符合所提供模式的 JSON。
    4. <|tool_call_end|>
  • 无效 token 会被即时屏蔽，并且每个阶段的掩码都是预先计算的，因此 GPU 可以以极小的开销应用它。

“这将模式准确率从尽力而为的方法转变为运行时保证。模型仍然决定生成哪个 token，但现在 token 是从一个受限且语法正确的集合中选择的。” – Ubicloud 博客

vLLM 0.31 中的变化

  • 约束解码在 vLLM 0.31 中作为 服务端标志（--tool-strict-level）添加。
  • 在 0.31 之前，该功能存在于早期版本（例如 0.25）中，但 默认禁用，以避免对不遵循预期工具调用格式的模型造成回归。
  • 为 Kimi 和 DeepSeek 启用该标志，强制引擎应用 XGrammar 掩码，使 K2VV 基准测试中的模式准确率提升至 100%。

为什么默认禁用

  • vLLM 服务多种模型；一些模型（例如 gpt-oss-20b、Qwen 3.6、GLM 5.1）生成的工具调用偏离预期格式，导致约束解码 拒绝过多 token 并降低性能。
  • 识别出三类问题：
    1. 一般模型问题 – 模型在无约束时偏离预期模式。
    2. 语法转换错误 – 将模型的工具模式转换为 XGrammar 标签时出错。
    3. 功能交互错误 – 例如，约束解码与推测解码之间的冲突导致有效 token 被错误屏蔽。
  • 由于这些回归，vLLM 维护者选择了 模型无关的默认禁用 约束解码，并为需要严格执行的用户引入了显式的 --tool-strict-level 标志。

社区见解

“约束解码在 vLLM 中已经存在很长时间了，约束工具调用解码在 vLLM 中也有一段时间了。这篇博客文章相当令人困惑，因为在理解整个情况之前，它似乎暗示他们修复了 vLLM（标题所暗示的），但实际上他们只需要正确配置它。” – @Aurornis（HN 评论）

  • 讨论强调，真正的修复是配置，而不是代码更改，并称赞 Ubicloud 维护了一个捕获回归的基准测试。
  • 其他评论者指出，约束解码现在在其他运行时（例如 llama.cpp、HuggingFace transformers.js）中很常见，100% 的工具调用准确率是生产智能体的基本期望。

部署实用指南

  1. 启用标志 当服务具有稳定工具调用格式的模型时（例如 Kimi K2.6、DeepSeek V4 Flash）：
    vllm serve model_path --tool-strict-level=2   # 或根据 vLLM 文档选择适当的级别
  2. 使用基准测试验证 例如 Moonshot AI 的 K2VV ToolCall，以确保任何引擎升级后模式准确率保持在 100%。
  3. 监控特定模型的回归；如果某个模型在约束解码下性能下降，请考虑仅对该模型禁用该标志。
  4. 保持 XGrammar 定义最新 当添加或重命名工具时；语法必须反映模型使用的确切 JSON 模式。

结论

工具调用模式准确性是智能体 LLM 质量的关键决定因素。通过启用 vLLM 0.31 的约束解码，Ubicloud 消除了错误的工具调用，将 Kimi 和 DeepSeek 模型的基准准确率从 92% 提升至 100%。这表明，对于提供可靠、高质量的 AI 服务，推理引擎配置与模型选择同样重要。

Sources