OpenAI API 怎样区分流式输出中的文本事件

OpenAI API 的 Responses 流不是连续字符串，而是一组带有 type 字段的语义事件。要区分流式输出中的文本，核心判断只有一个：只把 event.type === "response.output_text.delta" 的 event.delta 写入文本缓冲；response.completed 负责收尾，error 负责异常处理。

官方文档：https://developers.openai.com/api/docs/guides/streaming-responses

这个边界很重要：如果把所有事件都当作文本，完成对象、工具事件或错误信息可能混入最终回答。对于并发请求，先按事件类型分流，再分别维护文本和状态，后续扩展会更稳。

流式事件不是一串可以直接拼接的字符串

Responses API 为流事件定义了预先约定的结构。一次响应会经历创建、输出增量、完成或失败等不同信号，其中只有文本增量事件携带应直接展示给用户的文本片段。判断事件时，应先读取 type，再决定读取哪个字段。

这也是流式处理从“能输出”走向“可维护”的分界线。文本是数据，完成和错误是控制状态，三者应当走不同的处理出口。

只接收 response.output_text.delta

下面的最小示例使用 JavaScript SDK 读取 Responses 流。代码不依赖事件到达的具体数量，只关心类型和对应字段；每个增量到达时立即写出，避免等待整段回答完成后再拼接。

import OpenAI from "openai";

const client = new OpenAI();
const stream = await client.responses.create({
  model: "gpt-6-astra",
  input: "用一句话说明流式事件为什么需要按类型处理",
  stream: true,
});

for await (const event of stream) {
  // 只有文本增量进入用户可见的文本缓冲。
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}

这里不要用“对象是否有 delta 字段”代替类型判断，因为不同事件的字段语义并不相同。把 response.output_text.delta 作为唯一文本入口，能避免把控制事件误写入正文。

完成和错误要走独立分支

文本输出结束不等于任意一个事件都可以停止。完成信号用于释放本次流的收尾状态，错误信号则应进入异常路径。一个更完整的分流写法如下：

let text = "";

for await (const event of stream) {
  // 文本片段按到达顺序累积，便于保存完整结果。
  if (event.type === "response.output_text.delta") {
    text += event.delta;
    continue;
  }

  // 完成事件只更新生命周期状态，不把对象序列化进正文。
  if (event.type === "response.completed") {
    console.log("\n流式响应已完成，文本长度：", text.length);
    continue;
  }

  // 错误事件保留原始消息，交给调用方决定重试或展示。
  if (event.type === "error") {
    console.error("流式响应失败：", event.message);
    break;
  }
}

response.completed 和 error 都是状态信号，不应追加到 text。如果业务还需要处理拒答、工具调用或注释事件，可以继续增加明确的 else if 分支，并为每类事件定义自己的数据结构。

并发流消费时，为什么要把文本和状态分开

在只有一个请求的示例中，直接累积字符串已经够用；进入并发场景后，真正容易出问题的是边界混在一起：文本缓冲负责内容，完成状态负责生命周期，错误状态负责失败原因。如果所有逻辑都塞进一个“收到事件就拼字符串”的回调，重试、日志和前端增量渲染会互相影响。

更稳妥的结构是让流消费器只做三件事：读取事件、按 type 路由、把结果交给对应出口。文本出口维护增量缓冲，生命周期出口记录完成，异常出口统一记录错误。这样增加新事件类型时，不必修改已有文本拼接规则。

代价也很明确：分支和状态对象会比单一字符串复杂，调用方需要约定哪些状态可以重试、哪些状态只能结束请求。但这个复杂度换来了更清晰的故障定位，尤其适合同时维护多条流的服务。

常见问题

为什么不能把每个事件直接 JSON.stringify 后展示？
因为流中既有文本增量，也有完成、错误及其他语义事件。直接展示会把控制信息混入用户回答。

文本增量应该读取哪个字段？
在 Responses 流里，按类型命中 response.output_text.delta 后读取 event.delta，不要对其他事件猜测字段含义。

收到 response.completed 后还要继续拼接吗？
通常不再追加文本；它表示本次响应进入完成状态。若业务还要处理其他事件，应以官方事件类型定义为准。

小结

区分 OpenAI API 流式文本事件的关键不是解析字符串，而是建立类型边界：response.output_text.delta 进入文本缓冲，response.completed 负责收尾，error 进入异常处理。把数据和状态分开后，单请求示例可以保持简洁，并发服务也更容易扩展。