logo

Grok 4.7流式接入实战:从验证到渲染

作者:da吃一鲸8862026.11.17 03:32浏览量:0

简介:本文讲解如何在 zeekeAI 中接入 Grok 4.7 的流式输出,覆盖 curl 验证、Python 按事件解析、前端 fetch 与 ReadableStream 消费,以及 [DONE] 判断、半截数据处理和断流收尾。读完可跑通三段示例,并拿到上线前的检查清单和选型思路。

流式输出改变的是等待感受

流式输出主要降低感知延迟,对总生成时间影响不大。第一段内容会更早到达,用户可以边看边读。长回答、代码生成和文档解析这类任务,开启流式后的体验差距最明显。

在 zeekeAI 上接入 Grok 4.7 时,接口通常兼容 OpenAI 的 Chat Completions 格式。迁移时多数情况下只需替换 model 字段,请求结构基本不变。把请求体中的 stream 设为 true,服务端会以 SSE(Server-Sent Events)格式逐段推送增量内容。具体字段名和行为请以平台文档为准。

用 curl 确认链路通畅

先设置两个环境变量。ZEEKEAI_BASE_URL 需要写完整的基础路径,包括版本段(例如 /v1,是否需要以平台文档为准)。代码只会在末尾拼接 /chat/completions,基础路径写错会直接导致 404。

  1. export ZEEKEAI_BASE_URL="https://<平台提供的域名>/v1"
  2. export ZEEKEAI_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": [{"role": "user", "content": "用三句话解释什么是流式输出"}],
  9. "stream": true,
  10. "max_tokens": 300
  11. }'

-N 关闭 curl 的输出缓冲。省略它时,数据会攒在缓冲区里,看起来像一次性返回的非流式请求。

正常响应的响应头应包含 Content-Type: text/event-stream。响应体大致如下:

  1. data: {"choices":[{"delta":{"content":"流式输出"}}]}
  2. data: {"choices":[{"delta":{"content":"会把回答拆成多段"}}]}
  3. data: [DONE]

每个事件以空行结束。服务端还可能发送以冒号开头的注释行(如 : keep-alive)作为心跳。解析时应忽略这类行。data: [DONE] 表示本次输出结束。

Python:按 SSE 事件解析,不逐块解析 JSON

网络分片不会对齐 SSE 的行或事件。常见错误是每收到一个网络块就尝试解析 JSON,结果经常遇到半截数据。更稳妥的做法分三步:

  1. 使用增量解码器处理 UTF-8,避免一个中文字符被切在两个网络块之间。
  2. 按换行切出完整的行,最后一段不完整的内容留在缓冲区中。
  3. 遇到空行时,合并同一事件内的 data: 行,再整体解析。

由于只在空行处解析,解析器永远拿不到半截 JSON。解析失败意味着事件本身有问题,记录日志后跳过即可。

  1. import codecs
  2. import json
  3. import os
  4. import sys
  5. import requests
  6. MAX_BUFFER_CHARS = 64 * 1024 # 未完成行的上限,防止服务端持续发送无换行数据导致内存增长
  7. def handle_event(data: str) -> bool:
  8. """处理一个完整的 SSE 事件,返回 True 表示流已结束。"""
  9. if data == "[DONE]":
  10. return True
  11. try:
  12. obj = json.loads(data)
  13. except json.JSONDecodeError:
  14. print(f"\n[跳过无法解析的事件] {data[:80]}", file=sys.stderr)
  15. return False
  16. choices = obj.get("choices") or []
  17. if choices:
  18. content = (choices[0].get("delta") or {}).get("content") or ""
  19. if content:
  20. print(content, end="", flush=True)
  21. return False
  22. def stream_chat() -> bool:
  23. base_url = os.environ["ZEEKEAI_BASE_URL"].rstrip("/")
  24. api_key = os.environ["ZEEKEAI_API_KEY"]
  25. url = f"{base_url}/chat/completions"
  26. headers = {
  27. "Authorization": f"Bearer {api_key}",
  28. "Content-Type": "application/json",
  29. }
  30. payload = {
  31. "model": "grok-4.7",
  32. "messages": [{"role": "user", "content": "用三句话解释什么是流式输出"}],
  33. "stream": True,
  34. "max_tokens": 300,
  35. }
  36. decoder = codecs.getincrementaldecoder("utf-8")()
  37. buffer = ""
  38. data_parts: list[str] = []
  39. with requests.post(url, headers=headers, json=payload,
  40. stream=True, timeout=(5, 60)) as resp:
  41. resp.raise_for_status()
  42. for chunk in resp.iter_content(chunk_size=1024):
  43. if not chunk:
  44. continue
  45. buffer += decoder.decode(chunk)
  46. if len(buffer) > MAX_BUFFER_CHARS:
  47. raise RuntimeError("未完成的行超过缓存上限,已中止读取")
  48. while "\n" in buffer:
  49. line, buffer = buffer.split("\n", 1)
  50. line = line.rstrip("\r")
  51. if line == "":
  52. if data_parts and handle_event("\n".join(data_parts)):
  53. print()
  54. return True
  55. data_parts = []
  56. elif line.startswith("data:"):
  57. data_parts.append(line[5:].lstrip(" "))
  58. # 其他行(如 ": keep-alive" 注释)直接忽略
  59. # 连接关闭时仍有未处理的事件,尝试处理后再判断
  60. if data_parts and handle_event("\n".join(data_parts)):
  61. print()
  62. return True
  63. print("\n[警告] 连接结束但未收到 [DONE],回答可能不完整", file=sys.stderr)
  64. return False
  65. if __name__ == "__main__":
  66. try:
  67. ok = stream_chat()
  68. except requests.RequestException as exc:
  69. print(f"\n[请求失败] {exc}", file=sys.stderr)
  70. sys.exit(1)
  71. sys.exit(0 if ok else 1)

