简介:本文说明在 ZEEKEAI 上以 OpenAI 兼容方式接入 Grok 流式输出的完整方法,覆盖 curl 验证、Python 消费 SSE、前端 fetch 增量渲染、[DONE] 收尾与异常重试,并给出选型、成本评估和常见错误排查,帮助开发者快速稳定落地低延迟对话应用。
在 ZEEKEAI 上接入 Grok 流式输出,可以按约三步完成:先确认 OpenAI 兼容参数和模型标识,再用 curl 验证 SSE,最后在 Python 或前端补齐增量读取、结束标记和异常处理。模型标识请以 ZEEKEAI 控制台的模型列表为准;本文示例中的 grok-4.7 仅作为占位,若平台没有该标识,请替换为列表中的可用模型。
传统非流式请求需要等待完整答案生成后才返回,首字延迟较高。流式输出通过 SSE(Server-Sent Events)将生成内容分片推送,用户能更快看到第一个 token。对于长回答、代码生成、文档解析这类任务,开不开流式的体验差距非常明显。
流式对话适合要求快速响应的场景,也适合用户不需要完整答案即可继续交互的场景。从性能指标看,首 Token 时延、流式包间时延和每秒输出 token 数都是评估体验的重要指标。
ZEEKEAI 的 Grok 流式接口通常采用 OpenAI 兼容格式,常见配置包括:
/v1 或平台文档指定路径结尾。Authorization: Bearer 请求头传递。grok-4.7 仅用于演示,不代表固定可用标识。true,用于开启流式输出。这种方式与 OpenAI SDK 兼容思路一致。开发者可通过 API Key 和 Base URL 快速接入不同模型服务。如果已有 OpenAI SDK 代码,通常只需替换 base_url、api_key 和 model 字段,不必重写整套请求逻辑。
在写业务代码前,建议先用 curl 验证密钥、网络和流式开关是否正常。
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: [DONE] 结束。
如果返回的不是预期格式,优先检查四件事:Base URL 是否完整、API Key 是否有效、模型标识是否存在、stream 是否设置为 true。
Python 中可以使用 httpx 的 stream 模式读取响应。依赖安装方式如下:
pip install "httpx>=0.24"
示例使用 httpx>=0.24 的 stream() 和 timeout() 能力。stream() 用于保持响应连接并逐行读取;timeout 可分别控制连接超时和读取超时,避免长连接卡死。
# 依赖安装:pip install "httpx>=0.24"import osimport jsonimport httpxBASE_URL = os.environ["ZEEKEAI_BASE_URL"].rstrip("/")API_KEY = os.environ["ZEEKEAI_API_KEY"]def stream_chat(prompt: str, model: str = "grok-4.7"):# 示例标识仅用于演示,实际以 ZEEKEAI 平台模型列表为准payload = {"model": model,"messages": [{"role": "user", "content": prompt}],"stream": True,"max_tokens": 4096,"temperature": 0.3,}headers = {"Authorization": f"Bearer {API_KEY}"}with httpx.stream("POST",f"{BASE_URL}/chat/completions",headers=headers,json=payload,timeout=httpx.Timeout(120.0, connect=10.0),) as resp:resp.raise_for_status()for raw in resp.iter_lines():if not raw:continueline = raw.strip()if not line.startswith("data:"):continuedata = line[5:].strip()if data == "[DONE]":breaktry:chunk = json.loads(data)except json.JSONDecodeError:# httpx.iter_lines() 通常会按行返回完整 data 行。# 标准 OpenAI 兼容 SSE 下,这里一般不需要手动拼接半截 JSON。# 如果改用 iter_raw() / iter_bytes(),才需要自行维护缓冲。continuechoices = chunk.get("choices") or []if not choices:continuedelta = choices[0].get("delta") or {}piece = delta.get("content")if piece:yield piecefor piece in stream_chat("写一个判断字符串是否回文的 Java 方法"):print(piece, end="", flush=True)
这段代码的重点是 iter_lines() 和 [DONE]。httpx.iter_lines() 会按行返回,通常会给到完整的 data: 行。标准 OpenAI 兼容 SSE 中,每个 data: 行一般对应一个完整 JSON 对象,因此不必过度担心“文本行不总是完整 JSON”。真正更容易出现半截 JSON 的场景,是前端按字节读取,或开发者自己用 iter_bytes()、iter_raw() 解析流式响应时。
浏览器端不建议直接使用 EventSource,因为 EventSource 主要面向 GET 场景,而大模型对话通常需要 POST 请求和自定义 Header。更灵活的方式是使用 fetch 加 ReadableStream。
同时需要注意:API Key 不要硬编码在前端,也不要暴露给浏览器。生产环境建议由后端代理转发请求,前端只调用自己的接口。
下面是一个最小可运行示例,包含 data: 拆分、[DONE] 收尾和半截缓冲处理:
async function streamChat() {const resp = await fetch('/api/chat-proxy', {method: 'POST',headers: {'Content-Type': 'application/json'},body: JSON.stringify({model: 'grok-4.7', // 示例标识,以 ZEEKEAI 模型列表为准messages: [{ role: 'user', content: '用三句话解释流式输出' }],stream: true})});if (!resp.ok || !resp.body) {throw new Error('流式响应创建失败');}const reader = resp.body.getReader();const decoder = new TextDecoder();const output = document.getElementById('output');let buffer = ''; // 保存未读完的行let pending = ''; // 兼容异常分片:解析失败时暂存,等待下一段拼接while (true) {const { value, done } = await reader.read();if (done) break;buffer += decoder.decode(value, { stream: true });const lines = buffer.split('\n');buffer = lines.pop(); // 最后一段可能不完整,留到下一次读取for (const raw of lines) {const line = raw.trim();if (!line.startsWith('data:')) continue;const data = line.slice(5).trim();if (data === '[DONE]') return;const payload = pending + data;try {const chunk = JSON.parse(payload);pending = '';const piece = chunk?.choices?.[0]?.delta?.content;if (piece) {output.textContent += piece;}} catch (e) {pending = payload; // 半截或非标准分片,等待下一次拼接}}}}
这种方式的优势是可以精确控制请求方法、请求头、超时和错误处理,更适合生产环境中的聊天界面、代码助手和文档解析工具。
data: [DONE] 后应停止读取并释放连接。ReadableStream 读取时,尤其需要维护缓冲;解析失败时可先暂存,等待下一段数据拼接。流式输出改善的是交互体验,不会直接减少模型生成的 token 数量。实际成本仍与输入 token、输出 token、模型规格和调用次数相关。
| 评估维度 | 关注重点 | 建议动作 |
|---|---|---|
| 能力评估 | 代码生成、长文总结、多轮对话、文档解析 | 用真实业务样本做 A/B 测试 |
| 成本评估 | 输入输出价格、平均响应长度、max_tokens |
估算单次调用成本,设置上限 |
| 稳定性评估 | 首 Token 时延、流式稳定性、错误率、限流策略 | 记录失败率、超时率和重试成本 |
如果需要在多个模型之间做选择,可以结合模型能力、价格、性能和调用日志进行综合判断。对于已经上线的应用,建议观察不同模型的实际使用情况,再决定流量分配和成本优化策略。
相关服务/推广:如果你需要在接入前对比不同模型服务,可以了解百度智能云词元所,它提供模型发现、价格与性能对比、统一 API 接入和调用管理能力。
-N:输出被缓冲,看起来像非流式请求。stream 当成字符串:stream 应设置为布尔值 true,不是 "true" 这类字符串。usage:如果平台返回 usage,可用于统计 prompt_tokens、completion_tokens 和 total_tokens;如果流式响应默认不返回,可参考平台日志或用量页面。[DONE],可能导致连接不释放或重复读取。stream 参数。[DONE]、半截 JSON、超时和异常处理。fetch + ReadableStream 渲染增量内容。完成以上步骤后,ZEEKEAI 接入 Grok 流式输出就可以稳定用于对话、代码生成和文档处理等场景。