跳到正文
九维AI开放平台使用文档

开发指南

流式 API 使用指南:SSE、usage 与连接中断处理

配置 stream=true 和无缓冲读取,说明 SSE 用量、流式费用核对、超时与中断后避免重复提交的方法。

成都九维数创科技有限公司 · 文档团队更新于 约 6 分钟阅读
本页目录
  1. 什么是流式响应
  2. curl 流式示例
  3. 在程序中处理事件
  4. 如何核对流式费用
  5. 连接中断后不要盲目重试

什么是流式响应#

流式请求允许结果分段返回。它能缩短看到首段文字的等待,但不会减少模型实际生成的 Token,也不代表整个任务已经成功结束。

本站支持常见 SSE 和 NDJSON 响应的用量捕获。实际响应格式取决于模型与协议,不同协议的结束事件和用量字段可能不同。

curl 流式示例#

先按第一条 API 请求设置环境变量并复制真实模型 ID。下面用 -N 关闭 curl 输出缓冲。

bash
curl --silent --show-error -N \
  "$AI_ROUTER_API_BASE/chat/completions" \
  -H "Authorization: Bearer $AI_ROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role":"user","content":"给我一个三步写周报的方法。"}],
    "max_tokens": 256,
    "stream": true
  }'

生成请求会产生费用。OpenAI 兼容 SSE 通常使用 data: 行,应按事件边界解析;不要假设每次 TCP 读取就是一个完整 JSON。

在程序中处理事件#

维护读取缓冲区,按协议分割完整事件。解析正文增量与用量事件,收到结束信号后再标记完成;同时处理错误事件、连接中断和超时。

浏览器应用应通过自己的后端保管 API Key,避免把服务密钥嵌入公开前端代码。程序超时设置要区分首响应等待和整个输出过程。

如何核对流式费用#

平台会尝试获取上游 usage。不同协议可能把最终用量放在结束事件、单独事件或累计字段中。看到部分文字不说明最后用量已经收到。

若上游不返回可解析用量或连接提前中断,当前计费可能回退至预估值。需要核对时保存请求 ID 并查看平台账单,不要只用前端显示字数估算 Token。

连接中断后不要盲目重试#

中断只说明本地没有收到完整结果,上游可能仍已执行。自动重放同一付费 POST 可能生成第二笔调用。先查看用量状态、是否有异步任务 ID及已有结果,再决定下一步。

持续只有整段输出时,检查客户端、代理层和网关是否缓冲;如果非流式正常而流式不正常,先用这个最小示例区分网络与客户端问题。

准备好开始了吗?

在控制台选择账户可用模型,先用一条简单请求验证配置。

打开 Playground