配置基于特征的说明

如需将 Vertex Explainable AI 与自定义训练模型搭配使用，您必须在创建要向其请求说明的 Model 资源、部署模型或提交批量说明作业时配置特定选项。本页面介绍如何配置这些选项。

如果您想要将 Vertex Explainable AI 与 AutoML 表格模型搭配使用，则无需执行任何配置；Vertex AI 会自动为 Vertex Explainable AI 配置模型。请跳过本文档并阅读获取说明。

何时在何处配置说明

您可以在创建或导入模型时配置说明。您也可以对已创建的模型配置说明，即使您之前并未配置说明。

创建或导入模型时配置说明

您可以在创建或导入 Model 时使用 Model 的 explanationSpec 字段为其所有说明设置默认配置。

您可以通过以下方式在 Vertex AI 中创建自定义训练的 Model：

• 将 Model 导入或注册到 Vertex AI Model Registry
• 创建自定义 TrainingPipeline 资源，该资源会导入 Model。
• 创建 BigQuery ML 模型，并在 CREATE MODEL 语法中指定可选的 model_registry 设置。此设置会自动将模型注册到 Vertex AI Model Registry 并配置其 explanationSpec。

无论哪种情况，您都可以配置 Model 以支持 Vertex Explainable AI。本文档中的示例假定您导入 Model。如需在使用 TrainingPipeline 创建自定义训练的 Model 时配置 Vertex Explainable AI，请在 TrainingPipeline 的 modelToUpload 字段中使用本文档中描述的配置设置。

部署模型或获取批量预测结果时配置说明

将 Model 部署到 Endpoint 资源时，您可以执行以下任一操作：

• 配置解释，无论模型之前是否已配置为提供解释。如果您最初不打算获取解释（并在创建模型时省略了 explanationSpec 字段），但之后又决定要为模型提供解释，或是您想要替换某些解释设置，此选项都会非常有用。
• 停用解释。如果您的模型已配置为提供解释，但您不打算从端点获取解释，则此选项会非常有用。如需在将模型部署到端点时停用解释，您可以在 Cloud 控制台中取消勾选“可解释性”选项，也可以将 DeployedModel.disableExplanations 设置为 true。

同样，如果您通过 Model 进行批量预测，您可以通过填充 BatchPredictionJob.explanationSpec 字段来配置解释，也可以通过将 BatchPredictionJob.generateExplanation 设置为 false 来停用解释。

获取在线说明时替换配置

无论您是否使用说明设置创建或导入了 Model，在部署期间是否配置了说明设置，您都可以在获取在线说明时替换 Model 的初始说明设置。

当您向 Vertex AI 发送 explain 请求时，您可以替换您之前为 Model 或 DeployedModel 设置的一些说明配置。

在 explain 请求中，您可以替换以下字段：

• 任何自定义训练模型的输入基准
• 图片模型的可视化配置
• ExplanationParameters（method 除外）

请在说明请求的 explanationSpecOverride 字段中替换这些设置。

导入具有 explanationSpec 字段的模型

根据您是使用预构建容器还是自定义容器执行预测，为 ExplanationSpec 指定略为不同的详细信息。选择与您在使用的容器匹配的标签页：

TensorFlow 预构建容器

对于 Vertex Explainable AI，您可以使用以下任何归因方法。请参阅特征归因方法的比较，为您的 Model 选择适当的方法：

以下示例假定您的模型接受单个输入特征；依序 Keras 模型和许多其他 TensorFlow 模型通常如此。由于特征是任意形状的张量，它实际上可以对许多信息进行编码。当您请求说明时，Vertex Explainable AI 会为张量的每个元素提供说明。

如果您的模型接受多个已命名的输入张量，请将相应的条目添加到 inputs 元数据字段。

对于 TensorFlow 2 模型，ExplanationMetadata 是可选的。如果省略，Vertex AI 会自动根据模型推断值，并使用张量名称作为特征名称。 此笔记本演示了如何导入不使用 ExplanationMetadata 的模型。

采样 Shapley

根据您要用于创建或导入 Model 的工具，选择以下标签页之一：

控制台

