智能体 AI / 生成式 AI 使用 AI 智能体构建 Rust 工具调用解析器 A developer, code blocks, a checklist, and a rising bar chart connect to a central network diagram. 2026年11月19日 作者: Keiven Chang, Indrajit Maloji Bhosale, Krishnan Prashanth, Zhongdao Ren 和 Ryan McCormick 讨论 (0)

AI 生成的摘要

  • frontend-crates 提供可复用的 Rust 组件,可将大语言模型输出中的工具调用解析为供应用程序使用的结构化事件。
  • 这些解析器依据已有文档说明的恢复规则处理格式错误、不完整和流式输入,而不是猜测模型意图,从而在不泄露模型特有标记的情况下保留有效数据。
  • 共享的一致性语料库将模型特定输入与预期的 GOLDEN 输出配对,使 UNIFIED.* 等行为测试可以在 Beam、GPT-OSS、Muse Spark 和 NVIDIA Nemotron 3 等不同模型系列间复用。
  • 开发者可以通过定义一套由 UNIFIED.* 用例改编而来的 GOLDEN 测试集、按照模型语法实现解析器,并使用本地一致性报告验证结果,来创建新的解析器。
  • 引导解码支持将生成内容限制在模型的标记和参数模式之内,以减少格式错误的调用;但对于截断和语义错误,解析器的恢复检查仍不可或缺。
  • 一个示例演示了如何使用来自 dynamo-parsers-v2 crate 的 NVIDIA Nemotron 解析器处理流式数据块,并按顺序生成推理和工具调用事件。

后续步骤

由 NVIDIA Nemotron 提供支持。AI 生成的内容可能无法完整概括相关信息,请核实重要信息。 了解更多

工具调用可能分段到达,参数可能被截断,模型特有的标记也可能泄露到回答中。前端解析器会把以 token ID 或解码文本形式接收的输出,转换为应用程序可使用的可见文本、推理内容和工具调用。

本文将介绍工具调用解析的工作原理,并使用 AI 智能体为新模型构建解析器。你将从一个天气查询请求和一套经过人工审核的测试集入手,并使用 frontend-crates,也就是支撑 NVIDIA Dynamo 工具调用解析器的一组可复用 Rust 组件。

假设你询问巴黎的天气。模型可能先生成推理内容,随后生成一个 get_weather 带有城市参数的调用。前端会准备提示词并将其 token 化,随后由推理引擎运行 LLM 来生成 token。解析器接收 token ID 或解码文本,并依次分离出推理内容、可见文本和工具调用。协议适配器会将这些事件转换为与 OpenAI 兼容的响应,批量 JSON 和流式更新使用相同的解析路径。

A prepared, tokenized prompt feeds an LLM running in an inference engine. Generated token IDs go directly to a compatible parser or through optional text decoding. Ordered parser events feed batch JSON or streaming responses through a protocol adapter.
图1:LLM 生成 token;解析器在响应定形之前接收 token ID 或解码文本

棘手之处在于识别每一部分的起止位置。调用可能格式错误或不完整,标记可能出现在参数内部,调用周围也可能存在普通文本。解析器必须处理这些边界,同时避免数据丢失、调用重复或模型特有标记泄露。

回到天气查询请求:模型可能在城市名称生成到一半时停止,也可能调用一个未提供的工具。这两种情况都可能干扰智能体的下一步操作。以下 NVIDIA Nemotron 示例展示了这两类故障。

语法错误。 参数和工具调用框架始终没有闭合,因此无法解析出完整调用。

</think><tool_call>
<function=get_weather><parameter=city>Par

语义错误。 框架有效,但指定的工具并未包含在请求中。

</think><tool_call>
<function=unknown_tool><parameter=city>Paris</parameter></function>
</tool_call>

这些故障需要采用不同的处理方式。如果模型指定了不可用的工具,解析器会报告其收到的调用,而服务层则负责验证工具的可用性、授权、模式和调用策略。更改工具名称会掩盖模型实际生成的内容。

