# 单条推理可解释（Shapley值分析） #### 功能介绍 支持用户传入一组能够代表训练数据分布的参考数据集，以及待解释的单条推理样本，基于 Shapley 值理论计算该样本中各特征对模型预测结果的贡献程度，输出特征重要性排序。 基本原理：Shapley 值源自合作博弈论，通过计算某特征在所有可能特征组合顺序下的平均边际贡献，公平地分配模型预测结果至各个输入特征。其具备数学上的严谨性与可加性，满足： - 贡献归因公平。 - 所有特征 Shapley 值之和等于当前样本预测值与基准值（背景数据平均预测）的差。 该方法可为任意模型提供局部可解释性，适用于复杂黑盒模型的决策归因分析。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/productdesc-pangulm/pangulm_01_0020.html)。 #### URI POST /shapley-value 获取URI方式请参见[请求URI](https://support.huaweicloud.com/api-pangulm/pangulm_05_0004.html)。 #### 请求参数 请求参数 使用[Token认证](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__section94702116509)方式的请求Header参数见[表1]。 表1请求Header参数（Token认证） | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释：** 用户Token。 用于获取操作API的权限。如[图4](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__fig10797003103)中响应消息头中X-Subject-Token的值即为Token。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | | Content-Type | 是 | String | **参数解释：** 发送的实体的MIME类型。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** application/json | 使用[API Key认证](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__section148602501261)方式的请求Header参数见[表2]。 表2请求Header参数（API Key认证） | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Apig-AppCode | 是 | String | **参数解释：** API Key值。 用于获取操作API的权限。[API Key认证](https://support.huaweicloud.com/api-pangulm/pangulm_05_0009.html#pangulm_05_0009__section148602501261)响应消息头中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 | **参数解释：** 当启动服务时，本次请求服务各阶段耗时情况。 **约束限制：** 不涉及 **取值范围：** 不涉及 **默认取值：** 不涉及 | 表5results对应参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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 } } ``` #### 状态码 请参见[状态码](https://support.huaweicloud.com/api-pangulm/pangulm_05_0019.html)。 #### 错误码 请参见[错误码](https://support.huaweicloud.com/api-pangulm/pangulm_05_0020.html)。