alterlab-shap

SHAP（SHapley Additive exPlanations）

概述

SHAP 是一种统一的方法，利用合作博弈论中的 Shapley 值解释机器学习模型的输出。本技能为以下任务提供全面指导：

• 计算任意模型类型的 SHAP 值
• 创建可视化图表以了解特征重要性
• 调试并验证模型行为
• 分析公平性和偏见
• 在生产环境中实现可解释 AI

SHAP 适用于所有模型类型：基于树的模型（XGBoost、LightGBM、CatBoost、Random Forest）、深度学习模型（TensorFlow、PyTorch、Keras）、线性模型和黑盒模型。

何时使用本技能

当用户询问以下内容时，触发本技能：

• “解释模型中哪些特征最重要”
• “生成 SHAP 图”（waterfall、beeswarm、bar、scatter、force、heatmap 等）
• “为什么我的模型会做出这个预测？”
• “为我的模型计算 SHAP 值”
• “使用 SHAP 可视化特征重要性”
• “调试模型行为”或“验证模型”
• “检查模型是否存在偏见”或“分析公平性”
• “比较不同模型的特征重要性”
• “实现可解释 AI”或“为模型添加解释”
• “了解特征交互”
• “创建模型解释仪表板”

不会触发的情况

场景	改用
在模型建立之前分析原始数据集（分布、缺失情况、相关性）	alterlab-eda
构建、交叉验证或调优模型本身	alterlab-scikit-learn
估计某项干预的因果效应（SHAP 描述的是模型关联，而非因果关系）	alterlab-causal-inference

快速入门指南

第 1 步：选择合适的解释器

决策树：

1. 基于树的模型？（XGBoost、LightGBM、CatBoost、Random Forest、Gradient Boosting）

   • 使用 shap.TreeExplainer（快速、精确）

2. 深度神经网络？（TensorFlow、PyTorch、Keras、CNN、RNN、Transformer）

   • 使用 shap.DeepExplainer 或 shap.GradientExplainer

3. 线性模型？（线性／逻辑回归、GLM）

   • 使用 shap.LinearExplainer（速度极快）

4. 其他模型？（SVM、自定义函数、黑盒模型）

   • 使用 shap.KernelExplainer（与模型无关，但速度较慢）

5. 不确定？

   • 使用 shap.Explainer（自动选择最佳算法）

所有解释器类型的详细信息，请参见 references/explainers.md。

第 2 步：计算 SHAP 值

import shap

# Example with tree-based model (XGBoost)
import xgboost as xgb

# Train model
model = xgb.XGBClassifier().fit(X_train, y_train)

# Create explainer
explainer = shap.TreeExplainer(model)

# Compute SHAP values
shap_values = explainer(X_test)

# The shap_values object contains:
# - values: SHAP values (feature attributions)
# - base_values: Expected model output (baseline)
# - data: Original feature values

第 3 步：可视化结果

全局理解（整个数据集）：

# Beeswarm plot - shows feature importance with value distributions
shap.plots.beeswarm(shap_values, max_display=15)

# Bar plot - clean summary of feature importance
shap.plots.bar(shap_values)

单个预测：

# Waterfall plot - detailed breakdown of single prediction
shap.plots.waterfall(shap_values[0])

# Force plot - additive force visualization
shap.plots.force(shap_values[0])

特征关系：

# Scatter plot - feature-prediction relationship
shap.plots.scatter(shap_values[:, "Feature_Name"])

# Colored by another feature to show interactions
shap.plots.scatter(shap_values[:, "Age"], color=shap_values[:, "Education"])

所有图表类型的完整指南，请参见 references/plots.md。

核心工作流

本技能支持多种常见工作流。请选择与当前任务匹配的工作流。

工作流 1：基本模型解释

目标：了解模型预测受哪些因素驱动

步骤：

1. 训练模型并创建合适的解释器
2. 计算测试集的 SHAP 值
3. 生成全局重要性图（beeswarm 或 bar）
4. 查看主要特征关系（scatter 图）
5. 解释特定预测（waterfall 图）

示例：

# Step 1-2: Setup
explainer = shap.TreeExplainer(model)
shap_values = explainer(X_test)

# Step 3: Global importance
shap.plots.beeswarm(shap_values)

# Step 4: Feature relationships
shap.plots.scatter(shap_values[:, "Most_Important_Feature"])

# Step 5: Individual explanation
shap.plots.waterfall(shap_values[0])

工作流 2：模型调试

目标：发现并修复模型问题

步骤：

1. 计算 SHAP 值
2. 找出预测错误
3. 解释分类错误的样本
4. 检查是否存在意料之外的特征重要性（数据泄漏）
5. 验证特征关系是否合理
6. 检查特征交互

详细的调试工作流，请参见 references/workflows.md。

工作流 3：特征工程

目标：利用 SHAP 洞察改进特征

步骤：

1. 计算基线模型的 SHAP 值
2. 识别非线性关系（可进行转换的候选特征）
3. 识别特征交互（可添加交互项的候选特征）
4. 构建新特征
5. 重新训练并比较 SHAP 值
6. 验证改进效果