请按照指南使用 Google Cloud 控制台导入模型。进入可解释性步骤时，请执行以下操作：

1. 对于特征归因方法，请选择采样 Shapely（适用于表格模型）。

2. 将路径计数设置为用于采样 Shapley 归因方法的特征排列数量。该数值必须是 [1, 50] 范围内的整数。

   较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 25。

3. 配置模型中的每个输入特征：

   注意：对于 Tensorflow 2 模型，输入特征名称是可选的。

   1. 填写输入特征的名称。

   2. （可选）您可以添加一个或多个输入基准。否则，Vertex Explainable AI 会选择全零值的默认输入基准，这对于图片数据为黑色图片。

   3. 如果您要导入 TensorFlow 模型，则还需要填写一些额外的输入字段：

      1. 填写输入张量名称。

      2. 填写索引张量名称和/或密集形状张量名称（如果适用）。

      3. 在此步骤无法更新模态。对于表格模型，模态会被自动设置为 NUMERIC；对于图片模型，则为 IMAGE。

      4. 设置编码字段（如果适用）。如果未设置，则该字段默认为 IDENTITY。

      5. 设置群组名称字段（如果适用）。

4. 如果您要导入 TensorFlow 模型，请指定输出字段：

   1. 设置特征的输出名称。
   2. 设置特征的输出张量名称。
   3. 设置索引显示名称映射（如果适用）。
   4. 设置显示名称映射键（如果适用）。

5. 配置完毕可解释性设置后，点击导入按钮。

gcloud

1. 对于 TensorFlow 2，ExplanationMetadata 是可选的。

   将以下 ExplanationMetadata 写入本地环境中的 JSON 文件。文件名无关紧要，但在本示例中，请将文件命名为 explanation-metadata.json。

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
         "inputTensorName": "INPUT_TENSOR_NAME",
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
         "outputTensorName": "OUTPUT_TENSOR_NAME"
       }
     }
   }
   

   请替换以下内容：

   • FEATURE_NAME：输入特征的容易记住的名称。
   • INPUT_TENSOR_NAME：TensorFlow 中输入张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。
   • OUTPUT_NAME：模型输出的容易记住的名称。
   • OUTPUT_TENSOR_NAME：TensorFlow 中输出张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。

   您可以选择向 ExplanationMetadata 添加输入基准。否则，Vertex AI 会为 Model 选择输入基准。

2. 运行以下命令以创建支持 Vertex Explainable AI 的 Model 资源。突出显示了与 Vertex Explainable AI 最相关的标志。

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=sampled-shapley \
     --explanation-path-count=PATH_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   请替换以下内容：

   • IMAGE_URI：执行预测的 TensorFlow 预构建容器的 URI。

   • PATH_COUNT：用于采样 Shapley 归因方法的特征排列数量。必须是 [1, 50] 范围内的整数。

     较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 25。

   如需了解其他占位符的适当值，请参阅 upload 和导入模型。

REST

在使用任何请求数据之前，请先进行以下替换：

• IMAGE_URI：执行预测的 TensorFlow 预构建容器的 URI。

• PATH_COUNT：用于采样 Shapley 归因方法的特征排列数量。必须是 [1, 50] 范围内的整数。

  较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 25。

• FEATURE_NAME：输入特征的容易记住的名称。
• INPUT_TENSOR_NAME：TensorFlow 中输入张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。
• OUTPUT_NAME：模型输出的容易记住的名称。
• OUTPUT_TENSOR_NAME：TensorFlow 中输出张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。

如需了解其他占位符的适当值，请参阅 upload 和导入模型。

您可以选择向 ExplanationMetadata 添加输入基准。否则，Vertex AI 会为 Model 选择输入基准。

对于 TensorFlow 2 模型，metadata 字段是可选的。如果省略，Vertex AI 会自动根据模型推断 inputs 和 outputs。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

