SHAP Explanation 怎样区分样本特征与输出维度

拿到 shap.Explanation 后，最容易误读的不是某个特征的贡献值，而是 values 的轴。判断方法可以固定成一句话：先看 shape 的样本轴和特征轴，再看多输出模型是否在最后增加输出轴；feature_names 只负责解释特征轴，output_names 只负责解释输出轴。

单输出通常看成 [样本, 特征]，多输出通常看成 [样本, 特征, 输出]。不要因为最后一维也有数字，就把类别或回归目标误当成新的输入特征。

官方资料：https://shap.readthedocs.io/en/latest/generated/shap.Explanation.html

相关接口：https://shap.readthedocs.io/en/latest/generated/shap.Explainer.html

先把 Explanation 看成一组并行数组

Explanation 不是只有一块名为 values 的数组。它把贡献值、基准值、输入数据、特征名和输出名放在一个可以切片的对象里。阅读一个结果时，先把这些字段分工写下来，后面就不会把“数据值”和“贡献值”混在一起。

官方文档把 Explanation 描述为一组可并行切片的数组。因此，判断轴时不要只看 values 的长度，还要把 data、特征名和输出名放在同一张维度表里。

shape 怎么区分样本、特征和输出

以表格模型为例，输入 X 通常是“行代表样本、列代表特征”。单输出解释常见形状为 (n_samples, n_features)。例如 (120, 8) 表示 120 个样本、每个样本 8 个特征；它没有额外的输出轴。

多输出解释通常会把输出维度加在最后，形成 (n_samples, n_features, n_outputs)。例如 (120, 8, 3) 应当读作 120 个样本、8 个输入特征、3 个模型输出，而不是 120 个样本、24 个特征。

import numpy as np
import shap

# 这是构造 Explanation 的形状示例，数字只用于说明轴的含义。
values = np.zeros((120, 8, 3))
explanation = shap.Explanation(
    values=values,
    feature_names=[f"feature_{i}" for i in range(8)],
    output_names=["拒绝", "通过", "复核"],
)

# shape 的三个位置依次表示样本、特征和输出。
print(explanation.shape)

上面的代码是维度构造示例，不代表本文在本机执行了模型。按对象参数推导，explanation.shape 应为 (120, 8, 3)。关键不是打印本身，而是先确认你采用的轴约定，再把每个轴交给对应的标签字段。

单输出时为什么没有 output_names

回归模型或只解释一个输出的场景，经常只有 (n_samples, n_features) 两个轴。此时每一行是一条样本，每一列是一个特征；如果你要看第 5 条样本，使用 explanation[4] 就足够，结果仍然保留特征方向。

不要为了让形状“看起来统一”而强行添加一个长度为 1 的输出轴。只有模型解释结果本身确实带有多个输出，或者你的后续数据管道明确规定了统一的三维布局，才需要把输出作为额外维度管理。统一形状可以是工程选择，但不是 Explanation 的通用要求。

# 单输出时，每个样本有 4 个特征贡献值。
single_values = np.zeros((2, 4))
single = shap.Explanation(
    values=single_values,
    feature_names=["年龄", "收入", "次数", "地区"],
)

# 选择第 0 个样本后仍按特征排列，不存在类别轴。
one_sample = single[0]
print(one_sample.shape)

这里按形状推导，one_sample.shape 应为 (4,)。如果后续绘图函数需要二维输入，再根据该函数的参数要求显式增加批次维度；不要把“绘图库需要的形状”反过来当成 SHAP 结果的原始语义。

多输出模型怎样用 output_names 贴标签

output_names 是输出索引的可读名称，例如分类模型的类别名。它不会改变 values 的数字，也不会把输出轴移动到特征轴前面；它只让最后一轴从“索引 0、1、2”变成更容易读的业务标签。

可以先建立一张最小映射：output_names[0] 对应 values[:, :, 0]，output_names[1] 对应 values[:, :, 1]。如果模型输出是原始分数、对数几率或概率，还要以 explainer 的输出空间为准，不能仅凭标签名推断数值含义。

# 三维结果的最后一轴是模型输出，不是新的输入字段。
names = ["拒绝", "通过", "复核"]
multi = shap.Explanation(
    values=np.zeros((120, 8, 3)),
    feature_names=[f"feature_{i}" for i in range(8)],
    output_names=names,
)

output_index = 1  # 选择“通过”这个输出。
selected_name = multi.output_names[output_index]
selected_values = multi.values[:, :, output_index]

# 切完最后一轴后，结果回到 [样本, 特征]，便于逐特征分析。
print(selected_name, selected_values.shape)

按构造结果，selected_name 是“通过”，selected_values.shape 是 (120, 8)。如果要解释第 10 条样本的“通过”输出，可继续取 selected_values[9]，得到 8 个特征贡献值。

把 values 与 data、feature_names 对齐

读一条样本时，建议把三个对象放到同一个表格中：输入值来自 data，贡献值来自 values，列名来自 feature_names。如果是多输出模型，先固定一个输出索引，再生成这张二维表。

import pandas as pd

sample_index = 9
output_index = 1

# 先固定输出，再将同一条样本的输入值与贡献值按特征列对齐。
row = pd.DataFrame({
    "feature": list(multi.feature_names),
    "input_value": multi.data[sample_index],
    "shap_value": multi.values[sample_index, :, output_index],
})

# 这里的排序只用于展示，不改变 Explanation 的原始轴语义。
row = row.reindex(row["shap_value"].abs().sort_values(ascending=False).index)
print(row.head())

这个片段要求 data 与 values 的特征轴确实对齐。若输入经过了独热编码、文本分词或图像展开，feature_names 也必须是同一套变换后的名称；原始业务字段名不能直接覆盖已经展开的特征位置。

形状不符合预期时，按这几个信号排查

1. 先看模型到底有几个输出。 回归、二分类原始分数和分类概率可能处于不同输出空间，不能只按“二分类就一定三维”判断。
2. 再看是否发生了特征展开。 独热编码、文本 token 或图像像素会让特征轴变长，轴仍然是特征，但不再等于原始表格列数。
3. 确认 SHAP 版本和返回类型。 官方说明提到，0.45.0 起单输入多输出的返回类型从列表改为 ndarray；旧代码如果直接按列表索引，可能会误读。
4. 最后检查标签长度。 len(feature_names) 应对应特征轴长度；len(output_names) 应对应输出轴长度。标签数量不匹配时，不要用补位字符串掩盖问题。

常见问题

最后一维一定是输出维度吗？

在常见的表格模型多输出结果中通常是，但不能脱离输入类型和 explainer 约定硬猜。应同时对照 data、feature_names、output_names 和官方接口说明。

output_names 不设置会怎样？

解释对象仍可能有贡献值，但下游图表和表格缺少输出的可读标签。官方接口把它定义为可选参数，所以缺失时应按输出索引处理，并在业务层补充明确映射。

为什么 values 的和对不上 predict_proba？

SHAP 的加和关系取决于 explainer 的输出空间。某些树模型默认解释原始 margin 或 log-odds，而不是概率；先确认 model_output 和对应的基准值，再比较两边的数值。

最后可以把判断流程固定为：先读 shape，再核对标签长度，接着固定输出索引，最后把 data、values 和 feature_names 拼成一张表。这样既能区分样本特征与输出维度，也能让后续图表建立在明确的轴语义上。