这段代码有三个关键点:

  • 增量解码:codecs 的增量解码器会保留不完整的字节,等下一个块到达后再拼接。
  • 事件边界:只有遇到空行才解析,半截 JSON 不会进入解析逻辑。
  • 缓存上限:未完成的行超过 64 KB 时直接中止,避免异常响应撑爆内存。

前端:用 fetch 和 ReadableStream 消费

EventSource 只支持 GET 请求,无法自定义 Authorization 请求头,也不能发送 JSON 请求体。大模型对话接口通常需要 POST,因此不适合用它。fetch 配合 ReadableStream 可以覆盖 POST、请求头、取消请求和超时控制。

下面的代码假设页面中存在 id="output" 的元素,并且脚本在该元素之后加载。

  1. const outputElement = document.getElementById("output");
  2. async function streamChat(baseUrl, apiKey, timeoutMs = 60000) {
  3. const controller = new AbortController();
  4. const timer = setTimeout(() => controller.abort(), timeoutMs);
  5. try {
  6. const response = await fetch(`${baseUrl}/chat/completions`, {
  7. method: "POST",
  8. headers: {
  9. "Authorization": `Bearer ${apiKey}`,
  10. "Content-Type": "application/json"
  11. },
  12. body: JSON.stringify({
  13. model: "grok-4.7",
  14. messages: [{ role: "user", content: "用三句话解释什么是流式输出" }],
  15. stream: true,
  16. max_tokens: 300
  17. }),
  18. signal: controller.signal
  19. });
  20. if (!response.ok) {
  21. throw new Error(`HTTP ${response.status}`);
  22. }
  23. const reader = response.body.getReader();
  24. const decoder = new TextDecoder("utf-8");
  25. let buffer = "";
  26. let dataParts = [];
  27. while (true) {
  28. const { done, value } = await reader.read();
  29. if (done) break;
  30. buffer += decoder.decode(value, { stream: true });
  31. const lines = buffer.split("\n");
  32. buffer = lines.pop();
  33. for (const raw of lines) {
  34. const line = raw.replace(/\r$/, "");
  35. if (line === "") {
  36. if (dataParts.length > 0) {
  37. const finished = handleEvent(dataParts.join("\n"));
  38. dataParts = [];
  39. if (finished) {
  40. await reader.cancel();
  41. return true;
  42. }
  43. }
  44. } else if (line.startsWith("data:")) {
  45. dataParts.push(line.slice(5).replace(/^ /, ""));
  46. }
  47. }
  48. }
  49. console.warn("连接结束但未收到 [DONE],回答可能不完整");
  50. return false;
  51. } finally {
  52. clearTimeout(timer);
  53. }
  54. }
  55. function handleEvent(data) {
  56. if (data === "[DONE]") return true;
  57. let obj;
  58. try {
  59. obj = JSON.parse(data);
  60. } catch (err) {
  61. console.warn("无法解析的事件,已跳过", data);
  62. return false;
  63. }
  64. const content = obj.choices?.[0]?.delta?.content || "";
  65. if (content) {
  66. outputElement.textContent += content;
  67. }
  68. return false;
  69. }

这里要注意两点:

  • 密钥安全:浏览器中的代码会暴露 apiKey。生产环境应由自己的后端代理转发请求,前端只调用后端接口,密钥保存在服务端环境变量中。
  • 超时含义:timeoutMs 是整个流的总时长上限,不是单次读取的空闲超时。如果回答较长,可以在每次 reader.read() 成功后重置计时器,改为空闲超时。

