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