在流仍保持打开时,不完整的调用更难判断。城市名称的其余部分可能会在下一个数据块中到达,标记也可能被拆分到不同数据块中。过早发出内容会导致语法标记泄露到回答里;等待过久又会延迟普通文本。解析器需要采用一致的规则,决定哪些内容应当发出、哪些内容应当缓冲,以及如何处理流的结束。

解析器可能遇到范围无界的各种输入。面对无效输入时,它必须遵循已有文档说明的恢复规则,而不是猜测模型意图。即使某个调用在语法上有效并符合模式,也可能并非用户请求的正确选择。解析器需要一致的语法和恢复策略,才能在不虚构调用或泄露模型特有标记的情况下保留有效数据。

为了检查这些决策,frontend-crates 会在共享的一致性语料库中,将模型输出与预期结果配对。

使用一致性语料库

使用一致性语料库,可以检查适用的解析器如何处理最初在某个模型中发现的行为。其与语言无关的 YAML 测试夹具将固定输入与预期输出配对,使 Rust 解析器和 Python 参考实现能够运行相同的用例。针对标记泄露、调用重复或参数丢失的回归测试,在根据其他模型系列的语法进行改编后,也可以覆盖这些系列。

对于新解析器,应首先从所有 UNIFIED.* 模型系列的用例入手。这些用例涵盖完整、格式错误、截断、多个以及交错的调用,还包括流式边界和输入结束时的行为。请根据模型的语法和请求设置调整输入,添加模型特有的边界用例,并说明排除某些用例的原因。你无法测试所有可能的输出,但可以复用其他格式的用例。

表1展示了 UNIFIED.1-tool_only 以下用例,摘自 解析器一致性表。在此示例中,GOLDEN 测试集将四种模型特定输入与同一个预期结果配对:调用 get_weather,并将 city 设置为 Paris。虽然标记各不相同,但每个用例测试的都是相同行为。通过调整输入格式,同一项行为测试便可在不同模型之间复用。

模型原生输入
Beam<|start|>assistant to=get_weather<|channel|>analysis <|constrain|>xml<|message|><rfl:parameter name="city">
Paris
</rfl:parameter><|call|>
GPT-OSS<|start|>assistant<|channel|>commentary to=functions.get_weather <|constrain|>json<|message|>{"city": "Paris"}<|call|>
Muse Spark<|start|>assistant to=get_weather<|message|><atem:function_calls>
<atem:invoke name="get_weather">
<atem:parameter name="city">Paris</atem:parameter>
</atem:invoke>
</atem:function_calls><|eom|>
NVIDIA Nemotron 3</think><tool_call>
<function=get_weather>
<parameter=city>
Paris
</parameter>
</function>
</tool_call>
表 1. 不同模型的特定输入具有相同的预期 GOLDEN 输出:get_weather({“city”:”Paris”})

教程:创建新的解析器

现在,你可以为 frontend-crates 尚不支持的模型创建解析器。让你的 AI 智能体阅读本文,并从第 1 步中的提示词开始完成本教程。模型规范定义语法,共享用例则提供要测试的行为。

你需要准备 frontend-crates 的检出代码、Rust、Cargo 和一致性测试依赖项。解析器练习使用固定测试夹具在 CPU 上运行,因此不需要 GPU。端到端测试还需要一个正常工作的 Dynamo 运行时、发现服务以及适合模型的硬件。准备好进行端到端测试后,请在实际模型和 GPU 上使用 Dynamo 运行时启动测试。

图 2 所示的工作流从模型的语法、恢复规则以及经过审核的 GOLDEN 预期开始。智能体编写或修复解析器、运行测试,并根据失败结果指导下一次修改。如果它建议更改预期行为,请先审核这一决定,再予以接受。

