AI 流式输出怎样区分文本增量和工具事件

AI 流式输出里最容易出错的地方，是看到每个事件都有 delta 就直接拼到同一个字符串。正确做法是先看事件的 type：文本增量进入展示缓冲区，工具参数增量进入按调用标识隔离的参数缓冲区，完成事件和错误事件只更新状态，不当作正文展示。

官方资料入口：https://developers.openai.com/api/docs/guides/streaming-responses

Gemini 流式资料入口：https://ai.google.dev/gemini-api/docs/streaming

一句话判断：文本事件可以边到边显示，工具事件只能边到边收集；等参数完成后再做 JSON 解析、权限校验和工具执行。

• 不要用“是否存在 delta”区分文本和工具，因为工具参数也可能是增量。
• 文本和工具必须使用不同缓冲区，工具参数还要按调用 ID 隔离。
• 统一适配层只输出 text_delta、tool_delta、tool_done、completed、error 等内部事件。

先按事件类型分流，不要按字段猜

OpenAI Responses 的流式事件是有明确类型的。response.output_text.delta 表示文本内容继续增加，适合交给 UI；response.function_call_arguments.delta 表示函数参数仍在分段到达，应交给工具参数缓冲区；对应的 response.function_call_arguments.done 才提供完整参数。response.completed 和 error 则属于生命周期信号。

因此消费循环的第一层只做路由，不在这里执行工具，也不把未知事件默认为文本。这样当 API 增加搜索、代码执行或其他工具事件时，未知分支仍然是可记录的状态，而不是污染用户看到的答案。

// 文本增量立即展示；工具参数增量只进入对应调用的缓冲区。
for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    renderText(event.delta);
    continue;
  }
  if (event.type === "response.function_call_arguments.delta") {
    appendToolDelta(event.item_id, event.delta);
    continue;
  }
  if (event.type === "response.function_call_arguments.done") {
    finishToolArguments(event.item_id, event.arguments);
    continue;
  }
  if (event.type === "response.completed") {
    markCompleted();
    continue;
  }
  if (event.type === "error") {
    markFailed(event.message);
    continue;
  }
  // 未覆盖的事件先记录，避免被误渲染成普通文本。
  recordUnknownEvent(event.type);
}

文本和工具参数要用两套缓冲区

文本增量的目标通常是“尽快让用户看到”，可以按到达顺序写入界面或消息缓存。工具参数的目标则是得到一个完整、可校验的调用对象，不能因为中间片段看起来像 JSON 就立刻 JSON.parse。例如 {"city":"Sh 和 anghai"} 分别到达时，前一段显然不是完整 JSON。

参数缓冲还要按 item_id 或 SDK 提供的调用标识分组。并行工具调用时，多个调用的参数可能交错到达；如果只有一个全局字符串，最后得到的 JSON 可能无法对应正确的工具。完成事件到达后，再做 JSON 解析、schema 校验、权限判断和超时控制。

OpenAI 和 Gemini 怎样映射到同一套内部模型

OpenAI Responses 直接使用 response.output_text.delta 与 response.function_call_arguments.delta 这样的事件名。Gemini Interactions 的流式工具调用则会出现 step.start 和 step.delta，其中函数参数通过 arguments_delta 逐段发送；服务端工具还会产生不同的调用和结果步骤。两者名称不同，但消费端关心的状态相同。

可以在适配层把它们统一成如下内部事件：text_delta 携带可展示文本，tool_delta 携带调用标识和参数片段，tool_done 携带完整参数，completed 表示整条响应结束，error 表示流失败。业务层只依赖这组稳定语义，不把某家 SDK 的字段名扩散到 UI 和工具执行器。

性能指标和异常边界怎么留

如果按“第一次文本增量时间、文本增量数量、工具参数完成时间、工具执行耗时、最终完成时间”分别记录指标，就能区分模型生成慢、网络分片慢和工具执行慢。不要只记录总耗时，否则用户看到文字很快但工具迟迟没有结果时，无法判断瓶颈在哪一段。

异常处理至少保留三条边界：流断开时不能把未完成参数当作可执行调用；参数解析失败时保留调用标识和原始片段摘要；收到错误或完成事件后停止继续向同一会话追加重复状态。生产环境还应限制参数缓冲区大小，并对工具名称、参数 schema 和权限做服务端校验。

常见问题

文本增量和工具参数都叫 delta，能不能统一拼接？

不能。字段名相似不代表语义相同；应先按事件类型和调用标识分流。

工具参数每收到一段就解析一次可以吗？

一般不行。只有完成事件到达后才有完整输入，提前解析会把合法的半截 JSON 当成错误。

不同模型厂商是否必须写两套业务逻辑？

不必。保留厂商适配层，把事件归一为文本、工具、完成和错误等内部事件，业务层只处理统一模型。