跳到主要内容
Ed. notes

06 延迟与流式:首 token 之前的空白

长文 · 2026-11-17 · 合集第 7 / 10 篇

  • SSE
  • 流式
  • 性能
第 7 / 10 篇 · 查看全部章节 → 当前: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 自己决定「这次需不需要检索」。