流式协议
适用:
/v1/chat/completions、/v1/responses、/v1/messages、/v1/jobs/:id/events
Nexith 的流式响应统一为 text/event-stream(SSE)。文本生成使用 OpenAI 兼容的
chat.completion.chunk 帧;图片作业使用作业事件帧;另有少量 nexith.* 侧信道帧,
只在调用方显式开启对应 nexith_* 扩展时出现。
1. 文本流(Chat Completions)#
请求#
{
"model": "nexith-core",
"messages": [{"role": "user", "content": "写一首短诗"}],
"stream": true,
"stream_options": {"include_usage": true}
}帧格式#
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1795055220,"model":"nexith-core","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk",...,"choices":[{"index":0,"delta":{"content":"春"},"finish_reason":null}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk",...,"choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-...","object":"chat.completion.chunk",...,"choices":[],"usage":{"prompt_tokens":12,"completion_tokens":34,"total_tokens":46}}
data: [DONE]要点:
- 以
data: <json>\n\n发送,最后固定data: [DONE]。 stream_options.include_usage=true时,在[DONE]前有一帧choices: []+usage; 计费以该帧为准。不传则没有用量帧(OpenAI 旧行为)。- 工具调用以
delta.tool_calls增量下发,拼接规则与 OpenAI 一致。 - 连接由服务端保活(SSE comment 心跳),代理超时通常为 300s。
错误#
- 首个 token 之前失败:返回正常 HTTP 错误(4xx/5xx + JSON body),不会先发 200。
- 已经开始输出后失败:无法再改状态码,流内会发一帧错误对象后结束;客户端应把 已收到的内容视为不完整。
2. 侧信道帧(Nexith 扩展)#
仅当请求携带对应开关时出现。纯 OpenAI 客户端不会收到这些帧。
nexith.sources(联网搜索来源)#
在答案首帧之前发送,供前端先渲染引用卡:
{
"object": "nexith.sources",
"sources": [
{"title": "…", "url": "https://…", "content": "摘要片段"}
]
}nexith.step(深度研究进度)#
深度研究各阶段(规划、检索、抓取、压缩)逐帧回放,位于 nexith.sources 之前:
{"object": "nexith.step", "label": "检索", "model": "…", "content": "…", "items": [...]}nexith.image_request(生图意图)#
当请求携带 nexith_detect_media: true 且 L1 判定为生图意图时,网关不进入文本流,
直接返回非流式 JSON:
{
"object": "nexith.image_request",
"capability": "image.generate",
"target_model": "nexith-image",
"original_prompt": "画一只小猫",
"enhanced_prompt": "A cute kitten, …",
"size": "1024x1024"
}前端拿到后应调用 POST /v1/images/generations 提交异步作业。改图意图对应
nexith.image_edit_request(额外带参考图信息)。
nexith.routing_decision(Responses 适配层)#
/v1/responses 在需要调用方补充能力时可能返回该结构(status=requires_capability),
用于告诉客户端「这类请求需要哪个能力档」,而不是伪造一次文本回答。
3. 非流式响应里的 nexith 对象#
非流式 Chat Completions 响应体可能带一个顶层 nexith 对象(同样只在开启扩展时):
{
"id": "chatcmpl-...",
"object": "chat.completion",
"choices": [...],
"usage": {...},
"nexith": {
"memory": [{"id": "...", "content": "...", "score": 0.83}],
"sources": [{"title": "...", "url": "...", "content": "..."}],
"steps": [{"label": "...", "model": "...", "content": "..."}]
}
}字段均可选:return_memory → memory;nexith_web_search → sources;
nexith_deep_research → steps。
4. 作业事件流(Jobs SSE)#
GET /v1/jobs/:id/events 返回作业事件流,帧格式与文本流不同:
data: {"event":"queued","payload":{},"ts":"2026-11-19T02:00:00Z"}
data: {"event":"started","payload":{},"ts":"..."}
data: {"event":"completed","payload":{},"ts":"..."}- 事件类型:
queued/started/error/completed/failed/cancelled。 - 每次连接从事件 0 开始回放,客户端重连即可补齐全部历史事件。
- 服务端每 15 秒发一次 SSE comment 心跳,防代理空闲断连。
error/failed的payload.error是不透明的固定文案,不含上游模型名或内部错误原文。- 收到
completed/failed/cancelled后服务端结束流。
5. 客户端建议#
- 用官方 SDK 时不要手动解析 SSE,直接使用
stream=true。 - 自研客户端需处理:跨 chunk 边界的半帧、
[DONE]结束、空行心跳。 - 断线重试:文本流没有断点续传,重试会产生新的计费请求;作业流可以安全重连。