在声称支持部署之前,请使用真实模型对解析器进行端到端测试。预留时间来分配机器、加载模型、初始化运行时并运行你自己的测试用例。将失败情况转化为供智能体使用的单元测试,然后重新运行端到端测试以检查修复效果。

A vertical workflow starts with requirements and human-reviewed GOLDEN, followed by agent coding, unit tests, and end-to-end tests. Unit-test failures return to coding. End-to-end failures become regression tests before coding resumes.
图 2. 先通过单元测试反复迭代,再使用真实模型测试。继续之前,将端到端测试中的失败情况转化为回归测试

1. 从提示词开始

向智能体提供以下提示词:在 frontend-crates 检出代码中,按照 .agents/skills/tool-parser-generator/SKILL.md 为 [MODEL_NAME] 创建一个 v2 Unified 解析器。研究其语法并准备 GOLDEN 测试集,改编适用的 UNIFIED.* 用例。暂停并等待人工审核。获得批准后,完成实现和验证,并提供本地一致性报告的 URL,供人工检查。

2. 定义 GOLDEN 测试集

GOLDEN 测试集定义了解析器接受测试时所依据的行为。使用第 1 步中的提示词,让智能体在 conformance/fixtures-unified-v2/families/<name>/inputs_and_golden.yaml,且不受解析器结果影响的情况下生成初始测试集。每个用例都将输入与称为 GOLDEN 的预期输出配对。如果这些预期有误,即使解析器通过测试,其行为仍可能不正确。

以下示例将一个输入与其预期的 GOLDEN 输出配对。示例省略了请求定义、工具、初始化和分块设置;现有的 nemotron_v3/inputs_and_golden.yaml 展示了完整格式。

family: nemotron_v3
cases:
  UNIFIED.tool_only.nemotron_v3:
    input: |-
      </think><tool_call>
      <function=get_weather>
      <parameter=city>Paris</parameter>
      </function></tool_call>
    golden:
      - kind: tool_call
        name: get_weather
        arguments: {city: Paris}

让智能体进行对抗性审核,然后逐个用例手动检查该测试集。初始测试集可能包含错误,因为预期行为取决于智能体可能不了解的上下文。请依据以下来源和要求进行审核:

  • 模型格式和 API 规范。
  • 参考实现。
  • 其他解析器,包括 vLLM 和 SGLang。
  • 语法、工具模式和请求设置。
  • 相关论坛讨论和现有工单。
  • 调用方的需求,以及恢复操作在延迟和复杂度方面的成本。

当不同来源存在分歧时,你可能需要自行判断。记录恢复规则、选择该规则的原因,并说明任何 GOLDEN 更改的理由。预期结果应遵循这一决定,而不是解析器的输出。

3. 实现解析器并检查结果

审核 GOLDEN 测试集后,让智能体继续:构建解析器,运行所有适用的 UNIFIED.* 用例和共享回归测试,并修复失败项。让它重新捕获结果,在本地生成 conformance/CONFORMANCE_v2.html ,并提供本地报告 URL,以便你检查其工作成果。

在浏览器中打开该 URL。本地报告使用已发布的 解析器一致性表界面展示你的本地结果。检查每个用例的输入、请求设置、GOLDEN 和记录的输出。调查回归问题和缺失的捕获结果。绿色表示输出与 GOLDEN 匹配,因此该表依赖于你审核过的预期结果。图 3 展示了报告界面。

Filtered conformance report with four model families in rows: Beam, GPT-OSS, Muse Spark, and NVIDIA Nemotron 3. Single-call and multiple-call cases appear in columns. Green cells indicate recorded outputs matching GOLDEN.
图 3. 解析器一致性表中单次及多次工具调用用例的屏幕截图,已筛选为 Beam、GPT-OSS、Muse Spark 和 NVIDIA Nemotron 3

引导解码支持