收尾与异常处理

流式接口的难点通常不在开始,而在收尾。以下三类问题需要单独处理。

收到 [DONE] 才算完整

data: [DONE] 是流式结束的标志。如果连接关闭时没有收到它,说明输出可能不完整,代码应给出明确提示,而不是默认回答已完成。

半截数据与超时

SSE 数据持续到达,一个事件可能分散在多个网络块中。处理原则如下:

  • 先缓存原始字符串,再按行切分;
  • 只有遇到空行,才认为一个事件完整;
  • 事件无法解析时记录日志并跳过,不中断整个流;
  • 缓存超过上限或长时间没有新数据时,主动中止并提示用户。

超时分为连接超时和读取超时。Python 示例中的 timeout=(5, 60) 表示连接最多等 5 秒,两次数据之间最多等 60 秒。

断流后的重试

网络中断后,已显示的内容只是完整回答的一部分。重试时要避免两段内容拼接成重复文本,建议遵循以下规则:

  • 不自动重放已输出的内容;
  • 重新发起请求前,清空输出区域,或将新回答标记为新的一次生成;
  • 只对幂等的请求做有限次数的重试,并设置退避间隔;
  • 对非关键场景,可以降级为非流式请求;
  • 记录请求标识(若响应头提供 request id 字段)、模型名、首 token 到达时间和错误信息,便于排查。

接入检查清单

把 Grok 4.7 接入业务系统时,可以按下表逐项确认。

检查项 说明
Base URL 包含版本段,且末尾拼接 /chat/completions 后路径正确
API Key 从环境变量读取,不写入代码或日志,前端场景改由后端代理
Model 使用平台文档中的模型标识,如 grok-4.7
Stream 请求体设置 "stream": true
响应头 确认 Content-Type 为 text/event-stream
代理缓冲 经过 Nginx 等反向代理时,关闭缓冲,如 proxy_buffering off; 并设置 X-Accel-Buffering: no
SSE 解析 按空行切分事件,忽略注释行,处理 [DONE] 和无法解析的事件
前端方式 使用 fetch 与 ReadableStream,不使用 EventSource
超时策略 设置连接超时、读取超时,并限制 max_tokens
收尾逻辑 未收到 [DONE] 时提示内容可能不完整
成本评估 统计输入和输出 token 消耗,避免长上下文造成浪费

多模型场景下的选型

实际项目很少只接入一个模型。不同模型在代码生成、长文本理解、知识问答和多轮对话中的表现与成本差异明显。建议在接入阶段就按场景分层,并用同一批测试数据做横向对比。

下表列出的是需要测量的维度。具体数值应在自己的环境中实测,不应直接采用他人的基准数据。

维度 测量方法 记录方式
首 token 延迟 从发出请求到收到第一条含 content 的事件的时间 每次请求记录毫秒数,取 P50 和 P95
输出吞吐 输出 token 数除以从首 token 到 [DONE] 的耗时 按模型和提示词长度分组统计
上下文长度 以官方文档标称值为准,用接近上限的输入实测是否报错 记录可用的最大输入 token 数
单位价格 分别查询输入与输出每百万 token 的价格 按业务日均调用量估算月成本
稳定性 同一组提示词重复调用,统计失败和超时比例 记录失败率和错误码分布

分层时可以参考以下思路:

  • 快速响应场景:优先看首 token 延迟和稳定性。
  • 长文本场景:重点测上下文长度和摘要结果的一致性。
  • 代码场景:重点测补全、错误修复和结构化输出的正确率。
  • 知识问答场景:结合知识库检索,并要求回答标注来源。
  • 成本敏感场景:比较相同任务下的总 token 消耗和单次调用成本。

如果需要在多模型之间对比能力和价格,可以参考以下平台。

广告/合作说明:以下链接为合作推广内容,与本文的技术步骤没有直接依赖关系。百度智能云词元所,面向模型服务的供需双方,提供模型发现、价格与性能对比和统一 API 接入等能力。

总结

在 zeekeAI 上接入 Grok 4.7 的流式输出,可以按“curl 验证、Python 解析、前端消费、异常收尾”的顺序推进。解析时以空行划分事件,只在事件完整后再解析 JSON。前端使用 fetch 与 ReadableStream,并把密钥留在后端。收尾阶段以 [DONE] 作为完成标志,超时、缓存上限和重试规则需要提前设计好。完成这些步骤后,流式输出能稳定地改善对话类应用的交互体验。

发表评论

活动