请求 JSON 正文：

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "sampledShapleyAttribution": {
          "pathCount": PATH_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

积分梯度

根据您要用于创建或导入 Model 的工具，选择以下标签页之一：

控制台

请按照指南使用 Google Cloud 控制台导入模型。进入可解释性步骤时，请执行以下操作：

1. 对于特征归因方法，请选择积分梯度（适用于表格模型）或积分梯度（适用于图片分类模型），具体取决于哪种更合适您的模型。

2. 如果您要导入图片分类模型，请执行以下操作：

   1. 设置可视化类型和色表。

   2. 您可以将低于下限时裁剪、超出上限时裁剪、叠加层类型和积分步数保留为其默认设置。

   详细了解可视化设置。

3. 设置在特征归因期间用于近似计算路径积分的步数。该数值必须是 [1, 100] 范围内的整数。

   较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 50。

4. 配置模型中的每个输入特征：

   注意：对于 Tensorflow 2 模型，输入特征名称是可选的。

   1. 填写输入特征的名称。

   2. （可选）您可以添加一个或多个输入基准。否则，Vertex Explainable AI 会选择全零值的默认输入基准，这对于图片数据为黑色图片。

   3. 如果您要导入 TensorFlow 模型，则还需要填写一些额外的输入字段：

      1. 填写输入张量名称。

      2. 填写索引张量名称和/或密集形状张量名称（如果适用）。

      3. 在此步骤无法更新模态。对于表格模型，模态会被自动设置为 NUMERIC；对于图片模型，则为 IMAGE。

      4. 设置编码字段（如果适用）。如果未设置，则该字段默认为 IDENTITY。

      5. 设置群组名称字段（如果适用）。

5. 如果您要导入 TensorFlow 模型，请指定输出字段：

   1. 设置特征的输出名称。
   2. 设置特征的输出张量名称。
   3. 设置索引显示名称映射（如果适用）。
   4. 设置显示名称映射键（如果适用）。

6. 配置完毕可解释性设置后，点击导入按钮。

gcloud

1. 对于 TensorFlow 2，ExplanationMetadata 是可选的。

   将以下 ExplanationMetadata 写入本地环境中的 JSON 文件。文件名无关紧要，但在本示例中，请将文件命名为 explanation-metadata.json。

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
         "inputTensorName": "INPUT_TENSOR_NAME",
         "modality": "MODALITY",
         "visualization": VISUALIZATION_SETTINGS
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
         "outputTensorName": "OUTPUT_TENSOR_NAME"
       }
     }
   }
   

   请替换以下内容：

   • FEATURE_NAME：输入特征的容易记住的名称。
   • INPUT_TENSOR_NAME：TensorFlow 中输入张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。
   • MODALITY：如果 Model 接受将图片作为输入，则为 image；如果 Model 接受表格数据作为输入，则为 numeric。默认值为 numeric。

   • VIZUALIZATION_OPTIONS：直观显示说明的选项。如需了解如何填充此字段，请参阅为图片数据配置可视化设置。

     如果您省略 modality 字段或将 modality 字段设置为 numeric，则将完全省略 visualization 字段。

   • OUTPUT_NAME：模型输出的容易记住的名称。
   • OUTPUT_TENSOR_NAME：TensorFlow 中输出张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。

   您可以选择向 ExplanationMetadata 添加输入基准。否则，Vertex AI 会为 Model 选择输入基准。

2. 运行以下命令以创建支持 Vertex Explainable AI 的 Model 资源。突出显示了与 Vertex Explainable AI 最相关的标志。

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=integrated-gradients \
     --explanation-step-count=STEP_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   请替换以下内容：

   • IMAGE_URI：执行预测的 TensorFlow 预构建容器的 URI。
   • STEP_COUNT：在特征归因期间用于近似计算路径积分的步数。必须是 [1, 100] 范围内的整数。

     较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 50。

   如需了解其他占位符的适当值，请参阅 upload 和导入模型。

   您可以选择添加用于配置梯度的 SmoothGrad 近似的标志。

REST

在使用任何请求数据之前，请先进行以下替换：

• IMAGE_URI：执行预测的 TensorFlow 预构建容器的 URI。
• STEP_COUNT：在特征归因期间用于近似计算路径积分的步数。必须是 [1, 100] 范围内的整数。

  较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 50。