智能体的实现步骤还包括引导解码,它通过限制模型只能生成其标记和参数模式允许的内容,减少格式错误的调用。让智能体遵循解析器 README 中的“添加并验证结构化标签”以及智能体技能中的“实现并验证”。这些说明涵盖构建器注册、语法测试和后端资格验证。引导解码无法确保模型选择正确的城市,也无法防止输出被截断,因此仍需保留解析器的恢复检查。

常见陷阱:速度、流式传输和内存

通过正确性测试只是智能体生成的解析器的起点。实现仍可能速度缓慢或占用过多内存。请使用纯文本、工具调用、长参数和格式错误的输入,并搭配大小不同的分块进行测试。在相同构建版本和硬件上测量吞吐量、首个事件的到达时间和内存使用量。将输入长度增加一倍,以发现不断重新扫描或复制已读取内容的代码。

对于流式传输,请观察每个分块到达时调用方收到的内容。解析器可能返回正确的最终结果,却仍让调用方一直等到结束。请在每个可能的拆分点重放短测试夹具,然后尝试单字符分块和混合大小的分块,包括在标记、转义引号和参数内部拆分。检查事件是否按顺序到达,以及参数是否保持完整。如果事件会排队,还要测试慢速消费者和取消操作。

还应尝试在标记或参数传输到一半时截断数据流。检查恢复过程是否遵循已有文档说明的规则,且不会泄露标记、重复调用或丢失有效文本。解析器应处理实际收到的输入,而不是猜测缺失的部分。

测试文本应包含模型格式示例,以及符合文档所述语法和引号处理策略的工具调用。当前 v2 默认策略会将识别出的标记视为结构,即使它们位于带引号的文本中也是如此,因此仅靠引号无法在普通文本中保留完整的工具调用示例。请记录所配置的策略并测试其预期行为。

将以下提示词交给智能体,以检查常见陷阱:

检查此解析器是否存在常见陷阱。使用不同的分块大小,针对短输入、长输入和格式错误的输入测试速度与内存。查找重复扫描、复制或缓冲区持续增长的问题。验证输出是否会增量到达,并在跨分块边界及发生截断时保持正确。如果存在队列,请测试慢速消费者、背压和取消操作。根据文档所述的语法和配置的引号处理策略,检查字面格式示例和真实工具调用。报告测量结果、可复现的故障以及任何无法验证的内容。

如何在自己的 Rust 项目中使用解析器 crate

选择语法与你的模型匹配的解析器。此示例使用现有的 NVIDIA Nemotron 解析器,并将一个标记和城市名称分别拆分到不同分块中。

此示例已使用 Rust 1.96.1 和 dynamo-parsers-v2 0.10.3 进行测试。运行 cargo new parser-demo,然后运行 cd parser-demo。在以下位置下添加以下条目: [dependencies] 位于 Cargo.toml:

anyhow = "1"
dynamo-parsers-v2 = "=0.10.3"
serde_json = "1"

将 src/main.rs 替换为:

use dynamo_parsers_v2::{
    Tool, UnifiedParserInit, UnifiedParserOutput, create_unified_parser_for_family,
};
use serde_json::json;

