从 OpenAI 到 Anthropic/Gemini:Go 实现 LLM 网关 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(),导致问题极其隐蔽。
解决方案
- 显式调大
scanner.Buffer()上限(例如初始 64KB,最大允许 4MB 或 10MB),或者改用bufio.Reader.ReadBytes('\n'); - 循环结束后务必检查
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)
五、上线前自检清单
- 首字刷新:确认所有流式返回路径都调用了
flusher.Flush(),且响应头携带X-Accel-Buffering: no。 - 大包兼容:确认读取上游 SSE 行时已扩容
scanner.Buffer,并打印scanner.Err()。 - 超时与止损:确认
http.Client移除了总Timeout,改用ResponseHeaderTimeout+r.Context()透传取消信号。 - 错误透传:当上游返回非
200状态码时,不要按 SSE 解析,直接读取原始错误 Body 透传给调用方,方便排查鉴权或限流问题。
- 点赞
- 收藏
- 关注作者
评论(0)