• FEATURE_NAME：输入特征的容易记住的名称。
• INPUT_TENSOR_NAME：TensorFlow 中输入张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。
• MODALITY：如果 Model 接受将图片作为输入，则为 image；如果 Model 接受表格数据作为输入，则为 numeric。默认值为 numeric。

• VIZUALIZATION_OPTIONS：直观显示说明的选项。如需了解如何填充此字段，请参阅为图片数据配置可视化设置。

  如果您省略 modality 字段或将 modality 字段设置为 numeric，则将完全省略 visualization 字段。

• OUTPUT_NAME：模型输出的容易记住的名称。
• OUTPUT_TENSOR_NAME：TensorFlow 中输出张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。

如需了解其他占位符的适当值，请参阅 upload 和导入模型。

您可以选择向 ExplanationMetadata 添加输入基准。否则，Vertex AI 会为 Model 选择输入基准。

您可以选择向 ExplanationParameters 添加用于配置梯度的 SmoothGrad 近似的字段。

对于 TensorFlow 2 模型，metadata 字段是可选的。如果省略，Vertex AI 会自动根据模型推断 inputs 和 outputs。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

请求 JSON 正文：

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "integratedGradientsAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "MODALITY",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

XRAI

根据您要用于创建或导入 Model 的工具，选择以下标签页之一：

控制台

请按照指南使用 Google Cloud 控制台导入模型。进入可解释性步骤时，请执行以下操作：

1. 对于特征归因方法，请选择 XRAI（适用于图片分类模型）。

2. 设置以下可视化选项：

   1. 设置色表。

   2. 您可以将低于下限时裁剪、超出上限时裁剪、叠加层类型和积分步数保留为其默认设置。

      详细了解可视化设置。

3. 设置在特征归因期间用于近似计算路径积分的步数。该数值必须是 [1, 100] 范围内的整数。

   较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 50。

4. 配置模型中的每个输入特征：

   注意：对于 Tensorflow 2 模型，输入特征名称是可选的。

   1. 填写输入特征的名称。

   2. （可选）您可以添加一个或多个输入基准。否则，Vertex Explainable AI 会选择全零值的默认输入基准，这对于图片数据为黑色图片。

   3. 如果您要导入 TensorFlow 模型，则还需要填写一些额外的输入字段：

      1. 填写输入张量名称。

      2. 填写索引张量名称和/或密集形状张量名称（如果适用）。

      3. 在此步骤无法更新模态。对于表格模型，模态会被自动设置为 NUMERIC；对于图片模型，则为 IMAGE。

      4. 设置编码字段（如果适用）。如果未设置，则该字段默认为 IDENTITY。

      5. 设置群组名称字段（如果适用）。

5. 如果您要导入 TensorFlow 模型，请指定输出字段：

   1. 设置特征的输出名称。
   2. 设置特征的输出张量名称。
   3. 设置索引显示名称映射（如果适用）。
   4. 设置显示名称映射键（如果适用）。

6. 配置完毕可解释性设置后，点击导入按钮。

gcloud

1. 对于 TensorFlow 2，ExplanationMetadata 是可选的。

   将以下 ExplanationMetadata 写入本地环境中的 JSON 文件。文件名无关紧要，但在本示例中，请将文件命名为 explanation-metadata.json。

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
         "inputTensorName": "INPUT_TENSOR_NAME",
         "modality": "image",
         "visualization": VISUALIZATION_SETTINGS
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
         "outputTensorName": "OUTPUT_TENSOR_NAME"
       }
     }
   }
   

   请替换以下内容：

   • FEATURE_NAME：输入特征的容易记住的名称。
   • INPUT_TENSOR_NAME：TensorFlow 中输入张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。
   • VIZUALIZATION_OPTIONS：直观显示说明的选项。如需了解如何填充此字段，请参阅为图片数据配置可视化设置。
   • OUTPUT_NAME：模型输出的容易记住的名称。
   • OUTPUT_TENSOR_NAME：TensorFlow 中输出张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。

   您可以选择向 ExplanationMetadata 添加输入基准。否则，Vertex AI 会为 Model 选择输入基准。

