shap

SHAP

使用 SHAP 说明已拟合的预测模型如何将输入映射为输出。使用现代 shap.Explanation API，明确说明所解释的输出和背景分布，并在解读之前验证每项解释。

此技能与 SHAP 0.52.0（发布于 2026-05-28）保持一致。该版本要求 Python 3.12 或更高版本。

操作规则

1. 解释固定且经过评估的模型；不要用 SHAP 替代预测验证。
2. 使用留出数据或明确标注的分析行进行解释。仅从适当的训练总体或参考总体中选择背景行。
3. 说明所解释的输出：回归值、原始边际值、概率、对数损失、logit，或其他模型方法的输出。
4. 将解释保留为 shap.Explanation 对象。调用 explainer(X)；仅在维护旧版代码时使用 .shap_values(X)。
5. 对于多输出模型，使用表格图前先选择一个输出：explanation[..., output_index]。
6. 检查 base_values + values.sum(...) 是否与所解释的确切模型输出一致。
7. 将 SHAP 视为模型在特定屏蔽方式／背景选择下的行为描述。它不能证明因果关系、公平性、补救方案或科学机制。
8. 在检查输入形状、预处理、模型版本、输出空间和行顺序之前，切勿忽略加性检查失败。
9. 不要加载不可信的 pickle、joblib、模型或解释器工件；这些格式在反序列化时可能执行代码。

安装

创建隔离环境并固定使用文档所述版本：

uv venv --python 3.12
source .venv/bin/activate
uv pip install "shap[plots]==0.52.0"

shap[plots] 会安装绘图依赖项。添加与项目兼容版本的已拟合模型包。若需兼容较旧的 Python 版本，请阅读 references/migration.md，不要在未说明的情况下安装其他 SHAP 版本。

调试 API 不匹配问题前，先确认环境：

import platform
import shap

print("Python:", platform.python_version())
print("SHAP:", shap.__version__)

标准工作流

1. 定义解释目标

记录：

• 模型和预处理版本；
• 所解释的确切可调用对象或模型方法；
• 输出名称／索引和单位；
• 评估行；
• 背景／参考总体；
• 掩码器和解释器算法；
• SHAP 和模型库版本。

对于分类器，确定任务需要的是原始边际值还是概率。不同模型系列的默认值各不相同；切勿根据图表颜色或符号推断单位。

2. 选择解释器和掩码器

自动调度足够时，从 shap.Explainer(model, masker) 开始。如果解释器的假设或输出控制很重要，则实例化专用解释器。

情况	首选方案	重要限制
受支持的树集成模型	TreeExplainer	model_output="probability" 和 "log_loss" 需要采用干预式屏蔽并提供背景数据
线性模型	LinearExplainer	掩码器决定采用干预式行为还是考虑相关性的行为
特征空间较小	ExactExplainer	不受约束的特征数量增加时，计算成本会迅速上升
通用表格可调用对象	PermutationExplainer	预算至少要覆盖一次完整的正向／反向排列
分层特征组、文本或图像	PartitionExplainer	分区树会改变合作博弈
可微神经网络	DeepExplainer 或 GradientExplainer	需要测试框架支持、输出形状和背景选择
旧版 Kernel SHAP 工作流	KernelExplainer	通常比针对特定模型的方法慢得多

请参阅 references/explainers.md 中的详细选择指南。如果特征存在相关性、结构化、稀疏或按语义分组，请参阅 references/data-maskers.md。

3. 计算现代 Explanation

这个完整的二分类示例使用了显式背景数据，并选择正类输出：

import numpy as np
import shap
from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import train_test_split

X, y = load_breast_cancer(as_frame=True, return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
    X,
    y,
    test_size=0.2,
    stratify=y,
    random_state=7,
)

model = RandomForestClassifier(
    n_estimators=200,
    min_samples_leaf=3,
    random_state=7,
    n_jobs=-1,
).fit(X_train, y_train)

background = shap.sample(X_train, 100, random_state=7)
explainer = shap.Explainer(model, background, algorithm="tree")
all_outputs = explainer(X_test)

# sklearn tree classifiers expose one output per class.
positive = all_outputs[..., 1]
assert positive.values.shape == X_test.shape

reconstructed = np.asarray(positive.base_values) + positive.values.sum(axis=1)
expected = model.predict_proba(X_test)[:, 1]
np.testing.assert_allclose(reconstructed, expected, rtol=1e-5, atol=1e-6)

shap.plots.beeswarm(positive, max_display=15)
shap.plots.waterfall(positive[0], max_display=15)

输出形状取决于模型：

• 单个表格输出：(samples, features)；
• 多个表格输出：(samples, features, outputs)；
• 多个模型输入：通常是数组或解释组成的列表；
• 图像／文本解释：特征轴遵循输入表示；如果存在输出轴，则在最后一个轴上选择输出。

对于现代多输出数组，不要使用 0.45 之前的模式 values[class_index]。请使用 values[..., class_index] 或直接切片 Explanation。

4. 必要时控制树模型输出语义

对于受支持的树分类器，必须显式指定概率空间解释：

background = shap.sample(X_train, 200, random_state=7)

explainer = shap.TreeExplainer(
    model,
    data=background,
    feature_perturbation="interventional",
    model_output="probability",
)
probability_exp = explainer(X_test)

在 SHAP 0.52 中：

