OpenNave 文档中心

外观

流式响应 ​

流式响应让应用在模型生成过程中持续接收结果，而不必等待完整响应完成。它适合聊天界面、命令行交互和长文本生成场景。OpenNave 通过 Server-Sent Events（SSE）支持 OpenAI、Anthropic 和 Gemini 格式的流式调用。

启用流式响应 ​

OpenAI 格式 ​

在请求体中设置 stream 为 true。响应以 SSE 形式返回，每个 data: 行包含一个 JSON 数据块。

sh
curl -N https://api.opennave.top/v1/responses \
  -H "Authorization: Bearer $OPENNAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "input": "写一首关于编程的俳句。",
    "stream": true
  }'

Anthropic 格式 ​

同样在请求体中设置 stream 为 true。Anthropic 协议使用命名事件组织流式响应。

sh
curl -N https://api.opennave.top/v1/messages \
  -H "x-api-key: $OPENNAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "写一首关于编程的俳句。"}
    ]
  }'

使用 Messages 协议的兼容模型可沿用相同的流式处理方式，只需替换模型名称。

Gemini 格式 ​

Gemini 使用 streamGenerateContent 端点。若需要 SSE 增量事件，添加 alt=sse 查询参数；省略该参数或使用 alt=json 时，服务返回完整 JSON 数组。

sh
curl -N "https://api.opennave.top/v1beta/models/gemini-3.5-flash:streamGenerateContent?alt=sse&key=$OPENNAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"parts": [{"text": "写一首关于编程的俳句。"}]}
    ]
  }'

事件格式 ​

OpenAI 事件 ​

OpenAI 格式发送 data: 行，流结束时发送 data: [DONE]。

text
data: {"type":"response.output_item.added",...}
data: {"type":"response.content_part.added",...}
data: {"type":"response.output_text.delta","delta":"你好"}
data: {"type":"response.output_text.delta","delta":"世界"}
data: {"type":"response.output_text.done",...}
data: {"type":"response.completed",...}

Anthropic 事件 ​

Anthropic 格式使用 event: 和 data: 字段。

text
event: message_start
data: {"type":"message_start","message":{...}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你好"}}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}}

event: message_stop
data: {"type":"message_stop"}

Gemini 事件 ​

Gemini SSE 流同样发送 data: 行，每个数据块带有 candidates 数组。用量一般会出现在最后一个数据块的 usageMetadata 中。

text
data: {"candidates":[{"content":{"parts":[{"text":"你好"}],"role":"model"}}]}

data: {"candidates":[{"content":{"parts":[{"text":"世界"}],"role":"model"},"finishReason":"STOP"}],"usageMetadata":{...}}

持续读取至结束事件，不要在收到第一个文本块后中断连接，以便获得完整输出与准确用量。

最佳实践 ​

处理不完整数据块 ​

SSE 数据可能被拆分到多个 TCP 分段。解析器应缓冲传入内容，并按完整的 \n\n 分隔符拆分事件，而不能假设一次网络读取就是完整事件。

设置超时 ​

流式调用连接会持续到生成完成。客户端读取超时建议不低于 5 分钟：

python
import httpx
from openai import OpenAI

client = OpenAI(
    base_url="https://api.opennave.top/v1",
    api_key="YOUR_OPENNAVE_API_KEY",
    timeout=httpx.Timeout(300.0, connect=10.0),
)

处理连接中断 ​

捕获连接与超时异常。非幂等请求发生中断时，应保存已接收的部分输出并提示用户；可优先使用 SDK 内置重试能力。

优化界面渲染 ​

在浏览器界面中应缓冲增量文本，并按固定间隔或 requestAnimationFrame 刷新，而不要每收到一个增量事件就重新渲染整个视图。

关联文档 ​