2. 运行以下命令以创建支持 Vertex Explainable AI 的 Model 资源。突出显示了与 Vertex Explainable AI 最相关的标志。

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=xrai \
     --explanation-step-count=STEP_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   请替换以下内容：

   • IMAGE_URI：执行预测的 TensorFlow 预构建容器的 URI。
   • STEP_COUNT：在特征归因期间用于近似计算路径积分的步数。必须是 [1, 100] 范围内的整数。

     较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 50。

   如需了解其他占位符的适当值，请参阅 upload 和导入模型。

   您可以选择添加用于配置梯度的 SmoothGrad 近似的标志。

REST

在使用任何请求数据之前，请先进行以下替换：

• IMAGE_URI：执行预测的 TensorFlow 预构建容器的 URI。
• STEP_COUNT：在特征归因期间用于近似计算路径积分的步数。必须是 [1, 100] 范围内的整数。

  较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 50。

• FEATURE_NAME：输入特征的容易记住的名称。
• INPUT_TENSOR_NAME：TensorFlow 中输入张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。
• VIZUALIZATION_OPTIONS：直观显示说明的选项。如需了解如何填充此字段，请参阅为图片数据配置可视化设置。
• OUTPUT_NAME：模型输出的容易记住的名称。
• OUTPUT_TENSOR_NAME：TensorFlow 中输出张量的名称。如需查找此字段的正确值，请参阅将 TensorFlow 与 Vertex Explainable AI 搭配使用。

如需了解其他占位符的适当值，请参阅 upload 和导入模型。

您可以选择向 ExplanationMetadata 添加输入基准。否则，Vertex AI 会为 Model 选择输入基准。

您可以选择向 ExplanationParameters 添加用于配置梯度的 SmoothGrad 近似的字段。

对于 TensorFlow 2 模型，metadata 字段是可选的。如果省略，Vertex AI 会自动根据模型推断 inputs 和 outputs。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

请求 JSON 正文：

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "explanationSpec": {
      "parameters": {
        "xraiAttribution": {
          "stepCount": STEP_COUNT
        }
      },
      "metadata": {
        "inputs": {
          "FEATURE_NAME": {
            "inputTensorName": "INPUT_TENSOR_NAME",
            "modality": "image",
            "visualization": VISUALIZATION_SETTINGS
          }
        },
        "outputs": {
          "OUTPUT_NAME": {
            "outputTensorName": "OUTPUT_TENSOR_NAME"
          }
        }
      }
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

scikit-learn 和 XGBoost 预构建容器

如果您的 Model 接受表格数据作为输入，并使用预构建的用于预测的 scikit-learn 或 XGBoost 容器执行预测，则可以对其进行配置，以便为说明使用采样 Shapley 归因方法。

以下示例假定您的模型接受单个二维矩阵作为输入；scikit-learn 和 XGBoost 模型通常都是这种情况。当您请求说明时，Vertex Explainable AI 会为输入矩阵的每个元素提供归因。

根据您要用于创建或导入 Model 的工具，选择以下标签页之一：

控制台

请按照指南使用 Google Cloud 控制台导入模型。进入可解释性步骤时，请执行以下操作：

1. 对于特征归因方法，请选择采样 Shapely（适用于表格模型）。

2. 将路径计数设置为用于采样 Shapley 归因方法的特征排列数量。该数值必须是 [1, 50] 范围内的整数。

   较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 25。

3. 配置模型中的每个输入特征：

   1. 填写输入特征的名称。

      如果模型工件不包含特征名称，则 Vertex AI 无法将指定的输入特征名称映射到模型。在这种情况下，您应仅提供一个输入特征，您可以使用任意易记的名称，例如 input_features。在说明响应中，您将获得一个 N 维的归因列表，其中 N 是模型中的特征数量，并且列表中的元素以与训练数据集相同的顺序显示。

   2. （可选）您可以添加一个或多个输入基准。否则，Vertex Explainable AI 会选择全零值的默认输入基准，这对于图片数据为黑色图片。

4. 设置特征的输出名称。

5. 配置完毕可解释性设置后，点击导入按钮。

gcloud

1. 将以下 ExplanationMetadata 写入本地环境中的 JSON 文件。文件名无关紧要，但在本示例中，请将文件命名为 explanation-metadata.json。

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {
       }
     },
     "outputs": {
       "OUTPUT_NAME": {
       }
     }
   }
   

   请替换以下内容：

   • FEATURE_NAME：输入特征的容易记住的名称。
   • OUTPUT_NAME：模型输出的容易记住的名称。

   如果指定输入基准，请确保它们与模型的输入（通常是二维矩阵列表）匹配。否则，输入基准的默认值是输入形状的 0 值二维矩阵。

