shap

SHAP 用于描述已拟合的预测模型如何将输入映射到输出。该技能基于现代 shap.Explanation API，要求明确被解释的输出和背景分布，并在解读前验证每个解释。它对齐 SHAP 0.52.0（2026-05-28 发布），该版本要求 Python 3.12 或更高。

用途

SHAP 用于解释和审计机器学习预测，帮助理解模型行为。它描述的是在特定掩码/背景选择下模型的行为，不建立因果关系、公平性、补救措施或科学机制。

主要能力

选择 SHAP 解释器和掩码器，包括 TreeExplainer、LinearExplainer、ExactExplainer、PermutationExplainer、PartitionExplainer、DeepExplainer、GradientExplainer、KernelExplainer 等。
计算现代 Explanation 对象，支持回归值、原始边际、概率、对数损失、logit 等输出。
验证特征归因，检查 base_values + values.sum(...) 与模型输出是否一致。
提供多种可视化：bar、beeswarm、waterfall、scatter、heatmap、text、image 等。
支持多输出模型、多分类模型、队列与子组分析、文本和图像解释。
提供确定性脚本 tabular_report.py，可生成重要性数据、元数据和图表。

使用方式

安装：创建隔离环境并固定版本：

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

shap[plots] 安装绘图依赖。添加与项目兼容的已拟合模型包版本。对于较旧的 Python 兼容性，请阅读 references/migration.md，而不是静默安装不同的 SHAP 版本。

确认环境：

import platform import shap

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

标准工作流：

定义解释目标：记录模型和预处理版本、被解释的可调用对象或模型方法、输出名称/索引和单位、评估行、背景/参考总体、掩码器和解释器算法、SHAP 和模型库版本。对于分类器，决定需要原始边际还是概率。
选择解释器和掩码器：从 shap.Explainer(model, masker) 开始，当自动分派足够时。当假设或输出控制重要时，实例化专用解释器。参考 references/explainers.md 和 references/data-maskers.md。
计算现代 Explanation：使用显式背景并选择正类输出。示例代码见官方文档。输出形状取决于模型：一个表格输出为 (samples, features)；多个表格输出为 (samples, features, outputs)；多个模型输入通常为数组或解释列表；图像/文本解释的特征轴遵循输入表示，输出选择在最后轴。不要使用 0.45 之前的 values[class_index] 模式。
控制树输出语义：对于支持的树分类器，概率空间解释必须显式设置。在 SHAP 0.52 中，feature_perturbation="auto" 在提供背景数据时使用干预语义，否则使用树路径依赖语义；概率和对数损失输出模式仅支持干预语义；如果故意使用低保真度树近似，请将 approximate=True 传递给 explainer(X, approximate=True)，不要传递给构造函数。
有意识地使用模型无关可调用对象：传递将被解释的精确可调用对象。增加 max_evals 以在估计不稳定时对更多排列取平均。在报告中保留种子、背景样本和评估预算。
可视化问题：根据问题选择图表，如 bar、beeswarm、waterfall、scatter、heatmap、text、image 等。阅读 references/plots.md 后再自定义或保存图形。
报告限制：至少报告输出和单位、基线/参考总体、解释器和掩码器、样本数量和选择、输出索引/名称、可加性误差或适用近似诊断、已知相关/分组特征、结果是局部、聚合还是队列特定，以及明确的非因果声明。

常见任务

全局和局部分析：使用全局图定位重要模式，散点图检查模式，局部图调查选定行。不要仅选择视觉上戏剧性的行而不记录选择规则。
多分类模型：设置 output_names，检查 explanation.output_names，并在绘图前切片输出。切勿跨类平均有符号归因。
队列、子组分析和公平性：SHAP 可以比较模型跨队列使用特征的方式，但这不是公平性测试。将归因分析与性能、校准、错误率和领域适当的公平性指标配对。
文本和图像：使用领域掩码器，而不是将标记或像素视为普通独立列。

故障排除顺序

打印 Python、SHAP、模型库、NumPy 和框架版本。验证模型接收与拟合时完全相同的转换列、顺序、dtype 和缺失值表示。打印 values.shape、base_values.shape、data.shape、feature_names 和 output_names。确认选定的输出和输出单位。在相同行和顺序上重新计算预测。测试较小的批次和代表性背景。然后才调查包特定的兼容性或近似设置。

捆绑脚本

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

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

适用场景

适用于需要解释和审计机器学习预测的场景，包括选择解释器和掩码器、计算和验证特征归因、全局与局部分析、多分类模型解释、队列与子组分析、文本和图像模型解释，以及生产环境中的监控和审计工作流。

限制

SHAP 描述的是在特定掩码/背景选择下模型的行为，不建立因果关系、公平性、补救措施或科学机制。不要加载不受信任的 pickle、joblib、模型或解释器工件，因为这些格式在反序列化期间可能执行代码。不要使用 SHAP 替代预测验证。在可加性失败时，必须先检查输入形状、预处理、模型版本、输出空间和行顺序，然后再考虑静默处理。

技能介绍