Skip to main content
先跑通最小请求，再把失败处理和资源边界接入应用。本页是应用接入建议，不提供部署的统一限额、延迟或计费保证。

​
超时与请求生命周期

示例中的超时值只服务演示。SDK 的读取超时未必是整次调用总时限；业务应另设总截止时间。断开连接或客户端取消不保证上游已停止，特别是持久化媒体任务。

​
并发与重试

为应用、租户和模型分别设置有界并发与有限排队长度，队列满时返回可重试提示。一个 RAG 请求可能包含多次嵌入、重排和生成，需要计入整体请求预算。工具闭环也要设置调用轮数和每轮数量上限。 本站示例禁用 SDK 自动重试，方便观察一次请求的结果。生产重试策略见错误与重试：考虑 429、短暂 5xx、带随机抖动的退避以及已有的网关重试。避免客户端、应用任务队列和网关各自无界重试。HTTP 400 的参数错误应修正请求；收到部分输出后不能把第二次生成静默拼接为同一条回答。

​
代理与输出

SSE 接入应检查反向代理缓冲、压缩、空闲超时及响应逐步到达情况；只设置客户端 stream: true 无法消除代理缓冲。WebSocket 要验证协议升级和连接寿命。媒体上传需要客户端、代理与网关共同允许对应请求体大小，不能只调整其中一层。 最终文本检查完成状态、拒答和内容类型；结构化输出再检查业务 Schema；工具输出按调用 ID 关联；多媒体文件检查 MIME 与实际内容。HTTP 200、有效 JSON、成功下载都不是完整的业务验收。

​
可观测性与数据

记录应用请求 ID、网关返回的 X-Gateway-Request-Id（兼容头为 X-Oneapi-Request-Id）、时间与时区、模型、端点、状态、首事件耗时、总耗时和重试次数。前置代理拦截的响应可能没有网关 ID。不要假设 SDK _request_id 一定读取这些自定义头。 日志默认排除密钥、Cookie、完整输入、媒体 Base64 和压缩密文。按用途决定是否保存历史、工具结果与任务 ID，并与部署方确认网关日志、上游保留和产物 URL 有效期。store: false 只是一项请求选项。

​
真实服务验收表

  1. 同一地址、令牌和模型完成发现与最小调用；检查模型实际支持的协议。
  2. 分别验证文本、SSE、工具、结构化和多模态等业务确实使用的能力。
  3. 验证无权限、限流、超时、断流、拒答及任务失败路径；确认不会无限重试或重复发布。
  4. 使用代表性内容评估准确率、延迟和资源使用；记录版本与路由配置，升级后对比。
  5. 先小流量切换，保留可恢复配置；异常时降级到已验证的业务路径，而不是任意换模型。
本仓库 npm run check 只检查文档和本机模拟响应；以上真实服务验收需要部署地址与测试权限，尚未执行。GitHub、托管账号和域名连接留到发布阶段。 Read in English 模型路由 · 限流与重试 · 请求观测 · AI SDK