• feature_perturbation="auto" 在提供背景数据时使用干预式语义，否则使用依赖树路径的语义；
• 概率和对数损失输出模式仅支持干预式语义；
• 如果有意使用保真度较低的树模型近似，请向 explainer(X, approximate=True) 传递 approximate=True；不要将其传递给构造函数。

5. 有意使用模型无关的可调用对象

传入将要解释其输出的确切可调用对象：

masker = shap.maskers.Independent(background, max_samples=100)
explainer = shap.Explainer(
    model.predict_proba,
    masker,
    algorithm="permutation",
    output_names=[str(label) for label in model.classes_],
    seed=7,
)

budget = 2 * X_test.shape[1] + 1
all_outputs = explainer(X_test.iloc[:20], max_evals=budget)
positive = all_outputs[..., 1]

如果估算结果不稳定，可增大 max_evals，通过更多排列求平均。请在报告中保留种子、背景样本和评估预算。

6. 根据问题选择图表，而非仅使用现成图表

问题	图表
哪些特征的平均归因幅度最大？	shap.plots.bar(exp)
全局来看，方向、幅度和观测值如何变化？	shap.plots.beeswarm(exp)
为什么某个预测与其基线不同？	shap.plots.waterfall(exp[i])
某个特征的归因如何随其取值变化？	shap.plots.scatter(exp[:, feature])
解释是否呈现样本级模式？	shap.plots.heatmap(exp)
预定义队列之间有哪些描述性差异？	shap.plots.bar(exp.cohorts(labels).abs.mean(0))
哪些词元或图像区域对输出有贡献？	shap.plots.text(exp) 或 shap.plots.image(exp)

自定义或保存图表前，请阅读 references/plots.md。

7. 在报告结果时说明局限

至少应报告：

• 输出及单位；
• 基线／参考群体；
• 解释器和掩码器；
• 样本数量及选择方式；
• 输出索引／名称；
• 加性误差或适用的近似诊断；
• 已知的相关／分组特征；
• 结果是局部、汇总还是特定队列的；
• 明确说明结果不代表因果关系。

常见任务

全局和局部分析

使用全局图表定位重要模式，使用散点图检查这些模式，并使用局部图表调查选定的行。不要只选择视觉上特别显著的行而不记录选择规则。

多分类模型

尽可能设置 output_names，检查 explanation.output_names，并在绘图前切片选择一个输出：

class_exp = explanation[..., "class_name"]
# or
class_exp = explanation[..., class_index]

切勿跨类别对有符号归因求平均。比较不同类别时，应使用相同的模型、行、背景数据、输出空间和聚合方式。

队列、子组分析和公平性

SHAP 可比较模型在不同队列中如何使用特征，但这并不是公平性测试。受保护特征的 SHAP 幅度较小，并不能排除代理歧视；移除受保护特征也不能证明公平。应将归因分析与性能、校准、错误率及适用于具体领域的公平性指标结合起来。

有关队列构建、模型比较、错误分析、对数损失解释、监控和生产记录，请参阅 references/workflows.md。

文本和图像

使用领域掩码器，而不是将词元或像素视为普通的独立列：

• 使用 shap.maskers.Text(tokenizer) 和 PartitionExplainer 处理词元组；
• 使用 shap.maskers.Image(...) 和 PartitionExplainer 处理图像区域；
• 对计算开销较大的多输出模型使用 outputs=... 限制输出。

请阅读 references/modalities.md，了解当前示例和输出形状指南。

故障排查顺序

1. 打印 Python、SHAP、模型库、NumPy 和框架的版本。
2. 确认模型接收的转换后列、顺序、数据类型和缺失值表示，与训练时完全一致。
3. 打印 values.shape、base_values.shape、data.shape、feature_names 和 output_names。
4. 确认所选输出及其单位。
5. 按相同顺序对相同行重新计算预测。
6. 测试较小的批次和有代表性的背景数据。
7. 只有完成以上步骤后，才调查特定软件包的兼容性或近似设置。

请使用 references/troubleshooting.md 排查可加性错误、形状不匹配、类别特征、流水线、深度学习框架、绘图和性能问题。

附带脚本

运行一个确定性、自包含的表格示例，该示例会写入重要性数据、元数据和图表：

uv run --no-project --python 3.12 --with "shap[plots]==0.52.0" \
  skills/shap/scripts/tabular_report.py --output-dir /tmp/shap-report

该脚本不会下载数据或反序列化模型。请将其作为模板阅读，然后替换内置数据集和模型，同时保留输出选择和可加性验证。

参考索引

文件	何时加载
references/explainers.md	选择或配置解释器时
references/data-maskers.md	选择背景数据、掩码语义或特征组时
references/plots.md	选择、组合或保存可视化时
references/workflows.md	运行审计、比较、群组、监控或生产工作流时
references/modalities.md	解释文本、图像或深度模型时
references/migration.md	更新旧版 SHAP 代码或支持较旧的 Python 时
references/theory.md	解释估计目标、保证、依赖关系、交互和局限性时
references/troubleshooting.md	诊断运行时、形状、可加性和兼容性问题时

主要来源

• 文档：https://shap.readthedocs.io/en/latest/
• API 参考：https://shap.readthedocs.io/en/latest/api.html
• 发行说明：https://shap.readthedocs.io/en/latest/release_notes.html
• 代码仓库：https://github.com/shap/shap

相关技能

• alphagenome：查询任意 GRCh38 单核苷酸变异的预计算 AlphaGenome Atlas 效应（AVI 分数，含 Phred 和 18 个 SHAP 特征归因……）