把 AI 能力开放出去，等于把"不稳定"一起开放了
内部用的 AI 功能出问题，最多是自己挨一下；开放成 API 给外部用，问题会被放大：
调用方按"确定性服务"的预期来用你 ✗，而你的输出是概率性的 ✗。所以契约要写得更保守。
一、契约（比普通 API 多写三条）
常规 API 契约写：路径、参数、返回结构、错误码 ✔。AI API 还要写：
- 不确定性声明：输出可能变化（同样的输入不同次调用可能不同 ✔）；
- 不保证的内容：不保证事实正确、不保证合规可用、不保证时效 ✔（并写明"调用方需自行校验"✔）；
- 版本与变更策略：模型/提示词版本怎么升、升之前提前多久通知 ✔（外部依赖最怕静默变更 ✗）。
没有这三条，调用方会把你的输出当真理 ✗。
二、配额与限流（对外的三条底线）
- 默认额度必须是保守的 ✔（新接入方先给小额，按需提升 ✔）；
- 超额行为要明确：拒绝还是排队？返回什么状态码与重试建议？✔
- 成本可见：调用方能查自己的用量与配额 ✔（否则投诉会直接打到你这里 ✔）。
另外要按调用方隔离（见多租户限流那篇 ✔）：一个接入方的脚本不能拖垮其他接入方 ✔。
三、文档要写"不会什么"
对外文档最常见的缺陷是只写能力清单 ✗。应显式列出：
- 不支持的输入（超长、二进制、特定语言）；
- 不适合的场景（需要精确计算、需要法律责任认定）；
- 已知的失败模式（长文档中段遗漏、罕见专有名词误写）；
- 推荐用法（先给结论、如何校验、如何降级）。
写清"不会什么"能显著降低支持成本 ✔，也减少误用 ✗。
四、可观测与支持
- 给调用方一个请求 id，他们报问题时能直接定位 ✔；
- 提供状态页（可用性、延迟、已知问题）；
- 记录调用方维度的失败率与拒绝率，用于主动通知（别等他们发现 ✗）。
五、五条上线前检查
- 契约里有不确定性声明、版本策略、"需自行校验"提醒 ✔；
- 默认配额保守、超额行为明确 ✔；
- 文档写了不支持与不适合的场景 ✔；
- 按调用方隔离（配额/并发/成本）✔；
- 有一键熔断与降级通知渠道 ✔。
一条判据
一个没读过你内部实现的人，只看契约与文档，能否正确预期"什么时候该信、什么时候该校验" ✔？
答不上，就说明契约没写够 ✗。