大模型流式输出配置：SSE 接口设置与常见超时排查
流式输出能让大模型边生成边返回内容，用户不用等到全部生成完才看到结果。
如果你正在自建或代理大模型服务，需要配置流式输出，核心就是让后端以 text/event-stream 格式持续推送数据，并确保中间的 Nginx 等代理不缓冲、不超时。
下面按准备、配置、避坑、验证的顺序说明，适用于 Linux 服务器 + Nginx + 常见后端框架的环境。
先确认你的服务是否支持流式接口
不是所有大模型 API 都默认开启流式。
以 OpenAI 兼容接口为例，请求体里需要带 stream: true。
你可以先用 curl 直接测试后端服务，绕过 Nginx，确认流式本身是否正常：
curl -N -X POST http://127.0.0.1:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"your-model","messages":[{"role":"user","content":"你好"}],"stream":true}'如果终端里逐字或逐段出现 data: {...} 行，说明后端流式正常，问题可能出在代理层。
如果一次性返回全部内容，先检查后端代码是否真的用了流式生成器。
配置 Nginx 反向代理支持流式输出
Nginx 默认会缓冲上游响应，导致流式数据被攒着一起发。
需要在对应的 location 块中关闭缓冲和缓存，并适当延长超时时间。
编辑站点配置文件，通常位于 /etc/nginx/conf.d/ 或 /etc/nginx/sites-available/：
location /v1/ {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Connection '';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# 关闭缓冲，让数据即时转发
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding on;
# 延长读超时，避免长回答被切断
proxy_read_timeout 300s;
proxy_send_timeout 300s;
}保存后执行 nginx -t 检查语法，再 nginx -s reload 重载。
注意 proxy_buffering off 是关键，少了这一项前端很可能还是“一次性蹦出来”。
后端返回头与数据格式要点
流式响应需要正确的 Content-Type 和逐条发送。
以 Python FastAPI 为例，核心是返回 StreamingResponse 并设置 media_type="text/event-stream"：
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
app = FastAPI()
def event_generator():
for token in ["你", "好", "，", "世界"]:
yield f"data: {token}\n\n"
yield "data: [DONE]\n\n"
@app.post("/v1/chat/completions")
async def chat():
return StreamingResponse(event_generator(), media_type="text/event-stream")每条消息以 data: 开头，以两个换行结束，这是 SSE 协议的基本要求。
如果前端收不到增量，先检查返回体里有没有多余的空行或错误的换行符。
常见故障与避坑清单
流式配置出错时，现象通常很固定，可以按下面顺序排查：
- 前端一直转圈，最后一次性显示全部内容：优先检查 Nginx 是否加了
proxy_buffering off，以及后端是否真的逐条yield。 - 回答到一半断开：查看 Nginx 的
proxy_read_timeout是否过短，同时检查后端生成逻辑是否有超时限制。 - 浏览器控制台报 CORS 错误：流式接口同样需要正确设置跨域头，在 Nginx 或后端添加
Access-Control-Allow-Origin。 - 使用 CDN 后流式失效：部分 CDN 会缓冲响应，需要确认 CDN 是否支持 SSE 或关闭缓冲。
- 修改配置后不生效：执行
nginx -t和nginx -s reload后，再用curl -N测试，避免只改文件未重载。
验证流式输出是否真正生效
配置完成后，不要只看页面效果。
用 curl 带 -N 参数请求经过 Nginx 的地址，观察输出节奏：
curl -N -X POST https://你的域名/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"your-model","messages":[{"role":"user","content":"讲个短故事"}],"stream":true}'如果终端里内容逐段出现，而不是等好几秒后一次性打印，说明代理层没有缓冲，流式配置基本正确。
再打开浏览器开发者工具的 Network 面板，查看该请求的 Response 是否持续有数据到达，也能辅助判断。
流式输出配置并不复杂，关键是把后端生成、代理转发、前端接收三个环节的缓冲和超时都对齐。
按本文步骤操作后，如果仍有异常，优先回看 Nginx 的 proxy_buffering 和超时设置，这两个位置最容易遗漏。
