Skip to content
Lv5AI 对话前端进度 7 / 10

第 7 章:工具调用怎么显示 ​

用户不关心函数名,但关心"它到底在干什么、卡在哪、成没成"。工具调用的界面设计,本质是给这三件事找到位置。


学习目标 ​

  • 认出流式响应里工具调用的形状,知道参数是"拼"出来的
  • 用三态(running / done / failed)驱动界面,而不是靠转圈
  • 处理并行工具与参数解析时机
  • 知道工具失败该由谁来兜底

7.1 它在流里长什么样 ​

OpenAI 兼容的流式响应里,工具调用不是一个完整对象一次性到达,而是分片追加:

data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_1","function":{"name":"parse_pdf"}}]}}]}

data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"{\"fi"}}]}}]}

data: {"choices":[{"delta":{"tool_calls":[{"index":0,"function":{"arguments":"le\":\"a.pdf\"}"}}]}}]}

data: {"choices":[{"delta":{},"finish_reason":"tool_calls"}]}

关键点:

点说明
index并行调用时用序号区分,不是数组下标,要按它归并
function.name通常第一片就完整,但不保证
function.arguments增量字符串,必须拼完才能 JSON.parse
finish_reason出现 tool_calls 表示模型这轮说完了,等你执行

7.2 三态与之间的迁移 ​

ts
type ToolState =
  | { phase: "running"; startedAt: number }
  | { phase: "done"; endedAt: number; result: unknown }
  | { phase: "failed"; endedAt: number; reason: string };
用户能看见的三种状态,只允许这三条路径模型说出调用参数开始拼接参数拼完running显示转圈 + 已耗时done结果可折叠展开failed原因 + 是否可重试模型继续回传结果模型解释或换个做法禁止的第四种态:永远转圈。它意味着"没有超时、没有兜底",用户只会刷新页面。

7.3 参数拼接:别边拼边解析 ​

ts
const callAcc: Record<number, { name: string; args: string }> = {};

for (const tc of delta.tool_calls ?? []) {
  const acc = (callAcc[tc.index] ??= { name: "", args: "" });
  if (tc.function?.name) acc.name += tc.function.name;
  if (tc.function?.arguments) acc.args += tc.function.arguments;
}

// 收到 finish_reason === "tool_calls" 之后才统一解析
for (const [i, acc] of Object.entries(callAcc)) {
  let args: unknown;
  try {
    args = acc.args ? JSON.parse(acc.args) : {};
  } catch {
    markFailed(i, "参数不是合法 JSON");    // 罕见但真实存在
    continue;
  }
  runTool(acc.name, args);
}

为什么不能边拼边解析:{"fi 不是合法 JSON,{"file":"a 也不是。只有拼完才可能合法。


7.4 并行工具 ​

模型一轮可能同时发多个调用(比如"查库存"和"查价格"):

两条实践:

  • 界面上按 index 各自成卡片,不要"合并成一个正在执行的工具";
  • 回传顺序按 index,别按完成先后,否则模型对不上号。

7.5 卡片怎么设计 ​

一个够用的工具卡片包含四样:

元素作用
名称 + 图标让用户一眼知道类别(检索/计算/写库)
参数摘要只显示关键字段,别把整坨 JSON 摊开
状态与耗时running 2.4s / done 0.8s
结果默认折叠,展开看详情
tsx
<div className="tool-card">
  <span className={state.phase}>{iconFor(state.phase)}</span>
  <span className="name">{name}</span>
  <span className="summary">{summarize(args)}</span>
  <span className="elapsed">{elapsed}s</span>
  {state.phase !== "running" && <details>…</details>}
</div>

summarize 的写法:挑 1–2 个字段,超过 20 字截断。用户要的是"它在干什么",不是参数全貌。


7.6 失败归谁处理 ​

失败来源谁兜底界面表现
参数非法前端卡片 failed,说明原因,不重试
工具执行报错后端结果里带错误,回传给模型
工具超时前端 + 后端卡片超时态,可手动重试
模型放弃继续模型回答里说明"这一步没成功"

原则:前端的失败尽量"回传给模型",而不是直接弹红框。模型看到"工具返回超时",通常会换个做法或解释原因,体验比"出错了"好得多。


7.7 一个反例 ​

见过一个实现:工具一开始执行就把整块回答区域替换成"正在调用工具…",出来再换回文本。结果是:

  • 用户看到已生成的文字消失又出现;
  • 无法判断工具和文本的顺序关系;
  • 停止按钮在此期间无效。

正确做法就是第 6 章的 parts:工具是回答里的一个片段,插在文本之间,不覆盖文本。


本章小结 ​

要点说明
流式形状name 与 arguments 都是增量,按 index 归并
解析时机拼完且 finish_reason=tool_calls 后再 parse
三态running / done / failed,禁止永久转圈
并行各自卡片,回传按 index
卡片名称、参数摘要、耗时、折叠结果
失败尽量回传模型,别直接弹红框

下一章 ​

除了文字和工具,回答里还会有"引用"和"图表"。下一章讲这些富内容怎么放,以及怎么点回原文。

本文阅读--次|全站访问--次|访客--人