3. API 基础概念：RESTful API 设计原则、API 网关作用、模型服务化架构
在模型风险管理系统中，API 是模型服务与外部调用方之间的契约。理解 RESTful 设计原则、API 网关的职责以及模型服务化架构，是构建可靠流量控制与熔断机制的前提。本节从这三个维度展开，为后续的限流、熔断策略打下基础。
3.1 RESTful API 设计原则
REST（Representational State Transfer）是一种基于 HTTP 协议的架构风格，强调资源导向、无状态和统一接口。在模型服务场景中，遵循 RESTful 原则可以提升 API 的可读性、可维护性和可扩展性。
| 原则 | 说明 | 模型服务示例 |
|---|---|---|
| 资源导向 URI | 使用名词表示资源，避免动词 | /api/v1/models/credit-risk/predict |
| HTTP 方法语义 | GET 查询、POST 创建/执行、PUT 全量更新、DELETE 删除 | POST /predict 执行推理 |
| 无状态 | 每个请求包含所有必要信息，服务端不保存会话 | 请求头携带认证 Token 和请求 ID |
| 统一响应格式 | 使用标准 HTTP 状态码 + JSON 结构 | 200 OK + {"prediction": 0.87} |
| 版本管理 | 通过 URI 或请求头标识 API 版本 | /api/v2/models/... |
实践建议：模型推理接口推荐使用 POST 方法，因为请求体通常包含特征向量、元数据等复杂结构，且幂等性要求较低。避免使用 GET 传递大量特征参数，防止 URI 长度超限。
3.2 API 网关的核心作用
API 网关是模型服务架构中的统一入口，负责请求路由、流量控制、安全认证和协议转换。在模型风险管理场景中，网关是实施限流、熔断、降级策略的核心组件。
关键认知：在模型风险管理中，API 网关不仅是技术组件，更是风险控制策略的执行点。限流阈值、熔断窗口、降级响应等策略参数，应当与模型风险等级（如高、中、低）联动配置，实现差异化的流量治理。
3.3 模型服务化架构
模型服务化架构将训练好的机器学习模型封装为独立的微服务，通过标准 API 对外提供推理能力。典型的架构包含以下层次：
- 接入层：API 网关，负责请求路由、限流、熔断、认证。
- 服务层：模型推理服务，每个模型独立部署，支持水平扩展。
- 存储层：特征存储、模型版本仓库、推理日志存储。
- 监控层：指标采集（QPS、延迟、错误率）、告警、可视化。
3.4 模型服务化架构全景
下图展示了模型服务化架构的完整组件及其交互关系，突出流量路径和风险控制点。
风险提示：模型服务化架构中，每一层都可能成为故障点。接入层网关的限流策略配置不当可能导致正常请求被误杀；服务层模型推理超时可能引发网关熔断；存储层特征缓存失效会导致推理延迟飙升。建议在架构设计阶段就为每一层定义明确的熔断阈值和降级方案。
3.5 模型服务 API 设计示例
以下是一个符合 RESTful 原则的模型推理 API 设计示例，包含请求和响应结构：
POST /api/v1/models/credit-risk/predict
Content-Type: application/json
Authorization: Bearer <token>
X-Request-ID: 7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d
{
"features": {
"age": 35,
"income": 80000,
"credit_score": 720,
"loan_amount": 150000,
"employment_years": 8
},
"options": {
"return_probability": true,
"top_k_explanations": 3
}
}
Response 200 OK:
{
"prediction": "approved",
"probability": 0.92,
"explanations": [
{"feature": "credit_score", "importance": 0.45},
{"feature": "income", "importance": 0.30},
{"feature": "loan_amount", "importance": 0.15}
],
"model_version": "v2.1.0",
"inference_time_ms": 45,
"request_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d"
}
设计要点：请求头中的
X-Request-ID 用于全链路追踪，便于在熔断或限流发生时定位问题。响应中包含 model_version 和 inference_time_ms，方便监控系统采集模型性能指标，为动态调整限流阈值提供数据支撑。