本地模型通过SSE推送token时Nginx缓冲导致实时性差的问题关闭方法

文章导读
本地模型服务已经正常返回,但通过SSE推送token时,前端却像卡住一样迟迟不更新,我一般不会先怀疑模型推理速度,而是先确认Nginx是否在中间囤积了响应。SSE是长连接流式响应,任何一层缓冲都会让token不能及时送达。
📋 目录
  1. A 先确认现象,别急着改配置
  2. B 容易误判的地方
  3. C 建议的处理顺序
  4. D 配置示例与执行位置
  5. E 验证修改是否生效
  6. F 风险边界与回滚
A A

本地模型服务已经正常返回,但通过SSE推送token时,前端却像卡住一样迟迟不更新,我一般不会先怀疑模型推理速度,而是先确认Nginx是否在中间囤积了响应。SSE是长连接流式响应,任何一层缓冲都会让token不能及时送达。

在本地模型通过SSE推送token时,如果客户端迟迟收不到数据,而模型服务本身已正常返回,首先要检查Nginx是否启用了缓冲。默认情况下,Nginx会对动态请求开启proxy_buffering,将后端响应暂存到缓冲区,直到整个响应完成或缓冲区填满才转发给客户端。SSE是长连接流式响应,缓冲会造成token堆积,表现为T稳定延迟增加。此时可用curl -I或curl -v观察响应头,若没有X-Accel-Buffering: no且未关闭proxy_buffering,基本可以判定是缓冲导致的实时性问题。

先确认现象,别急着改配置

我会先用curl -N直接打后端服务,确认原始SSE流是否正常。如果直连后端时token每秒都有输出,而经由Nginx后却变成积攒一批才发出去,那问题基本就锁定在Nginx缓冲。用curl -v还能看到响应头的Transfer-Encoding和是否有X-Accel-Buffering字段,这两个是判断缓冲是否生效的关键线索。

容易误判的地方

一个容易忽略的坑是只设置了proxy_buffering off,但upstream响应头中携带了X-Accel-Buffering: yes,这个头会覆盖Nginx的本地配置,导致缓冲依然生效。解决办法是使用proxy_hide_header X-Accel-Buffering;来主动清除该头,或者在location中通过proxy_set_header X-Accel-Buffering no;强制指定。另外,如果Nginx以反向代理模式运行,且在HTTP/1.0下开启chunked传输,也可能导致客户端无法及时解析SSE数据,需要确保上游使用HTTP/1.1并设置proxy_http_version 1.1。

本地模型通过SSE推送token时Nginx缓冲导致实时性差的问题关闭方法

还有一种情况是Nginx配置本身没有缓冲,但应用层在发送数据时没有主动flush,数据停留在语言运行时的输出缓冲里。这时候即使Nginx这边全关了,前端依然感觉不实时。所以我会把Nginx和应用的缓冲分开排查,不要一上来就把责任推到Nginx头上。

建议的处理顺序

针对SSE流式接口,最简单的做法是在对应的location中设置proxy_buffering off;,同时建议加上proxy_cache off;以确保动态响应不被缓存。如果上游服务自身设置了X-Accel-Buffering头,需要显式用proxy_hide_header X-Accel-Buffering;移除,或通过proxy_set_header X-Accel-Buffering no;主动覆盖。另外,若Nginx版本较旧,还需要调整proxy_buffer_size和proxy_buffers参数,避免小缓冲区提前触发下半场。配置完成后务必执行nginx -t检查语法,然后平滑重启或重载。

我通常会把SSE接口单独放到一个location或独立子域中处理,不要全部接口都关缓冲。这样即使出了问题,影响面也局限在流式接口上,不会让静态文件和普通API的原有缓冲策略跟着变化。

本地模型通过SSE推送token时Nginx缓冲导致实时性差的问题关闭方法

配置示例与执行位置

以下是一段适用于Nginx反向代理SSE接口的配置示例,放在server或location上下文均可。关键参数是proxy_buffering off和proxy_http_version 1.1,后者是为了保证上游使用HTTP/1.1,避免chunked传输解析问题。

location /api/sse {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header X-Accel-Buffering no;
    # 如果上游返回了X-Accel-Buffering头,下面这行会清除它
    proxy_hide_header X-Accel-Buffering;
    proxy_read_timeout 3600s;
}

修改后先执行nginx -t检查语法,再执行nginx -s reload平滑重载。验证时用curl的-N参数关闭curl自身的缓冲,直接观察数据到达速度:

curl -N -v http://你的Nginx地址/api/sse

如果看到响应头中没有X-Accel-Buffering: yes,并且token随着生成陆续打印出来,说明Nginx这层已经不再囤积数据。如果还是积攒到一批才出现,再看一下上游应用是否调用flush,以及系统TCP缓冲区是否有异常。

本地模型通过SSE推送token时Nginx缓冲导致实时性差的问题关闭方法

验证修改是否生效

配置修改后,建议用curl的-N参数关闭缓冲直连测试,例如curl -N http://nginx地址/api/sse,观察每批token是否在打印时间上明显提前。同时再次检查响应头,确认没有X-Accel-Buffering: yes,且Nginx没有添加额外的缓冲标志。如果条件允许,可以在Nginx配置中临时添加error_log的调试级别,查看proxy缓冲是否被禁用。若验证延迟仍然存在,则需要排查应用层是否在发送数据时调用了flush,或者是否被操作系统的TCP缓冲区所影响。

风险边界与回滚

关闭proxy_buffering本质上是让Nginx不再用磁盘或内存暂存响应,而是直接将后端数据流式转发给客户端。这会使得每个SSE连接都占用后端的一个处理线程,且连接持续时间较长。如果客户端断开,Nginx和后端连接状态需要及时清理,否则可能出现连接残留。在高并发场景下,关闭缓冲可能超出Nginx的worker连接数或后端的并发限制,建议在独立location或子域中仅对SSE接口关闭缓冲,避免影响静态文件或其他普通接口的原有缓冲策略。

回滚方案很简单:把配置里的proxy_buffering off改回on或直接移除,然后reload。如果没有备份配置文件,改前先cp一份。另外,如果上游使用了gzip压缩,Nginx可能在压缩开始前等待整个响应,这种压缩和缓冲叠加的情况同样会拖慢SSE,必要时可以关闭gzip或对SSE接口单独禁用gzip。