大模型流式输出断在半句：增量 JSON 缓冲、finish_reason 与重连收口

对话接口已经返回了半句中文，前端却一直停在“正在生成”，日志里还看不到明确错误。这个现象通常不是模型突然忘了后半句，而是客户端把分片当成完整 JSON 解析，或者在连接断开时没有区分“正常结束”和“可恢复的中断”。解决办法是把字节流、增量文本、结束原因和重连状态分开记录，只有看到终止事件或完成标记，才把消息收口。

流式响应要先缓冲、再解析、后提交；连接断开时依据已保存的请求标识和结束原因决定续接、重试还是明确失败，不能用“收到过内容”代替完成判断。

半句停住时，先确认到底断在哪一层

我更建议先抓一份原始流，而不是马上提高超时。把服务端返回的 SSE 行、解析后的增量文本和 UI 最后一次提交位置分成三列，通常很快能看出问题属于网络、JSON 边界，还是状态机没有收尾。

增量 JSON 缓冲为什么不能一行一解析

网络层交付的是字节块，不承诺一次正好对应一个 JSON 对象。下面的示例故意把一条消息拆在字符串内部；readChunk 只负责追加数据，json.Decoder 在缓冲区有完整对象后才消费。真实项目中可以把 SSE 的 data: 行先剥离，再交给相同的缓冲策略。

type StreamState struct {
    Buffer          []byte
    LastCommittedSeq int
    Status          string
}

func readChunk(state *StreamState, chunk []byte) (string, error) {
    state.Buffer = append(state.Buffer, chunk...)
    for {
        end := bytes.IndexByte(state.Buffer, '\n')
        if end 

这里的关键不是示例代码是否正好匹配某一家接口，而是职责边界：readChunk 不负责判定完成，json.Decoder 不负责决定 UI 状态。若协议使用换行分隔事件，就按事件边界切分；若协议给出结构化事件，就保留未闭合 JSON，绝不要把一次 Read 当成一次完整消息。

finish_reason 只负责解释结束，不负责修补缺失文本

当服务端明确返回 finish_reason，客户端才知道生成是自然停止、长度达到上限，还是因为内容策略等原因提前结束。不同 API 的字段位置和事件名称可能不同，所以适配层应把它们统一成内部枚举，例如 stop、length、content_filter、unknown。

如果最后只有半句且连接直接关闭，内部状态应先变成 interrupted，保留已有文本和请求标识。不要把它偷偷改成 completed，也不要立刻把相同请求完整重放，否则用户会看到重复内容，服务端也可能重复产生计量结果。

func closeStream(state *StreamState, reason string) {
    switch reason {
    case "stop":
        state.Status = "completed"
    case "length", "content_filter":
        state.Status = "interrupted"
    default:
        state.Status = "interrupted"
    }
}

重连时用状态机避免重复追加

重连不是简单地再发一次请求。客户端至少要保存请求标识、已提交的序号和当前状态；收到重复事件时，只接受序号大于 LastCommittedSeq 的增量。若上游不提供序号，就在自己的适配层为每个事件分配单调序号，并在日志中记录原始事件 ID。

func retry(state *StreamState, event StreamEvent) bool {
    if event.Seq 

重连成功后仍要等待新的结束信号。若达到重试上限，才向用户展示“输出被中断，可重新发送”，并保留诊断字段。这样既不丢掉已经确认的文字，也不会把未确认的半句当成最终答案。

一份能落地的排查与回归清单

• 记录原始事件边界：每个事件的序号、字节长度和接收时间。
• 测试切分点：把 JSON 分别截在中文 UTF-8、反斜杠转义和结束括号之前。
• 覆盖结束分支：stop、length、content_filter 与连接异常。
• 模拟重连重复：重复发送最后两个事件，确认 LastCommittedSeq 不回退。
• 检查界面状态：完成、被截断、网络中断三种状态的提示必须不同。

OpenAI 的 Responses 流式文档把流式结果描述为服务器发送事件，并提供完成及不完整原因等结构化事件；实现时仍应以所接入模型的实际事件契约为准，先在适配层核对字段，再把内部状态暴露给前端。

常见问题

收到 [DONE] 就一定代表文本完整吗？

它通常代表传输流结束，但是否是业务上的完整答案，还要结合此前的结束原因、错误事件和应用自己的状态。

为什么不能把最后一次 delta 当作结束信号？

delta 只表示增量内容，可能还有结束事件没有到达；把它当终态会让 UI 提前收口。

重连后出现重复句子怎么修？

保存请求标识和最后提交序号，重连时丢弃不大于该序号的事件，并对追加操作做幂等处理。

半句内容要不要直接清空？

不要。保留已确认文本并标记 interrupted，用户可以继续重试或主动重新发送，排查日志也需要这段现场。

把“停在半句”变成可解释的状态

稳定的流式输出不是让网络永远不断，而是让每一次中断都有证据：缓冲区知道自己是否还有未解析片段，适配层知道结束原因，状态机知道最后提交到哪里。三者分开后，半句不再是一个模糊的前端故障，而是可以复现、重连和验收的状态转换。