logo

大模型流式输出接入:SSE解析与断流处理

作者:问题终结者2026.11.17 03:48浏览量:1

简介:流式输出能让用户在模型生成时就看到文字,改善等待体验。本文以 Grok 4.7 为例,讲解如何用 curl 验证 stream 开关,用 Python 和前端 fetch 按行解析 SSE,并处理 [DONE] 缺失、半截 JSON、超时与重试。读完可以搭出一套能上线的最小流式对话链路。

一、流式输出改变了什么

很多开发者以为开启 stream: true 后,模型生成速度会变快。实际上,整段回答的生成时间通常不会明显缩短。流式输出真正改变的是首字等待时间和用户的感知延迟。

非流式调用时,接口会等整段内容生成完成后一次性返回。对于长回答、代码生成、文档解析这类任务,用户可能等几十秒却看不到任何输出,于是会误以为系统卡死,进而刷新页面或重复提交。重复调用不仅增加响应时间,还会产生额外费用。

流式输出通过 SSE(Server-Sent Events)持续返回多个 chunk。每个 chunk 通常只包含一小段文本,前端收到后即可渲染。用户看到文字不断出现,就能判断系统正在工作。

zeekeAI 提供的接口通常采用 OpenAI 兼容格式。切换到 Grok 4.7 时,一般只需要修改 model 字段,请求结构和解析逻辑可以保持不变。具体的模型名称和地址以平台文档为准。

二、先用 curl 验证三件事

在写 Python 或前端代码之前,建议先用 curl 确认三件事:

  1. API Key 是否有效;
  2. 网络是否通畅;
  3. 流式输出是否真正开启。

先确认基础地址。OpenAI 兼容接口的路径通常是 /v1/chat/completions,所以 BASE_URL 是否包含 /v1 要以平台文档为准。下面的示例假设地址已包含 /v1:

  1. export ZEEKEAI_BASE_URL="https://<平台提供的域名>/v1"
  2. export ZEEKEAI_API_KEY="你的 API Key"
  3. curl -N -s "$ZEEKEAI_BASE_URL/chat/completions" \
  4. -H "Authorization: Bearer $ZEEKEAI_API_KEY" \
  5. -H "Content-Type: application/json" \
  6. -d '{
  7. "model": "grok-4.7",
  8. "messages": [
  9. {"role": "user", "content": "用三句话解释什么是流式输出"}
  10. ],
  11. "stream": true,
  12. "max_tokens": 300
  13. }'

-N 的作用是关闭 curl 的输出缓冲。如果去掉它,数据可能先积攒在缓冲区里,终端看起来像非流式调用,一次性输出全部内容。

正常返回是一系列以 data: 开头的行,类似下面这样:

  1. data: {"choices":[{"index":0,"delta":{"content":"流式输出"}}]}
  2. data: {"choices":[{"index":0,"delta":{"content":"是一种"}}]}
  3. data: [DONE]

SSE 事件之间通常用空行分隔,解析时要跳过空行。data: [DONE] 表示本次流式输出结束,业务代码必须识别这个标记,否则可能一直等待。另外,部分兼容接口会在末尾返回 choices 为空数组的块,例如携带用量统计的块。代码需要先判断数组是否为空,再取值。

三、Python 按行消费流式响应

Python 中可以用 requests 或 httpx 发起流式请求。核心做法是不一次性读取完整响应,而是按行读取,并逐行解析 data: 后面的 JSON。

  1. import json
  2. import requests
  3. BASE_URL = "https://<平台提供的域名>/v1"
  4. API_KEY = "从环境变量读取" # 示例中的占位,实际应使用 os.environ 读取
  5. def stream_chat(prompt: str):
  6. url = f"{BASE_URL}/chat/completions"
  7. headers = {
  8. "Authorization": f"Bearer {API_KEY}",
  9. "Content-Type": "application/json",
  10. }
  11. payload = {
  12. "model": "grok-4.7",
  13. "messages": [{"role": "user", "content": prompt}],
  14. "stream": True,
  15. "max_tokens": 500,
  16. }
  17. # timeout=(连接超时, 读取超时)
  18. with requests.post(
  19. url,
  20. headers=headers,
  21. json=payload,
  22. stream=True,
  23. timeout=(5, 60),
  24. ) as resp:
  25. resp.raise_for_status()
  26. for raw_line in resp.iter_lines(decode_unicode=True):
  27. if not raw_line or not raw_line.startswith("data:"):
  28. continue
  29. data = raw_line[5:].strip()
  30. if data == "[DONE]":
  31. break
  32. try:
  33. obj = json.loads(data)
  34. except json.JSONDecodeError:
  35. # 生产环境应记录原始内容,便于排查
  36. continue
  37. choices = obj.get("choices") or []
  38. if not choices:
  39. continue
  40. delta = choices[0].get("delta", {}).get("content", "")
  41. if delta:
  42. print(delta, end="", flush=True)
  43. if __name__ == "__main__":
  44. stream_chat("请解释什么是 SSE")