详细的特征工程工作流请参见 references/workflows.md。

工作流 4：模型比较

目标：比较多个模型，选择最佳且可解释的方案

步骤：

1. 训练多个模型
2. 分别计算各模型的 SHAP 值
3. 比较全局特征重要性
4. 检查特征排名的一致性
5. 分析不同模型对特定预测的结果
6. 根据准确性、可解释性和一致性进行选择

详细的模型比较工作流请参见 references/workflows.md。

工作流 5：公平性与偏差分析

目标：检测并分析模型在不同人口群体中的偏差

步骤：

1. 确定受保护属性（性别、种族、年龄等）
2. 计算 SHAP 值
3. 比较不同群体的特征重要性
4. 检查受保护属性的 SHAP 重要性
5. 识别代理特征
6. 如果发现偏差，则实施缓解策略

详细的公平性分析工作流请参见 references/workflows.md。

工作流 6：生产环境部署

目标：将 SHAP 解释集成到生产系统中

步骤：

1. 训练并保存模型
2. 创建并保存解释器
3. 构建解释服务
4. 创建提供预测及解释的 API 端点
5. 实施缓存和优化
6. 监控解释质量

详细的生产环境部署工作流请参见 references/workflows.md。

核心概念

SHAP 值

定义：SHAP 值用于量化各特征对预测的贡献，其衡量方式是相对于模型输出期望值（基线）的偏差。

属性：

• 可加性：SHAP 值之和等于预测值与基线之间的差值
• 公平性：基于博弈论中的 Shapley 值
• 一致性：如果某个特征变得更重要，其 SHAP 值会增大

解读：

• 正 SHAP 值 → 特征使预测值升高
• 负 SHAP 值 → 特征使预测值降低
• 绝对值 → 特征影响的强度
• SHAP 值之和 → 预测值相对于基线的总变化

示例：

Baseline (expected value): 0.30
Feature contributions (SHAP values):
  Age: +0.15
  Income: +0.10
  Education: -0.05
Final prediction: 0.30 + 0.15 + 0.10 - 0.05 = 0.50

背景数据 / 基线

用途：表示“典型”输入，用于建立基线预期

选择方式：

• 从训练数据中随机抽样（50-1000 个样本）
• 或使用 kmeans 选择有代表性的样本
• 对于 DeepExplainer/KernelExplainer：使用 100-1000 个样本可兼顾准确性与速度

影响：基线会影响 SHAP 值的大小，但不会影响相对重要性

模型输出类型

关键考量：了解模型的输出内容

• 原始输出：适用于回归或树模型边际值
• 概率：适用于分类概率
• 对数几率：适用于逻辑回归（sigmoid 函数之前）

示例：XGBoost 分类器默认解释边际输出（对数几率）。若要解释概率，请在 TreeExplainer 中使用 model_output="probability"。

常见模式

模式 1：完整模型分析

# 1. Setup
explainer = shap.TreeExplainer(model)
shap_values = explainer(X_test)

# 2. Global importance
shap.plots.beeswarm(shap_values)
shap.plots.bar(shap_values)

# 3. Top feature relationships
top_features = X_test.columns[np.abs(shap_values.values).mean(0).argsort()[-5:]]
for feature in top_features:
    shap.plots.scatter(shap_values[:, feature])

# 4. Example predictions
for i in range(5):
    shap.plots.waterfall(shap_values[i])

模式 2：群组比较

# Define cohorts
cohort1_mask = X_test['Group'] == 'A'
cohort2_mask = X_test['Group'] == 'B'

# Compare feature importance
shap.plots.bar({
    "Group A": shap_values[cohort1_mask],
    "Group B": shap_values[cohort2_mask]
})

模式 3：错误调试

# Find errors
errors = model.predict(X_test) != y_test
error_indices = np.where(errors)[0]

# Explain errors
for idx in error_indices[:5]:
    print(f"Sample {idx}:")
    shap.plots.waterfall(shap_values[idx])

    # Investigate key features
    shap.plots.scatter(shap_values[:, "Suspicious_Feature"])

性能优化

速度考量

解释器速度（从快到慢）：

1. LinearExplainer - 几乎即时
2. TreeExplainer - 非常快
3. DeepExplainer - 适用于神经网络，速度快
4. GradientExplainer - 适用于神经网络，速度快
5. KernelExplainer - 速度慢（仅在必要时使用）
6. PermutationExplainer - 非常慢，但准确

优化策略

针对大型数据集：

# Compute SHAP for subset
shap_values = explainer(X_test[:1000])

# Or use batching
batch_size = 100
all_shap_values = []
for i in range(0, len(X_test), batch_size):
    batch_shap = explainer(X_test[i:i+batch_size])
    all_shap_values.append(batch_shap)

针对可视化：

# Sample subset for plots
shap.plots.beeswarm(shap_values[:1000])

# Adjust transparency for dense plots
shap.plots.scatter(shap_values[:, "Feature"], alpha=0.3)

针对生产环境：

# Cache explainer
import joblib
joblib.dump(explainer, 'explainer.pkl')
explainer = joblib.load('explainer.pkl')

