logo

ZeekeAI接入Grok 4.7流式输出指南

作者:沙与沫2026.11.17 03:26浏览量:1

简介:本文讲解如何在ZeekeAI中接入Grok 4.7并启用流式输出。内容包括用curl验证接口、Python解析SSE数据、通过后端代理在前端用fetch消费流式回答,以及[DONE]收尾、半截JSON处理和成本控制。读完即可搭建一条可上线的流式对话链路。

前言

把请求体中的 stream 设为 true 只是第一步。真正决定体验的,是 SSE 数据解析、[DONE] 收尾和网络异常处理。本文按顺序说明每一步,并给出可以直接运行的示例代码。

一、哪些场景适合流式输出

长回答、代码生成、文档解析和客服问答都适合流式输出。模型每生成一段文字,用户就能立刻看到,不必等待整段答案完成。首字出现得更快,交互也更自然。

ZeekeAI 上的 Grok 4.7 接口采用 OpenAI 兼容格式。如果你的项目已经调用过 OpenAI 风格的接口,通常只需要修改 model 字段,原有的请求结构可以保持不变。

二、接入前确认三项配置

  • ZEEKEAI_BASE_URL:接口基础地址,通常包含版本路径,例如 /v1。
  • ZEEKEAI_API_KEY:访问密钥,只放在服务端的环境变量中,不写入代码或前端页面。
  • model:模型名。示例中写的是 grok-4.7,但请以 ZeekeAI 控制台列出的实际模型名为准。

最终请求地址的格式如下:

  1. {ZEEKEAI_BASE_URL}/chat/completions

如果返回 400 或 404,先核对模型名是否存在,再检查 Base URL 是否缺少 /v1。

三、用 curl 验证流式接口

写代码前,先用 curl 确认密钥、网络和流式输出都正常:

  1. curl -N -s --max-time 60 "$ZEEKEAI_BASE_URL/chat/completions" \
  2. -H "Authorization: Bearer $ZEEKEAI_API_KEY" \
  3. -H "Content-Type: application/json" \
  4. -H "Accept: text/event-stream" \
  5. -d '{
  6. "model": "grok-4.7",
  7. "messages": [
  8. {"role": "user", "content": "用三句话解释什么是流式输出"}
  9. ],
  10. "stream": true,
  11. "max_tokens": 300
  12. }'

参数说明如下。-N 会关闭 curl 的输出缓冲,必须保留,否则数据会积压,看起来像非流式请求。--max-time 设置总超时,避免命令长时间挂起。

正常返回时,每行会逐步出现,格式类似下面这样:

  1. data: {"choices":[{"delta":{"content":"流式输出"}}]}
  2. data: {"choices":[{"delta":{"content":"会把模型生成的内容"}}]}
  3. data: [DONE]

如果返回的是一整段 JSON,而不是逐行的 data: 事件,说明请求体中的 stream 没有生效,或者中间的网关开启了响应缓冲。

四、Python 流式消费

SSE 协议用空行分隔事件。一个事件可能包含多行 data:,所以代码需要先按空行合并,再解析 JSON。示例基于 httpx,安装命令为 pip install httpx。

  1. import json
  2. import os
  3. import httpx
  4. BASE_URL = os.environ["ZEEKEAI_BASE_URL"].rstrip("/")
  5. API_KEY = os.environ["ZEEKEAI_API_KEY"]
  6. def iter_sse_data(lines):
  7. """把 SSE 行合并为事件,每个事件返回完整的 data 内容。"""
  8. data_lines = []
  9. for line in lines:
  10. if line == "":
  11. if data_lines:
  12. yield "\n".join(data_lines)
  13. data_lines = []
  14. continue
  15. if line.startswith("data:"):
  16. data_lines.append(line[5:].lstrip())
  17. if data_lines:
  18. # 连接在事件中途断开,最后这段数据不完整,直接丢弃
  19. pass
  20. def stream_chat(prompt: str, model: str = "grok-4.7"):
  21. payload = {
  22. "model": model,
  23. "messages": [{"role": "user", "content": prompt}],
  24. "stream": True,
  25. "max_tokens": 1024,
  26. "temperature": 0.3,
  27. }
  28. headers = {
  29. "Authorization": f"Bearer {API_KEY}",
  30. "Accept": "text/event-stream",
  31. }
  32. timeout = httpx.Timeout(120.0, connect=10.0)
  33. with httpx.Client(timeout=timeout) as client:
  34. with client.stream(
  35. "POST", f"{BASE_URL}/chat/completions", headers=headers, json=payload
  36. ) as resp:
  37. if resp.status_code != 200:
  38. resp.read()
  39. raise RuntimeError(f"HTTP {resp.status_code}: {resp.text[:200]}")
  40. for data in iter_sse_data(resp.iter_lines()):
  41. if data.strip() == "[DONE]":
  42. return
  43. try:
  44. event = json.loads(data)
  45. except json.JSONDecodeError:
  46. continue # 丢弃无法解析的事件
  47. choices = event.get("choices") or []
  48. if not choices:
  49. continue
  50. content = choices[0].get("delta", {}).get("content")
  51. if content:
  52. yield content
  53. if __name__ == "__main__":
  54. for piece in stream_chat("写一个判断字符串是否回文的 Java 方法"):
  55. print(piece, end="", flush=True)
  56. print()

