模型 API

它是什么

模型 API 是应用通过网络访问模型推理能力的一组服务契约。它规定请求发到哪里、如何鉴权、输入和生成配置怎样表达、响应与错误采用什么结构，以及客户端如何选择版本。模型是完成推理的能力主体，API 是访问这项能力的边界，SDK 则是帮助程序按该边界构造请求的工具；三者不能互换。[S1][S2]

为什么需要它

清楚的 API 契约把应用代码与模型服务的内部实现隔开。产品可以稳定地提交消息、接收流式结果、识别限流或超时，并把请求关联到日志和成本记录；服务方也能在契约内演进实现。如果团队只针对一次成功响应写代码，生产中的错误、版本变化和重试很快会变成用户可见故障。

它如何工作

客户端先把业务输入转换成 API 所需的消息、模型标识与参数，附上服务端安全保存的凭证和版本信息，再发送请求。服务验证契约并返回完整响应、数据流或结构化错误；客户端按错误类别决定重试、回退或停止，同时记录请求标识、用量和各阶段延迟。官方 SDK 可以处理序列化、认证和部分重试细节，但应用仍要负责超时、权限、业务幂等和可观测性。[S1][S2]

必须澄清的误会

模型 API ≠ 模型服务。 模型 API 是对外的调用契约，模型服务是内部把它撑起来的部署与容量管理；换服务实现不该改变契约。

模型 API ≠ API 调用。 模型 API 问的是推理结果，调用方是应用；API 调用是「按协议发请求」这个动作本身，可以指向任意服务。

契约稳定不等于服务稳定。 字段没变不代表可用性没变。上层按契约写代码，同时也必须按失败来设计：超时、限流、降级都要有默认动作。

真实例子

客服摘要服务收到一段对话后，由后端调用模型 API。成功时，前端逐段显示摘要；收到限流错误时，后端按带抖动的退避策略有限重试；请求超过 8 秒仍未返回时取消调用并提示稍后重试。日志保存内部任务号、供应商请求标识、模型版本、令牌用量和耗时，但不保存密钥，也不把完整敏感对话写入普通日志。

什么时候适合与不适合

需要快速接入托管模型、按量扩展或比较供应商时，模型 API 是常见入口。严格的数据驻留、离线运行或硬实时要求可能更适合自托管推理。共同使用 HTTP 和 JSON 不代表不同 API 语义等价：消息角色、工具协议、错误类型、上下文限制和版本规则都可能不同。抽象层可以减少重复代码，却不能消除这些差异。[S1][S2]

亲自试一下

为“把客服对话总结成三条行动项”画出一张请求契约表，至少包含输入、鉴权位置、成功响应、流式事件、四类错误、超时、最大重试和请求追踪字段。再写两个契约测试：一个验证正常流结束，一个验证限流后只重试规定次数。若密钥出现在浏览器代码里，或未知错误会无限重试，方案还未通过。

接下来学什么

先用AI 应用理解 API 在完整产品中的位置，再学习函数调用连接外部工具；需要在多个模型之间选择时继续学习模型路由，需要处理服务故障时学习备用模型。

来源与修订

请求头、版本、SDK、流式和请求标识等契约细节参考 Anthropic API 概览 [S1]；API 文档、契约、安全、限额、可靠性目标和追踪原则参考 Google Cloud AI/ML 可靠性指南 [S2]。端点、字段、鉴权方式、限额、模型标识和 SDK 行为变化较快，接入时必须复核当前版本文档。