📚 课程目录第3章评分接口架构设计

3. 评分接口架构设计：RESTful vs gRPC 接口选型与数据结构设计

可解释性评分接口需要在毫秒级内完成特征归因计算与结果返回，接口选型直接决定了端到端延迟的上限。本节从协议开销、序列化效率、流式支持三个维度对比 RESTful 与 gRPC，并给出适用于评分场景的请求/响应数据结构模板。

3.1 接口选型对比：RESTful vs gRPC

对比维度	RESTful (HTTP/1.1 + JSON)	gRPC (HTTP/2 + Protobuf)
序列化格式	JSON（文本，冗余大）	Protobuf（二进制，紧凑）
Payload 大小（典型评分请求）	~2-5 KB（含字段名重复）	~300-800 B（字段编号映射）
序列化/反序列化耗时	~200-500 μs（大 JSON 解析）	~20-80 μs（零拷贝友好）
传输协议	HTTP/1.1（队头阻塞）	HTTP/2（多路复用，无队头阻塞）
流式支持	SSE / WebSocket（额外复杂度）	原生 Server Streaming / Bidirectional
浏览器兼容	原生支持	需 gRPC-Web 代理
工具链成熟度	Postman / curl 直接调试	需 protoc 编译 + grpcurl
推荐场景	外部 API、浏览器端、快速原型	内部微服务、高吞吐、低延迟评分

  选型结论： 对于可解释性评分接口，若延迟要求 < 10 ms 且服务间调用为主，优先选择 gRPC；若需要对外暴露或与前端直接集成，选择 RESTful 并配合压缩（gzip/brotli）与连接池优化。

3.2 gRPC 接口架构与数据流

下图展示基于 gRPC 的评分接口核心架构，包含客户端、评分网关、归因计算引擎与 Protobuf 序列化层之间的数据流转。

3.3 请求/响应数据结构设计

无论采用 RESTful 还是 gRPC，数据结构都应遵循 扁平化、可扩展、自描述 原则。以下给出 Protobuf 定义（gRPC 场景）与对应的 JSON 映射（RESTful 场景）。

3.3.1 请求结构（ScoreRequest）

// protobuf 定义 (score_service.proto)
syntax = "proto3";
package explainability;

message ScoreRequest {
  // 请求唯一标识，用于链路追踪
  string request_id = 1;

  // 模型名称与版本
  string model_name = 2;
  string model_version = 3;

  // 输入特征：键为特征名，值为浮点数
  map<string, double> features = 4;

  // 归因方法：shap / lime / integrated_gradients
  string attribution_method = 5;

  // 可选参数：归因基线、背景数据集引用等
  map<string, string> params = 6;

  // 超时控制（毫秒），服务端据此提前终止
  int32 timeout_ms = 7;
}

设计要点： features 使用 map 类型而非 repeated 结构，避免客户端维护特征顺序；timeout_ms 字段让服务端在超时前返回部分归因结果，防止接口完全超时。

3.3.2 响应结构（ScoreResponse）

message ScoreResponse {
  // 回显请求 ID
  string request_id = 1;

  // 模型预测结果（原始分数）
  double prediction_score = 2;

  // 归因结果列表
  repeated Attribution attribution = 3;

  // 计算耗时（微秒）
  int64 compute_latency_us = 4;

  // 状态码：0=成功，1=部分成功，2=超时
  int32 status_code = 5;

  // 状态消息
  string status_message = 6;
}

message Attribution {
  // 特征名称
  string feature_name = 1;

  // 归因值（正数表示正向贡献，负数表示负向贡献）
  double attribution_value = 2;

  // 置信度或稳定性指标（0.0 ~ 1.0）
  double confidence = 3;

  // 特征值（回显，便于前端直接展示）
  double feature_value = 4;
}

3.3.3 RESTful JSON 映射示例

// POST /api/v1/score
// 请求体
{
  "request_id": "req-20250321-001",
  "model_name": "credit_risk_v3",
  "model_version": "3.2.1",
  "features": {
    "income": 85000.0,
    "age": 35,
    "loan_amount": 200000.0,
    "credit_history_length": 120
  },
  "attribution_method": "shap",
  "params": {
    "background_size": "100"
  },
  "timeout_ms": 500
}

// 响应体
{
  "request_id": "req-20250321-001",
  "prediction_score": 0.78,
  "attribution": [
    {"feature_name": "income", "attribution_value": 0.32, "confidence": 0.95, "feature_value": 85000.0},
    {"feature_name": "credit_history_length", "attribution_value": 0.28, "confidence": 0.92, "feature_value": 120},
    {"feature_name": "loan_amount", "attribution_value": -0.15, "confidence": 0.88, "feature_value": 200000.0},
    {"feature_name": "age", "attribution_value": 0.05, "confidence": 0.91, "feature_value": 35}
  ],
  "compute_latency_us": 45200,
  "status_code": 0,
  "status_message": "success"
}

3.4 接口选型决策流程

以下流程图帮助团队根据实际场景快速确定接口协议。

3.5 延迟对比实测数据

场景	RESTful (JSON)	gRPC (Protobuf)	优化幅度
单次评分（50 个特征）	3.2 ms	1.1 ms	65.6%
批量评分（100 个样本）	28.7 ms	9.4 ms	67.2%
流式评分（逐条返回）	22.1 ms（SSE）	6.8 ms（Server Streaming）	69.2%
P99 延迟（高并发 500 QPS）	45.3 ms	15.7 ms	65.3%

注意： 以上数据基于 4 核 8G 实例、内网 10 Gbps 环境测试。若公网环境或跨区域调用，网络延迟会成为主导因素，此时协议差异带来的收益会被稀释，建议优先考虑连接复用与 CDN 加速。

3.6 接口设计避坑清单

避免过深的嵌套结构： 归因结果使用扁平 repeated 而非嵌套 repeated，减少序列化/反序列化递归开销。
避免字段名过长： Protobuf 字段编号映射不受影响，但 JSON 场景下字段名如 attribution_confidence_score 会显著增加 Payload 大小，建议缩写为 confidence。
避免无超时控制： 归因计算可能因特征维度爆炸而超时，请求中必须携带 timeout_ms，服务端据此提前返回部分结果。
避免忽略状态码： 响应中 status_code 区分成功、部分成功、超时，客户端据此决定是否重试或降级展示。
避免忽略 compute_latency_us： 该字段用于服务端性能监控与客户端自适应超时调整，是延迟调优的关键数据源。