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”或“为模型添加解释”
• “了解特征交互”
• “创建模型解读仪表板”

快速入门指南

第 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 值
• 一致性：若某特征变得更 important，其 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 值的量级，但不影响相对重要性

模型输出类型

关键考量：理解模型输出的是什么

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

示例：XGBoost 分类器默认解释 margin 输出（对数几率）。若要解释概率，请在 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 Notebooks

• 交互式 force 图可无缝运行
• 使用 show=True（默认）内联显示图表
• 结合 markdown 进行叙述性说明

MLflow / 实验跟踪

import mlflow

with mlflow.start_run():
    # Train model
    model = train_model(X_train, y_train)

    # Compute SHAP
    explainer = shap.TreeExplainer(model)
    shap_values = explainer(X_test)

    # Log plots
    shap.plots.beeswarm(shap_values, show=False)
    mlflow.log_figure(plt.gcf(), "shap_beeswarm.png")
    plt.close()

    # Log feature importance metrics
    mean_abs_shap = np.abs(shap_values.values).mean(axis=0)
    for feature, importance in zip(X_test.columns, mean_abs_shap):
        mlflow.log_metric(f"shap_{feature}", importance)

生产 API

class ExplanationService:
    def __init__(self, model_path, explainer_path):
        self.model = joblib.load(model_path)
        self.explainer = joblib.load(explainer_path)

    def predict_with_explanation(self, X):
        prediction = self.model.predict(X)
        shap_values = self.explainer(X)

        return {
            'prediction': prediction[0],
            'base_value': shap_values.base_values[0],
            'feature_contributions': dict(zip(X.columns, shap_values.values[0]))
        }

参考文档

此技能包含按主题组织的全面参考文档：

references/explainers.md

所有解释器类的完整指南：

• TreeExplainer - 对基于树的模型进行快速、精确的解释
• DeepExplainer - 深度学习模型（TensorFlow、PyTorch）
• KernelExplainer - 与模型无关（适用于任何模型）
• LinearExplainer - 对线性模型进行快速解释
• GradientExplainer - 基于梯度的神经网络解释
• PermutationExplainer - 对任何模型精确但缓慢

包括：构造函数参数、方法、支持的模型、何时使用、示例、性能注意事项。

references/plots.md

全面的可视化指南：

• Waterfall 图 - 单个预测的分解
• Beeswarm 图 - 带值分布的全局重要性
• Bar 图 - 简洁的特征重要性摘要
• Scatter 图 - 特征与预测的关系及交互
• Force 图 - 交互式加性 force 可视化
• Heatmap 图 - 多样本比较网格
• Violin 图 - 以分布为重点的替代方案
• Decision 图 - 多类预测路径

包括：参数、用例、示例、最佳实践、图表选择指南。

references/workflows.md

详细的工作流和最佳实践：

• 基本模型解释工作流
• 模型调试与验证
• 特征工程指导
• 模型比较与选择
• 公平性与偏差分析
• 深度学习模型解释
• 生产部署
• 时间序列模型解释
• 常见陷阱与解决方案
• 高级技术
• MLOps 集成

包括：分步说明、代码示例、决策标准、故障排除。

references/theory.md

理论基础：

• 来自博弈论的 Shapley 值
• 数学公式与性质
• 与其他解释方法（LIME、DeepLIFT 等）的联系
• SHAP 计算算法（Tree SHAP、Kernel SHAP 等）
• 条件期望与基线选择
• 解释 SHAP 值
• 交互值
• 理论局限与注意事项

包括：数学基础、证明、比较、高级主题。

使用指南

何时加载参考文件：

• 当用户需要关于特定解释器类型或参数的详细信息时，加载 explainers.md
• 当用户需要详细的可视化指导或探索图表选项时，加载 plots.md
• 当用户有复杂的多步骤任务（调试、公平性分析、生产部署）时，加载 workflows.md
• 当用户询问理论基础、Shapley 值或数学细节时，加载 theory.md

默认方法（不加载参考文件）：

• 使用此 SKILL.md 进行基本解释和快速上手
• 提供标准工作流和常见模式
• 如需更多细节，可加载参考文件

加载参考文件：

# To load reference files, use the Read tool with appropriate file path:
# /path/to/shap/references/explainers.md
# /path/to/shap/references/plots.md
# /path/to/shap/references/workflows.md
# /path/to/shap/references/theory.md

最佳实践总结

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

2. 先全局，再局部：先使用蜂群图/条形图进行整体理解，再深入瀑布图/散点图查看细节

3. 使用多种可视化：不同的图能揭示不同的洞见；结合全局（蜂群图）+ 局部（瀑布图）+ 关系（散点图）视图

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

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

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

7. 针对性能进行优化：可视化时对子集采样，大数据集分批处理，在生产环境中缓存解释器

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

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

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

安装

# Basic installation
uv pip install shap

# With visualization dependencies
uv pip install shap matplotlib

# Latest version
uv pip install -U shap

依赖项：numpy、pandas、scikit-learn、matplotlib、scipy

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

其他资源

• 官方文档：https://shap.readthedocs.io/
• GitHub 仓库：https://github.com/slundberg/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 在各类用例和模型类型中的模型可解释性应用。