AI 回复为什么要转圈 3 秒才「啪」一下全出来?把流式输出拆开看,顺便踩了 6 个坑

0 阅读12分钟

上一篇《同一个问题写了 4 遍》里,四种接入方式我都跑了一遍,但全都是 call() —— 问完,等,然后一整段话砸下来。

那时候我没觉得有问题。直到我把这个接口给朋友试,他说了一句:

「点了发送之后,它到底是在思考,还是卡死了?」

这句话把我点醒了。用户看不到「正在发生」,就会认为「坏了」。

于是我花了一个周末把 call() 改成 stream()。原以为只是换个方法名,结果是:代码改了 20 行,配置调了 3 处,踩了 6 个坑,其中 2 个在本地完全测不出来。


一、先把「快」这件事拆开

大多数人以为流式是为了「更快」。不是。

先看两张时间线: fig1-时间线.png 图 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。其实它简陋得有点可爱:

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:

@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;
    }
}

这里有两个不起眼但致命的点:

  1. produces = TEXT_EVENT_STREAM_VALUE 不能省。 少了它,Spring 会按普通 JSON 序列化,把所有分片拼成一个字符串再返回 —— 接口能通、内容也对,就是不分片。
  2. disposable 必须存下来并在断开时 dispose()。 否则用户关了页面,后端还在傻乎乎地调模型、烧你的 token。

写法二:WebFlux(项目本来就是响应式)

如果 pom.xml 里是 spring-boot-starter-webflux,一行就够:

@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 一看,逐字输出,很开心。部署上线,整段砸下来。

因为流式请求不是「直接到你屏幕」,它要穿过四道关:

fig2-四道关.png

图 2|任何一关配错,表现都一样:转圈 → 最后一次性全吐出来

第 ② 关:Nginx 的缓冲(最常见的元凶)

Nginx 默认开启 proxy_buffering,它的逻辑是「攒够 4KB 或者响应结束,再转发给客户端」。对普通接口这是优化,对 SSE 是灾难 —— 你的每帧才十几个字节,永远攒不满 4KB,于是一直憋着,直到响应结束才一次性发出去。

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 认得它:

response.setHeader("X-Accel-Buffering", "no");

这一行救过我一次 —— 生产环境的 Nginx 配置我没有权限改,加这个头就绕过去了。

第 ③ 关:produces 和超时

spring:
  mvc:
    async:
      request-timeout: 300000   # 5 分钟,默认值往往撑不住长回答

SseEmitter 的默认超时跟着容器走(Tomcat 下通常 30 秒),一次长回答很容易超。超时的表现不是报错,是「话说一半突然停住」,特别难查。

第 ① 关:浏览器的 EventSource 有两个硬限制

EventSource 用起来最简单:

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。

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 漏了

现象是接口完全正常,就是不分片。一条命令验证:

curl -N -i "http://localhost:8123/api/ai/chat?message=你好"

-N 关掉 curl 自己的缓冲,-i 打响应头。看两件事:响应头里有没有 Content-Type: text/event-stream,以及输出是一行行往外冒还是停几秒后一次性刷出来。

坑 3:Nginx 缓冲 / gzip

判断方法很干脆:本地 curl 逐字、线上 curl 整段,就是网关这一层。

curl -N -i "https://你的域名/api/ai/chat?message=你好"

如果响应头里 Content-Type 是对的、但输出仍是整段,基本可以确定是 proxy_buffering。

坑 4:客户端断开,服务端还在烧钱

用户在生成到一半时关掉页面,你以为结束了,实际上:

  • Flux 还在订阅状态
  • 模型还在一个 token 一个 token 地生成
  • 你的账单还在涨

所以要 disposable.dispose()(MVC)或依赖 WebFlux 的自动取消。

反过来这也是流式的一个隐藏优点:用户看到第三句发现答偏了,直接点停止 —— 后面的 token 就不生成了,真金白银省下来。非流式做不到这点,你只能等它全部生成完。

坑 5:流式和结构化输出天生冲突

entity() 要求拿到的是一段完整合法的 JSON 才能反序列化。而流式给你的是一堆碎片:

data: {"title":"恋爱
data: 建议","score":
data: 8}

碎片拼不成对象。 所以这两个能力不能同时用:

需求做法
给人看流式,边收边显示
给程序用(entity())非流式,等完整 JSON
都要流式展示 + 前端拼完整字符串,结束后再单独调一次解析接口

第三条的代价是两次调用、两份 token。我的选择是:给人看的场景不返回结构化数据,给程序用的场景不做流式。 别为了「看起来高级」把两个拧在一起。

坑 6:Advisor 静默失效(这个最阴)

这个坑最值得单独说,因为它不报错。

Spring AI 的 Advisor 有两个接口:

public interface CallAroundAdvisor   { AdvisedResponse aroundCall(...); }
public interface StreamAroundAdvisor { Flux<AdvisedResponse> aroundStream(...); }

只实现 CallAroundAdvisor 的 Advisor,在 call() 下工作正常,在 stream() 下整段逻辑根本不会执行。

我第一次写日志 Advisor 就是这样:call() 能看到日志,改 stream() 之后日志一条都没有,接口却照常返回内容。查了半小时才反应过来 —— 少了 StreamAroundAdvisor。

public class MyLogAdvisor implements CallAroundAdvisor, StreamAroundAdvisor {
    // 两个都要实现,否则其中一个方法下会静默跳过
}

判断口诀:只要你的应用会同时用到 call() 和 stream(),自定义 Advisor 就必须两个接口都实现。

流式下的日志还有个坑:aroundStream 拿到的是 Flux,直接 map 打日志会打出几百条碎片。想打完整回答,要用 MessageAggregator 把流聚合起来:

new MessageAggregator().aggregateAdvisedResponse(flux, this::observeAfter);

六、一个常见的错觉:前端打字机能不能替代真流式?

写完流式我又想到一个问题:如果后端实在改不动,前端拿到整段后自己逐字显示,是不是也能骗过用户?

// 假流式:等整段返回后,逐字显示
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.2s3.2s
后端改造需要不需要
省 token用户中断可省不省,已经全生成了

结论:假流式不是替代品,是补充。 它只在一个场景下真有用 —— 回放历史消息。你已经把整段存在数据库里了,展示时做成逐字效果,纯粹为了观感。

真流式解决的是「等待」,假流式解决的是「观感」,别混。


七、什么时候不该用流式

流式不是银弹,下面这些场景用了反而添乱:

场景为什么不适合
结构化输出(entity())碎片拼不成 JSON
内容审核要先拿到全文才能过敏感词,边流边审等于边审边发
需要后处理再返回翻译、摘要、格式化,都得等全文
批量 / 离线任务没人看,流式只增加复杂度
极短回答(< 20 字)首字优势体现不出来,反而多了一堆连接开销

一个简单的判断标准:有没有一个「人」在屏幕前等。 有,就流式;没有,就别流。


八、速查表(建议截图)

出问题时按这个表倒着查,比从头读代码快:

现象最可能的原因怎么修
接口返回整段,不流式缺 produces = text/event-stream加上,curl -N 验证
本地流式、线上整段Nginx proxy_bufferingproxy_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 的第一次跑通:文档怎么切、向量怎么存,以及为什么我第一版问它「恋爱建议」,它回我一句「根据资料我无法回答」。

那是另一个方向的坑 —— 这次不是「看不见」,是「看见了但答错」。