06 延迟与流式:首 token 之前的空白
一句话结论
用户感知的「快」几乎完全由首 token 之前的时间决定。优化它有两个方向:缩短真实等待(裁剪历史、减少串行调用),或者用真实的阶段反馈填满它。不要做假进度条,也不要在流开始之后才想返回错误码。
它解决什么问题
一个能流式输出的助手,仍然可能「感觉很慢」:
- 点发送后一两秒没有任何反馈;
- 模型卡住时,用户要等满 60 秒才看到错误;
- 为了加一个「是否检索」的判断,所有正常问题都慢了几百毫秒;
- 反向代理开了缓冲,流式变成「等半天然后一次性出现」。
这些都不是模型速度问题,而是等待没有被正确设计。
首 token 时间花在哪
0ms 用户点发送
├─ 代理转发 ~1-5ms
├─ 参数校验 / 限流 ~1ms
├─ 索引就绪检查(1 次 DB) ~2ms
├─ [可选] 追问改写(LLM) +300~800ms
├─ query embedding(外部 API) +100~500ms
├─ 向量检索(Postgres) +2~10ms
├─ 分级 + 上下文选择 ~1ms
└─ LLM prefill + 首 token +300~1500ms
两个大头是 embedding 和模型 prefill。这里有一个常被忽略的因果:prompt 越长,prefill 越慢。 不只是更贵。把 12000 token 的历史压到 1500 token,首 token 可能提前几百毫秒。
感知阈值
经验分界:
| 时间 | 用户感受 | 需要什么 |
|---|---|---|
| < 100ms | 瞬时 | 无 |
| < 1s | 连贯 | 无 |
| 1~10s | 变慢但可忍 | 必须有反馈 |
| > 10s | 以为坏了 | 进度 + 取消 |
站点助手的首 token 通常落在 0.5~2 秒,正好是「必须给反馈」的区间。一句「正在查找资料…」能明显改善主观感受,而实际延迟一点没变。
SSE 为什么能边算边发
HTTP/1.1 的 chunked transfer encoding 让响应体分块发送。SSE 只是约定了一种文本格式:
event: token
data: {"text":"多阶段构建"}
规则:event: 给事件名,data: 给内容,空行表示事件结束。后端手写这个格式即可:
def _sse(event: str, data: dict[str, object]) -> str:
return f"event: {event}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n"
前端用 fetch 拿 ReadableStream,逐块读、按空行切事件。不用 WebSocket 的理由:聊天只需要单向推送,SSE 走普通 HTTP,代理、鉴权、断线语义都更简单。
一个不可逆的约束
第一个字节发出后,HTTP 状态码和响应头就固定了。 你不能再把 200 改成 503。
所以错误处理必须分两段:
| 错误发现时机 | 处理方式 |
|---|---|
| 流开始前(索引没建、模型没配、限流) | 正常 JSON + 正确状态码 |
| 流开始后(上游超时、模型崩) | error 事件,关闭流 |
这也是「索引就绪检查」要放在依赖注入里、而不是塞进流式生成的原因。检查失败时,还能返回一个体面的 503。
phase 事件:只报阶段,不报百分比
accepted → rewriting → retrieving → generating → done
yield _sse("phase", {"stage": "retrieving"})
为什么不报百分比?因为不知道模型还要多久。猜出来的进度条一旦停住,比没有更糟。
这个改动几乎零风险:前端只处理 sources / token / done / error 四种事件,未知事件会被自然忽略,所以后端可以先上,前端慢慢跟。
超时要分层
现在通常是一个总时长(例如 60 秒)。坏体验是:模型一直不吐字,用户干等一分钟。
建议拆成两层:
async with asyncio.timeout(8):
first = await anext(stream)
async with asyncio.timeout(settings.chat_timeout_seconds):
async for token in stream:
...
首 token 8 秒不出现就报错,用户能马上重试;总时长仍然兜住长回答。
我怎么试的
1. 在服务端给每个阶段打点
started = time.perf_counter()
first_token_at: float | None = None
async for mode, payload in graph.astream(state, stream_mode=["updates", "messages"]):
if mode == "messages" and first_token_at is None:
first_token_at = time.perf_counter()
日志里至少记录:
rewrite_ms、embed_ms、search_ms、first_token_ms、total_ms、sources、answer_chars
这样「首 token 慢」才能拆成「慢在 embedding、检索还是 prefill」。
2. 用 curl 看事件是否真的逐条到达
curl -N -X POST http://127.0.0.1:8000/api/chat \
-H 'content-type: application/json' \
-d '{"query":"多阶段构建解决了什么问题?","history":[],"top_k":5}'
-N 关闭 curl 自己的缓冲。如果所有事件同时出现,问题大概率在代理层;检查 X-Accel-Buffering: no 和 Cache-Control: no-cache。
3. 对比裁剪前后的 prompt 长度
在发送前记录 estimate_tokens 的估算值,分别跑「不裁剪」和「1800 字预算」两组。看首 token 的 p50 / p95,而不是单次值。
坑和限制
- 假进度条比没有更糟。 不知道进度时,只报阶段;不要编百分比。
- 代理默认会缓冲。 Nginx 需要
X-Accel-Buffering: no,Caddy 和 Nitro 转发也要确认流式透传;否则前端看到的是「一次性响应」。 - 流内错误只能用事件表达。 不要在
StreamingResponse开始后再raise HTTPException,那不会改变已经发出的状态码。 - 提前返回要结算额度。 如果在限流之后短路返回,预占的 token 不会自动释放;要么放进图里复用流式路径,要么手动
settle()。 - 不要为了「感觉快」把检索和生成并行。 生成依赖检索结果,真并行只会让模型拿到空上下文;该并行的是多路检索。
- 首 token 快不等于总时长短。 两者要分开测;一个很快开头、很慢结尾的回答,体验仍然差。
适合谁
适合已经能流式输出、但用户仍说「慢」的人。先量出首 token 的构成,再决定是裁剪 prompt、减少串行调用,还是补阶段反馈。通常不需要换模型。
下一篇讨论一个更根本的选择:要不要让 LLM 自己决定「这次需不需要检索」。