简介:Grok 4.7在ZEEKEAI上提供OpenAI兼容的流式接口,替换base_url、API Key和model三项配置后,原有OpenAI SDK代码基本可以复用。本文给出Python与Node.js的流式调用代码、SSE数据的解析方法、常见故障排查以及按Token控制成本的做法,帮你在接入前后少走弯路。
OpenAI兼容网关的设计思路是协议不变,只换配置。接入时需要确认下面三项:
| 配置项 | 填什么 | 核对要点 |
|---|---|---|
base_url |
平台提供的兼容地址 | 路径是否包含 /v1 以平台文档为准,路径错误通常返回 404 |
api_key |
控制台创建的密钥 | 请求头格式为 Authorization: Bearer 密钥,缺少 Bearer 前缀会返回 401 |
model |
平台模型列表中的名称 | 大小写和版本号需要与列表逐字一致 |
换模型时,通常只需修改 model 字段,消息结构和流式解析逻辑可以沿用。不过不同平台的路径设计和模型命名并不完全相同。文中的 grok-4.7 是示例名称,实际可用的模型名、价格和上下文长度,以平台模型列表和控制台为准。
流式输出基于 Server-Sent Events(SSE)。服务端保持一条长连接,把生成的内容拆成多行 data: 数据陆续推送。客户端每收到一行就能立即显示,无需等待整段回复生成完毕。
一次典型的响应如下:
data: {"choices":[{"delta":{"role":"assistant","content":""}}]}data: {"choices":[{"delta":{"content":"流式"}}]}data: {"choices":[{"delta":{"content":"输出"}}]}data: [DONE]
解析时需要注意三点:
delta 只包含增量文本,客户端要自己累加拼接。role,content 为空或缺失,解析时要先判空。data: [DONE] 是结束标记,收到后应停止读取。SSE 还允许以冒号开头的注释行、空行,以及 event、id 等字段。手工解析时应跳过这些非 data: 行,不要把它们当作 JSON 处理。
使用官方 SDK 最省事:
from openai import OpenAIclient = OpenAI(api_key="YOUR_API_KEY",base_url="https://<你的接入地址>/v1",)stream = client.chat.completions.create(model="grok-4.7",messages=[{"role": "system", "content": "你是简洁的技术助手"},{"role": "user", "content": "用三句话解释什么是流式输出"},],stream=True,temperature=0.7,)for chunk in stream:if not chunk.choices:continuedelta = chunk.choices[0].delta.contentif delta:print(delta, end="", flush=True)
choices 是列表,取第一个候选结果需要写成 chunk.choices[0]。部分 chunk(例如开启用量回传时的最后一个 chunk)的 choices 可能为空,因此要先判断。
如果不方便引入 SDK,也可以直接解析原始 SSE:
import jsonimport requestsresp = requests.post("https://<你的接入地址>/v1/chat/completions",headers={"Authorization": "Bearer YOUR_API_KEY","Content-Type": "application/json",},json={"model": "grok-4.7","messages": [{"role": "user", "content": "你好"}],"stream": True,},stream=True,timeout=(5, 120), # 连接超时, 读取超时)resp.raise_for_status() # 状态码异常时直接报错,不进入解析流程resp.encoding = "utf-8" # SSE 数据为 UTF-8,服务端未声明编码时需手动指定for raw in resp.iter_lines(decode_unicode=True):if not raw or raw.startswith(":"): # 跳过空行与注释行continueif not raw.startswith("data:"): # 跳过 event、id 等非数据行continuepayload = raw[len("data:"):].strip()if payload == "[DONE]":breaktry:event = json.loads(payload)except json.JSONDecodeError:print("\n[跳过无法解析的数据行]", payload[:80])continuechoices = event.get("choices") or []if not choices:continuedelta = choices[0].get("delta", {}).get("content")if delta:print(delta, end="", flush=True)
这段代码假设接口返回标准 Chat Completions 结构。如果平台的返回字段有差异,应以实际响应为准调整解析逻辑。
Node.js 端使用 openai 4.x 及以上版本,返回结构遵循 Chat Completions 规范:
import OpenAI from "openai";const client = new OpenAI({apiKey: process.env.ZEEKE_KEY,baseURL: "https://<你的接入地址>/v1",});const stream = await client.chat.completions.create({model: "grok-4.7",messages: [{ role: "user", content: "写一个快速排序" }],stream: true,});for await (const chunk of stream) {const delta = chunk.choices?.[0]?.delta?.content ?? "";process.stdout.write(delta);}
浏览器端不能直接持有 API Key,应由自己的后端转发请求。转发层至少要做三件事:校验用户登录状态,限制单个用户的调用频率,限制单次请求的消息长度和 max_tokens。后端把上游 SSE 原样透传给前端。
中间的反向代理(如 Nginx)默认会缓冲响应,流式效果会退化为一次性返回。需要关闭代理缓冲并延长读取超时:
location /api/chat/ {proxy_pass http://127.0.0.1:8080;proxy_buffering off;proxy_read_timeout 300s;}
后端响应中还可以加上 X-Accel-Buffering: no 头,告诉 Nginx 对该响应关闭缓冲。
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
| 401 Unauthorized | 密钥错误,或请求头缺少 Bearer |
核对密钥有效性与请求头格式 |
| 404 或 model not found | base_url 路径不对,或 model 名称与列表不一致 |
对照平台文档检查路径,逐字校对模型名 |
| 没有流式效果,一次性返回 | 请求体未设置 stream: true,或中间代理开启了缓冲 |
检查请求体,关闭代理缓冲 |
| 首字延迟明显偏高 | 输入过长、冷启动或排队 | 精简 system prompt,设置合理超时 |
| 中文显示乱码 | 手工解析时未按 UTF-8 解码 | 显式指定 UTF-8,检查响应头 Content-Type 的 charset |
| 输出中途断开 | 网络波动,或读取超时过短 | 区分连接超时与读取超时,对未完成的回复做重试 |
大模型按