这段代码有几个要点:

  • stream=True 必须设置,否则 requests 会先下载完整响应再返回。
  • OpenAI 兼容响应中,choices 是数组,取内容时要使用 choices[0]。
  • timeout=(5, 60) 中,第一个值是连接超时,第二个值是读取超时。requests 的读取超时指的是两次数据读取之间的最长等待,而不是整个请求的总时长。因此它在流式场景中相当于空闲超时。如果服务端迟迟不发送任何数据,这个值也会限制等待首包的时间。若希望单独限制首包时间,需要在业务层计时:发起请求后启动计时器,收到第一个有效 chunk 后取消。
  • 必须判断 [DONE],否则会把结束标记当成 JSON 去解析。
  • 对 JSONDecodeError 做兜底,避免半截数据导致程序崩溃。

四、前端用 fetch 和 ReadableStream 消费

前端消费流式接口时,不建议直接使用 EventSource。它主要面向 GET 请求,而大模型对话接口通常需要 POST、JSON Body 和 Authorization 请求头。fetch 配合 ReadableStream 可以满足这些需求。

下面的示例中,appendToUI 由业务侧提供,这里给出一个最小实现:

  1. function appendToUI(text) {
  2. document.getElementById("output").textContent += text;
  3. }
  4. async function streamChat(prompt) {
  5. const response = await fetch("https://<平台提供的域名>/v1/chat/completions", {
  6. method: "POST",
  7. headers: {
  8. "Authorization": "Bearer " + apiKey,
  9. "Content-Type": "application/json",
  10. },
  11. body: JSON.stringify({
  12. model: "grok-4.7",
  13. messages: [{ role: "user", content: prompt }],
  14. stream: true,
  15. max_tokens: 500,
  16. }),
  17. });
  18. if (!response.ok) {
  19. throw new Error(`HTTP error: ${response.status}`);
  20. }
  21. const reader = response.body.getReader();
  22. const decoder = new TextDecoder();
  23. let buffer = "";
  24. function handleLine(line) {
  25. const trimmed = line.trim();
  26. if (!trimmed.startsWith("data:")) return false;
  27. const data = trimmed.slice(5).trim();
  28. if (data === "[DONE]") return true;
  29. try {
  30. const obj = JSON.parse(data);
  31. const delta = obj.choices?.[0]?.delta?.content || "";
  32. if (delta) appendToUI(delta);
  33. } catch (err) {
  34. console.warn("解析流式数据失败", err, data);
  35. }
  36. return false;
  37. }
  38. while (true) {
  39. const { done, value } = await reader.read();
  40. if (done) break;
  41. buffer += decoder.decode(value, { stream: true });
  42. const lines = buffer.split("\n");
  43. buffer = lines.pop();
  44. for (const line of lines) {
  45. if (handleLine(line)) return;
  46. }
  47. }
  48. // 流结束后,处理缓冲区里残留的最后一行
  49. buffer += decoder.decode();
  50. if (buffer) handleLine(buffer);
  51. }

前端实现中最容易出错的是缓冲区。网络返回的字节流不一定正好按完整行切分,一次 reader.read() 可能只拿到半行。因此要保留最后一段不完整的内容,等下一次读取后再拼接。循环结束后还要处理残留内容,否则最后一行可能丢失。

