Go 接入 Responses API 流式输出中断怎么排查：从事件序列到 Context 取消

线上问答接口接入 Responses API 的流式输出后，最容易出现误判的情况就是「用户没看到完整答案」。排查的时候最先要确认的，其实是服务端收到了哪些事件、浏览器什么时候断开的，以及Go请求的 context.Context 是否已经触发取消。把这三件事记录到同一条请求日志里，断流问题通常几分钟就能定位出是上游返回异常、客户端提前退出，还是本地读取逻辑出了问题。

把事件序列、客户端断开时机、Context 取消状态三个维度的信息聚合到单条请求日志，就能快速拆分断流根因，不用盲目翻上下游分散的日志。

先看断流发生在哪一段

这类故障一般有三种常见现场：模型还在生成内容时浏览器就断开了；上游已经返回错误事件，但网关直接把连接关掉没透传消息；或者 Go 客户端读取 SSE 时把一次事件拆成了两次读取，误把半行内容当成了完整消息。

Responses API 开启 stream 后，服务端会通过 Server-Sent Events 发送一串事件。排查时不要只打印最终输出的文本，至少保留下面四个字段：

• request_id：业务请求号，用来串起网关和应用层的全链路日志。
• response_id：上游响应标识，拿不到的情况下直接记为空即可。
• event_type：当前事件类型，例如创建、增量、完成或错误。
• bytes_out：已经写给浏览器的字节数。

图里的事件链对应这个交互逻辑：请求先触发创建事件，再返回增量内容片段，最后才进入完成或异常分支。它不是完整的协议示意图，只是用来提醒我们：没有收到结束事件的连接，不能仅凭 EOF 就判定请求成功。

用事件序列确认上游有没有正常收尾

读取流的时候建议把“网络读取成功”和“业务处理完成”两个状态分开判断。下面的示例只保留排查需要的状态逻辑，真实项目里可以把日志直接写入结构化日志系统。

type StreamState struct {
    ResponseID string
    LastEvent  string
    BytesOut   int
    Completed  bool
}

func recordEvent(st *StreamState, eventType, responseID string, n int) {
    if responseID != "" {
        st.ResponseID = responseID
    }
    st.LastEvent = eventType
    st.BytesOut += n
    log.Printf("stream event=%s response_id=%s bytes_out=%d completed=%t",
        eventType, st.ResponseID, st.BytesOut, st.Completed)
}

循环退出的时候再做一次最终状态校验：

if err == io.EOF && !state.Completed {
    return fmt.Errorf("stream ended before completion, last_event=%s", state.LastEvent)
}
if err != nil {
    return fmt.Errorf("read stream: %w", err)
}

这里先别急着加自动重试逻辑。如果最后一个事件是上游返回的错误，应该先保留错误码和原始消息；如果最后一个事件是增量内容，但浏览器已经断开连接，就要去查请求的 Context 状态；只有遇到网络短暂失败、且服务端还没进入完成状态的场景，才值得进入受控重试流程。

把浏览器取消传到上游请求

Go 的 Context 非常适合携带请求级的取消信号和截止时间。HTTP handler 收到客户端断开的通知后，由它派生出来的 Context 会直接结束；发向上游的请求必须使用这个 Context，不能偷偷换成 context.Background()。

func streamAnswer(w http.ResponseWriter, r *http.Request) error {
    ctx, cancel := context.WithTimeout(r.Context(), 90*time.Second)
    defer cancel()

    req, err := http.NewRequestWithContext(ctx, http.MethodPost,
        "https://api.openai.com/v1/responses", bytes.NewReader(body))
    if err != nil {
        return err
    }
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Accept", "text/event-stream")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    return copyEvents(w, resp.Body)
}

如果日志显示浏览器已经断开，但上游连接还持续几十秒不释放，通常就是取消传递链断了。图里把客户端、Go handler 和上游响应画成一条完整链路，红色的取消信号必须穿过 handler 层到达 HTTP 请求；只在写响应的位置检查断开状态是不够的。

处理步骤：先观测，再修复读取和取消

第一步：给每次请求固定请求号

网关生成 request_id，应用日志、上游请求头和前端错误回报都统一使用这个编号。不要把完整提示词、密钥令牌或用户私密内容写入日志，只记录长度、事件类型和错误摘要就够了。

第二步：区分四种结束状态

把所有结束场景收敛成 completed、upstream_error、client_canceled、deadline_exceeded。同一个 context.Canceled 在业务上大概率代表用户主动离开，告警级别不能和上游故障设成一样。

第三步：按 SSE 边界读取

不要假设一次 Read 就是一条完整事件。使用带缓冲的逐行读取器，保留跨读取边界的剩余内容；空行通常标志一条 SSE 事件的结束，具体字段规则仍要以当前接口的官方文档为准。

第四步：只对可重试错误重试

重试需要发起新的上游请求，但不能再次把已经展示过的片段无条件拼回页面。更稳妥的做法是：服务端保存本次请求的幂等键和当前状态，前端收到重试信号后清空未完成答案，再从新响应开始渲染。

回滚路径：先关闭流式开关

如果新的SSE解析器刚上线、错误率突然升高，最短平快的回滚操作不是调整模型参数，而是把同一业务请求暂时切回非流式响应，同时保留相同的超时、请求号和敏感字段脱敏规则。这样就能快速判断问题是不是集中在 SSE 解析和增量转发层。

回滚后要观察两个指标：完整响应成功率有没有恢复、平均响应时间是不是只是变长。如果成功率恢复但延迟明显增加，说明上游服务本身大概率没有故障，下一步只需要回滚本地流式解析的改动即可。

告警确认和复盘清单

• 每分钟未完成流占比是否超过正常基线。
• client_canceled 是否集中在固定浏览器或代理版本。
• 上游错误是否有共同的 HTTP 状态或错误码。
• Context 取消后，上游连接是否在合理时间内释放。
• 重试后是否出现重复片段、重复计费或状态覆盖的问题。

复盘时把一条真实请求的事件序列、Context 状态和最终分类放在一起对照查看。只盯着“前端显示不完整”这个表象，很容易把客户端离开误判成模型故障。

相关问题

为什么收到 EOF 不能直接标记成功？

EOF 只说明读取端没有更多可读字节，不等于上游已经发送了完成事件。必须结合 Completed 和最后事件类型共同判断。

客户端断开后还要继续读取上游吗？

通常不需要。应让请求 Context 尽快取消并关闭上游连接，只有确实要做后台异步任务的场景，才把逻辑设计成独立的后台任务。

流式请求失败后能否原样重试？

可以重试，但要先区分失败发生在首字节返回前还是已经输出了部分片段；后者要先清理旧片段，并且使用幂等键避免生成重复业务记录。

收尾检查

线上流式接口的核心要求不是“能出字”，而是每一条响应都有可追溯可解释的完整生命周期。先落地事件打点，再校验 Context 取消全链路，最后才决定回滚或执行重试。把收到完成事件作为请求成功的唯一门槛，很多看似随机出现的断流问题，都会变成可以明确复盘归类的四种标准状态。