大模型应用开发 / 系统课时
处理流式响应
处理流式响应
学习目标
完成本课后,你将能够:
- 理解 Ollama 原生 API 的 NDJSON 流式格式
- 逐行解析内容并识别最终完成块
- 处理空行、错误行、超时和用户取消
- 在界面中正确拼接文本与统计信息
为什么使用流式响应
模型可能需要较长时间完成回答。流式响应会在生成过程中持续发送数据块,让用户更早看到内容。它改善的是交互体验,不会减少模型的计算量。
Ollama 原生 API 的流式数据通常是 NDJSON:每一行是一个独立 JSON 对象,而不是一个外层 JSON 数组。
观察原始流
执行:
bash
curl --no-buffer http://localhost:11434/api/generate -H "Content-Type: application/json" -d '{
"model": "gemma3:1b",
"prompt": "用三点说明流式响应。",
"stream": true
}'预期输出结构:
text
{"model":"gemma3:1b","response":"<CHUNK>","done":false}
{"model":"gemma3:1b","response":"<CHUNK>","done":false}
...
{"model":"gemma3:1b","response":"","done":true,"total_duration":<NANOSECONDS>,...}数据块边界不等于单词或句子边界,客户端必须按顺序拼接。
Python 流式解析
保存为 stream_generate.py:
python
import json
import sys
import urllib.error
import urllib.request
URL = "http://localhost:11434/api/generate"
payload = {
"model": "gemma3:1b",
"prompt": "用四个要点说明为什么要解析结束块。",
"stream": True,
}
request = urllib.request.Request(
URL,
data=json.dumps(payload).encode("utf-8"),
headers={"Content-Type": "application/json"},
)
try:
with urllib.request.urlopen(request, timeout=300) as response:
final_record = None
for raw_line in response:
line = raw_line.decode("utf-8").strip()
if not line:
continue
record = json.loads(line)
chunk = record.get("response", "")
if chunk:
print(chunk, end="", flush=True)
if record.get("done"):
final_record = record
break
print()
if final_record is None:
raise RuntimeError("连接结束但没有收到 done=true")
print(f"output_tokens={final_record.get('eval_count', 0)}")
except json.JSONDecodeError as exc:
raise SystemExit(f"收到无效 NDJSON: {exc}") from exc
except urllib.error.URLError as exc:
raise SystemExit(f"请求失败: {exc}") from exc
except KeyboardInterrupt:
print("\n用户取消请求", file=sys.stderr)运行:
bash
python stream_generate.py预期输出结构:
text
<INCREMENTAL_MODEL_RESPONSE>
output_tokens=<COUNT>结束块的重要性
最终块通常包含:
done: true- 停止原因
- 总耗时
- 输入和输出 Token 计数
- 加载与评估耗时
如果客户端只拼接文本,不读取最终块,就会丢失性能和结束状态,也无法区分正常结束与连接中断。
取消请求
用户取消时,客户端应关闭 HTTP 响应或中止请求。需要同时处理:
- 界面停止追加内容
- 释放客户端连接
- 标记回答为未完成
- 不把残缺回答当作完整助手消息
- 记录取消时间和已生成长度
服务端是否立即停止计算取决于连接关闭的传播和运行状态,不能仅凭按钮状态判断资源已释放。
代理与缓冲
反向代理如果启用响应缓冲,可能把多个数据块积累后一次发送,导致“服务端在流式生成,但前端长时间不显示”。Nginx 常见配置需要:
nginx
proxy_buffering off;
proxy_read_timeout 600s;配置片段必须结合实际代理文件、TLS 和访问控制使用,并在后续部署章节完整讲解。
前端拼接原则
- 按到达顺序追加文本。
- 不假设每个块包含完整 Unicode 单词或 Markdown 节点。
- 渲染 Markdown 时控制刷新频率,避免每个字符触发重排。
- 最终块到达后再标记回答完成。
- 解析错误时保留已接收内容,但标记为失败或中断。
- 工具调用和思考内容应按对应字段单独处理。
本课练习
练习 1:保存流式全文
任务目标:同时展示和保存回答。输入或初始条件:使用 Python 流式示例。实现要求:边打印边追加到字符串。验收条件:最终字符串与屏幕拼接内容一致。
练习 2:模拟异常行
任务目标:增强 NDJSON 容错。输入或初始条件:在测试数据中插入空行和无效 JSON。实现要求:空行跳过,无效行报告明确位置。验收条件:不会静默把错误当作正常完成。
练习 3:实现取消状态
任务目标:正确处理用户中止。输入或初始条件:一个持续时间较长的请求。实现要求:捕获取消并标记未完成。验收条件:残缺内容不会加入正式会话历史。
按自己的节奏,确认真正理解。