上一篇《同一个问题写了 4 遍》里,四种接入方式我都跑了一遍,但全都是 call() ------ 问完,等,然后一整段话砸下来。
那时候我没觉得有问题。直到我把这个接口给朋友试,他说了一句:
「点了发送之后,它到底是在思考,还是卡死了?」
这句话把我点醒了。用户看不到「正在发生」,就会认为「坏了」。
于是我花了一个周末把 call() 改成 stream()。原以为只是换个方法名,结果是:代码改了 20 行,配置调了 3 处,踩了 6 个坑,其中 2 个在本地完全测不出来。
一、先把「快」这件事拆开
大多数人以为流式是为了「更快」。不是。
先看两张时间线:
图 1|总耗时完全相同,差别只在「第一个字什么时候出现」
这两个请求用掉的时间一秒不差,都是 3.2 秒。 但体验差了一个数量级,原因是它们优化的是两个不同指标:
| 指标 | 含义 | 用户感受 |
|---|---|---|
| 总耗时(Latency) | 从发请求到最后一个字 | 「总算答完了」 |
| 首字延迟(TTFT,Time To First Token) | 从发请求到第一个字出现 | 「它活着」 |
call() 把 TTFT 和总耗时绑成了同一个数:3.2 秒。
stream() 把它拆开了:TTFT 0.4 秒,总耗时还是 3.2 秒。
流式不是让模型变快,是让「有反应」这件事提前发生。
模型该生成多少 token 一个没少,总时间一秒没省。
这也是为什么所有对话产品都做流式,而所有批处理任务都不做 ------ 它们优化的根本不是同一个指标。
记住这个结论,后面所有配置都是在保护它 :只要有一条链路把响应「攒住」,TTFT 立刻退化成总耗时,你写再多 stream() 也没用。
二、SSE 不是什么黑科技,就是一段纯文本
第一次听到 SSE(Server-Sent Events)我以为是某种二进制协议,要专门的 SDK。其实它简陋得有点可爱:
vbnet
HTTP/1.1 200 OK
Content-Type: text/event-stream;charset=UTF-8
data: 你
data: 好
data: 呀
就这样。一个不结束的 HTTP 响应,每隔一会儿往里写几行文本,每帧以两个换行结尾。
浏览器收到一段 data: xxx\n\n 就触发一次 onmessage。所谓「流式」,本质是服务端不关闭连接,让 HTTP 响应体持续有内容。
完整格式只有四个字段:
| 字段 | 作用 | 例子 |
|---|---|---|
data: |
实际内容,可多行 | data: 你好 |
event: |
事件名,前端用 addEventListener 接 |
event: done |
id: |
事件 id,断线重连时用来续传 | id: 12 |
retry: |
重连间隔毫秒 | retry: 3000 |
大部分场景只用 data: 就够了。
那为什么不直接用 WebSocket?
因为我只需要「服务端 → 浏览器」这一个方向。
| 方案 | 方向 | 实现成本 | 适合 |
|---|---|---|---|
| 轮询 | 客户端反复问 | 最低,但延迟高、请求多 | 状态查询(进度条) |
| SSE | 单向,服务端推 | 低,就是一个 HTTP 响应 | AI 流式输出、通知推送 |
| WebSocket | 双向 | 高,要握手、要心跳、要处理断线 | 聊天室、协同编辑 |
AI 对话的输入是一次性的(用户点发送),输出是持续的。单向就够,用 WebSocket 是杀鸡用牛刀 ------ 你还得管连接保活、心跳、重连,全是额外负担。
还有一个隐性好处:SSE 走的是普通 HTTP,你现有的鉴权、网关、日志、限流全都能复用,不用为一个 WebSocket 单独开一套。
三、Spring 里两种写法,选一个就行
Spring AI 的 stream() 返回的是 Flux<String>。问题在于:你的项目是 Spring MVC 还是 WebFlux,写法完全不同。
写法一:Spring MVC(大多数项目的实际情况)
pom.xml 里是 spring-boot-starter-web 的,用 SseEmitter:
java
@RestController
@RequestMapping("/ai")
public class ChatController {
private final ChatClient chatClient;
public ChatController(ChatClient.Builder builder) {
this.chatClient = builder.build();
}
@GetMapping(value = "/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter chat(@RequestParam String message) {
// 0L = 不超时。默认会超时,长回答会被硬生生切断
SseEmitter emitter = new SseEmitter(0L);
Flux<String> flux = chatClient.prompt()
.user(message)
.stream()
.content();
Disposable disposable = flux.subscribe(
chunk -> {
try {
emitter.send(chunk); // 自动按 data: 帧发出
} catch (IOException e) {
emitter.completeWithError(e);
}
},
emitter::completeWithError, // 出错
emitter::complete // 正常结束
);
// 客户端断开(用户关页面 / 点停止)→ 取消订阅
emitter.onTimeout(disposable::dispose);
emitter.onError(e -> disposable.dispose());
emitter.onCompletion(disposable::dispose);
return emitter;
}
}
这里有两个不起眼但致命的点:
produces = TEXT_EVENT_STREAM_VALUE不能省。 少了它,Spring 会按普通 JSON 序列化,把所有分片拼成一个字符串再返回 ------ 接口能通、内容也对,就是不分片。disposable必须存下来并在断开时dispose()。 否则用户关了页面,后端还在傻乎乎地调模型、烧你的 token。
写法二:WebFlux(项目本来就是响应式)
如果 pom.xml 里是 spring-boot-starter-webflux,一行就够:
java
@GetMapping(value = "/chat", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<String> chat(@RequestParam String message) {
return chatClient.prompt()
.user(message)
.stream()
.content();
}
没有 subscribe、不用管 Disposable,WebFlux 自己会处理背压和取消。
⚠️ 别为了写流式就把 MVC 换成 WebFlux。 两者不能混用(同时引入时 Servlet 栈优先),换过去意味着你项目里所有阻塞式代码、所有
ThreadLocal、所有 JDBC 调用都要重新审一遍。MVC 用SseEmitter完全够用,多写十行而已。
四、一次流式请求要过四道关
代码写完,本地 curl 一看,逐字输出,很开心。部署上线,整段砸下来。
因为流式请求不是「直接到你屏幕」,它要穿过四道关:

图 2|任何一关配错,表现都一样:转圈 → 最后一次性全吐出来
第 ② 关:Nginx 的缓冲(最常见的元凶)
Nginx 默认开启 proxy_buffering,它的逻辑是「攒够 4KB 或者响应结束,再转发给客户端」。对普通接口这是优化,对 SSE 是灾难 ------ 你的每帧才十几个字节,永远攒不满 4KB,于是一直憋着,直到响应结束才一次性发出去。
nginx
location /api/ai/ {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Connection '';
proxy_buffering off; # 关键:关掉缓冲
proxy_cache off;
gzip off; # 关键:gzip 也会缓冲
}
不想改 Nginx 配置(比如用的是云厂商托管的网关),可以在代码里加一个响应头,Nginx 认得它:
java
response.setHeader("X-Accel-Buffering", "no");
这一行救过我一次 ------ 生产环境的 Nginx 配置我没有权限改,加这个头就绕过去了。
第 ③ 关:produces 和超时
yaml
spring:
mvc:
async:
request-timeout: 300000 # 5 分钟,默认值往往撑不住长回答
SseEmitter 的默认超时跟着容器走(Tomcat 下通常 30 秒),一次长回答很容易超。超时的表现不是报错,是「话说一半突然停住」,特别难查。
第 ① 关:浏览器的 EventSource 有两个硬限制
EventSource 用起来最简单:
js
const es = new EventSource('/api/ai/chat?message=你好');
es.onmessage = e => appendToScreen(e.data);
但它有两个绕不过去的限制:
| 限制 | 后果 |
|---|---|
| 只能发 GET | 长 prompt 塞不进 URL |
| 不能自定义请求头 | Authorization: Bearer xxx 加不了 |
所以只要你的接口要带 token,EventSource 就直接出局。换成 fetch + 流式读取,顺便解决这两个限制。
五、6 个坑,从最常见到最阴
坑 1:fetch 读流,把半条消息当成一条
这个坑我卡了半天。fetch 的 reader.read() 返回的是任意长度的字节块 ,不是「一条完整消息」。一次 read() 可能拿到 data: 你\n\ndata: 好,也可能拿到半截 data: 你\n\ndat。
js
const resp = await fetch('/api/ai/chat?message=' + encodeURIComponent(q), {
headers: { Authorization: 'Bearer ' + token }
});
const reader = resp.body.getReader();
const decoder = new TextDecoder();
let buffer = '';
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const frames = buffer.split('\n\n');
buffer = frames.pop(); // ← 关键:最后一段可能不完整,留着下次拼
for (const frame of frames) {
const line = frame.split('\n').find(l => l.startsWith('data:'));
if (!line) continue;
appendToScreen(line.slice(5).trim());
}
}
buffer = frames.pop() 这一行不能省。 少了它,中文会被从中间切开变成乱码,而且时好时坏 ------ 因为取决于网络恰好怎么分包。
decoder.decode(value, { stream: true }) 里的 stream: true 同理,是告诉解码器「可能不完整,先别急着报错」。
坑 2:produces 漏了
现象是接口完全正常,就是不分片。一条命令验证:
bash
curl -N -i "http://localhost:8123/api/ai/chat?message=你好"
-N 关掉 curl 自己的缓冲,-i 打响应头。看两件事 :响应头里有没有 Content-Type: text/event-stream,以及输出是一行行往外冒还是停几秒后一次性刷出来。
坑 3:Nginx 缓冲 / gzip
判断方法很干脆:本地 curl 逐字、线上 curl 整段,就是网关这一层。
bash
curl -N -i "https://你的域名/api/ai/chat?message=你好"
如果响应头里 Content-Type 是对的、但输出仍是整段,基本可以确定是 proxy_buffering。
坑 4:客户端断开,服务端还在烧钱
用户在生成到一半时关掉页面,你以为结束了,实际上:
Flux还在订阅状态- 模型还在一个 token 一个 token 地生成
- 你的账单还在涨
所以要 disposable.dispose()(MVC)或依赖 WebFlux 的自动取消。
反过来这也是流式的一个隐藏优点:用户看到第三句发现答偏了,直接点停止 ------ 后面的 token 就不生成了,真金白银省下来。非流式做不到这点,你只能等它全部生成完。
坑 5:流式和结构化输出天生冲突
entity() 要求拿到的是一段完整合法的 JSON 才能反序列化。而流式给你的是一堆碎片:
kotlin
data: {"title":"恋爱
data: 建议","score":
data: 8}
碎片拼不成对象。 所以这两个能力不能同时用:
| 需求 | 做法 |
|---|---|
| 给人看 | 流式,边收边显示 |
给程序用(entity()) |
非流式,等完整 JSON |
| 都要 | 流式展示 + 前端拼完整字符串,结束后再单独调一次解析接口 |
第三条的代价是两次调用、两份 token。我的选择是:给人看的场景不返回结构化数据,给程序用的场景不做流式。 别为了「看起来高级」把两个拧在一起。
坑 6:Advisor 静默失效(这个最阴)
这个坑最值得单独说,因为它不报错。
Spring AI 的 Advisor 有两个接口:
java
public interface CallAroundAdvisor { AdvisedResponse aroundCall(...); }
public interface StreamAroundAdvisor { Flux<AdvisedResponse> aroundStream(...); }
只实现 CallAroundAdvisor 的 Advisor,在 call() 下工作正常,在 stream() 下整段逻辑根本不会执行。
我第一次写日志 Advisor 就是这样:call() 能看到日志,改 stream() 之后日志一条都没有,接口却照常返回内容。查了半小时才反应过来 ------ 少了 StreamAroundAdvisor。
java
public class MyLogAdvisor implements CallAroundAdvisor, StreamAroundAdvisor {
// 两个都要实现,否则其中一个方法下会静默跳过
}
判断口诀:只要你的应用会同时用到
call()和stream(),自定义 Advisor 就必须两个接口都实现。
流式下的日志还有个坑:aroundStream 拿到的是 Flux,直接 map 打日志会打出几百条碎片。想打完整回答,要用 MessageAggregator 把流聚合起来:
java
new MessageAggregator().aggregateAdvisedResponse(flux, this::observeAfter);
六、一个常见的错觉:前端打字机能不能替代真流式?
写完流式我又想到一个问题:如果后端实在改不动,前端拿到整段后自己逐字显示,是不是也能骗过用户?
js
// 假流式:等整段返回后,逐字显示
const text = await resp.text();
let i = 0;
const timer = setInterval(() => {
el.textContent += text[i++];
if (i >= text.length) clearInterval(timer);
}, 30);
看起来很美好,但这段代码有个前提:它必须等 await resp.text() 执行完才会开始。
也就是说,用户还是要盯着转圈等 3.2 秒。假流式优化的是「后半段」,真流式优化的是「前半段」------它救不了 TTFT。
| 真流式 | 前端打字机 | |
|---|---|---|
| 首字出现 | 0.4s(模型吐出第一个 token) | 3.2s(等全文) |
| 总耗时 | 3.2s | 3.2s |
| 后端改造 | 需要 | 不需要 |
| 省 token | 用户中断可省 | 不省,已经全生成了 |
结论:假流式不是替代品,是补充。 它只在一个场景下真有用 ------ 回放历史消息。你已经把整段存在数据库里了,展示时做成逐字效果,纯粹为了观感。
真流式解决的是「等待」,假流式解决的是「观感」,别混。
七、什么时候不该用流式
流式不是银弹,下面这些场景用了反而添乱:
| 场景 | 为什么不适合 |
|---|---|
结构化输出(entity()) |
碎片拼不成 JSON |
| 内容审核 | 要先拿到全文才能过敏感词,边流边审等于边审边发 |
| 需要后处理再返回 | 翻译、摘要、格式化,都得等全文 |
| 批量 / 离线任务 | 没人看,流式只增加复杂度 |
| 极短回答(< 20 字) | 首字优势体现不出来,反而多了一堆连接开销 |
一个简单的判断标准:有没有一个「人」在屏幕前等。 有,就流式;没有,就别流。
八、速查表(建议截图)
出问题时按这个表倒着查,比从头读代码快:
| 现象 | 最可能的原因 | 怎么修 |
|---|---|---|
| 接口返回整段,不流式 | 缺 produces = text/event-stream |
加上,curl -N 验证 |
| 本地流式、线上整段 | Nginx proxy_buffering |
proxy_buffering off 或 X-Accel-Buffering: no |
| 说完一半突然停 | SseEmitter 超时 |
new SseEmitter(0L) + spring.mvc.async.request-timeout |
| 中文偶尔乱码 | 分帧没处理半包 | buffer.split('\n\n') + frames.pop() 留残片 |
| 带了 token 就调不通 | EventSource 不支持请求头 |
换 fetch + ReadableStream |
| 用户关页面后还在扣费 | 没 dispose() |
emitter.onCompletion(disposable::dispose) |
Advisor 在 stream() 下没反应 |
只实现了 CallAroundAdvisor |
同时实现StreamAroundAdvisor |
| 日志刷屏几百条 | 在 map 里直接打印 |
用 MessageAggregator 聚合 |
九、最后
回到开头那个问题:「它到底是在思考,还是卡死了?」
流式输出解决的其实不是技术问题,是信任问题。用户需要在 0.4 秒内看到「有东西在动」,剩下 3 秒他才愿意等。
这一点想通了,你会发现很多「性能优化」都是同一个思路:优化的不是总时长,是「可感知的进展」。进度条、骨架屏、分页加载,都是这个道理。
下一篇想写 RAG 的第一次跑通:文档怎么切、向量怎么存,以及为什么我第一版问它「恋爱建议」,它回我一句「根据资料我无法回答」。
那是另一个方向的坑 ------ 这次不是「看不见」,是「看见了但答错」。