Nginx代理大模型API流式输出中断怎么解决

文章导读
Nginx 反向代理大模型 API 时出现流式中断,通常先要把责任层分清楚:是 Nginx 把 SSE 响应缓冲后一次性发出、是 proxy_read_timeout 之类的读超时先把连接掐掉,还是应用本身没有逐块 flush、又或者前面还有 CDN、Ingress、网关在做二次聚合。判断顺序建议从「直连后端是否持续出块」开始,再逐个中间层加回来对比,而不是直接改一大堆 Nginx 参数。
📋 目录
  1. A 先确认当前场景和目标
  2. B 按这个顺序处理
  3. C 改完后怎么验证
  4. D 容易忽略的边界
A A

Nginx 反向代理大模型 API 时出现流式中断,通常先要把责任层分清楚:是 Nginx 把 SSE 响应缓冲后一次性发出、是 proxy_read_timeout 之类的读超时先把连接掐掉,还是应用本身没有逐块 flush、又或者前面还有 CDN、Ingress、网关在做二次聚合。判断顺序建议从「直连后端是否持续出块」开始,再逐个中间层加回来对比,而不是直接改一大堆 Nginx 参数。

流式中断通常先查三层:Nginx 缓冲、读超时、链路上的其他中间层。建议在 location 级别关掉 proxy_buffering 与 proxy_cache、指定 HTTP/1.1 并清空 Connection 头、放宽 proxy_read_timeout,再用 curl -N 对比直连与经 Nginx 的分块节奏。若仍断流,重点看应用是否逐块 flush,或前面还有一层在聚合响应。改动只作用于流式接口,代价是上游长连接占用变多。

先确认当前场景和目标

这个问题成立的前提是:接口返回的是 text/event-stream 这类分块流式内容,客户端正常情况下能边收边显示,只是经过 Nginx 后变成「卡很久再一次性吐完」或者「收到一半连接被断」。如果客户端本来就在等完整 JSON,那不算流式中断,改 Nginx 也不会有效果。

动手前先确认四件事:

  • 响应形态:响应头是否为 Content-Type: text/event-stream、Transfer-Encoding: chunked,且没有 Content-Length。出现 Content-Length 说明某一段已经把响应聚合了。
  • 请求路径:客户端到后端之间有几层代理。只在 Nginx 上改,如果前面还有 CDN、负载均衡或 K8s Ingress,问题可能不在这一层。
  • 中断特征:是固定时长后断开(更像超时),还是随机时长后断开(更像连接或上游异常),或者是「长时间无输出然后全部到达」(更像缓冲)。
  • 后端能力:应用是否支持流式响应,框架和 WSGI/ASGI 中间件有没有把响应体整体缓存。

目标是让分块按上游产生节奏到达客户端,而不是追求把超时设到无限大。超时只是兜底,不是解决方案。

按这个顺序处理

第一步先做对照实验:用 curl -N 直连后端端口,观察输出是否连续出现。如果直连也是「攒一会儿一次吐出」,那就是应用侧的 flush 问题,Nginx 无论怎么调都无法让响应提前到达客户端。确认直连正常后,再在 Nginx 配置上逐项处理。

第二步,把流式接口单独放到一个 location 下,避免影响站点内其他普通接口。下面是一段可替换的通用骨架,proxy_pass 的地址、超时值、路径前缀需要按自己的环境改:

Nginx代理大模型API流式输出中断怎么解决
location /v1/ {
    proxy_pass http://llm_backend;

    # 关闭缓冲,让分块按上游节奏下发
    proxy_buffering off;
    proxy_cache off;
    proxy_request_buffering off;

    # 使用 1.1 与 chunked,清空 Connection 避免被降级为短连接
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    chunked_transfer_encoding on;

    # 避免上游压缩导致块边界被打乱
    gzip off;
    proxy_set_header Accept-Encoding "";

    # 读超时要覆盖模型最长思考时间,按实际调整
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;

    # 保留原始 Host / 客户端信息,供后端鉴权与日志使用
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

改完先执行 nginx -t 校验语法,通过后再 reload 平滑生效。如果配置里存在 upstream 块,也可以只在流式接口对应的 upstream 上确认 keepalive 设置,避免长连接被提前回收。

第三步,如果 Nginx 侧改完仍不稳定,检查应用是否在响应头里加了 X-Accel-Buffering: no,这是让 Nginx 对该响应不做缓冲的常用手段;同时确认框架的中间件、日志组件、APM 探针没有读取完整响应体后再转发。

改完后怎么验证

验证的核心是对比「到达节奏」,而不是只看最后能不能拿到完整内容。可以先用响应头确认链路形态:

curl -N -s -D - -H "Authorization: Bearer $TOKEN" \
  https://your-domain/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"stream":true,"messages":[{"role":"user","content":"ping"}]}' \
  -o /dev/null

预期信号是:响应头出现 Transfer-Encoding: chunked,没有 Content-Length;Content-Type 与后端直连时保持一致。然后再看时间维度,把每一行到达的时刻打出来:

curl -N -s https://your-domain/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"stream":true,"messages":[{"role":"user","content":"ping"}]}' \
  | while IFS= read -r line; do printf '%s %s\n' "$(date +%T)" "$line"; done

判断标准:时间戳应当分散在整个输出过程中,并且与直连后端的时间分布大体接近。如果所有行集中在同一个秒级时间点,说明仍存在聚合;如果输出在固定时长后截断,回到超时配置上核对。同时查看 Nginx 错误日志中是否有上游提前关闭连接、客户端断开一类的记录,能把「谁先断的」定位出来。

Nginx代理大模型API流式输出中断怎么解决

验证通过后再做一次稍长的请求,覆盖模型输出较慢的场景,避免只在短回答上测试而漏掉超时相关的中断。

容易忽略的边界

关闭 proxy_buffering 后,Nginx 会为每个流式请求长时间占住一条到上游的连接。并发流式请求较多的环境里,需要同步核对 worker_connections 与上游的连接上限,否则可能把中断问题换成排队和超时问题。这类改动应当只作用于流式 location,不建议对整站关闭缓冲。

超时值不宜无限放大。proxy_read_timeout 设得过长,会让已经失效的连接长期挂着,反而掩盖真正的故障。合理做法是按业务允许的最长生成时间留出余量,并在客户端侧也配置同量级的超时。

还有几类条件需要单独确认:客户端若走 HTTP/2 或 HTTP/3,分块行为与 HTTP/1.1 不完全一致,需要分别测试;启用了 WebSocket 或 gRPC 转发的场景,不能直接套用上面的 SSE 配置;如果链路前面存在 CDN 或云负载均衡,它们各自的缓冲和空闲超时也要一起调整,只改 Nginx 往往看不到完整效果。

回退方式比较直接:保留改动前的配置副本,出现异常时 reload 回原配置即可。如果关闭缓冲后前端表现变差,可以先只保留 proxy_http_version 1.1、清空 Connection 头、放宽读超时这三项,验证是否能缓解,再逐项加回缓冲相关设置,避免一次改太多无法归因。