文档首页/ 盘古大模型 PanguLargeModels/ API参考/ API/ 模型推理接口/ 预测大模型/ 盘古统一编码表格预测分类大模型/ 单条推理可解释（Shapley值分析）
更新时间：2025-12-25 GMT+08:00
查看PDF
分享

单条推理可解释（Shapley值分析）

功能介绍

支持用户传入一组能够代表训练数据分布的参考数据集，以及待解释的单条推理样本，基于 Shapley 值理论计算该样本中各特征对模型预测结果的贡献程度，输出特征重要性排序。

基本原理：Shapley 值源自合作博弈论，通过计算某特征在所有可能特征组合顺序下的平均边际贡献，公平地分配模型预测结果至各个输入特征。其具备数学上的严谨性与可加性，满足：

  • 贡献归因公平。
  • 所有特征 Shapley 值之和等于当前样本预测值与基准值（背景数据平均预测）的差。

该方法可为任意模型提供局部可解释性，适用于复杂黑盒模型的决策归因分析。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见权限和授权项。

URI

POST /shapley-value

获取URI方式请参见请求URI。

请求参数

请求参数

使用Token认证方式的请求Header参数见表1。

表1 请求Header参数（Token认证）

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

参数解释：

用户Token。

用于获取操作API的权限。如图4中响应消息头中X-Subject-Token的值即为Token。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

Content-Type

是

String

参数解释：

发送的实体的MIME类型。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

application/json

使用API Key认证方式的请求Header参数见表2。

表2 请求Header参数（API Key认证）

参数

是否必选

参数类型

描述

X-Apig-AppCode

是

String

参数解释：

API Key值。

用于获取操作API的权限。API Key认证响应消息头中X-Apig-AppCode的值即为API Key。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

Content-Type

是

String

参数解释：

发送的实体的MIME类型。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

application/json
表3 请求Body参数（模型推理）

参数

是否必选

参数类型

描述

trainset_data

是

Array

参数解释：

用户传入一组能够代表训练数据分布的参考数据集，需要限制请求体的大小和条数，不然可能会出现维度爆炸。

约束限制：参考数据集需具有以下性质：

  1. 代表性：背景数据集应能代表模型训练数据的分布。这确保了模拟"缺失特征值"时（通过从背景数据抽样实现），结果符合真实场景。若解释单一样本的预测，背景数据集可以是训练数据的子集。
  2. 规模：更大的背景数据集通常能提供更稳定、准确的估计。但过大的数据集会增加计算成本。实践中常从训练数据中抽取合理子集（如10-200个样本）。
  3. 情境: 若需针对特定子群组（如解释"高价值客户的流失概率"），背景数据集应仅包含该子群组的数据。这能提供更针对性的解释。

背景数据集的选择直接影响解释的可解释性与可靠性。需确保其具备代表性、计算高效性，并与解释目标的情境紧密相关。

以预测维护为例，假设训练时使用了100台设备，每台设备200条数据。

现在设备A发生了报警。则优先使用设备A的200条训练数据（符合代表性、规模和情景原则），和当前的报警数据。进行模型解释。

取值范围：

训练数据中的一组数据集，不可少于10条，超过200条。

analysis_data

是

Array

参数解释：

用户传入单条待解释样本数据。

约束限制：

需要为单条待分析数据。

取值范围：

需要为单条待分析数据。

npermutations

否

int

参数解释：

特征分析迭代次数。

约束限制：

推理耗时和特征维度（feature dim）、迭代次数（npermutations）、基础模型耗时有关。

shapley计算用时和npermutations成正比，npermutations越大，计算用时越长。

公式如下：

最大评估次数 = npermutations * (2 * 特征数量 + 1)

需要大于1，同时为了防止时间过长限制，限制小于20，默认为10。

取值范围：

[1, 20]

默认取值：

10

响应参数

状态码： 200

表4 响应Body参数

参数

参数类型

描述

results

DICT

参数解释：

单条推理可解释（Shapley值分析）结果，results具体内容见表5。feature_dim指的是特征列的数量，class_num指的是多分类任务下类别的数量。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

time_cost

JSON

参数解释：

当启动服务时，本次请求服务各阶段耗时情况。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及
表5 results对应参数

参数

参数类型

描述

shap_values

LIST[FLOAT]

参数解释：

贡献度结果，维度为[feature_dim]，多分类情况下维度为[feature_dim,class_num]。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

base_values

LIST[FLOAT]

参数解释：

贡献度基准值，二分类情况下维度为[1]，多分类情况下维度为[class_num]。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

feature_name

list[str]

参数解释：

特征列名和贡献度对应。因为会出现请求数据特征列顺序和训练数据不一致的情况，返回体指明特征列名顺序。

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

label_class

dict

参数解释：

只在分类的类别场景返回类别和对应的编码数字。

约束限制：

仅在分类场景会返回此字段。

取值范围：

不涉及

默认取值：

不涉及

状态码： 400

表6 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误信息。

请求示例

对指定的预测目标进行分类预测。 
{
  "trainset_data": [
    {
      "feature_1": xx,
      "feature_2": xx,
      ...
      "feature_n": xx
    },
    ...
    {
      "feature_1": xx,
      "feature_2": xx,
      ...
      "feature_n": xx
    }
  ],
  "analysis_data": [
    {
      "feature_1": xx,
      "feature_2": xx,
      ...
      "feature_n": xx
    }
  ],
  "npermutations": 10
}

响应示例

状态码： 200

成功响应示例。 
{
  "results": {
      "shap_values": [...], #若为二分类/回归任务矩阵维度为（feature_num,)，若为多分类问题矩阵维度为（feature_num, num_classes）
      "base_values": [...], #若为二分类/回归任务矩阵维度为（1），若为多分类问题矩阵维度为（num_classes）
      "feature_name": ["feature_1", "feature_2", ..., "feature_n"], 
      "label_class": {"class_1": 0, "class_2":1, ...}
   },
  "time_cost": {
      "infer_cost_time": 233, 
      "postprocess_cost_time": 13, 
      "preprocess_cost_time": 12, 
      "service_cost_total_time": 258
    }
}

状态码

请参见状态码。

错误码

请参见错误码。

相关文档