# Pre-compute for batch predictions
# Only compute top N features for API responses

故障排查

问题：解释器选择错误

问题：对树模型使用 KernelExplainer（速度慢且没有必要） 解决方案：始终对基于树的模型使用 TreeExplainer

问题：背景数据不足

问题：DeepExplainer/KernelExplainer 使用的背景样本过少 解决方案：使用 100-1000 个有代表性的样本

问题：单位混淆

问题：将对数几率解读为概率 解决方案：检查模型输出类型；了解数值表示的是概率、对数几率还是原始输出

问题：图表无法显示

问题：Matplotlib 后端问题 解决方案：确保正确设置后端；必要时使用 plt.show()

问题：过多特征导致图表杂乱

问题：默认的 max_display=10 可能过多或过少 解决方案：调整 max_display 参数或使用特征聚类

问题：计算速度慢

问题：为超大型数据集计算 SHAP 解决方案：抽取子集、使用批处理，或确保使用专用解释器（而非 KernelExplainer）

与其他工具集成

• Jupyter：交互式 force 图会内联渲染；图表通过 show=True（默认值）显示。要保存到文件，请传入 show=False，然后调用 plt.savefig(...)。
• MLflow / 实验跟踪：使用 mlflow.log_figure(plt.gcf(), "shap_beeswarm.png") 记录图表，并将每个特征的 np.abs(shap_values.values).mean(0) 作为指标记录。完整代码片段见 references/workflows.md（MLOps 集成）。
• 生产 API：使用 joblib 持久化模型和解释器，在收到请求时重新计算 SHAP，并返回基准值和各特征的贡献值。完整的 ExplanationService 类见 references/workflows.md（工作流 7）。

参考文档

按需加载这些文档（通过 Read），了解此 SKILL.md 之外的详细内容：

• references/explainers.md — 所有解释器类（构造函数参数、支持的模型、方法、性能）。选择解释器或需要确切参数时加载。
• references/plots.md — 所有绘图函数（参数、适用场景、图表选择指南）。选择或调整可视化图表时加载。
• references/workflows.md — 完整的分步工作流（调试、特征工程、模型比较、公平性、深度学习、生产、时间序列、MLOps）。执行多步骤任务时加载。
• references/theory.md — Shapley 值数学、公理、计算算法、条件期望，以及与 LIME/置换重要性/Gini 重要性的比较。回答理论问题时加载。

最佳实践总结

1. 选择合适的解释器：尽可能使用专用解释器（TreeExplainer、DeepExplainer、LinearExplainer）；除非必要，否则避免使用 KernelExplainer

2. 先看全局，再看局部：先通过 beeswarm/bar 图了解整体情况，再深入查看 waterfall/scatter 图以了解详情

3. 使用多种可视化图表：不同图表能揭示不同见解；结合全局（beeswarm）+ 局部（waterfall）+ 关系（scatter）视图

4. 选择合适的背景数据：使用训练数据中 50-1000 个有代表性的样本

5. 理解模型输出单位：明确解释的是概率、对数几率还是原始输出

6. 结合领域知识进行验证：SHAP 展示的是模型行为；使用领域专业知识进行解读和验证

7. 优化性能：为可视化抽取子集，对大型数据集进行批处理，并在生产环境中缓存解释器

8. 检查数据泄漏：特征重要性异常偏高可能表明存在数据质量问题

9. 考虑特征相关性：对于冗余特征，使用 TreeExplainer 的相关性敏感选项或特征聚类

10. 牢记 SHAP 展示的是关联，而非因果关系：使用领域知识进行因果解读

安装

此技能中使用的现代 API——可调用的 explainer(X)（返回一个 Explanation 对象），以及 shap.plots.* 命名空间——要求 shap >= 0.41。当前版本为 0.52（2026 年 5 月；要求 Python ≥ 3.12 和 NumPy ≥ 2），截至 2026-09，0.53 处于候选发布阶段。在 uv 项目中固定版本：

# In a uv project (adds to pyproject.toml + uv.lock):
uv add "shap>=0.41" matplotlib

# Scratch / one-off run (ephemeral env, nothing persisted):
uv run --with "shap>=0.41" --with matplotlib python explain.py

（uv pip install 仅适用于已激活的 venv；建议使用 uv add / uv run --with，以便记录依赖。）

依赖项：numpy、pandas、scikit-learn、scipy 和 numba 会自动安装。matplotlib 是可选项（shap[plots] 扩展），因此在调用 shap.plots.* 之前，请按上述方式显式安装。

可选项：xgboost、lightgbm、catboost、tensorflow、torch（取决于模型类型）。

更多资源

• 官方文档：https://shap.readthedocs.io/
• GitHub 仓库：https://github.com/shap/shap
• 原始论文：Lundberg & Lee（2017）—“A Unified Approach to Interpreting Model Predictions”
• Nature MI 论文：Lundberg et al.（2020）—“From local explanations to global understanding with explainable AI for trees”

此技能全面介绍了 SHAP，涵盖各种用例和模型类型下的模型可解释性。