shap值计算前须确保模型支持predict/predict_proba接口，pipeline需用pipeline.predict，pytorch/tensorflow模型要设eval()并禁梯度，树模型优先用treeexplainer；summary_plot需校验feature_names与数据列序一致；force_plot推荐matplotlib模式避免js依赖问题；treeexplainer结果更准，kernelexplainer需足够采样与合理背景数据。
SHAP值计算前必须确认模型可调用 predict 或 predict_proba
SHAP解释器本身不关心你用的是什么模型，只认一个接口：能输入 X（二维数组），输出一维预测值（回归）或概率向量（分类）。很多自定义封装模型、Keras子类模型、带预处理的Pipeline对象，直接传给 shap.Explainer 会报 AttributeError: 'xxx' object has no attribute 'predict'。
- 先手动测试：
model.predict(X_sample)能否跑通，X_sample必须和训练时维度一致（包括是否含截距项、是否标准化） - sklearn Pipeline 需用
pipeline.predict，别传pipeline.steps[-1][1]——后者可能漏掉前面的 StandardScaler 或 OneHotEncoder - PyTorch/TensorFlow 模型要设为
eval()模式并禁用梯度，否则shap.DeepExplainer会卡在 forward 里 - LightGBM/XGBoost 建议用
shap.TreeExplainer，比通用Explainer快 10 倍以上，且支持原生缺失值处理
shap.summary_plot 显示空白或坐标错乱？检查 feature_names 和数据顺序
shap.summary_plot 对输入数据非常敏感：它默认按列顺序把 X 的每一列当成一个特征，并用你传入的 feature_names 标注横轴。一旦两者不一致，就会出现“变量名对不上”“重要性条纹全挤在左边”“y轴显示 Feature 0 到 Feature N”这类问题。
-
feature_names必须是 Python list，不能是 pandas Index（哪怕看着一样）；建议显式转：list(X.columns) - 如果用了
pd.get_dummies或ColumnTransformer，特征顺序很可能和原始X不同，务必用transformer.get_feature_names_out()获取真实列名 - 传给
summary_plot的shap_values必须和X行数一致；抽样时两个要同步：X_sample = X.iloc[idxs]; shap_vals_sample = shap_vals[idxs] - 分类任务中，
shap_values是 list of array（每类一个），画某类需指定：shap.summary_plot(shap_vals[1], X)
单样本解释图（force_plot）加载慢或报错 Failed to display widget
shap.force_plot 默认用 JavaScript 渲染交互式图表，本地 Jupyter 运行时常见两类失败：一是没装 shap 的 JS 依赖，二是 notebook 内核和前端通信异常。这不是代码写错了，而是环境链路断了。
Python 3.14.2是Python编程语言在2025年12月5日发布的稳定版本，属于3.14系列的第二个维护更新。该版本包含了18项修复，重点解决了多进程、数据类及正则表达式等模块的回归问题，并修复了CVE-2025-12084等安全漏洞。此版本标志着自由线程模式（移除GIL）正式获得官方支持，是Python发展的重要里程碑。
- 优先用静态图替代：
shap.plots.force(shap_vals[0], X.iloc[0], matplotlib=True)（注意是shap.plots.force，不是旧版shap.force_plot） - 确保
shap_vals是 numpy array，不是稀疏矩阵；若来自TreeExplainer，它返回的是 dense，但KernelExplainer可能返回 sparse，加一步.toarray() - force_plot 的 base_value（预期值）必须是标量；多分类场景下，
shap_vals[0].base_values是数组，得取对应类：base_val = shap_vals[0].base_values[1] - 别在 for 循环里反复调
force_plot——它每次生成完整 HTML，内存涨得快，导出 PDF 时容易崩溃
TreeExplainer 和 KernelExplainer 结果差异大，该信谁
差异不是 bug，是原理决定的：前者基于模型结构做精确 Shapley 计算（快、准、仅限树模型），后者用采样逼近（慢、有方差、通用但不稳定）。如果你看到同一特征在两种解释器下重要性排序相反，大概率是 KernelExplainer 的采样不足或背景数据没选好。
- TreeExplainer 无需 background dataset，直接传训练集或验证集即可；KernelExplainer 必须传有意义的 background（如
X_train.mean(0).reshape(1, -1)或随机采 100 行） - KernelExplainer 的
n_samples至少设为2 * X.shape[1]，低于这个值，特征重要性会严重失真 - 对类别型特征，KernelExplainer 容易把 one-hot 后的多个列当成独立变量，误判“某个 dummy 列重要”，实际应合并看原始变量
- 当模型本身有强非线性交互（比如树深度 > 8），TreeExplainer 更可靠；若模型是线性回归，用
LinearExplainer，比 Kernel 快且无噪声
真正难的不是跑出 SHAP 图，是让 shap_values 和你心里想解释的那个“模型行为”严格对齐——从数据进模型的那一刻起，每一步预处理、填充、编码、裁剪，都得在解释流程里复现一遍。漏掉任何一环，图看起来再漂亮，也是在解释另一个模型。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
