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

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 拦截规则。