大模型应用开发 / 系统课时

解析工具请求

解析工具请求

模型决定调用工具后,应用拿到的并不是“已经执行的函数”,而是一段描述调用意图的数据。本节把工具名称、调用 ID 和参数安全地解析出来,转换成稳定的内部调用对象,并在真正执行前完成格式与参数校验。

学习目标

  • 识别工具请求中的调用 ID、工具名称和参数三类核心信息
  • 将模型返回格式归一化为应用内部的调用对象
  • 在执行工具前处理 JSON 参数错误、未知工具和缺失字段

工具请求不是普通文本

典型工具请求至少包含三部分:唯一的调用 ID、模型选择的工具名称,以及序列化后的参数。应用应把这三部分当作结构化数据处理,而不是从自然语言答案中用正则表达式“猜”函数名。

模型工具请求到内部调用对象的解析流程

应用内部最好只认一种稳定结构,例如统一成 { id, name, args }。这样模型供应商的字段差异只留在适配层,后续的权限检查、日志、工具路由和执行逻辑都不需要理解外部响应格式。

归一化并校验参数

下面的 TypeScript 示例模拟一种常见响应:参数以 JSON 字符串返回。解析函数会先检查必需字段,再解析参数,最后确认工具是否已经注册。

ts
type RawToolCall = {
  id?: string;
  function?: {
    name?: string;
    arguments?: string;
  };
};

type ToolCall = {
  id: string;
  name: string;
  args: Record<string, unknown>;
};

const toolRegistry = new Set(["get_weather", "search_docs"]);

function parseToolCall(raw: RawToolCall): ToolCall {
  const id = raw.id;
  const name = raw.function?.name;
  const argsText = raw.function?.arguments;

  if (!id || !name || argsText === undefined) {
    throw new Error("tool call is missing required fields");
  }

  if (!toolRegistry.has(name)) {
    throw new Error(`unknown tool: ${name}`);
  }

  let args: unknown;
  try {
    args = JSON.parse(argsText);
  } catch {
    throw new Error("tool arguments are not valid JSON");
  }

  if (typeof args !== "object" || args === null || Array.isArray(args)) {
    throw new Error("tool arguments must be a JSON object");
  }

  return { id, name, args: args as Record<string, unknown> };
}

const raw: RawToolCall = {
  id: "call_<ID>",
  function: {
    name: "get_weather",
    arguments: "{\"city\":\"Shanghai\"}"
  }
};

console.log(parseToolCall(raw));

预期输出:

text
{ id: 'call_<ID>', name: 'get_weather', args: { city: 'Shanghai' } }

<ID> 代表模型接口实际生成的动态调用标识。生产代码必须完整保存这个 ID,因为后续回传工具结果时还要依靠它建立请求与结果的对应关系。

参数合法不等于可以执行

JSON.parse 成功只说明参数语法正确,并不说明参数满足业务约束。真正执行前还应按工具自己的输入 Schema 检查字段类型、必填项、枚举范围和长度限制。例如 get_weather 若要求 city 为非空字符串,就不能接受 { "city": 123 }。

如果一次响应含多个工具请求,应逐个生成内部 ToolCall,并分别保留各自的调用 ID。是否并行执行取决于工具之间有没有依赖关系,而不是由解析阶段自行决定。

解析失败时怎么处理

解析层应尽量把错误分成可定位的类别:响应缺字段、参数不是合法 JSON、工具未注册、参数 Schema 不通过。不要在这一层吞掉异常后继续调用工具,否则后面的失败会变成更难排查的业务错误。

对于可恢复的参数错误,可以把结构化失败信息交给上层,由上层决定是否请求模型重新生成参数;对于未知工具或越权调用,则应直接拒绝执行。解析后的对象只有同时满足名称可信、参数可读和调用 ID 可追踪,才应进入真正的工具执行阶段。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

解析工具请求

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通