Skip to content
Lv1HTTP 与 JSON进度 6 / 6

第 6 章:流式响应与 SSE ​

普通请求是"等全部算完再一次性返回",流式是"算出一个字就发一个字"。大模型之所以能像 ChatGPT 那样边想边吐,靠的就是后者。


学习目标 ​

  • 说清流式响应解决的到底是什么问题(不是"更快",是"更早看到")
  • 看懂 SSE 报文格式,知道 data:、空行、[DONE] 各自的作用
  • 会用 Python 边收边处理,把字实时打印出来
  • 知道流式场景下超时、断线、编码该怎么处理

6.1 真正的痛点:首字延迟 ​

大模型生成 500 个字要 8 秒。如果等全部生成完再返回,用户面对的是 8 秒白屏——多数人会以为"卡死了",直接刷新或关掉。

流式的价值不是把 8 秒变短,而是把"第一次看到内容"从 8 秒提前到 0.3 秒:

普通响应:等全部生成完请求等待 8.0 秒,屏幕上没有任何内容一次性返回全文首字延迟 ≈ 8.0sSSE 流式:生成一点发一点请求你好,世界后续 token 持续到达,边生成边显示首字延迟 ≈ 0.3s

同样的 8 秒总耗时,体验完全不同。这就是所有大模型产品都默认开流式的原因。


6.2 流式在协议层是什么 ​

普通响应靠 Content-Length 告诉客户端"体有多长",收满就结束。流式响应没有固定的长度,改成"一小块一小块地送",块与块之间由格式约定分隔。

大模型几乎都用 SSE(Server-Sent Events,服务器发送事件):

http
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() 边收边读:

python
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 版本 ​

python
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:

json
{"choices":[{"delta":{"content":"你"},"index":0}]}

所以:

  • delta 可能没有 content 字段:第一个块通常只带 role,最后一个块可能只带 finish_reason;
  • 取值一定要 .get("content"),不能直接 ["content"];
  • 结束的标志可能是 [DONE],也可能是一个 finish_reason: "stop" 的块,两者都要处理。

一个更稳的解析:

python
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:
    break

6.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 章的方式把流式输出接住。

👉 返回 课程主页

本文阅读--次|全站访问--次|访客--人