第 6 章:流式响应与 SSE
普通请求是"等全部算完再一次性返回",流式是"算出一个字就发一个字"。大模型之所以能像 ChatGPT 那样边想边吐,靠的就是后者。
学习目标
- 说清流式响应解决的到底是什么问题(不是"更快",是"更早看到")
- 看懂 SSE 报文格式,知道
data:、空行、[DONE]各自的作用 - 会用 Python 边收边处理,把字实时打印出来
- 知道流式场景下超时、断线、编码该怎么处理
6.1 真正的痛点:首字延迟
大模型生成 500 个字要 8 秒。如果等全部生成完再返回,用户面对的是 8 秒白屏——多数人会以为"卡死了",直接刷新或关掉。
流式的价值不是把 8 秒变短,而是把"第一次看到内容"从 8 秒提前到 0.3 秒:
同样的 8 秒总耗时,体验完全不同。这就是所有大模型产品都默认开流式的原因。
6.2 流式在协议层是什么
普通响应靠 Content-Length 告诉客户端"体有多长",收满就结束。流式响应没有固定的长度,改成"一小块一小块地送",块与块之间由格式约定分隔。
大模型几乎都用 SSE(Server-Sent Events,服务器发送事件):
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive关键在 Content-Type: text/event-stream。客户端看到它,就知道"别等收满,来一块处理一块"。
SSE 的报文格式
data: {"choices":[{"delta":{"content":"你"}}]}
data: {"choices":[{"delta":{"content":"好"}}]}
data: [DONE]规则很简单:
| 组成 | 含义 |
|---|---|
data: | 一条数据,冒号后有一个空格 |
| 空行 | 一条事件的结束标记,必须两个换行 |
event: | 可选,事件类型(如 error) |
id: | 可选,事件编号,断线重连时用 |
retry: | 可选,建议客户端重连等待多少毫秒 |
[DONE] | 大模型约定的"结束"标记,不是 SSE 标准 |
一条事件可以由多行 data: 组成,客户端拼接后用 \n 连接。大模型通常一行一条,简单。
为什么不用 WebSocket:SSE 是"服务器单向推",基于普通 HTTP,不需要协议升级,实现和穿透代理都更简单。大模型的输出正好是单向的,用不上双向通道。
6.3 Python 逐行读
读到一块就处理一块,处理完再读下一块——整个过程是一条串行的流:
requests 默认会把响应体全部收完再返回。要流式处理,必须加 stream=True,然后用 iter_lines() 边收边读:
import json
import requests
payload = {
"model": "gpt-4o",
"messages": [{"role": "user", "content": "用三句话介绍 HTTP"}],
"stream": True,
}
with requests.post(
"https://api.example.com/v1/chat/completions",
json=payload,
headers={"Authorization": "Bearer sk-xxx"},
stream=True,
timeout=(5, 120), # 读取超时要留够,流式可能持续很久
) as resp:
resp.raise_for_status()
resp.encoding = "utf-8" # 显式指定,避免编码猜测出错
for line in resp.iter_lines(decode_unicode=True):
if not line:
continue # 空行是事件分隔符,跳过
if not line.startswith("data: "):
continue # 忽略注释行(有些服务会发 ": ping")
data = line[len("data: "):]
if data == "[DONE]":
break
chunk = json.loads(data)
delta = chunk["choices"][0]["delta"].get("content")
if delta:
print(delta, end="", flush=True)几个必须知道的细节:
| 细节 | 为什么 |
|---|---|
stream=True | 不加它,iter_lines 拿到的是一次性收完的体 |
| 跳过空行 | 空行是事件分隔,不是数据 |
跳过非 data: 行 | 有些服务会发 : keep-alive 注释 |
显式 encoding="utf-8" | 中文跨块时,自动猜测可能切坏字符 |
flush=True | 不刷新缓冲区,输出会攒着一起显示 |
| 读取超时设大 | 流式总时长可能到分钟级,不能用普通接口的 10 秒 |
httpx 版本
import httpx
with httpx.stream("POST", url, json=payload, headers=headers, timeout=120) as r:
r.raise_for_status()
for line in r.iter_lines():
if line.startswith("data: "):
...httpx.iter_lines() 默认返回 str,编码由它处理,用起来比 requests 省心一点。
6.4 增量字段:delta 不是 message
普通响应里,完整内容在 choices[0].message.content。流式响应里,每个块只有"新增的那几个字",放在 choices[0].delta.content:
{"choices":[{"delta":{"content":"你"},"index":0}]}所以:
delta可能没有content字段:第一个块通常只带role,最后一个块可能只带finish_reason;- 取值一定要
.get("content"),不能直接["content"]; - 结束的标志可能是
[DONE],也可能是一个finish_reason: "stop"的块,两者都要处理。
一个更稳的解析:
chunk = json.loads(data)
choice = chunk.get("choices", [{}])[0]
delta = choice.get("delta") or {}
content = delta.get("content")
finish = choice.get("finish_reason")
if content:
print(content, end="", flush=True)
if finish:
break6.5 流式场景的三个坑
坑一:超时设成普通接口的值
流式响应可能持续 1–2 分钟。读取超时设 10 秒,会在生成到一半时报 ReadTimeout。正确做法:读取超时设到"单块之间最长间隔"的容忍值,通常 60–120 秒。
坑二:中间层缓冲
反向代理和 CDN 默认会缓冲响应,导致"服务端在流,客户端收不到"。需要在代理层关掉缓冲(Nginx 的 proxy_buffering off,X-Accel-Buffering: no)。自建服务时容易踩,用云厂商的 API 通常已经处理好。
坑三:断线后从头重来
流到一半断了,如果没有记录"收到哪了",只能重新请求,用户会看到内容重复。SSE 协议本身支持 Last-Event-ID 续传,但多数大模型 API 不支持——实务做法是把已收到的内容存下来,重连后让模型"接着写",或者直接提示重试。
6.6 和后面课程的关系
这门课到这里就结束了,但它直接决定你后面几门课的上手速度:
| 后续课程 | 用到的内容 |
|---|---|
| Lv2《大模型 API 调用》 | 第 4 章的 requests、第 5 章的 Key 管理、第 6 章的流式解析 |
| Lv2《结构化输出与 Function Calling》 | 第 3 章的 JSON、第 4 章的状态码与重试 |
| Lv3《FastAPI 实战》 | 第 2 章的方法语义、第 6 章的 SSE 转发 |
| Lv4《AI Agent 前端开发》 | 第 6 章:浏览器端接收 SSE |
一句话总结这门课:HTTP 是"怎么把话说出去、怎么听懂回话",JSON 是"话的语法",SSE 是"边说边听"。
本章小结
| 要点 | 说明 |
|---|---|
| 流式解决首字延迟 | 总耗时不变,第一次看到内容从 8s 降到 0.3s |
| SSE 的关键头 | Content-Type: text/event-stream |
| 事件格式 | data: ... + 空行分隔,[DONE] 结束 |
| 逐行读 | stream=True + iter_lines() |
| 显式 UTF-8 | 避免中文跨块被切坏 |
delta 而非 message | 每个块只有增量,字段可能缺失 |
| 读取超时要大 | 流式可能持续分钟级 |
| 代理缓冲 | 会导致"服务端在流、客户端不动" |
| 断线代价 | 多数 API 不支持续传,需自己保存已收内容 |
课程到此结束
下一步建议直接进 Lv2 的《大模型 API 调用》,把那门课的"第一次调用"当成这门课的练习:用第 4 章的写法发请求,用第 5 章的方式管 Key,用第 6 章的方式把流式输出接住。
👉 返回 课程主页