配置说明

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

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

何时在何处配置说明

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

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

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

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

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

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

当您Model 部署到 Endpoint 资源时,它会创建一个 DeployedModel。您可以通过填充 DeployedModelexplanationSpec 字段来为其设置默认说明配置。您可以在创建 Model 时使用此步骤替换配置集。

同样,当您Model 获取批量预测结果或在批量预测请求中请求说明时,您可以通过填充 BatchPredictionJob 资源的 explanationSpec 字段来替换 Model 的部分或全部说明配置。

如果您原本不打算获取说明(创建模型时省略了 explanationSpec 字段),但后来决定需要模型的说明,则这些选项非常有用。

获取在线说明时替换配置

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

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

explain 请求中,您可以替换以下字段:

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

导入具有 explanationSpec 字段的模型

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

TensorFlow 预构建容器

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

采样 Shapley

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

控制台

请按照指南使用 Cloud Console 导入模型。进入可解释性步骤后,请执行以下操作:

  1. 对于特征归因方法,请选择采样 Shapely(适用于表格模型)

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

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

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

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

    2. (可选)您可以添加一个或多个输入基准。否则,Explainable AI 会为您的模型选择输入基准。

    3. 如果您要导入 TensorFlow 模型,则还有其他输入字段:

      1. 填写输入张量名称

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

      3. 在此无法更新模态。对于表格模型,该字段自动设置为 NUMERIC;对于图片模型,该字段自动设置为 IMAGE

      4. 设置编码字段(如果适用)。如果未设置,则默认为 IDENTITY

      5. 设置群组名称字段(如果适用)。

  4. 如果要导入 TensorFlow 模型,请指定输出字段:

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

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

gcloud

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

    explanation-metadata.json

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

    请替换以下内容:

    您可以选择向 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
    

    请替换以下内容:

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

REST 和命令行

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

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

您可以选择向 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": {
           "inputTensorName": "INPUT_TENSOR_NAME",
         }
       },
       "outputs": {
         "OUTPUT_NAME": {
           "outputTensorName": "OUTPUT_TENSOR_NAME"
         }
       }
    }
  }
}

如需发送请求,请选择以下方式之一:

curl

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

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default 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 application-default 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 的工具,选择以下标签页之一:

控制台

请按照指南使用 Cloud Console 导入模型。进入可解释性步骤后,请执行以下操作:

  1. 对于特征归因方法,请选择积分梯度(用于表格模型)积分梯度(用于图片分类模型),具体取决于哪种更合适。

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

    1. 设置可视化类型色表

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

    详细了解可视化设置

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

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

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

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

    2. (可选)您可以添加一个或多个输入基准。否则,Explainable AI 会为您的模型选择输入基准。

    3. 如果您要导入 TensorFlow 模型,则还有其他输入字段:

      1. 填写输入张量名称

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

      3. 在此无法更新模态。对于表格模型,该字段自动设置为 NUMERIC;对于图片模型,该字段自动设置为 IMAGE

      4. 设置编码字段(如果适用)。如果未设置,则默认为 IDENTITY

      5. 设置群组名称字段(如果适用)。

  5. 如果要导入 TensorFlow 模型,请指定输出字段:

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

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

gcloud

  1. 将以下 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

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

    您可以选择添加用于配置梯度的 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 搭配使用

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

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

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

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 application-default 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 application-default 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 的工具,选择以下标签页之一:

控制台

请按照指南使用 Cloud Console 导入模型。进入可解释性步骤后,请执行以下操作:

  1. 对于特征归因方法,请选择 XRAI(适用于图片分类模型)

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

    1. 设置色表

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

      详细了解可视化设置

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

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

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

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

    2. (可选)您可以添加一个或多个输入基准。否则,Explainable AI 会为您的模型选择输入基准。

    3. 如果您要导入 TensorFlow 模型,则还有其他输入字段:

      1. 填写输入张量名称

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

      3. 在此无法更新模态。对于表格模型,该字段自动设置为 NUMERIC;对于图片模型,该字段自动设置为 IMAGE

      4. 设置编码字段(如果适用)。如果未设置,则默认为 IDENTITY

      5. 设置群组名称字段(如果适用)。

  5. 如果要导入 TensorFlow 模型,请指定输出字段:

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

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

gcloud

  1. 将以下 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"
        }
      }
    }
    

    请替换以下内容:

    您可以选择向 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

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

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

REST 和命令行

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

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

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

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

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 application-default 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 application-default 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 的工具,选择以下标签页之一:

控制台

请按照指南使用 Cloud Console 导入模型。进入可解释性步骤后,请执行以下操作:

  1. 对于特征归因方法,请选择采样 Shapely(适用于表格模型)

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

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

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

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

    2. (可选)您可以添加一个或多个输入基准。否则,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
    

    替换以下内容:

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

REST 和命令行

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

  • IMAGE_URI执行预测的预构建容器的 URI。
  • PATH_COUNT:用于采样 Shapley 归因方法的特征排列数量。必须是 [1, 50] 范围内的整数。

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

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

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

如果指定输入基准,请确保它们与模型的输入(通常是二维矩阵列表)匹配。否则,输入基准的默认值是输入形状的 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 application-default 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 application-default 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>
}

在本例中,特征名称为 lengthwidth。即使这些字段的值包含嵌套列表或对象,lengthwidth 也是以下步骤所需的唯一键。当您请求说明时,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 以提供输出字段的其他元素的特征归因,您可以指定 ExplanationParameterstopKoutputIndices 字段。但是,本文档中的示例并未介绍这些选项。

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

创建 Model

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

控制台

请按照指南使用 Cloud Console 导入模型。进入可解释性步骤后,请执行以下操作:

  1. 对于特征归因方法,请选择采样 Shapely(适用于表格模型)

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

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

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

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

    2. (可选)您可以添加一个或多个输入基准。否则,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

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

REST 和命令行

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

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

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

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

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

您可以选择向 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 application-default 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 application-default 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

后续步骤