兼容接口的最小契约
客户端向 /v1/chat/completions 发送模型 ID、消息数组和生成参数，并通过 Authorization: Bearer API_KEY 鉴权。应用不应把上游供应商名称写死在业务逻辑中，而应从模型目录读取公共模型 ID。
基础调用示例
curl https://openrambo.com/v1/chat/completions \
-H "Authorization: Bearer $OPENRAMBO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL_ID",
"messages": [{"role": "user", "content": "解释向量检索"}],
"temperature": 0.3
}'密钥应存入服务端环境变量或密钥管理系统，不要出现在浏览器代码、移动应用包、公开仓库或错误日志中。
流式响应与取消
设置 stream: true 后，服务端通过 Server-Sent Events 持续返回增量内容。客户端要处理空增量、结束标记、网络中断和用户主动取消。取消请求时应同时关闭 HTTP 连接和本地读取循环，避免后台继续消耗 Token。
超时、限流与重试
| 情况 | 建议 |
|---|---|
| 连接失败或 502/503 | 使用指数退避并加入随机抖动，设置最大重试次数。 |
| 429 限流 | 优先读取 Retry-After；控制客户端并发，不要立即循环重试。 |
| 400 参数错误 | 不要重试，记录请求 ID并修正参数。 |
| 流式中断 | 默认不要透明重试生成请求，避免输出重复；由业务决定是否重新发起。 |
生产环境检查表
设置连接超时与总超时；限制最大输出 Token；为每个请求生成业务追踪 ID；记录模型、耗时、Token 和状态码；对用户输入做大小限制；对工具调用参数进行 JSON Schema 校验；对生成内容执行与业务风险匹配的审核。
常见问题
- 更换 Base URL 后是否需要修改 SDK？
- 多数 OpenAI SDK 支持自定义 Base URL，不需要修改 SDK 源码。
- 模型名称为什么可能变化？
- 供应商会发布新版本或下线旧版本。生产环境应使用平台公布的稳定模型 ID，并监控弃用通知。