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 控制台列出的实际模型名为准。
最终请求地址的格式如下:
{ZEEKEAI_BASE_URL}/chat/completions
如果返回 400 或 404,先核对模型名是否存在,再检查 Base URL 是否缺少 /v1。
三、用 curl 验证流式接口
写代码前,先用 curl 确认密钥、网络和流式输出都正常:
curl -N -s --max-time 60 "$ZEEKEAI_BASE_URL/chat/completions" \-H "Authorization: Bearer $ZEEKEAI_API_KEY" \-H "Content-Type: application/json" \-H "Accept: text/event-stream" \-d '{"model": "grok-4.7","messages": [{"role": "user", "content": "用三句话解释什么是流式输出"}],"stream": true,"max_tokens": 300}'
参数说明如下。-N 会关闭 curl 的输出缓冲,必须保留,否则数据会积压,看起来像非流式请求。--max-time 设置总超时,避免命令长时间挂起。
正常返回时,每行会逐步出现,格式类似下面这样:
data: {"choices":[{"delta":{"content":"流式输出"}}]}data: {"choices":[{"delta":{"content":"会把模型生成的内容"}}]}data: [DONE]
如果返回的是一整段 JSON,而不是逐行的 data: 事件,说明请求体中的 stream 没有生效,或者中间的网关开启了响应缓冲。
四、Python 流式消费
SSE 协议用空行分隔事件。一个事件可能包含多行 data:,所以代码需要先按空行合并,再解析 JSON。示例基于 httpx,安装命令为 pip install httpx。
import jsonimport osimport httpxBASE_URL = os.environ["ZEEKEAI_BASE_URL"].rstrip("/")API_KEY = os.environ["ZEEKEAI_API_KEY"]def iter_sse_data(lines):"""把 SSE 行合并为事件,每个事件返回完整的 data 内容。"""data_lines = []for line in lines:if line == "":if data_lines:yield "\n".join(data_lines)data_lines = []continueif line.startswith("data:"):data_lines.append(line[5:].lstrip())if data_lines:# 连接在事件中途断开,最后这段数据不完整,直接丢弃passdef stream_chat(prompt: str, model: str = "grok-4.7"):payload = {"model": model,"messages": [{"role": "user", "content": prompt}],"stream": True,"max_tokens": 1024,"temperature": 0.3,}headers = {"Authorization": f"Bearer {API_KEY}","Accept": "text/event-stream",}timeout = httpx.Timeout(120.0, connect=10.0)with httpx.Client(timeout=timeout) as client:with client.stream("POST", f"{BASE_URL}/chat/completions", headers=headers, json=payload) as resp:if resp.status_code != 200:resp.read()raise RuntimeError(f"HTTP {resp.status_code}: {resp.text[:200]}")for data in iter_sse_data(resp.iter_lines()):if data.strip() == "[DONE]":returntry:event = json.loads(data)except json.JSONDecodeError:continue # 丢弃无法解析的事件choices = event.get("choices") or []if not choices:continuecontent = choices[0].get("delta", {}).get("content")if content:yield contentif __name__ == "__main__":for piece in stream_chat("写一个判断字符串是否回文的 Java 方法"):print(piece, end="", flush=True)print()
这段代码有三个要点。第一,状态码不是 200 时直接抛出异常。第二,遇到 [DONE] 立即返回,防止无限等待。第三,choices 是列表,代码先取 choices[0],再读取 delta,避免把列表当成字典调用 .get。
五、前端通过后端代理消费流式输出
前端不建议直接使用 EventSource。它只支持 GET 请求,无法携带 JSON 请求体和自定义 Header,而大模型对话通常需要 POST 请求。前端应改用 fetch 加 ReadableStream。
更重要的是,API Key 不能出现在前端代码中。浏览器中的任何代码都可以被查看和复制。正确做法是让前端请求自己的后端,由后端持有密钥并转发请求。
下面是一个 FastAPI 代理示例:
import osimport httpxfrom fastapi import FastAPIfrom fastapi.responses import StreamingResponsefrom pydantic import BaseModel, FieldBASE_URL = os.environ["ZEEKEAI_BASE_URL"].rstrip("/")API_KEY = os.environ["ZEEKEAI_API_KEY"]MODEL = os.environ.get("ZEEKEAI_MODEL", "grok-4.7")app = FastAPI()class ChatRequest(BaseModel):prompt: str = Field(min_length=1, max_length=4000)@app.post("/api/chat/stream")async def chat_stream(req: ChatRequest):payload = {"model": MODEL,"messages": [{"role": "user", "content": req.prompt}],"stream": True,"max_tokens": 1024,}headers = {"Authorization": f"Bearer {API_KEY}"}async def relay():timeout = httpx.Timeout(120.0, connect=10.0)async with httpx.AsyncClient(timeout=timeout) as client:async with client.stream("POST", f"{BASE_URL}/chat/completions", headers=headers, json=payload) as resp:if resp.status_code != 200:# 上游错误细节不直接透传给前端,生产环境应在服务端记录状态码和 request_idyield "event: error\ndata: upstream_error\n\n"returnasync for line in resp.aiter_lines():yield line + "\n"return StreamingResponse(relay(), media_type="text/event-stream")
代理逐行转发上游的 SSE 数据。空行会原样保留,前端据此判断事件边界。代理只做转发,不做额外的解析。
前端代码如下。outputEl 是页面中用于显示内容的 DOM 元素,例如 document.getElementById("output")。
async function streamChat(prompt, outputEl) {const response = await fetch("/api/chat/stream", {method: "POST",headers: { "Content-Type": "application/json" },body: JSON.stringify({ prompt }),});if (!response.ok || !response.body) {throw new Error(`请求失败,状态码 ${response.status}`);}const reader = response.body.getReader();const decoder = new TextDecoder();let buffer = "";try {while (true) {const { done, value } = await reader.read();if (done) break;buffer += decoder.decode(value, { stream: true });const events = buffer.split("\n\n");buffer = events.pop(); // 最后一段可能不完整,留到下一次读取时再处理for (const event of events) {const data = event.split("\n").filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trimStart()).join("\n");if (!data) continue;if (data === "[DONE]") return;let json;try {json = JSON.parse(data);} catch {continue; // 跳过无法解析的事件,例如 error 事件的数据}const delta = json.choices?.[0]?.delta?.content;if (delta) {outputEl.textContent += delta;}}}} finally {// 无论正常结束还是中途报错,都释放连接await reader.cancel().catch(() => {});}}
这段代码假设服务端使用 \n 作为换行符。它在读取到 [DONE] 时直接返回,finally 中会取消读取器,关闭底层连接。
六、半截 JSON 与网络异常处理
正常情况下,每个 JSON 都在一个完整的 SSE 事件中。半截数据通常来自连接中断,例如网络波动、代理超时或上游限流。
遇到这些情况,可以按下面的策略处理:
- 未以空行结束的事件直接丢弃,不尝试修补 JSON。Python 示例中的
iter_sse_data和前端中的buffer都遵循这一规则。 - 已经输出了部分内容后连接断开,不要自动整段重试。否则页面会出现重复文字。应提示用户“回答中断”,并允许用户手动重新生成。
- 连接失败或首包之前就出错,可以重试一到两次,并逐次拉长等待时间。
- 记录 request_id、模型名、耗时和已输出的字符数,便于事后排查。
七、常见问题排查
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| 没有逐字输出,整段一次返回 | curl 未加 -N,或网关开启了响应缓冲 |
加上 -N,关闭代理缓冲,例如检查 Nginx 的 proxy_buffering |
| 401 或 403 |

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