大模型流式输出接入: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 确认三件事:
- API Key 是否有效;
- 网络是否通畅;
- 流式输出是否真正开启。
先确认基础地址。OpenAI 兼容接口的路径通常是 /v1/chat/completions,所以 BASE_URL 是否包含 /v1 要以平台文档为准。下面的示例假设地址已包含 /v1:
export ZEEKEAI_BASE_URL="https://<平台提供的域名>/v1"export ZEEKEAI_API_KEY="你的 API Key"curl -N -s "$ZEEKEAI_BASE_URL/chat/completions" \-H "Authorization: Bearer $ZEEKEAI_API_KEY" \-H "Content-Type: application/json" \-d '{"model": "grok-4.7","messages": [{"role": "user", "content": "用三句话解释什么是流式输出"}],"stream": true,"max_tokens": 300}'
-N 的作用是关闭 curl 的输出缓冲。如果去掉它,数据可能先积攒在缓冲区里,终端看起来像非流式调用,一次性输出全部内容。
正常返回是一系列以 data: 开头的行,类似下面这样:
data: {"choices":[{"index":0,"delta":{"content":"流式输出"}}]}data: {"choices":[{"index":0,"delta":{"content":"是一种"}}]}data: [DONE]
SSE 事件之间通常用空行分隔,解析时要跳过空行。data: [DONE] 表示本次流式输出结束,业务代码必须识别这个标记,否则可能一直等待。另外,部分兼容接口会在末尾返回 choices 为空数组的块,例如携带用量统计的块。代码需要先判断数组是否为空,再取值。
三、Python 按行消费流式响应
Python 中可以用 requests 或 httpx 发起流式请求。核心做法是不一次性读取完整响应,而是按行读取,并逐行解析 data: 后面的 JSON。
import jsonimport requestsBASE_URL = "https://<平台提供的域名>/v1"API_KEY = "从环境变量读取" # 示例中的占位,实际应使用 os.environ 读取def stream_chat(prompt: str):url = f"{BASE_URL}/chat/completions"headers = {"Authorization": f"Bearer {API_KEY}","Content-Type": "application/json",}payload = {"model": "grok-4.7","messages": [{"role": "user", "content": prompt}],"stream": True,"max_tokens": 500,}# timeout=(连接超时, 读取超时)with requests.post(url,headers=headers,json=payload,stream=True,timeout=(5, 60),) as resp:resp.raise_for_status()for raw_line in resp.iter_lines(decode_unicode=True):if not raw_line or not raw_line.startswith("data:"):continuedata = raw_line[5:].strip()if data == "[DONE]":breaktry:obj = json.loads(data)except json.JSONDecodeError:# 生产环境应记录原始内容,便于排查continuechoices = obj.get("choices") or []if not choices:continuedelta = choices[0].get("delta", {}).get("content", "")if delta:print(delta, end="", flush=True)if __name__ == "__main__":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 由业务侧提供,这里给出一个最小实现:
function appendToUI(text) {document.getElementById("output").textContent += text;}async function streamChat(prompt) {const response = await fetch("https://<平台提供的域名>/v1/chat/completions", {method: "POST",headers: {"Authorization": "Bearer " + apiKey,"Content-Type": "application/json",},body: JSON.stringify({model: "grok-4.7",messages: [{ role: "user", content: prompt }],stream: true,max_tokens: 500,}),});if (!response.ok) {throw new Error(`HTTP error: ${response.status}`);}const reader = response.body.getReader();const decoder = new TextDecoder();let buffer = "";function handleLine(line) {const trimmed = line.trim();if (!trimmed.startsWith("data:")) return false;const data = trimmed.slice(5).trim();if (data === "[DONE]") return true;try {const obj = JSON.parse(data);const delta = obj.choices?.[0]?.delta?.content || "";if (delta) appendToUI(delta);} catch (err) {console.warn("解析流式数据失败", err, data);}return false;}while (true) {const { done, value } = await reader.read();if (done) break;buffer += decoder.decode(value, { stream: true });const lines = buffer.split("\n");buffer = lines.pop();for (const line of lines) {if (handleLine(line)) return;}}// 流结束后,处理缓冲区里残留的最后一行buffer += decoder.decode();if (buffer) handleLine(buffer);}
前端实现中最容易出错的是缓冲区。网络返回的字节流不一定正好按完整行切分,一次 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,控制成本和时延; - 对重复提交做防抖处理。
七、选型与成本控制
流式输出解决的是体验问题。真正影响成本和稳定性的,仍然是模型选型、输出长度和调用策略。
选择合适的模型。 选型时可以从以下维度比较:任务类型(如代码、摘要、分类、长文写作)、上下文长度是否足够、首 token 时延、单价以及输出速度。分类、摘要、简单问答等任务不一定需要旗舰模型,可以用较轻量的模型先做测试。
控制输出长度。 如果业务只需要简短回答,应在 prompt 中明确长度要求,并设置
max_tokens作为上限。精简结构化输出。 要求模型返回 JSON 时,字段名尽量简短,减少嵌套层级,可以降低生成的 token 数量。
关闭不需要的附加能力。 如果场景不需要联网检索或其他增强功能,应关闭对应选项,减少额外耗时和费用。
建立监控指标。 建议持续观察首 token 时延、chunk 间隔、每秒输出 token 数、错误率和平均响应长度。这些数据比“是否流式”更能反映真实体验。
结语
在 zeekeAI 上接入 Grok 4.7 的流式输出,核心是一次围绕用户体验的工程改造。stream: true 只是起点,决定稳定性的是 SSE 按行解析、[DONE] 收尾、残留内容处理、断流提示、超时设置和受控的重试。
建议按以下顺序推进:先用 curl 确认 Key、地址和流式开关;再用 Python 或前端

登录后可评论,请前往 登录 或 注册