4. 模型接口设计原则：无状态性、幂等性、超时与重试机制、接口版本管理

模型接口不是普通的 RESTful API。它跑在推理集群上，每次调用都可能触发 GPU 计算、加载模型权重、甚至动态 batch。如果接口设计得糙，生产环境迟早给你颜色看。我这些年接手的 DLP 项目，出过问题的接口大多踩了同样的坑——状态泄漏、重复调用、超时不处理、版本混乱。咱们一个一个说透。

4.1 无状态性：接口的“失忆”是最好的记忆

说白了，就是每次请求都要自包含。接口不认上一次调用，不存 Session，不靠上下文。为什么必须这样？想想看，你调模型做文本分类，如果第一次请求传了个特征，第二次请求依赖第一次的结果——那负载均衡器把两次请求转发到不同 Pod 上，立马崩掉。

我在项目中遇到过一例：某风险评分接口为了“优化性能”，在服务端缓存了用户最近5条记录。结果 A/B 测试时，新版模型和旧版模型混跑，缓存里的上下文全乱套了。最后回滚到无状态设计，性能虽然降了一点，但正确率稳了。教训就是——模型接口不适合做有状态优化。

4.2 幂等性：同样的请求，同样的结果

幂等是个数学概念，放在接口里很简单：调用一次和调用一千次，对系统的影响是一样的。你可能会问：“模型预测又不是转账，为什么需要幂等？”

因为网络会丢包，客户端会超时重试，消息队列可能重复投递。如果你的接口不幂等，一次 PDF 脱敏请求被重试了3次，结果生成了3份脱敏结果——存储爆了，审计对不上。曾经有同事因为这个半夜被叫起来回滚，我印象很深。

实现幂等的常见做法：

• 请求 ID 去重：客户端生成唯一 request_id，服务端用 Redis 做天然去重，相同 ID 直接返回已处理结果。
• 结果不变性：对于纯预测接口，只要输入相同，模型输出就相同（不考虑随机种子）。那你只需保证接口内部没有副作用。
• 幂等键设计：用文档哈希、时间戳+随机数组合成幂等键，存入数据库或缓存。

4.3 超时与重试机制：别让调用方等到地老天荒

模型推理有时候很慢，尤其是大模型。一次请求耗时从 200ms 到 20s 都有可能。如果客户端不设超时，线程池会被慢慢占满，最终雪崩。超时设置是个平衡——太短容易误判失败，太长拖垮系统。

我以前处理过一个数据泄露检测接口，默认超时 60s。结果某个大文件深度分析占用了所有推理资源，其他正常请求全部排队超时。后来我把超时分成了两级：

层级	超时值	触发动作
连接超时	3s	快速失败，返回 503
读取超时	15s	返回 504，触发客户端重试
整体超时	30s	强制中断，记录慢请求日志

重试机制就更讲究了。别一失败就立马重试——那叫“自杀式重试”。正确的姿势：

• 指数退避：第一次等 1s，第二次 2s，第三次 4s…… 最多 5 次。
• 随机抖动：在退避时间上加减 0~500ms，防止所有客户端同时重试形成“惊群效应”。
• 业务区分：只有 500/502/503/504 才重试，4xx 错误不重试（除非是 429 限流）。

4.4 接口版本管理：别让用户的脚本一夜之间失效

模型会迭代，特征工程会改，输出格式会变。如果不做版本管理，更新模型就等于强制所有调用方升级。遇到不配合的合作方，你只能保持两套接口并存。版本管理不是锦上添花，是刚需。

我推荐两种主流方式：

方式	用法	适用场景
URL 路径版本	/v1/predict、/v2/predict	接口不兼容、输出结构变化
请求头版本	Accept-Version: v2	兼容性较好、只改行为不改结构

我个人习惯用 URL 路径版本。因为直观——查看日志、调试请求、写 API 文档都一目了然。但要注意，版本号只往上加，不删除旧版本，直到确认旧版本没人用了再下掉。我见过有人直接把 /v1 改成 /v2，结果下游 20 个业务线一起炸锅。

4.5 本章知识点结构

下面这张图把四个原则串起来了，你可以当做一个速查框架。

四个原则不是独立存在的。你想想看——无状态性让接口天然支持横向扩展，幂等性让重试变得安全，超时机制防止雪崩，版本管理让迭代不伤人。它们合在一起，才是生产级模型接口该有的样子。