2. 运行以下命令以创建支持 Vertex Explainable AI 的 Model 资源。突出显示了与 Vertex Explainable AI 最相关的标志。

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=sampled-shapley \
     --explanation-path-count=PATH_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   替换以下内容：

   • IMAGE_URI：执行预测的预构建容器的 URI。

   • PATH_COUNT：用于采样 Shapley 归因方法的特征排列数量。必须是 [1, 50] 范围内的整数。

     较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 25。

   如需了解其他占位符的适当值，请参阅 upload 和导入模型。

REST

在使用任何请求数据之前，请先进行以下替换：

• IMAGE_URI：执行预测的预构建容器的 URI。

• PATH_COUNT：用于采样 Shapley 归因方法的特征排列数量。必须是 [1, 50] 范围内的整数。

  较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 25。

• FEATURE_NAME：输入特征的容易记住的名称。
• OUTPUT_NAME：模型输出的容易记住的名称。

如需了解其他占位符的适当值，请参阅 upload 和导入模型。

如果指定输入基准，请确保它们与模型的输入（通常是二维矩阵列表）匹配。否则，输入基准的默认值是输入形状的 0 值二维矩阵。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

请求 JSON 正文：

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {
         }
       },
       "outputs": {
         "OUTPUT_NAME": {
         }
       }
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

自定义容器

如果您的 Model 接受表格数据作为输入并使用自定义容器执行预测，则可以对其进行配置，以便为说明使用采样 Shapley 归因方法。

注意：如果您使用 Vertex AI 的任何预构建容器执行预测，则以下说明不适用。您必须使用不是由 Vertex AI 管理且满足自定义容器要求的自定义容器映像。

确定特征和输出名称

在以下步骤中，您必须向 Vertex AI 提供 Model 接受为输入的特征的名称。您还必须在 Model 的预测中指定用于输出的键。

确定特征名称

如果您的 Model 要求每个输入实例都有特定的顶级键，那么这些键就是您的特征名称。

例如，假设 Model 要求每个输入实例都采用以下格式：

{
  "length": <value>,
  "width": <value>
}

在本例中，特征名称为 length 和 width。即使这些字段的值包含嵌套列表或对象，length 和 width 也是以下步骤所需的唯一键。当您请求说明时，Vertex Explainable AI 会为特征的每个嵌套元素提供提供说明。

如果您的 Model 接受不包含键的输入，则 Vertex Explainable AI 将 Model 视为具有一个特征。您可以使用任何易于记忆的字符串作为特征名称。

例如，假设 Model 要求每个输入实例都采用以下格式：

[
  <value>,
  <value>
]

在这种情况下，请向 Vertex Explainable AI 提供您选择的单个特征名称，例如 dimensions。

注意：以下示例假设您的模型具有单一输入特征。如果您的模型有多个特征（如本部分所述），请将相应的条目添加到 inputs 字段。

确定输出名称

如果 Model 返回每个在线预测实例和包含键的输出，则该键就是输出名称。

例如，假设 Model 采用以下格式返回每个预测结果：

{
  "scores": <value>
}

在这种情况下，输出名称为 scores。如果 scores 字段的值是一个数组，那么在您获取说明时，Vertex Explainable AI 会返回每个预测中具有最高值的元素的特征归因。如需配置 Vertex Explainable AI 以提供输出字段的其他元素的特征归因，您可以指定 ExplanationParameters 的 topK 或 outputIndices 字段。但是，本文档中的示例并未介绍这些选项。

如果 Model 返回不包含键的预测，您可以使用任何易于记忆的字符串作为输出名称。例如，如果 Model 返回每个预测一个标量的数组，则适用此情况。