fn main() -> anyhow::Result<()> {
    let tools = [Tool {
        name: "get_weather".into(),
        description: None,
        parameters: json!({"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}),
        strict: None,
    }];
    let mut parser = create_unified_parser_for_family("nemotron_v3", &tools)?;
    parser.initialize_request(UnifiedParserInit::default())?;
    let mut output = UnifiedParserOutput::default();
    for chunk in [
        "Check the forecast.</think><tool_",
        "call><function=get_weather><parameter=city>Par",
        "is</parameter></function></tool_call>",
    ] {
        let mut delta = UnifiedParserOutput::default();
        parser.parse_into(chunk, &mut delta)?;
        output.append(&mut delta);
    }
    output.append(&mut parser.finish()?);
    println!("{}", serde_json::to_string(&output.assembled())?);
    Ok(())
}

运行 cargo generate-lockfile,然后运行 cargo run --locked。结果包含推理内容,随后是一个 get_weather 调用,其中 city 设置为 Paris:

[{"kind":"reasoning","text":"Check the forecast."},
 {"kind":"tool_call","name":"get_weather","arguments":{"city":"Paris"}}]

为每个请求选项保留一个已初始化的解析器。

  • create_unified_parser_for_family 用于选择语法。
  • initialize_request 用于设置初始状态。
  • parse_into 用于处理每个分块。
  • 仅执行一次最终化:使用 finish() 处理截断、取消或传输流结束。使用 finish_at_eos() 仅处理后端确认的语法结束序列(EOS)信号。
  • 使用 assembled() 获取有序结果。

在流式应用中,转发其中的事件 delta.events 在每次 parse_into 调用后,并转发由 finish()返回的事件。此示例会收集事件,以便打印最终输出。在执行工具之前,请验证已完成的调用是否满足工具可用性、授权、架构和调用策略要求。

开始使用

要为你的模型构建解析器,请先查看 frontend-crates 中的源代码、固件和说明,并改编一个现有测试用例。将模型的格式规范和仓库说明提供给你的智能体,然后使用 解析器一致性表 ,将解析器记录的输出与 GOLDEN 进行对照检查。提交议题或拉取请求时,请附上导致失败的确切输入、用例标识符和测试结果,以便审核者复现该行为。

你可以在自己的 Rust 项目中使用这些解析器,也可以将其作为 NVIDIA Dynamo的一部分使用。NVIDIA Dynamo 是一个使用 frontend-crates 的推理框架。开始之前,请查看 最新的仓库说明 ,确保你和你的智能体遵循当前步骤。

致谢

Jesse Gu, Alec Flowers、Dong Xu、Qi Wang,以及协助撰写本博客和 frontend-crates 的众多合作伙伴与校对人员。

讨论(0)

标签

智能体 AI / 生成式 AI | 开发者工具与技术 | 综合 | Dynamo | Nemotron | 中级技术 | 教程 | 推理性能

关于作者

Keiven Chang 关于 Keiven Chang
Keiven Chang 是 NVIDIA Dynamo 团队的高级系统软件工程师,拥有分布式系统和推理领域的背景。他拥有 UCLA 计算机科学硕士学位和 UC Berkeley 计算机科学学士学位。 查看 Keiven Chang 的所有文章 Avatar photo 关于 Indrajit Maloji Bhosale
Indrajit Maloji Bhosale 是 NVIDIA Dynamo 团队的高级系统软件工程师,负责用于 LLM 推理的 Dynamo 运行时,重点关注智能体工作流、多模态推理以及跨后端的新模型适配。他拥有卡内基梅隆大学计算机系统与网络专业硕士学位。 查看 Indrajit Maloji Bhosale 的所有文章 Krishnan Prashanth 关于 Krishnan Prashanth
Krishnan Prashanth 是 NVIDIA Dynamo 团队的软件工程师,负责高性能分布式推理,重点关注跨数据中心基础设施的智能体和多模态工作流。他拥有德州农工大学计算机科学学士和硕士学位。 查看 Krishnan Prashanth 的所有文章 Zhongdao Ren 关于 Zhongdao Ren
Zhongdao Ren 是 NVIDIA Dynamo 团队的高级软件工程师,专注于高性能分布式 AI 推理和智能体工作流。他拥有高性能计算、大规模分布式系统和数据中心基础设施方面的背景,并获得了加州大学圣迭戈分校计算科学硕士学位。 查看 Zhongdao Ren 的所有文章 Ryan McCormick 关于 Ryan McCormick
Ryan McCormick 是 NVIDIA Dynamo 团队的工程经理,专注于高性能分布式推理、大规模自托管智能体,以及跨数据中心基础设施优化多模态工作负载。他拥有宾厄姆顿大学计算机科学和数学学士学位。 查看 Ryan McCormick 的所有文章

评论

评论已关闭。