获取说明

本指南介绍如何从 Vertex AI 上的 Model 资源获取说明。您可以通过两种方式获得说明：

  • 在线说明：对 Vertex AI API 的同步请求，类似于使用特征归因返回预测的在线预测。

  • 批量说明：对使用特征归因返回预测 Vertex AI API 的异步请求。批量预测是批量预测请求的可选部分。

准备工作

在获取说明之前，您必须完成以下操作：

  1. 这一步因您使用的机器学习模型类型而异：

  2. 如需获取在线说明，请将您在上一步中创建的 Model 部署到 Endpoint 资源。

获取在线说明

要获取在线说明，请按照完成在线预测的大多数步骤执行操作。但是，您无需向 Vertex AI API 发送 projects.locations.endpoints.predict 请求，只需发送 projects.locations.endpoints.explain 请求即可。

以下指南提供了有关准备和发送在线说明请求的详细说明：

获取批量说明

仅支持基于特征的批量说明；您无法获取基于样本的批量说明。

如需获得批量预测说明，请在创建批量预测作业时，将 generateExplanation 字段设置为 true。

如需详细了解如何准备和创建批量预测作业，请参阅获取批量预测。

在 Vertex AI Workbench 用户管理的笔记本中本地获取说明

在 Vertex AI Workbench 用户管理的笔记本中，您可以通过在笔记本的本地内核或运行时内运行 Vertex Explainable AI 来为自定义训练的模型生成说明，而无需为了获取说明而将模型部署到 Vertex AI。使用本地说明使您可以试用不同的 Vertex Explainable AI 设置，而无需针对每次更改调整 Vertex AI 模型部署。这样可以更轻松、更快速地评估使用不同基准、尝试对说明进行不同可视化设置，或者调整算法使用的步数或路径数的影响。

本地说明仅在用户管理的笔记本内可用，因此这项功能在用户管理笔记本实例外部运行的 Jupyter 笔记本中不起作用。

要在用户管理的笔记本实例中本地生成说明，请执行以下操作：

  • 创建用户管理的笔记本实例
  • 从用户管理的笔记本实例启动 JupyterLab 环境，然后创建或导入笔记本。
  • 将模型工件保存到笔记本的本地环境或 Cloud Storage 存储桶。
  • 生成并保存元数据以描述模型，并配置说明请求。

获取并发说明

Explainable AI 支持并发说明。借助并发说明，您可以从同一已部署模型端点请求基于特征的说明和基于示例的说明，而无需针对每种说明方法单独部署模型。

如需获取并行说明，请上传模型并配置基于样本或基于特征的说明。然后，照常部署模型。

部署模型后，您可以像往常一样请求已配置的说明。此外，您还可以通过指定 concurrent_explanation_spec_override 来请求并发说明。

使用并发说明时，请注意以下事项：

  • 并发说明仅适用于 v1beta1 API 版本。如果您使用的是 Vertex Python SDK，则需要使用 preview 模型来使用并发说明。
  • 在使用基于特征的说明进行部署后，无法请求基于示例的说明。如果您希望同时使用基于示例的说明和基于特征的说明，请使用基于示例的说明部署模型，并使用并发说明字段请求基于特征的说明。
  • 并发说明不支持批量说明。在线说明是使用此功能的唯一方式。

在用户管理的笔记本中使用 Explainable AI SDK

用户管理的笔记本实例中已经预安装 Explainable AI SDK。您可以在您的笔记本中使用 Explainable AI SDK 保存模型工件，并自动识别关于模型输入和输出的说明元数据。您还可以指定其他参数以配置说明请求，然后直观呈现说明结果。

您可以在笔记本的本地环境或 Cloud Storage 存储桶中保存模型和元数据。如果您使用的是 TensorFlow，则可以使用 save_model_with_metadata() 方法推断模型的输入和输出，并将此说明元数据与您的模型一同保存。

随后使用 load_model_from_local_path() 将模型加载到 Explainable AI SDK 中。如果需要，您可以为特定 Vertex Explainable AI 算法调整配置。例如，您可以更改用于采样 Shapley 的路径数量，也可以更改用于积分梯度或 XRAI 的步数。

最后，使用数据实例调用 explain()，并直观呈现特征归因。

您可以使用以下示例代码，在用户管理的笔记本实例中获取 TensorFlow 2 模型的本地说明：

# This sample code only works within a user-managed notebooks instance.
import explainable_ai_sdk
from explainable_ai_sdk.metadata.tf.v2 import SavedModelMetadataBuilder

metadata_and_model_builder = SavedModelMetadataBuilder('LOCAL_PATH_TO_MODEL')
metadata_and_model_builder.save_model_with_metadata('LOCAL_PATH_TO_SAVED_MODEL_ARTIFACT')

# Load the model and adjust the configuration for Explainable AI parameters
num_paths = 20
model_artifact_with_metadata = explainable_ai_sdk.load_model_from_local_path(
    'LOCAL_PATH_TO_SAVED_MODEL_ARTIFACT',
    explainable_ai_sdk.SampledShapleyConfig(num_paths))

# Explainable AI supports generating explanations for multiple predictions
instances = [{feature_a: 10, feature_2: 100,...}, ... ]
explanations = model_artifact_with_metadata.explain(instances)
explanations[0].visualize_attributions()

如需详细了解 Explainable AI SDK（包括不同的配置和参数），请参阅 GitHub 上 SDK 的 config.py 文件。详细了解 Vertex AI Workbench 用户管理的笔记本。

问题排查

本部分介绍您在获取说明期间遇到问题时的实用问题排查步骤。

错误：列表索引超出范围

如果您在请求说明时收到以下错误消息：

"error": "Explainability failed with exception: listindex out of range"

请确保您没有将空数组传递给需要对象数组的字段。例如，如果 field1 接受对象数组，则以下请求正文可能会导致错误：

{
  "instances": [
    {
      "field1": [],
    }
  ]
}

请确保数组不为空，例如：

{
  "instances": [
    {
      "field1": [
        {}
      ],
    }
  ]
}

后续步骤