评分接口基础：典型架构、特征输入与分数输出

评分接口（Scoring API）是模型可解释性落地的核心载体。在生产环境中，模型通常以请求-响应（Request-Response）模式对外暴露服务，接收特征数据并返回预测分数。理解评分接口的典型架构、输入输出规范以及延迟/吞吐量要求，是后续嵌入可解释性逻辑的前提。

典型架构：请求-响应模式

评分接口最常见的架构是同步的请求-响应模式。客户端发送一个包含特征数据的 HTTP POST 请求，服务端完成模型推理后返回预测分数。该模式结构清晰、易于集成，适用于大多数实时或准实时评分场景。

下图展示了评分接口的核心组件与调用流程：

特征输入与分数输出

评分接口的输入输出设计直接影响可解释性的实现方式。标准化的特征输入和结构化的分数输出是可解释性模块能够无缝接入的基础。

特征输入规范

特征输入通常采用 JSON 格式，包含以下关键字段：

字段	类型	说明	示例
request_id	string	请求唯一标识，用于日志追踪	"req_20250321_001"
features	object	特征名-特征值键值对	{"age": 35, "income": 80000}
feature_version	string	特征工程版本号	"v2.1"
timestamp	string	请求发起时间（ISO 8601）	"2025-03-21T10:30:00Z"

分数输出规范

分数输出同样采用 JSON 格式，除了预测分数外，还应包含元数据以支持可解释性：

字段	类型	说明	示例
score	float	模型预测分数（0~1 或自定义范围）	0.87
decision	string	基于阈值的决策结果	"approve"
model_version	string	模型版本标识	"xgboost_v3.2"
explanation	object	可解释性信息（可选）	{"shap_values": {...}}

以下是一个完整的请求-响应示例：

// 请求
POST /api/v1/score
Content-Type: application/json

{
  "request_id": "req_20250321_001",
  "features": {
    "age": 35,
    "income": 80000,
    "credit_history_length": 10,
    "loan_amount": 150000,
    "employment_status": "employed"
  },
  "feature_version": "v2.1",
  "timestamp": "2025-03-21T10:30:00Z"
}

// 响应
HTTP/1.1 200 OK
Content-Type: application/json

{
  "score": 0.87,
  "decision": "approve",
  "model_version": "xgboost_v3.2",
  "explanation": {
    "top_positive_features": [
      {"feature": "income", "contribution": 0.32},
      {"feature": "credit_history_length", "contribution": 0.28}
    ],
    "top_negative_features": [
      {"feature": "loan_amount", "contribution": -0.15}
    ]
  }
}

延迟与吞吐量要求

评分接口的性能指标直接影响可解释性模块的设计复杂度。延迟（Latency）和吞吐量（Throughput）是两个核心约束。

延迟要求

不同业务场景对延迟的要求差异显著：

场景	目标延迟（P99）	可解释性影响
实时风控	< 50 ms	可解释性计算必须轻量，避免复杂 SHAP 计算
在线推荐	< 100 ms	可解释性可预计算或使用近似方法
批量评分	< 5 s	可解释性可完整计算，无严格时间约束

吞吐量要求

吞吐量通常以 QPS（Queries Per Second）衡量。高吞吐场景下，可解释性模块的资源消耗必须被严格管控：

• 低吞吐（< 100 QPS）：可解释性计算可以较为完整，甚至支持实时 SHAP 计算。
• 中吞吐（100~1000 QPS）：需要引入可解释性缓存、异步计算或降级策略。
• 高吞吐（> 1000 QPS）：可解释性信息通常通过离线预计算或采样方式提供，在线接口仅返回分数。

下图展示了延迟与吞吐量对可解释性策略选择的决策流程：