大模型应用开发 / 系统课时

处理流式响应

处理流式响应

学习目标

完成本课后,你将能够:

  • 理解 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:实现取消状态

任务目标:正确处理用户中止。输入或初始条件:一个持续时间较长的请求。实现要求:捕获取消并标记未完成。验收条件:残缺内容不会加入正式会话历史。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理流式响应

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通