兼容 API 可靠性判断与上线前验收清单¶
最后核验：2026-07-19
适合：准备给聊天客户端、编程 Agent、知识库或生产应用配置兼容 API 的用户
[!NOTE] 本文适用于任何符合对应协议的 API。还没有测试 Key 时，可查看 教程配套 API。
需要先按计费口径与任务类型筛选模型时，可先看 NexoToken AI API 计费与模型选择专题；本文继续保留上线前的完整验收清单。
判断一个兼容接口是否可靠，不能只看价格、模型列表或一次“你好”。真正有用的结论来自一套可重复的验收：协议是否正确、能力是否完整、用量能否对账、错误能否恢复、数据和密钥是否可控。
1. 先定义你的验收目标¶
不同场景的最低标准不同：
| 场景 | 必测能力 |
|---|---|
| 普通聊天 | 非流式、流式、多轮上下文、停止原因 |
| 编程 Agent | 工具调用、多轮工具结果、长输出、429/5xx 恢复 |
| RAG / 知识库 | Chat、Embedding、向量维度、批量请求、引用链路 |
| 自动化工作流 | 超时、重试、幂等、并发、预算、日志脱敏 |
| 生产应用 | 上述能力 + SLA、监控、数据处理、密钥轮换和退出方案 |
先写下“必须可用”和“可以没有”的能力，避免被一长串模型名称带偏。
2. 第一层：服务信息是否透明¶
在发送任何敏感数据前，检查服务是否能明确回答：
- Base URL 和支持的协议是什么；
- 模型 ID 是否可以直接复制；
- Chat Completions、Responses、Messages 各支持到什么程度；
- 输入、输出、缓存和其他能力如何计费；
- 是否能查看请求用量、余额和充值记录；
- Key 能否创建多个、单独禁用和轮换；
- 数据是否记录、保存多久、用于什么目的；
- 服务中断、模型下线和退款如何处理；
- 文档或价格的最后更新时间是什么。
没有说明不一定代表不可用，但意味着你无法建立稳定预期，不适合直接承载重要业务。
3. 第二层：完成最小协议测试¶
建立独立测试环境变量：
export AI_BASE_URL="https://your-api.example.com/v1"
read -s AI_API_KEY
export AI_API_KEY
export AI_MODEL_ID="YOUR_MODEL_ID"
模型列表¶
/models 返回 404 不一定代表聊天不可用，因为部分服务不开放模型列表。但文档必须提供可用模型 ID，不能靠猜。
Chat Completions 最小请求¶
curl --fail-with-body --show-error \
"$AI_BASE_URL/chat/completions" \
-H "Authorization: Bearer $AI_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"model\": \"$AI_MODEL_ID\",
\"messages\": [{\"role\": \"user\", \"content\": \"只回复 OK\"}],
\"stream\": false,
\"temperature\": 0
}"
至少记录：
- HTTP 状态码；
- 响应耗时；
- 返回中的模型字段；
finish_reason或对应停止原因；- 输入、输出和总 Token；
- 请求 ID 或可供客服定位的追踪信息。
返回中的模型名称只是服务声明的一部分，不能单独作为模型身份的技术证明。评估应结合官方能力、稳定性、输出质量、账单和长期测试，不要用一道题下结论。
4. 第三层：协议能力逐项验证¶
“OpenAI 兼容”不是一个精确的功能版本。应建立测试矩阵：
| 能力 | 结果 | 备注 |
|---|---|---|
/models |
☐ | 可选，但应有其他模型目录 |
| Chat Completions 非流式 | ☐ | 检查结构与 usage |
| Chat Completions SSE | ☐ | 检查增量到达和结束标记 |
| Responses 非流式 | ☐ | 不能用 Chat 成功替代 |
| Responses 语义事件 | ☐ | 检查事件类型与完成事件 |
| Anthropic Messages | ☐ | 检查专用请求头和内容块 |
| 多轮上下文 | ☐ | 检查历史是否保留 |
| Tool Calling | ☐ | 完成调用和回传两轮 |
| JSON / 结构化输出 | ☐ | 用 Schema 校验结果 |
| 图片输入 | ☐ | 检查格式、大小和计费 |
| 长上下文 | ☐ | 检查截断与错误行为 |
| 最大输出 | ☐ | 检查停止原因，不只看长度 |
| Embedding | ☐ | 检查维度和批量顺序 |
| 429 重试 | ☐ | 尊重 retry-after |
| 流中错误 | ☐ | 200 后仍可能出现错误事件 |
详细测试载荷见流式输出、工具调用与长上下文完整测试，429 与恢复策略见限流、重试与并发控制。
5. 第四层：核对 Token 和账单¶
至少选三种请求：
- 很短的单轮文本；
- 带固定系统提示的重复请求；
- 一次较长的多轮对话或工具调用。
为每次请求保存：
允许存在统计展示延迟和不同 Tokenizer 造成的小差异，但计费规则必须能够解释。若客户端没有保存 usage，可先用 Apifox、Postman 或最小 SDK 脚本测试。
重点确认：
- 输入价和输出价是否分开；
- 缓存读写是否单独计价；
- 工具调用是否产生额外模型轮次；
- 失败、取消和中断请求如何计费；
- 展示单位是人民币、美元、积分还是 Token；
- 价格是每 1K 还是每 1M Token。
6. 第五层：做稳定性小样本¶
一次成功没有统计意义。建议在不制造无意义流量的前提下，分时段执行同一个轻量请求，例如连续三天、每天早中晚各几次。
记录：
| 指标 | 说明 |
|---|---|
| 成功率 | 2xx 且响应结构完整 |
| 首 Token 时间 | 流式请求从发送到首个有效增量 |
| 总耗时 | 请求完成时间 |
| 429 比例 | 是否经常触发速率限制 |
| 5xx / 529 比例 | 服务端或过载错误 |
| 中途断流 | 已返回 200 后流异常结束 |
| 输出完整率 | 是否频繁无故截断 |
不要使用大并发压测未知服务。未经许可的压力测试可能违反规则，也无法代表普通用户体验。
7. 第六层：验证错误是否可恢复¶
主动制造安全、低成本的错误：
- 把 Key 最后一个字符临时改错，预期得到 401；
- 使用不存在的模型 ID，预期得到明确的 400/404；
- 把 URL 多写一个
/v1，确认能定位路径错误； - 将输出上限设得很小，确认停止原因；
- 手动取消流式请求，观察客户端是否能正常结束；
- 在测试环境模拟 429，确认重试有上限并带抖动。
合格的调用端不应无限重试，也不应把所有 4xx 当成可重试错误。
建议的重试分类¶
| 类型 | 是否自动重试 | 做法 |
|---|---|---|
| 400 参数错误 | 否 | 修正请求 |
| 401 认证错误 | 否 | 检查或轮换 Key |
| 403 权限错误 | 否 | 检查模型和项目权限 |
| 404 路径/模型错误 | 否 | 检查 Base URL 与模型 ID |
| 408 / 网络超时 | 有限重试 | 指数退避 + 抖动 |
| 429 限流 | 是 | 优先遵守 retry-after |
| 500 / 502 / 503 / 529 | 有限重试 | 退避，超过上限后失败 |
8. 第七层：密钥和数据安全¶
Key 管理¶
- 测试、个人设备、服务器和生产环境分别创建 Key；
- 不在前端 JavaScript、移动端安装包或公开仓库中放长期 Key；
- 日志只保留 Key 指纹或末四位；
- 支持单 Key 撤销，定期轮换；
- CI 使用 Secret 管理，不写入 YAML 明文；
- 离职、设备丢失或疑似泄露时立即撤销。
完整的存放、无中断轮换和泄露处置流程见 API Key 安全与轮换。如果应用连接了 MCP Server，还应按 MCP 入门与安全配置限制工具和数据权限。
数据边界¶
确认请求可能包含哪些内容：源码、客户数据、合同、病历、密钥、内部 URL、数据库结果、工具返回值。编程 Agent 还可能自动读取整个工作区。
正式接入前至少回答：
- 请求和响应是否记录；
- 日志保存多久；
- 是否用于训练或产品改进；
- 数据存放地区和子处理方如何说明；
- 能否删除数据；
- 支持怎样的访问控制和审计。
无法确认时，只发送公开或合成测试数据。
9. 第八层：准备退出方案¶
可靠不只是“今天能用”，还包括“明天换得掉”：
- Base URL、Key 和模型 ID 使用环境变量；
- 不把供应商特有字段散落在业务代码中；
- 保存一套协议契约测试；
- 为关键任务准备备用模型，但不要静默切换导致质量变化；
- 导出非敏感配置和用量记录；
- 明确余额、退款、数据删除和账号注销方式。
不要只测试故障切换是否“有字返回”，还要检查工具调用、结构化输出和安全策略是否保持一致。
10. 上线评分表¶
每项 0～2 分：0 为不满足，1 为部分满足，2 为明确满足。
| 项目 | 分数 |
|---|---|
| 协议和模型文档清楚 | /2 |
| 核心请求结构正确 | /2 |
| 流式和工具调用完整 | /2 |
| Token 与账单可核对 | /2 |
| 错误信息和请求 ID 可排查 | /2 |
| 限流与重试行为明确 | /2 |
| Key 可分项目、撤销和轮换 | /2 |
| 数据处理规则明确 | /2 |
| 多时段稳定性达到要求 | /2 |
| 有迁移和退出方案 | /2 |
- 17～20 分： 可以进入受控生产试运行；
- 13～16 分： 适合个人或非关键任务，先补齐薄弱项；
- 9～12 分： 只适合小额测试；
- 0～8 分： 信息或能力不足，不建议承载真实数据。
分数只是决策记录，不是行业认证。关键项如数据安全、账单可解释性或协议完整性为 0 时，即使总分较高也不应直接上线。
11. 15 分钟快速版¶
时间有限时，至少完成：
- 文档明确 Base URL、协议和模型 ID；
- 独立测试 Key 已创建；
- 非流式文本请求成功；
- SSE 确实逐段到达；
- 目标工具能完成一次真实能力测试；
-
usage与控制台扣费可以解释； - 错误响应不泄露 Key，且有请求 ID；
- Key 可以立即撤销；
- 只发送了合成测试数据；
- 已记录测试日期与结果。
12. 官方参考¶
- OpenAI API Reference
- OpenAI：流式响应
- OpenAI：Function Calling
- Anthropic：流式 Messages
- Anthropic：API 错误
- Anthropic：速率限制
下一步：用Apifox / Postman 教程完成基础请求，再按完整能力测试验证 Agent 链路。