创建 Model

根据您要用于创建或导入 Model 的工具，选择以下标签页之一：

控制台

请按照指南使用 Google Cloud 控制台导入模型。进入可解释性步骤时，请执行以下操作：

1. 对于特征归因方法，请选择采样 Shapely（适用于表格模型）。

2. 将路径计数设置为用于采样 Shapley 归因方法的特征排列数量。该数值必须是 [1, 50] 范围内的整数。

   较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 25。

3. 配置模型中的每个输入特征：

   1. 填写输入特征的名称。

      如果模型工件不包含特征名称，则 Vertex AI 无法将指定的输入特征名称映射到模型。在这种情况下，您应仅提供一个输入特征，您可以使用任意易记的名称，例如 input_features。在说明响应中，您将获得一个 N 维的归因列表，其中 N 是模型中的特征数量，并且列表中的元素以与训练数据集相同的顺序显示。

   2. （可选）您可以添加一个或多个输入基准。否则，Vertex Explainable AI 会选择全零值的默认输入基准，这对于图片数据为黑色图片。

4. 设置特征的输出名称。

5. 配置完毕可解释性设置后，点击导入按钮。

gcloud

1. 将以下 ExplanationMetadata 写入本地环境中的 JSON 文件。文件名无关紧要，但在本示例中，请将文件命名为 explanation-metadata.json。

   explanation-metadata.json

   {
     "inputs": {
       "FEATURE_NAME": {}
     },
     "outputs": {
       "OUTPUT_NAME": {}
     }
   }
   

   请替换以下内容：

   • FEATURE_NAME：特征的名称，如本文档的“确定特征名称”部分所述。
   • OUTPUT_NAME：输出的名称，如本文档的“确定输出名称”部分所述。

   您可以选择向 ExplanationMetadata 添加输入基准。否则，Vertex AI 会为 Model 选择输入基准。

   如果指定输入基准，请确保它们与模型的输入（通常是二维矩阵列表）匹配。否则，输入基准的默认值是输入形状的 0 值二维矩阵。

2. 运行以下命令以创建支持 Vertex Explainable AI 的 Model 资源。突出显示了与 Vertex Explainable AI 最相关的标志。

   gcloud ai models upload \
     --region=LOCATION \
     --display-name=MODEL_NAME \
     --container-image-uri=IMAGE_URI \
     --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \
     --explanation-method=sampled-shapley \
     --explanation-path-count=PATH_COUNT \
     --explanation-metadata-file=explanation-metadata.json
   

   请替换以下内容：

   • PATH_COUNT：用于采样 Shapley 归因方法的特征排列数量。必须是 [1, 50] 范围内的整数。

     较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 25。

   如需了解其他占位符的适当值，请参阅 upload 和导入模型。

REST

在使用任何请求数据之前，请先进行以下替换：

• PATH_COUNT：用于采样 Shapley 归因方法的特征排列数量。必须是 [1, 50] 范围内的整数。

  较高的值可能会减少近似误差，但计算密集度更高。如果您不知道要使用哪个值，请尝试 25。

• FEATURE_NAME：特征的名称，如本文档的“确定特征名称”部分所述。
• OUTPUT_NAME：输出的名称，如本文档的“确定输出名称”部分所述。

如需了解其他占位符的适当值，请参阅 upload 和导入模型。

您可以选择向 ExplanationMetadata 添加输入基准。否则，Vertex AI 会为 Model 选择输入基准。

HTTP 方法和网址：

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload

请求 JSON 正文：

{
  "model": {
    "displayName": "MODEL_NAME",
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
  "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
  "explanationSpec": {
    "parameters": {
      "sampledShapleyAttribution": {
        "pathCount": PATH_COUNT
      }
    },
    "metadata": {
       "inputs": {
         "FEATURE_NAME": {}
       },
       "outputs": {
         "OUTPUT_NAME": {}
       }
    }
  }
}

如需发送请求，请选择以下方式之一：

curl

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content

后续步骤

• 将您的 Model 部署到 Endpoint 并获取说明。