从 OpenAI 到 Anthropic/Gemini:Go 实现 LLM 网关 SSE 流式透传的 3 个隐蔽坑

举报
yd_293806894 发表于 2026/11/13 09:13:02 2026/11/13
【摘要】 在基于 Go 搭建多模型 LLM API 网关时,非流式接口通常一调就通,但切到 stream: true 的 SSE 流式响应后,往往会出现首字延迟极高、前端收不到分段推送或客户端断开后上游仍在扣费等问题。本文结合实际协议转换与网关转发场景,拆解最容易踩中的 3 个缓冲与超时坑及对应修复方案。

一、背景:为什么非流式正常,一流式就出问题?

在聚合 OpenAI、Anthropic、Gemini 等多家大模型接口时,网关的核心职责是协议字段映射与响应透传。对于普通 JSON 请求,只需反序列化响应体再原样写回即可;但开启 stream: true 后,通信模式变为基于 HTTP 长连接的 Server-Sent Events(SSE):

  • 响应头必须为 Content-Type: text/event-stream;
  • 服务端需要按 data: {...}\n\n 的格式逐块吐出增量 Token;
  • 经过反向代理(如 OpenResty / Nginx)和 Go net/http 服务时,任意一环开启了缓冲或设置了过短的读写超时,都会让「流式输出」退化成「等全部生成完才一次性吐出」。

下面记录开发与联调过程中最容易忽略的 3 个坑。


二、坑 1:只写 w.Write() 忘记 Flusher,导致响应被 Go 缓冲区攒满才发

现象

本地抓包发现上游模型明明已经每秒返回好几个 chunk,但客户端一直卡在等待首包,直到整个对话生成完毕才一次性收到所有 data: 行。

原因

Go 标准库的 http.ResponseWriter 默认自带内存缓冲(通常 4KB 左右)。如果只在循环里调用 w.Write(chunk) 而不显式刷新,数据会一直滞留在缓冲区里,直到缓冲区满或 Handler 函数返回才发送给客户端。

解决方案

在写入每个 SSE 事件后,必须通过类型断言获取 http.Flusher 并主动调用 Flush():

func streamHandler(w http.ResponseWriter, r *http.Request) {
    // 1. 设置标准 SSE 响应头
    w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
    w.Header().Set("Cache-Control", "no-cache")
    w.Header().Set("Connection", "keep-alive")
    // 关键:告知 Nginx / OpenResty 等反向代理关闭缓冲
    w.Header().Set("X-Accel-Buffering", "no")

    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "Streaming unsupported", http.StatusInternalServerError)
        return
    }

    // 2. 逐行读取上游 SSE 响应并转换
    // ... 省略上游请求构建逻辑
    for scanner.Scan() {
        line := scanner.Bytes()
        if len(line) == 0 {
            continue
        }
        // 转换后写入并立即刷出
        converted := convertChunkToOpenAI(line)
        if _, err := w.Write(converted); err != nil {
            return
        }
        w.Write([]byte("\n\n"))
        flusher.Flush()
    }
}

补充提示:如果网关前面还挂了 Nginx 或 OpenResty,除了在代码里加 X-Accel-Buffering: no,也建议在站点配置中显式加上 proxy_buffering off; 与 proxy_cache off;。


三、坑 2:使用 bufio.Scanner 默认配置读取大 JSON Chunk,直接静默截断

现象

普通短文本输出一切正常,但遇到模型输出超长代码块、或者 Anthropic / Gemini 在单条 SSE 事件里返回包含大量 thinking 内容、工具调用参数(Tool Call Arguments)的 JSON 时,流式连接突然中断,且无明显报错。

原因

Go 标准库 bufio.Scanner 的默认单行最大 Token 缓冲限制是 64KB(bufio.MaxScanTokenSize = 64 * 1024)。一旦上游单条 data: {...} 超过 64KB,scanner.Scan() 会直接返回 false,并在 scanner.Err() 中留下 bufio.ErrTooLong。很多代码习惯只写 for scanner.Scan() 却忘了检查 scanner.Err(),导致问题极其隐蔽。

解决方案

  1. 显式调大 scanner.Buffer() 上限(例如初始 64KB,最大允许 4MB 或 10MB),或者改用 bufio.Reader.ReadBytes('\n');
  2. 循环结束后务必检查 scanner.Err() 并记录日志:
scanner := bufio.NewScanner(upstreamResp.Body)
// 初始 64KB,最大支持单行 4MB,防止长 Tool Call 或思考过程触发 ErrTooLong
const maxCapacity = 4 * 1024 * 1024
buf := make([]byte, 0, 64*1024)
scanner.Buffer(buf, maxCapacity)

for scanner.Scan() {
    // 处理每一行 SSE 数据
}

if err := scanner.Err(); err != nil {
    log.Printf("upstream sse read error: %v", err)
}

四、坑 3:上游 http.Client 的 Timeout 设成了固定总超时,长对话中途被掐断

现象

短回复正常,但只要模型生成时间超过 30 秒(例如深度推理模型输出较长思考过程),网关就会在 30 秒整点报错 context deadline exceeded (Client.Timeout exceeded while awaiting headers / reading body)。

原因

在 Go 的 http.Client{Timeout: 30 * time.Second} 中,Timeout 指的是从发起请求到完整读完整个响应 Body 的总耗时,而不是「建连超时」或「首包超时」。对于流式输出而言,一次长推理持续 1~3 分钟非常正常,总超时一旦触发就会直接掐断正常传输中的连接。

解决方案

不要给流式专用 http.Client 设置全局 Timeout,而是拆分控制建连/TLS 握手/首包响应头超时,并将请求生命周期绑定到客户端的 r.Context() 上——这样既不会误杀长流式响应,又能在用户主动点「停止生成」时第一时间取消上游请求、避免继续扣费:

var streamHTTPClient = &http.Client{
    // 不设置整体 Timeout,避免长流式输出被中途掐断
    Transport: &http.Transport{
        DialContext: (&net.Dialer{
            Timeout:   10 * time.Second, // TCP 建连超时
            KeepAlive: 30 * time.Second,
        }).DialContext,
        TLSHandshakeTimeout:   10 * time.Second, // TLS 握手超时
        ResponseHeaderTimeout: 60 * time.Second, // 等待上游返回首包 Header 的超时(可按推理模型适当放宽)
        IdleConnTimeout:       90 * time.Second,
    },
}

// 发起上游请求时绑定 r.Context(),客户端断开即自动 Cancel 上游
req, err := http.NewRequestWithContext(r.Context(), http.MethodPost, upstreamURL, bodyReader)

五、上线前自检清单

  1. 首字刷新:确认所有流式返回路径都调用了 flusher.Flush(),且响应头携带 X-Accel-Buffering: no。
  2. 大包兼容:确认读取上游 SSE 行时已扩容 scanner.Buffer,并打印 scanner.Err()。
  3. 超时与止损:确认 http.Client 移除了总 Timeout,改用 ResponseHeaderTimeout + r.Context() 透传取消信号。
  4. 错误透传:当上游返回非 200 状态码时,不要按 SSE 解析,直接读取原始错误 Body 透传给调用方,方便排查鉴权或限流问题。
【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。