AI API流式响应中的delta、done、stop_reason和连接关闭有什么区别？
直接答案
依据OpenAI Responses、Anthropic Messages Streaming与WHATWG Server-Sent Events文档，解释增量事件、内容完成、响应完成、停止原因、错误事件和网络断开各自代表什么。
症状、差异与判断依据
直接答案
delta是尚在生成过程中的增量片段；内容级 done表示某个文本或内容块已定稿；响应级 completed或最终结束事件表示整个模型响应成功完成；finishreason或 stopreason说明模型为何停止生成；连接关闭只说明传输通道结束，可能发生在正常完成之后，也可能是代理超时、客户端取消或网络中断。 因此，不能把“读到EOF”当作成功，也不能在收到第一个done事件后就提交业务结果。客户端应按所用API的事件状态机收集片段，识别响应级成功、失败或不完整状态，再执行解析、计费记录、工具调用或数据库写入。
一、概念对比
信号 所在层级 是否代表完整响应成功 典型用途 ----------- delta 内容增量 否 实时显示或累积内容 内容done 内容块 否，不一定 定稿一个文本、参数或音频部分 响应completed 整体响应 是，需检查最终对象 触发最终解析与持久化 finish/stop reason 模型生成语义 不一定是自然结束 判断截断、工具调用、拒绝等 error/failed/incomplete 整体或事件 否 错误恢复、用户提示、监控 连接关闭/EOF 网络传输 无法单独判断 结束读取并核对终态 事件名称随供应商和接口变化。不要把某个SDK的字段名硬编码为所有AI API的通用协议。
二、delta是什么
Delta事件只携带相对上一状态新增的内容。文本可能按任意边界分片，一个汉字、标点、JSON转义或工具参数都可能跨多个事件。片段边界不是词、句子或完整JSON对象的语义边界。 客户端应按事件提供的输出索引、内容索引或块ID累积，而不是简单把所有字符串追加到一个全局缓冲区。并行工具调用、多输出项目和多模态内容可能同时存在，需要分别维护状态。
三、内容done表示什么
OpenAI Responses流中存在如 response.outputtext.done、response.contentpart.done 和 response.outputitem.done 的不同完成事件。它们分别结束一个文本字段、内容部分或输出项目，不代表整个Response已经完成。 收到内容done后，可对该部分做局部渲染或校验，但最终usage、其他输出项、工具调用和整体状态可能尚未到达。业务提交应等待响应级终态。
四、响应completed表示什么
OpenAI Responses API的 response.completed携带完整响应对象，并标记整体生成完成。客户端应检查最终 status、error、incompletedetails和输出结构，而不是只根据事件名称放行。 一个流可能包含多个内容块和工具项目，只有响应级完成事件能说明服务端状态机已走到成功终态。此时再执行完整JSON解析、Schema验证和一次性下游写入更安全。
五、stop_reason或finish_reason是什么
停止原因说明模型为什么停止生成，而不是网络为什么断开。常见语义包括自然结束、达到输出Token上限、命中自定义停止序列、请求调用工具、暂停等待后续操作或安全拒绝。 Anthropic文档说明，stopreason属于成功响应的生成语义，流式场景中可在 messagedelta中出现，最终还有 messagestop事件。不同值需要不同业务动作，不能把所有非空stop reason都当作“答案完整”。
六、达到max_tokens算成功吗
HTTP请求可能成功，模型也返回了有效内容，但输出因 maxtokens达到上限而截断。传输层是成功的，业务层却可能不完整；JSON、代码块或工具参数甚至可能停在半截。 应明确标记截断，避免直接解析或发布。是否继续生成取决于任务可续接性、上下文、成本和幂等设计，不能无上限自动发送“继续”。
七、工具调用为什么不是最终答案
停止原因为工具调用时，模型正在请求应用执行工具，而不是结束整个用户任务。客户端需校验工具名称和参数，执行被授权的操作，再把工具结果按协议返回模型，形成下一轮响应。 工具参数的delta同样可能是分段JSON。只有对应参数或内容块完成后才能解析，且解析成功仍需Schema、权限和业务校验。不要边接收边执行未完整参数。
八、SSE连接关闭代表什么
Server-Sent Events使用 text/event-stream传递由字段和空行分隔的事件。连接可能由服务器正常关闭，也可能被浏览器、客户端、代理、负载均衡器或网络中间层中断。 EOF不包含“成功”语义。若未收到协议要求的最终事件，应把本次响应标记为终态未知或失败，而不是把已累积文本冒充完整结果。
九、网络断开和模型停止如何区分
模型停止通常伴随供应商定义的停止原因和响应级结束事件；网络断开可能只有读取异常、超时或无终态EOF。保存最后一个完整事件类型、sequence number、response ID和时间，可帮助判断丢失发生在哪一段。 如果流已收到completed后客户端才感知连接关闭，业务结果通常可按最终对象处理；若只收到若干delta，则不能推断服务端是否完成。支持查询Response状态的API可用response ID做只读恢复检查。
十、错误事件和HTTP错误有什么区别
在流建立前发生的认证、限流或请求格式错误，通常以非2xx HTTP响应返回，客户端不会进入正常事件循环。流建立后发生的生成或服务错误，则可能作为流内error、failed或incomplete事件出现。 反向代理还可能在上游失败时返回HTML错误页。客户端应先检查HTTP状态和Content-Type，再解析SSE；不要把网关HTML逐行当成模型delta。
排障步骤与验证
十一、SSE事件如何解析
合规解析器按SSE规则处理 event:、data:、id:、retry:和空行事件边界。一个事件可包含多个data行，注释行还可用作keepalive。直接按每个TCP数据包或每行执行JSON.parse会产生间歇错误。 优先使用供应商官方SDK或成熟SSE解析器。自行实现时建立最大事件大小、UTF-8处理、未知事件兼容和取消机制，防止无界缓冲。
十二、为什么不能对每个delta执行JSON.parse
JSON对象可在任意字符位置被拆分： 前两个片段都不是有效完整JSON。应按接口提供的参数done或响应完成事件拼接，再解析一次。Structured Outputs也不改变网络分片规律，约束的是最终输出结构。
十三、sequence number有什么用
部分事件模型提供sequence number，用于描述事件顺序。客户端可检测重复、乱序或缺口，并把最后确认序号写入脱敏诊断日志。它不自动提供跨连接重放能力，除非API明确支持恢复。 不要自行猜测缺失delta并拼接文本。发现序号异常时应停止提交结果，按供应商协议查询、重试或报告失败。
十四、客户端取消如何处理
用户点击停止、请求超时或上游任务取消时，客户端应主动中止读取并把本地状态标记为cancelled。服务端是否同步停止计费和生成由具体API定义，不能只关闭UI读取器便假设请求已取消。 下游写操作应发生在明确终态之后，或具备可回滚和幂等性。若用户取消时已经执行工具，需要单独记录工具结果，避免重试后重复副作用。
十五、可靠状态机示例
连接EOF只是读取器事件：若当前状态已是COMPLETED，可结束；若仍是INPROGRESS，则转入TRANSPORTLOST并禁止把结果标记完成。实际事件类型以使用中的API参考为准。
十六、重试如何避免重复副作用
纯文本生成失败后重试可能产生不同答案；工具调用失败后重试还可能重复发邮件、创建工单或扣费。把模型生成、工具执行和业务提交拆成独立阶段，分别使用request ID、tool call ID和业务幂等键。 只有在确认错误可重试、未收到成功终态且副作用状态可判断时才重试。网络中断后的“状态未知”不能等同于“服务端肯定没执行”。
十七、监控应记录什么
API和SDK版本、模型ID、stream模式。 HTTP状态、Content-Type、response ID与request ID。 首事件、首文本和终态耗时。 最后一个完整事件类型与sequence number。 stop/finish reason、最终status和incomplete reason。 delta数量、累计字节和解析错误。 客户端取消、代理超时与网络断开分类。 日志不得包含API Key、完整用户输入、敏感模型输出或工具凭据。
十八、最小测试矩阵
短文本自然结束，必须收到响应级完成。 极小输出上限，验证截断不会被标记完整。 工具调用，确认参数完成后才解析和执行。 安全拒绝，确认不进入普通答案处理。 中途断开连接，确认状态为transport lost。 代理返回HTML错误，确认不会进入SSE解析。 客户端主动取消，确认不触发最终业务提交。 重复事件或模拟序号缺口，确认检测并停止。
十九、常见误区
读到EOF就把响应标成success。 收到内容done就忽略后续输出项目。 把stop reason当成网络断开原因。 对每个delta单独JSON.parse。 HTTP 200后不再处理流内错误。 达到max tokens仍发布半截JSON。 工具参数未完成就开始执行。 网络中断后无条件重试有副作用操作。 只记录拼接文本，不记录事件终态。
二十一、结论
Delta是增量，内容done只结束局部，response completed才是整体成功终态，stop或finish reason解释模型为何停止，连接关闭则只是传输事实。客户端用明确状态机连接这些信号，并把未收到终态的EOF视为异常，才能避免半截内容、重复工具调用和错误成功标记。
常见问题
收到response.output_text.done就可以保存答案吗？
可以保存为临时内容，但不应标记整个响应成功。还需等待响应级completed，并检查最终状态和其他输出项。
stop_reason=end_turn一定表示内容符合业务要求吗？
不一定。它表示模型自然结束，不证明事实正确、Schema有效或业务校验通过。仍需执行应用验证。
连接正常关闭却没有最终事件怎么办？
按协议异常处理。若API支持按response ID查询状态，可先只读核对；否则将结果标记不完整，不要提交为成功。
SSE会保证一个data行就是一个完整JSON吗？
事件载荷由具体API定义。TCP分包与SSE事件边界不同，应使用SSE解析器先恢复完整事件，再按供应商格式解析data。
流式响应比非流式更容易重复计费吗？
流式本身不等于重复计费；风险来自状态未知后的不受控重试。应记录response ID、终态和幂等上下文，再决定是否重试。