第 4 章:流式输出——打字机效果是怎么来的
本章目标:让周报边生成边显示,并搞清楚「流式」快在哪、不快在哪。
开篇:几秒的空白
到第 3 章为止,每次运行周报生成器,终端都要空白几秒,然后整段周报一下子冒出来。几秒不算长,但盯着一个没反应的终端,总会怀疑它是不是卡死了。
网页版没有这个问题:你刚按下回车,字就开始一个一个往外蹦。这叫流式输出。API 也能做到,只需要一个参数。
学完这一章,你能:
- 说清流式输出改变的是什么、没改变什么
- 看懂服务器一块一块发回来的数据
- 把周报生成器改成边写边显示,同时拿到完整文本
4.1 它快在哪
先看实测。同一份记录、同一套规矩,普通调用和流式调用各跑 3 次:
| 第 1 次 | 第 2 次 | 第 3 次 | |
|---|---|---|---|
| 普通调用:看到周报 | 5.3s | 3.0s | 3.0s |
| 流式调用:第一次有动静 | 0.5s | 1.3s | 0.5s |
| 流式调用:正文开始出现 | 2.1s | 1.3s | 1.6s |
| 流式调用:写完 | 2.6s | 2.0s | 2.3s |
流式不会让模型写得更快。 总时间主要看模型在后台想了多久(第 3 章说过,每次差别很大),上表流式略快只是这几次碰巧想得少。它真正改变的是第一次反馈的时间:从「等全部写完」变成「写一块就发一块」。
对读的人来说,0.5 秒看到「思考中」、两秒左右开始看到字,和干等 3 秒,体验完全不同。
4.2 服务器到底发回了什么
用 curl 看一眼原始数据。在请求里加一个 "stream": true,再给 curl 加 -N(收到就显示,不攒着):
curl -sN https://api.deepseek.com/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-d '{"model": "deepseek-flash", "stream": true,
"messages": [{"role": "user", "content": "用一句话介绍你自己"}]}'回来的不再是一整段 JSON,而是一行一行的 data:。下面是真实返回的节选,省掉了每行重复的 id、model 等字段:
data: {"choices":[{"delta":{"role":"assistant","content":null,"reasoning_content":""}}]}
data: {"choices":[{"delta":{"content":null,"reasoning_content":"我们需要"}}]}
data: {"choices":[{"delta":{"content":null,"reasoning_content":"回答"}}]}
……(推理片段,这次一共 72 块)
data: {"choices":[{"delta":{"content":"。","reasoning_content":null}}]}
data: {"choices":[{"delta":{"content":""},"finish_reason":"stop"}],"usage":{"prompt_tokens":34,"completion_tokens":86,"total_tokens":120,…}}
data: [DONE]能看出三件事:
- 每块只带一小段,放在
delta(增量)里,不是message - 先来推理,后来正文:前面的块只有
reasoning_content,后面的块才有content - 最后一块带着
finish_reason和usage,然后是一行data: [DONE]表示结束
这种「一行一个 data:」的格式叫 SSE(Server-Sent Events),是网页版打字机效果背后的同一套东西。
4.3 周报生成器 v4:边写边显示
SDK 替你解析好了每一块。加上 stream=True 之后,create() 返回的不再是一个结果,而是一个可以 for 循环的流:
stream = client.chat.completions.create(
model="deepseek-flash",
messages=[{"role": "system", "content": SYSTEM}, {"role": "user", "content": notes}],
max_tokens=4000,
stream=True, # 打开流式
)
parts = []
thinking_shown = False
for chunk in stream:
if not chunk.choices:
continue
delta = chunk.choices[0].delta
if getattr(delta, "reasoning_content", None) and not thinking_shown:
print("(思考中…)", flush=True) # 推理阶段只提示一次
thinking_shown = True
if delta.content:
print(delta.content, end="", flush=True) # 正文来一块打一块
parts.append(delta.content)
if chunk.choices[0].finish_reason not in (None, "stop"):
raise RuntimeError(f"周报没写完:finish_reason={chunk.choices[0].finish_reason}")
report = "".join(parts) # 拼回完整周报,后面可以存文件SYSTEM 和 notes 与第 3 章相同。运行后,终端先出现一行「(思考中…)」,接着周报一行一行地长出来。最后终端里的样子:
(思考中…)
【本周完成】
- 处理登录页偶发500,将Redis连接池调大到50
- 与产品对齐月报导出需求,需支持Excel
- Review小王PR,提了3条意见
- 参加周五下午周会
【进行中】
- 月报导出已完成一半,Excel样式还没调
- 线上再次出现500,日志显示超时,仍在排查
【下周计划】
- 继续排查线上500超时问题
- 继续月报导出开发,调整Excel样式为什么不把推理内容也打出来
可以打,用法和 content 一样,读 delta.reasoning_content 就行。但推理是模型的草稿,经常是英文、来回推敲,对看周报的人是噪音。这里只给一个「思考中」的提示,让人知道它没卡住。
踩坑:流式的三个小细节
- 忘了
flush=True:Python 默认攒到换行才输出,字会一行一行跳出来,而不是一个字一个字 - 忘了自己拼文本:流式没有完整的
message.content,想存文件,就得像上面那样把每块content收进parts finish_reason和usage在最后一块:中间每一块的finish_reason都是None。DeepSeek 会自动在最后一块附上usage;有的服务商(比如 OpenAI)要额外传stream_options={"include_usage": True}才会给
4.4 什么时候不用流式
流式是给人看的。如果结果是给程序接着用的(比如生成完直接写进文件、发进群里,中间没人盯着看),普通调用更简单:一个返回值,不用拼,不用管块。
周报生成器两种场景都有:你自己在终端跑,用流式;以后每周五定时自动跑,用普通调用。第 8 章会把这做成一个开关。
试一试
- [ ] 把 4.2 的 curl 跑一遍,数数推理片段和正文片段各有多少块
- [ ] 去掉
flush=True,对比一下显示效果 - [ ] 把推理内容也打出来(换个颜色或加个前缀),看看它是怎么理解你的模板的
本章小结
| 要点 | 说明 |
|---|---|
| 流式改变了什么 | 第一次反馈从几秒提前到 0.5 秒左右;总时间基本不变 |
| 怎么开 | stream=True,返回值变成可以 for 循环的流 |
| 每一块 | 内容在 delta 里;先 reasoning_content 后 content |
| 最后一块 | 带 finish_reason 和 usage,之后是 data: [DONE] |
| 周报生成器 v4 | 显示「思考中」,正文逐字出现,同时拼出完整文本 |
| 什么时候不用 | 结果给程序用、没人盯着看时 |
下一章预告
每块最后都带着一个
usage:这次是 34 个输入 token、86 个输出 token。这些数字就是账单。一份周报到底花多少钱?推理那几百个看不见的 token 要不要算钱?下一章把账算清楚,并让周报生成器每次运行都打印花费。