这段代码有三个要点。第一,状态码不是 200 时直接抛出异常。第二,遇到 [DONE] 立即返回,防止无限等待。第三,choices 是列表,代码先取 choices[0],再读取 delta,避免把列表当成字典调用 .get。

五、前端通过后端代理消费流式输出

前端不建议直接使用 EventSource。它只支持 GET 请求,无法携带 JSON 请求体和自定义 Header,而大模型对话通常需要 POST 请求。前端应改用 fetch 加 ReadableStream。

更重要的是,API Key 不能出现在前端代码中。浏览器中的任何代码都可以被查看和复制。正确做法是让前端请求自己的后端,由后端持有密钥并转发请求。

下面是一个 FastAPI 代理示例:

  1. import os
  2. import httpx
  3. from fastapi import FastAPI
  4. from fastapi.responses import StreamingResponse
  5. from pydantic import BaseModel, Field
  6. BASE_URL = os.environ["ZEEKEAI_BASE_URL"].rstrip("/")
  7. API_KEY = os.environ["ZEEKEAI_API_KEY"]
  8. MODEL = os.environ.get("ZEEKEAI_MODEL", "grok-4.7")
  9. app = FastAPI()
  10. class ChatRequest(BaseModel):
  11. prompt: str = Field(min_length=1, max_length=4000)
  12. @app.post("/api/chat/stream")
  13. async def chat_stream(req: ChatRequest):
  14. payload = {
  15. "model": MODEL,
  16. "messages": [{"role": "user", "content": req.prompt}],
  17. "stream": True,
  18. "max_tokens": 1024,
  19. }
  20. headers = {"Authorization": f"Bearer {API_KEY}"}
  21. async def relay():
  22. timeout = httpx.Timeout(120.0, connect=10.0)
  23. async with httpx.AsyncClient(timeout=timeout) as client:
  24. async with client.stream(
  25. "POST", f"{BASE_URL}/chat/completions", headers=headers, json=payload
  26. ) as resp:
  27. if resp.status_code != 200:
  28. # 上游错误细节不直接透传给前端,生产环境应在服务端记录状态码和 request_id
  29. yield "event: error\ndata: upstream_error\n\n"
  30. return
  31. async for line in resp.aiter_lines():
  32. yield line + "\n"
  33. return StreamingResponse(relay(), media_type="text/event-stream")

代理逐行转发上游的 SSE 数据。空行会原样保留,前端据此判断事件边界。代理只做转发,不做额外的解析。

前端代码如下。outputEl 是页面中用于显示内容的 DOM 元素,例如 document.getElementById("output")。

  1. async function streamChat(prompt, outputEl) {
  2. const response = await fetch("/api/chat/stream", {
  3. method: "POST",
  4. headers: { "Content-Type": "application/json" },
  5. body: JSON.stringify({ prompt }),
  6. });
  7. if (!response.ok || !response.body) {
  8. throw new Error(`请求失败,状态码 ${response.status}`);
  9. }
  10. const reader = response.body.getReader();
  11. const decoder = new TextDecoder();
  12. let buffer = "";
  13. try {
  14. while (true) {
  15. const { done, value } = await reader.read();
  16. if (done) break;
  17. buffer += decoder.decode(value, { stream: true });
  18. const events = buffer.split("\n\n");
  19. buffer = events.pop(); // 最后一段可能不完整,留到下一次读取时再处理
  20. for (const event of events) {
  21. const data = event
  22. .split("\n")
  23. .filter((line) => line.startsWith("data:"))
  24. .map((line) => line.slice(5).trimStart())
  25. .join("\n");
  26. if (!data) continue;
  27. if (data === "[DONE]") return;
  28. let json;
  29. try {
  30. json = JSON.parse(data);
  31. } catch {
  32. continue; // 跳过无法解析的事件,例如 error 事件的数据
  33. }
  34. const delta = json.choices?.[0]?.delta?.content;
  35. if (delta) {
  36. outputEl.textContent += delta;
  37. }
  38. }
  39. }
  40. } finally {
  41. // 无论正常结束还是中途报错,都释放连接
  42. await reader.cancel().catch(() => {});
  43. }
  44. }

这段代码假设服务端使用 \n 作为换行符。它在读取到 [DONE] 时直接返回,finally 中会取消读取器,关闭底层连接。

六、半截 JSON 与网络异常处理

正常情况下,每个 JSON 都在一个完整的 SSE 事件中。半截数据通常来自连接中断,例如网络波动、代理超时或上游限流。

遇到这些情况,可以按下面的策略处理:

  1. 未以空行结束的事件直接丢弃,不尝试修补 JSON。Python 示例中的 iter_sse_data 和前端中的 buffer 都遵循这一规则。
  2. 已经输出了部分内容后连接断开,不要自动整段重试。否则页面会出现重复文字。应提示用户“回答中断”,并允许用户手动重新生成。
  3. 连接失败或首包之前就出错,可以重试一到两次,并逐次拉长等待时间。
  4. 记录 request_id、模型名、耗时和已输出的字符数,便于事后排查。

七、常见问题排查

现象 可能原因 处理方式
没有逐字输出,整段一次返回 curl 未加 -N,或网关开启了响应缓冲 加上 -N,关闭代理缓冲,例如检查 Nginx 的 proxy_buffering
401 或 403

发表评论

活动