GPT-6 Astra 流式传输指南：响应 API 事件、工具和错误处理

流式传输通过在GPT-6 Astra工作时传递事件来改善感知延迟。但这并不能使底层计算免费或消除故障情况。生产环境中的客户端必须组装增量输出、渲染工具进度、区分终端状态，并在连接失败时进行恢复。

从类型化事件开始

设置 stream: true 并遍历 SDK 的类型化事件流。

const stream = await client.responses.create({
  model: "gpt-6-astra",
  "用五个步骤解释迁移计划。"
  stream: true
});

for await (const event of stream) {
  switch (event.type) {
    case "response.output_text.delta":
      process.stdout.write(event.delta);
      break;
    ("response.completed"):
      console.log("\n完成");
      break;
    .failed
      console.error("失败", event.response.error);
      break;
    case "error":
      console.error(event.message);
      break;
  }
}

常见的文本生命周期事件包括 response.created、response.output_text.delta、response.completed 和 error。完整的事件联合还包含输出项、内容部分、注释、拒绝、失败及其他事件。请安全处理未知事件类型，以确保新增事件不会导致旧版客户端崩溃。

构建汇编器，而非文本追加循环

可以包含多个输出项和内容部分。按响应、输出项和内容部分索引状态，而不是将每个增量追加到一个全局字符串中。在可用时使用文档化的标识符或序列数据进行去重，并仅渲染已提交的本地状态。

注释和引用可能与正文分开出现。在拼接时，应保留它们的偏移量或关联关系，而非直接移除。若存在最终响应对象，应以其为准。

终端状态不可互换

response.completed 表示成功完成。response.failed 表示失败。response.incomplete 可能反映令牌限制或其他原因，并可能包含有用的部分输出。传输级别的 error 可能在没有正常响应终止事件的情况下发生。

不要仅仅因为 socket 关闭就标记请求为成功。一旦收到 response.created，立即持久化响应 ID，然后单独保存最终状态。

如实记录流工具活动

工具调用引入多个阶段：模型规划、参数生成、服务器或客户端执行、工具结果以及恢复生成。您的界面应仅在存在相应事件/状态时显示“搜索中”或“等待批准”。请勿虚构进度百分比。

对于客户端执行的函数，除非API合约明确支持增量消费，否则应在解析前组装完整的参数。验证这些参数，执行一次，并使用调用ID返回结果。流式传输重复事件不得触发重复的副作用。

背压与UI性能

令牌大小的增量到达速度可能超过浏览器的渲染速度。短暂缓冲并以受控节奏更新UI。这能减少布局工作，同时不会明显损害感知延迟。如果框架支持，请限制内存缓冲区并暂停下游处理。

将原始事件日志与视图模型分离。事件日志支持调试；视图模型将增量合并为稳定的用户可见内容。在记录前对敏感工具负载进行脱敏处理。

断开连接、超时与取消

断开连接时，在状态恢复前将操作归类为未知。模型响应可能已在服务器端继续，外部工具可能已经执行了操作。避免自动重放写入操作。

使用请求截止时间和空闲流计时器，但要区分“无文本增量”和“无活动”；长时间的工具调用可能仍然正常。取消操作应传播到您自己的可取消工具。它无法保证已完成效果的回滚。

如果您继续通过响应状态，请保留最后提交的响应和工具结果。WebSocket特定的恢复可能会报告previous_response_not_found；官方错误指南建议在状态无法解析时，使用完整输入上下文和previous_response_id: null重试。

可观测性

记录到 response.created 的时间、第一个文本增量、第一个工具事件和终端事件；总时长；事件计数；终端状态；断开连接；重试次数；以及用户取消。将所有事件与一个应用程序请求ID和OpenAI响应ID关联起来。

测试格式错误的订单、重复投递、未知事件、工具超时、可见文本后的延迟失败，以及写入后的连接丢失。流式正确性即状态机正确性。

浏览器与服务器实现模式

在许多产品中，应用服务器应持有OpenAI连接，并将经过净化的事件流中继到浏览器。这样可以将API凭据保留在客户端之外，集中授权，并让服务器隐藏内部工具参数。浏览器仅接收渲染所需的事件：状态、安全文本增量、引用、审批提示和终端结果。

持久化粗粒度的检查点，而非每个字符。保存每个增量会产生过多的写入操作；仅在完成时保存则会在断开连接时丢失过多数据。通常，采用较短的间隔或内容分块边界是更好的折中方案。重新连接时，发送最新的已提交视图，并根据你的传输设计从下一个已知事件继续。

审核与安全需要流式策略。部分文本在最终响应生成前就会到达用户，因此仅在完成时进行下游审查可能为时已晚。根据风险选择预生成控制、增量防护、缓冲或受限流式传输。高风险工作流可能有意牺牲部分即时性以换取审查。

最后，确保分析不会重复计算浏览器刷新后恢复的响应。OpenAI 响应 ID 和您稳定的应用程序请求 ID 应将每个片段合并为一个逻辑任务。

常见问题解答

流式传输能降低Token成本吗？

不。它改变的是交付方式，而非生成的令牌数量。

我能立即显示部分输出吗？

是的，但请将其标记为进行中，并做好被拒绝、不完整或失败结果的准备。

连接关闭时我应该重试吗？

优先进行恢复或协调，尤其是在工具可能产生副作用的情况下。盲目重放可能导致操作重复。

SSE 和 WebSocket 事件处理是否相同？

它们共享响应概念，但传输和延续行为有所不同。请按照所选模式的指南进行操作。

结论

可靠的GPT-6 Astra流式传输需要类型化事件处理、结构化汇编器、明确的终端状态、幂等的工具执行、背压机制以及恢复能力。优化用户对进度的感知，避免将部分文本或已关闭的连接错误地视为成功。