如需将 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
选择适当的方法:
采样 Shapley
根据您要用于创建或导入 Model
的工具,选择以下标签页之一:
控制台
请按照指南使用 Google Cloud 控制台导入模型。进入可解释性步骤时,请执行以下操作:
对于特征归因方法,请选择采样 Shapely(适用于表格模型)。
将路径计数设置为用于采样 Shapley 归因方法的特征排列数量。该数值必须是
[1, 50]
范围内的整数。较高的值可能会减少近似误差,但计算密集度更高。如果您不知道要使用哪个值,请尝试
25
。配置模型中的每个输入特征:
-
填写输入特征的名称。
-
(可选)您可以添加一个或多个输入基准。否则,Vertex Explainable AI 会选择全零值的默认输入基准,这对于图片数据为黑色图片。
-
如果您要导入 TensorFlow 模型,则还需要填写一些额外的输入字段:
填写输入张量名称。
填写索引张量名称和/或密集形状张量名称(如果适用)。
在此步骤无法更新模态。对于表格模型,模态会被自动设置为
NUMERIC
;对于图片模型,则为IMAGE
。设置编码字段(如果适用)。如果未设置,则该字段默认为
IDENTITY
。设置群组名称字段(如果适用)。
-
如果您要导入 TensorFlow 模型,请指定输出字段:
- 设置特征的输出名称。
- 设置特征的输出张量名称。
- 设置索引显示名称映射(如果适用)。
- 设置显示名称映射键(如果适用)。
配置完毕可解释性设置后,点击导入按钮。
gcloud
对于 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
选择输入基准。运行以下命令以创建支持 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
。
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
将请求正文保存在名为 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
将请求正文保存在名为 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, 100]
范围内的整数。较高的值可能会减少近似误差,但计算密集度更高。如果您不知道要使用哪个值,请尝试
50
。配置模型中的每个输入特征:
-
填写输入特征的名称。
-
(可选)您可以添加一个或多个输入基准。否则,Vertex Explainable AI 会选择全零值的默认输入基准,这对于图片数据为黑色图片。
-
如果您要导入 TensorFlow 模型,则还需要填写一些额外的输入字段:
填写输入张量名称。
填写索引张量名称和/或密集形状张量名称(如果适用)。
在此步骤无法更新模态。对于表格模型,模态会被自动设置为
NUMERIC
;对于图片模型,则为IMAGE
。设置编码字段(如果适用)。如果未设置,则该字段默认为
IDENTITY
。设置群组名称字段(如果适用)。
-
如果您要导入 TensorFlow 模型,请指定输出字段:
- 设置特征的输出名称。
- 设置特征的输出张量名称。
- 设置索引显示名称映射(如果适用)。
- 设置显示名称映射键(如果适用)。
配置完毕可解释性设置后,点击导入按钮。
gcloud
对于 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
选择输入基准。运行以下命令以创建支持 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
将请求正文保存在名为 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
将请求正文保存在名为 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 控制台导入模型。进入可解释性步骤时,请执行以下操作:
对于特征归因方法,请选择 XRAI(适用于图片分类模型)。
设置以下可视化选项:
设置色表。
您可以将低于下限时裁剪、超出上限时裁剪、叠加层类型和积分步数保留为其默认设置。
详细了解可视化设置。
设置在特征归因期间用于近似计算路径积分的步数。该数值必须是
[1, 100]
范围内的整数。较高的值可能会减少近似误差,但计算密集度更高。如果您不知道要使用哪个值,请尝试
50
。配置模型中的每个输入特征:
-
填写输入特征的名称。
-
(可选)您可以添加一个或多个输入基准。否则,Vertex Explainable AI 会选择全零值的默认输入基准,这对于图片数据为黑色图片。
-
如果您要导入 TensorFlow 模型,则还需要填写一些额外的输入字段:
填写输入张量名称。
填写索引张量名称和/或密集形状张量名称(如果适用)。
在此步骤无法更新模态。对于表格模型,模态会被自动设置为
NUMERIC
;对于图片模型,则为IMAGE
。设置编码字段(如果适用)。如果未设置,则该字段默认为
IDENTITY
。设置群组名称字段(如果适用)。
-
如果您要导入 TensorFlow 模型,请指定输出字段:
- 设置特征的输出名称。
- 设置特征的输出张量名称。
- 设置索引显示名称映射(如果适用)。
- 设置显示名称映射键(如果适用)。
配置完毕可解释性设置后,点击导入按钮。
gcloud
对于 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
选择输入基准。运行以下命令以创建支持 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
将请求正文保存在名为 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
将请求正文保存在名为 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 归因方法。
根据您要用于创建或导入 Model
的工具,选择以下标签页之一:
控制台
请按照指南使用 Google Cloud 控制台导入模型。进入可解释性步骤时,请执行以下操作:
对于特征归因方法,请选择采样 Shapely(适用于表格模型)。
将路径计数设置为用于采样 Shapley 归因方法的特征排列数量。该数值必须是
[1, 50]
范围内的整数。较高的值可能会减少近似误差,但计算密集度更高。如果您不知道要使用哪个值,请尝试
25
。配置模型中的每个输入特征:
填写输入特征的名称。
如果模型工件不包含特征名称,则 Vertex AI 无法将指定的输入特征名称映射到模型。在这种情况下,您应仅提供一个输入特征,您可以使用任意易记的名称,例如
input_features
。在说明响应中,您将获得一个 N 维的归因列表,其中 N 是模型中的特征数量,并且列表中的元素以与训练数据集相同的顺序显示。(可选)您可以添加一个或多个输入基准。否则,Vertex Explainable AI 会选择全零值的默认输入基准,这对于图片数据为黑色图片。
设置特征的输出名称。
配置完毕可解释性设置后,点击导入按钮。
gcloud
将以下
ExplanationMetadata
写入本地环境中的 JSON 文件。文件名无关紧要,但在本示例中,请将文件命名为explanation-metadata.json
。explanation-metadata.json
{ "inputs": { "FEATURE_NAME": { } }, "outputs": { "OUTPUT_NAME": { } } }
请替换以下内容:
- FEATURE_NAME:输入特征的容易记住的名称。
- OUTPUT_NAME:模型输出的容易记住的名称。
如果指定输入基准,请确保它们与模型的输入(通常是二维矩阵列表)匹配。否则,输入基准的默认值是输入形状的 0 值二维矩阵。
运行以下命令以创建支持 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
。
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
将请求正文保存在名为 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
将请求正文保存在名为 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 提供 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
。
确定输出名称
如果 Model
返回每个在线预测实例和包含键的输出,则该键就是输出名称。
例如,假设 Model
采用以下格式返回每个预测结果:
{
"scores": <value>
}
在这种情况下,输出名称为 scores
。如果 scores
字段的值是一个数组,那么在您获取说明时,Vertex Explainable AI 会返回每个预测中具有最高值的元素的特征归因。如需配置 Vertex Explainable AI 以提供输出字段的其他元素的特征归因,您可以指定 ExplanationParameters
的 topK
或 outputIndices
字段。但是,本文档中的示例并未介绍这些选项。
如果 Model
返回不包含键的预测,您可以使用任何易于记忆的字符串作为输出名称。例如,如果 Model
返回每个预测一个标量的数组,则适用此情况。
创建 Model
根据您要用于创建或导入 Model
的工具,选择以下标签页之一:
控制台
请按照指南使用 Google Cloud 控制台导入模型。进入可解释性步骤时,请执行以下操作:
对于特征归因方法,请选择采样 Shapely(适用于表格模型)。
将路径计数设置为用于采样 Shapley 归因方法的特征排列数量。该数值必须是
[1, 50]
范围内的整数。较高的值可能会减少近似误差,但计算密集度更高。如果您不知道要使用哪个值,请尝试
25
。配置模型中的每个输入特征:
填写输入特征的名称。
如果模型工件不包含特征名称,则 Vertex AI 无法将指定的输入特征名称映射到模型。在这种情况下,您应仅提供一个输入特征,您可以使用任意易记的名称,例如
input_features
。在说明响应中,您将获得一个 N 维的归因列表,其中 N 是模型中的特征数量,并且列表中的元素以与训练数据集相同的顺序显示。(可选)您可以添加一个或多个输入基准。否则,Vertex Explainable AI 会选择全零值的默认输入基准,这对于图片数据为黑色图片。
设置特征的输出名称。
配置完毕可解释性设置后,点击导入按钮。
gcloud
将以下
ExplanationMetadata
写入本地环境中的 JSON 文件。文件名无关紧要,但在本示例中,请将文件命名为explanation-metadata.json
。explanation-metadata.json
{ "inputs": { "FEATURE_NAME": {} }, "outputs": { "OUTPUT_NAME": {} } }
请替换以下内容:
- FEATURE_NAME:特征的名称,如本文档的“确定特征名称”部分所述。
- OUTPUT_NAME:输出的名称,如本文档的“确定输出名称”部分所述。
您可以选择向
ExplanationMetadata
添加输入基准。否则,Vertex AI 会为Model
选择输入基准。如果指定输入基准,请确保它们与模型的输入(通常是二维矩阵列表)匹配。否则,输入基准的默认值是输入形状的 0 值二维矩阵。
运行以下命令以创建支持 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
请替换以下内容:
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
将请求正文保存在名为 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
将请求正文保存在名为 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