Skip to content

第 4 章:流式输出——打字机效果是怎么来的 ​

本章目标:让周报边生成边显示,并搞清楚「流式」快在哪、不快在哪。

开篇:几秒的空白 ​

到第 3 章为止,每次运行周报生成器,终端都要空白几秒,然后整段周报一下子冒出来。几秒不算长,但盯着一个没反应的终端,总会怀疑它是不是卡死了。

网页版没有这个问题:你刚按下回车,字就开始一个一个往外蹦。这叫流式输出。API 也能做到,只需要一个参数。

学完这一章,你能:

  • 说清流式输出改变的是什么、没改变什么
  • 看懂服务器一块一块发回来的数据
  • 把周报生成器改成边写边显示,同时拿到完整文本

4.1 它快在哪 ​

先看实测。同一份记录、同一套规矩,普通调用和流式调用各跑 3 次:

第 1 次第 2 次第 3 次
普通调用:看到周报5.3s3.0s3.0s
流式调用:第一次有动静0.5s1.3s0.5s
流式调用:正文开始出现2.1s1.3s1.6s
流式调用:写完2.6s2.0s2.3s

普通调用前 3 秒一片空白,3 秒时整段出现;流式调用 0.5 秒开始有推理片段,2.1 秒起正文逐字出现

流式不会让模型写得更快。 总时间主要看模型在后台想了多久(第 3 章说过,每次差别很大),上表流式略快只是这几次碰巧想得少。它真正改变的是第一次反馈的时间:从「等全部写完」变成「写一块就发一块」。

对读的人来说,0.5 秒看到「思考中」、两秒左右开始看到字,和干等 3 秒,体验完全不同。


4.2 服务器到底发回了什么 ​

用 curl 看一眼原始数据。在请求里加一个 "stream": true,再给 curl 加 -N(收到就显示,不攒着):

bash
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 等字段:

text
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]

能看出三件事:

  1. 每块只带一小段,放在 delta(增量)里,不是 message
  2. 先来推理,后来正文:前面的块只有 reasoning_content,后面的块才有 content
  3. 最后一块带着 finish_reason 和 usage,然后是一行 data: [DONE] 表示结束

这种「一行一个 data:」的格式叫 SSE(Server-Sent Events),是网页版打字机效果背后的同一套东西。


4.3 周报生成器 v4:边写边显示 ​

SDK 替你解析好了每一块。加上 stream=True 之后,create() 返回的不再是一个结果,而是一个可以 for 循环的流:

python
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 章相同。运行后,终端先出现一行「(思考中…)」,接着周报一行一行地长出来。最后终端里的样子:

text
(思考中…)
【本周完成】
- 处理登录页偶发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 要不要算钱?

下一章把账算清楚,并让周报生成器每次运行都打印花费。

👉 第 5 章:Token 与计费——一份周报花多少钱

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