把 AI 能力做成 API 给别人用：契约、配额与文档

对外开放 AI 能力会把不稳定性一起放大。本文给出 AI API 契约该多写的三条、对外的配额与限流底线、文档必须写「不会什么」、可观测与支持要求，以及五条上线前检查。

把 AI 能力开放出去，等于把"不稳定"一起开放了

内部用的 AI 功能出问题，最多是自己挨一下；**开放成 API 给外部用**，问题会被放大：

调用方按"确定性服务"的预期来用你 ✗，而你的输出是概率性的 ✗。所以契约要写得更保守。

常规 API 契约写：路径、参数、返回结构、错误码 ✔。**AI API 还要写**：

1. **不确定性声明**：输出可能变化（同样的输入不同次调用可能不同 ✔）；

2. **不保证的内容**：不保证事实正确、不保证合规可用、不保证时效 ✔（并写明"调用方需自行校验"✔）；

3. **版本与变更策略**：模型/提示词版本怎么升、升之前提前多久通知 ✔（外部依赖最怕静默变更 ✗）。

**没有这三条，调用方会把你的输出当真理** ✗。

**默认额度**必须是**保守**的 ✔（新接入方先给小额，按需提升 ✔）；

**超额行为要明确**：拒绝还是排队？返回什么状态码与重试建议？✔

**成本可见**：调用方能查自己的用量与配额 ✔（否则投诉会直接打到你这里 ✔）。

另外要**按调用方隔离**（见多租户限流那篇 ✔）：一个接入方的脚本不能拖垮其他接入方 ✔。

对外文档最常见的缺陷是**只写能力清单** ✗。应显式列出：

**不支持**的输入（超长、二进制、特定语言）；

**不适合**的场景（需要精确计算、需要法律责任认定）；

**已知的失败模式**（长文档中段遗漏、罕见专有名词误写）；

**推荐用法**（先给结论、如何校验、如何降级）。

**写清"不会什么"能显著降低支持成本** ✔，也减少误用 ✗。

给调用方一个**请求 id**，他们报问题时能直接定位 ✔；

提供**状态页**（可用性、延迟、已知问题）；

记录**调用方维度的失败率与拒绝率**，用于主动通知（别等他们发现 ✗）。

1. 契约里有不确定性声明、版本策略、"需自行校验"提醒 ✔；

2. 默认配额保守、超额行为明确 ✔；

3. 文档写了不支持与不适合的场景 ✔；

4. 按调用方隔离（配额/并发/成本）✔；

5. 有一键**熔断**与**降级**通知渠道 ✔。

> 一个没读过你内部实现的人，只看契约与文档，能否正确预期"什么时候该信、什么时候该校验" ✔？

> 答不上，就说明契约没写够 ✗。