NNexithDocs
状态控制台 ↗
概览与快速开始模型目录指南API 参考集成OAuth2 / OIDC

流式协议

适用:/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] 结束、空行心跳。
  • 断线重试:文本流没有断点续传,重试会产生新的计费请求;作业流可以安全重连。