内容
# 模型可解释性技能
Claude Code MCP 技能，解释任何已训练的预测模型。指向一个模型文件和一个特征 CSV，说 **"分析这个模型"**，然后获得一份完整的 9 节可解释性报告，内含嵌入的图表 — 无需编写代码。
适用于 scikit-learn、PyTorch、XGBoost、LightGBM、随机森林等任何其他与 sklearn 兼容的估计器。
---
## 支持的模型类型
| 模型 | 文件格式 | SHAP 方法 |
| --- | --- | --- |
| scikit-learn 估计器 / 管道 | `.pkl` | TreeExplainer 或 KernelExplainer |
| PyTorch `nn.Module` | `.pt` / `.pth` | KernelExplainer |
| XGBoost（原生 Booster） | `.json` / `.ubj` | TreeExplainer |
| XGBoost（sklearn API） | `.pkl` | TreeExplainer |
| LightGBM（原生 Booster） | `.txt` / `.bin` | TreeExplainer |
| LightGBM（sklearn API） | `.pkl` | TreeExplainer |
| 任意 joblib/pickle 模型 | `.pkl` | KernelExplainer 备用 |
---
## 生成内容
| 方法 | 学习内容 |
| --- | --- |
| **Sobol / 功能方差分析** | 哪些特征驱动输出方差，以及多少来自交互作用与主效应（S1、ST、S2） |
| **排列重要性** | 每个特征被打乱时，模型分数下降多少 |
| **SHAP** | 每项观察的归因 — 全局蜂群图、重要性条形图、交互热图 |
| **SHAP 依赖图** | 特征 A 的效应如何随特征 B 变化（前 Sobol S2 对） |
| **ALE / PDP + ICE** | 效应形状图 — ALE 在特征相关时自动选择 |
| **跨方法共识** | 所有三种方法都高度排名的特征是稳健重要的 |
该技能自动选择合适的方法：
- 相关特征 → ALE 而非 PDP（避免外推偏差）
- 树模型 → TreeExplainer（快速、精确的 SHAP + 交互值）
- 其他模型 → KernelExplainer（模型无关）+ SHAP 值相关热图作为交互代理
- 所有分析运行一次（`precompute_all`），然后缓存 — 后续问题在毫秒内回答
---
## 快速开始
### 步骤 1 — 注册 MCP 服务器
```bash
claude mcp add model-explainability \
-e EXPLAIN_OUTPUT_DIR="$HOME/Desktop/nn-explainability-skill/output" \
-- python3 "$HOME/Desktop/nn-explainability-skill/mcp_server/server.py"
```
### 步骤 2 — 安装依赖项（在 Claude Code 中执行）
```
set up
```
### 步骤 3 — 运行分析
```
analyse this model:
model: examples/credit_risk_artifacts/model_state_dict.pt
data: examples/credit_risk_artifacts/X_test_processed.csv
features: examples/credit_risk_artifacts/feature_names.json
```
然后提出纯语言问题：
```
What drives this model?
Are there any feature interactions?
What is the effect of loan_int_rate?
Why was row 42 scored high?
Write a summary report.
```
---
## 示例输出
`examples/credit_risk_artifacts/explain_output/` 目录包含一个预生成的 PyTorch 贷款等级模型报告：
- [`explainability_report.md`](examples/credit_risk_artifacts/explain_output/explainability_report.md) — 完整的 9 节报告
- 前 5 个特征的 ALE 效应形状图
- SHAP 蜂群图、重要性条形图和交互热图
- SHAP 依赖图，用于前 Sobol S2 交互对
关键发现：`loan_int_rate` 占主导地位，Sobol ST = 0.97 和 SHAP 平均 |φ| = 0.78。`cb_person_default_on_file_num` 和 `loan_status` 是所有三种方法的一致驱动因素。
---
## 项目结构
```
nn-explainability-skill/
├── SKILL.md # Claude Code 技能定义
├── INSTRUCTIONS.md # 安装和用法指南
├── setup.sh # 自动依赖安装程序
├── regen_report.py # 从缓存结果重新生成报告
│
├── mcp_server/
│ ├── server.py # 9 个 MCP 工具
│ ├── requirements.txt
│ └── explainability/
│ ├── utils.py # 模型加载（PyTorch/sklearn/XGBoost/LightGBM）、
│ │ # 预测包装器、相关性诊断
│ ├── sobol.py # Sobol / 功能方差分析（SALib）
│ ├── pdp_ice.py # PDP + ICE（scikit-learn）
│ ├── ale.py # ALE（PyALE）
│ ├── shap_explain.py # SHAP 全局 + 局部 + 交互图
│ ├── report.py # 9 节 Markdown 报告组装器
│ └── cache.py # 预计算缓存（cache.json + shap_values.npy）
│
├── examples/
│ └── credit_risk_artifacts/ # 示例：PyTorch MLP，信用风险
│ ├── README.md
│ ├── nn_model_generator.ipynb
│ ├── model_state_dict.pt
│ ├── X_test_processed.csv
│ ├── feature_names.json
│ └── explain_output/ # 预生成的分析结果和报告
│
└── references/
├── sobol_sensitivity_notes.md
├── pdp_ale_ice_notes.md
├── neural_network_anova_notes.md
└── model_risk_explainability_template.md
```
---
## MCP 工具
| 工具 | 描述 |
| --- | --- |
| `precompute_all` | 运行完整管道一次，并将所有内容缓存到磁盘 |
| `ask` | 从缓存中回答任何纯语言问题（无需重新计算） |
| `run_full_analysis` | 端到端分析，直接返回 Markdown 报告 |
| `run_sobol_analysis` | Sobol S1 / ST (+ S2 如果 `second_order=True`) |
| `run_pdp_ice` | 指定特征的 PDP + ICE |
| `run_ale` | 指定特征的 ALE |
| `run_shap_importance` | 全局 SHAP 重要性 + 蜂群图 |
| `run_shap_interactions` | 顶级成对 SHAP 交互（树模型） |
| `explain_single_observation` | 单行局部 SHAP 瀑布图 |
---
## 依赖项
```
torch
numpy
pandas
matplotlib
scikit-learn
shap
PyALE
SALib
joblib
mcp[cli]
```
通过 `setup.sh` 自动安装，或手动安装：
```bash
pip install -r mcp_server/requirements.txt
```
---
## 参考文献
- **信用风险数据集和端到端管道：** [orbenh/credit-risk-scoring-end-to-end](https://github.com/orbenh/credit-risk-scoring-end-to-end) — 示例模型来源
- **Sobol 灵敏度分析：** Saltelli, A. et al. (2010). *Variance based sensitivity analysis of model output.* Computer Physics Communications.
- **SHAP：** Lundberg, S. & Lee, S.-I. (2017). *A unified approach to interpreting model predictions.* NeurIPS.
- **ALE：** Apley, D.W. & Zhu, J. (2020). *Visualizing the effects of predictor variables in black box supervised learning models.* JRSS-B.
- **可解释性 ML 书籍：** Molnar, C. (2022). [christophm.github.io/interpretable-ml-book](https://christophm.github.io/interpretable-ml-book)