这段代码适合演示和内部调试。正式上线时,不应把 API Key 写在前端代码中,任何访问页面的人都能看到它。更稳妥的做法是由自己的后端代理请求,把 Key 保存在服务端环境变量中,前端只与自己的后端通信。

五、断流、半截 JSON 与重试

流式输出的难点在于收尾,而不是开启。生产环境至少要处理以下三类问题。

1. 没有收到 [DONE]

连接正常关闭但没有收到 data: [DONE],说明流可能被中途截断。此时不能简单认为生成成功。可以根据业务场景决定如何处理:

  • 保留已经显示的内容;
  • 提示用户“内容生成中断”,并提供重试按钮;
  • 记录请求 ID、模型名、耗时和错误信息;
  • 对已产生的 token 用量做记录,因为中断的请求也可能被计费。

2. 半截 JSON

网络异常、代理截断或客户端缓冲都可能让某一行 JSON 不完整。处理原则如下:

  • 不要把整个流作为一个 JSON 解析;
  • 按行解析,并对每一行单独捕获异常;
  • 对无法解析的内容保存原始文本,方便排查;
  • 如果业务允许,可以忽略单个坏块,继续处理后续数据。

3. 超时与重试

流式请求的持续时间可能较长,超时策略需要分层设置:

  • 连接超时:约 5 秒;
  • 读取超时:根据最大输出长度和业务容忍度设置,同时作为空闲超时使用;
  • 首包时间:如果长时间没有收到第一个有效 chunk,应告警或触发重试。

重试需要特别谨慎。大模型生成具有随机性,重试会重新生成内容,并再次计费。建议遵循以下规则:

  • 只有在尚未向用户展示任何内容时才自动重试;
  • 已经展示过部分内容的请求,交给用户决定是否重新生成;
  • 使用指数退避,并限制最大次数,例如最多重试 2 到 3 次;
  • 4xx 类错误(如 Key 无效、参数错误)不要重试,直接修正请求;
  • 为每次请求生成唯一的请求 ID,写入日志,便于对账和排查重复扣费。

六、上线前的检查清单

  • 请求体包含 stream: true;
  • 基础地址已按平台文档确认是否包含 /v1;
  • 按行解析 SSE,并跳过空行;
  • 解析前检查 choices 是否为非空数组,取值使用 choices[0];
  • 正确识别 data: [DONE] 并结束读取;
  • 流结束后处理缓冲区残留内容;
  • 对每一行的 JSON 解析单独捕获异常;
  • 设置连接超时、读取超时,并监控首包时间;
  • 断流后保留已生成内容,并给出明确提示;
  • 重试只在安全条件下进行,并设置最大次数;
  • API Key 不出现在前端代码或日志中;
  • 记录请求 ID、模型名、耗时、token 用量和错误信息;
  • 限制 max_tokens,控制成本和时延;
  • 对重复提交做防抖处理。

七、选型与成本控制

流式输出解决的是体验问题。真正影响成本和稳定性的,仍然是模型选型、输出长度和调用策略。

  1. 选择合适的模型。 选型时可以从以下维度比较:任务类型(如代码、摘要、分类、长文写作)、上下文长度是否足够、首 token 时延、单价以及输出速度。分类、摘要、简单问答等任务不一定需要旗舰模型,可以用较轻量的模型先做测试。

  2. 控制输出长度。 如果业务只需要简短回答,应在 prompt 中明确长度要求,并设置 max_tokens 作为上限。

  3. 精简结构化输出。 要求模型返回 JSON 时,字段名尽量简短,减少嵌套层级,可以降低生成的 token 数量。

  4. 关闭不需要的附加能力。 如果场景不需要联网检索或其他增强功能,应关闭对应选项,减少额外耗时和费用。

  5. 建立监控指标。 建议持续观察首 token 时延、chunk 间隔、每秒输出 token 数、错误率和平均响应长度。这些数据比“是否流式”更能反映真实体验。

结语

在 zeekeAI 上接入 Grok 4.7 的流式输出,核心是一次围绕用户体验的工程改造。stream: true 只是起点,决定稳定性的是 SSE 按行解析、[DONE] 收尾、残留内容处理、断流提示、超时设置和受控的重试。

建议按以下顺序推进:先用 curl 确认 Key、地址和流式开关;再用 Python 或前端

发表评论

活动