基金量化定投选基系统

# CR-007: [Backlog] 批量推荐接口 SHAP 全量计算性能优化方案

---

| 字段 | 内容 |

|------|------|

| **CR ID** | CR-007 |

| **标题** | 批量推荐接口恢复 SHAP 归因计算（多进程并行优化） |

| **发起人** | Henry Lin (PM) |

| **日期** | 2026-04-11 |

| **状态** | ⏸️ Deferred (Backlog) |

| **互斥关系** | 本文档实施时，将自动废弃 **CR-006** |

| **影响范围** | 规约 6.1 节（批量推荐输出）、`src/inference.py` 批量分支、服务器 CPU/内存资源基线 |

### 1. 变更描述

**原状态（CR-006 锁定）**：批量接口 `top_features` 字段固定返回空字符串，以保障 RT < 3 秒。

**变更为**：批量接口对 DataFrame 中的所有基金，全量调用 SHAP TreeExplainer 计算特征贡献度。`top_features` 字段返回具体的 Top5 正向与 Top5 负向特征拼接字符串（格式与单基金接口保持绝对一致）。

### 2. 变更原因（业务诉求预判）

在高级量化投研场景中，投研人员希望在批量导出或列表页直视所有基金的“看多/看空理由”，而不愿逐个点击进入详情页。此需求将显著提升投研人员的筛选效率，但代价是牺牲接口响应时间。

### 3. 实施路径与性能保障方案（未来技术指导）

若要恢复此功能，严禁直接在主线程串行调用 SHAP，必须采用以下并行架构：

- **方案一（推荐）：多进程并行计算**

  - 使用 Python `concurrent.futures.ProcessPoolExecutor` 或 `joblib.Parallel`。

  - 将待预测的基金 DataFrame 切分为 N 个 Chunk（N 建议设为 CPU 物理核数的一半，如 12 核）。

  - 每个进程独立加载 LightGBM 模型（或利用共享内存减少拷贝），独立计算 Chunk 内的 SHAP 值。

  - **预期耗时**：1000 只基金，单次 5ms，12 进程并行理论耗时可降至 **0.5 - 0.8 秒**（含进程启动开销）。

- **方案二（高成本）：GPU 加速 SHAP**

  - 若实体机后续引入 GPU，需重新编译 GPU 版本的 LightGBM。

  - 使用 `shap.GPUTreeExplainer` 替代 `shap.TreeExplainer`，可实现毫秒级批量矩阵运算。

  - **预期耗时**：1000 只基金可压缩至 **< 100ms**。

### 4. 风险与代价评估（实施前必读）

- **内存暴增风险**：12 个子进程同时驻留，如果每个进程加载一份模型与特征字典，内存峰值可能瞬时增加 5-8 GB。需重新评估当前 64GB 内存的余量（特别是 Docker 容器的 cgroup 限制）。

- **SLA 放宽**：即使采用多进程，批量接口的 P99 RT 也将从当前的 200ms 放宽至 1000ms 左右，需与前端团队重新对齐加载动画或异步轮询机制。

- **CI 红线移除**：实施本 CR 时，必须同步移除 CI 中针对 `inference.py` 批量分支“严禁包含 `shap` 关键字”的 AST 拦截规则。