从自定义训练模型获取在线预测结果

本页面介绍了如何使用 Google Cloud 控制台或 Vertex AI API 从自定义训练模型获取在线（实时）预测结果。

格式化输入以进行在线预测

本部分介绍了如何设置预测输入实例的格式并编码为 JSON，如果您使用的是 predict 或 explain 方法，则需要执行此操作。如果您使用的是 rawPredict 方法，则不需要执行此操作。如需了解选择哪种方法，请参阅向端点发送请求。

如果您使用 Vertex AI SDK for Python 发送预测请求，请指定不带 instances 字段的实例列表。例如，指定 [ ["the","quick","brown"], ... ] 而不是 { "instances": [ ["the","quick","brown"], ... ] }。

如果您的模型使用自定义容器，则输入必须采用 JSON 格式，并且还有一个可用于容器的额外 parameters 字段。详细了解如何使用自定义容器设置预测输入的格式。

将实例格式设置为 JSON 字符串

在线预测的基本格式是数据实例列表。这些列表可以是普通的值列表，也可以是 JSON 对象的成员，具体取决于您在训练应用中配置输入的方式。TensorFlow 模型可以接受更复杂的输入，大多数 scikit-learn 和 XGBoost 模型则接受数字列表形式的输入。

以下示例显示了 TensorFlow 模型的输入张量和实例键：

 {"values": [1, 2, 3, 4], "key": 1}

JSON 字符串的构成可以很复杂，但只要遵循以下规则即可：

顶级实例数据必须是 JSON 对象，即键值对的字典。
实例对象中的各个值可以是字符串、数字或列表。您无法嵌入 JSON 对象。
列表必须仅包含相同类型的内容（包括其他列表）。您不能混合使用字符串和数值。

您将在线预测的输入实例作为 projects.locations.endpoints.predict 调用的消息正文进行传递。详细了解请求正文的格式要求。

使每个实例成为 JSON 数组中的一项，并将该数组作为 JSON 对象的 instances 字段提供。例如：

{"instances": [
  {"values": [1, 2, 3, 4], "key": 1},
  {"values": [5, 6, 7, 8], "key": 2}
]}

对二进制数据进行编码以进行预测预测

二进制数据不能格式化为 JSON 支持的 UTF-8 编码字符串。如果输入中包含二进制数据，则必须使用 base64 编码表示。此时需要用到以下特殊格式：

编码的字符串必须设置为 JSON 对象格式，并包含名为 b64 的单个键。在 Python 3 中，base64 编码会输出一个字节序列。您必须将此字节序列转换为字符串，使其能够进行 JSON 序列化：
```
{'image_bytes': {'b64': base64.b64encode(jpeg_data).decode()}}
```
在 TensorFlow 模型代码中，您必须为二进制输入和输出张量提供别名，以便它们以“_bytes”结尾。

请求和响应示例

本部分介绍预测请求正文和响应正文的格式，以及 TensorFlow、scikit-learn、XGBoost 的示例。

请求正文详情

TensorFlow

请求正文包含的数据采用以下结构（JSON 表示法）：

{
  "instances": [
    <value>|<simple/nested list>|<object>,
    ...
  ]
}

instances[] 是必需对象，而且必须包含待预测实例的列表。

实例列表中每个元素的结构由模型的输入定义决定。实例可包含命名输入（作为对象），或者仅包含未加标签的值。

并非所有数据都包含命名输入。有些实例是简单的 JSON 值（布尔值、数字或字符串）。但是，实例通常是简单值列表或复杂的嵌套列表。

以下是请求正文的一些示例。

CSV 数据，其中每行编码为字符串值：

{"instances": ["1.0,true,\\"x\\"", "-2.0,false,\\"y\\""]}

纯文本：

{"instances": ["the quick brown fox", "the lazy dog"]}

编码为字词列表的句子（字符串矢量）：

{
  "instances": [
    ["the","quick","brown"],
    ["the","lazy","dog"],
    ...
  ]
}

浮点标量值：

{"instances": [0.0, 1.1, 2.2]}

整数矢量：

{
  "instances": [
    [0, 1, 2],
    [3, 4, 5],
    ...
  ]
}

张量（在本示例中为二维张量）：

{
  "instances": [
    [
      [0, 1, 2],
      [3, 4, 5]
    ],
    ...
  ]
}

图片，可通过不同方式来表示。在本编码方案中，前两个维度表示图片的行和列，第三个维度包含每个像素的 R、G 和 B 值的列表（矢量）：

{
  "instances": [
    [
      [
        [138, 30, 66],
        [130, 20, 56],
        ...
      ],
      [
        [126, 38, 61],
        [122, 24, 57],
        ...
      ],
      ...
    ],
    ...
  ]
}

数据编码

JSON 字符串必须采用 UTF-8 编码。如要发送二进制数据，您必须对数据进行 base64 编码并将数据标记为二进制。如要将 JSON 字符串标记为二进制，请将其替换为具有单一 b64 特性的 JSON 对象：

{"b64": "..."}

以下示例展示了两个需要 base64 编码的序列化 tf.Examples 实例（虚构的数据，仅作说明之用）：

{"instances": [{"b64": "X5ad6u"}, {"b64": "IA9j4nx"}]}

以下示例显示两个需要 base64 编码的 JPEG 图片字节字符串（虚构的数据，仅作说明之用）：

{"instances": [{"b64": "ASa8asdf"}, {"b64": "JLK7ljk3"}]}

多个输入张量

一些模型具有可接受多个输入张量的底层 TensorFlow 图。在这种情况下，请使用 JSON 名称/值对的名称来识别输入张量。

对于带有输入张量别名“tag”（字符串）和“image”（base64 编码的字符串）的图，请使用以下代码：

{
  "instances": [
    {
      "tag": "beach",
      "image": {"b64": "ASa8asdf"}
    },
    {
      "tag": "car",
      "image": {"b64": "JLK7ljk3"}
    }
  ]
}

对于带有输入张量别名“tag”（字符串）和“image”（8 位整数的三维数组）的图，请使用以下代码：

{
  "instances": [
    {
      "tag": "beach",
      "image": [
        [
          [138, 30, 66],
          [130, 20, 56],
          ...
        ],
        [
          [126, 38, 61],
          [122, 24, 57],
          ...
        ],
        ...
      ]
    },
    {
      "tag": "car",
      "image": [
        [
          [255, 0, 102],
          [255, 0, 97],
          ...
        ],
        [
          [254, 1, 101],
          [254, 2, 93],
          ...
        ],
        ...
      ]
    },
    ...
  ]
}

scikit-learn

请求正文包含的数据采用以下结构（JSON 表示法）：

{
  "instances": [
    <simple list>,
    ...
  ]
}

instances[] 是必需对象，而且必须包含待预测实例的列表。在以下示例中，每个输入实例都是一个浮点数列表：

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

输入实例的维度必须与模型所期望的维度一致。例如，如果模型需要三个特征，则每个输入实例的长度必须为 3。

XGBoost

请求正文包含的数据采用以下结构（JSON 表示法）：

{
  "instances": [
    <simple list>,
    ...
  ]
}

instances[] 是必需对象，而且必须包含待预测实例的列表。在以下示例中，每个输入实例都是一个浮点数列表：

{
  "instances": [
    [0.0, 1.1, 2.2],
    [3.3, 4.4, 5.5],
    ...
  ]
}

输入实例的维度必须与模型所期望的维度一致。例如，如果模型需要三个特征，则每个输入实例的长度必须为 3。

对于 XGBoost 的输入实例，Vertex AI 不支持稀疏表示法。

在线预测服务以不同方式解析零和 NaN。如果特征值为零，请使用 0.0 作为相应的输入。如果缺少特征值，请使用 "NaN" 作为相应的输入。

以下示例表示具有单个输入实例的预测请求，其中第一个特征的值是 0.0，第二个特征的值是 1.1，第三个特征的值缺失：

{"instances": [[0.0, 1.1, "NaN"]]}

PyTorch

如果您的模型使用 PyTorch 预构建容器，则 TorchServe 的默认处理程序预期将每个实例封装在 data 字段中。例如：

{
  "instances": [
    { "data": , <value> },
    { "data": , <value> }
  ]
}

响应正文详情

如果调用成功，则对于请求正文中的每个实例，响应正文都包含一个预测条目，并按相同顺序列出：

{
  "predictions": [
    {
      object
    }
  ],
  "deployedModelId": string
}

如有任何实例的预测失败，则响应正文不会包含任何预测条目，而是包含一个错误条目：

{
  "error": string
}

predictions[] 对象包含预测结果列表，其中每个预测结果对应请求中的一个实例。

如果发生错误，error 字符串会包含一条描述问题的消息。如果在处理任何实例时发生错误，则系统会返回错误，而非预测结果列表。

即使每个实例只有一个预测结果，预测结果的格式也与实例的格式没有直接关联。预测结果的格式是由模型中定义的输出集合所指定。预测结果集合会以 JSON 列表的形式返回。列表的每个成员可以是简单值、列表或任何复杂度的 JSON 对象。如果模型具有多个输出张量，则每个预测结果将为 JSON 对象，其中包含每个输出的名称/值对。这些名称可标识图中的输出别名。

响应正文示例

TensorFlow

以下示例展示了一些可能的响应：

三个输入实例的一组简单预测结果，其中每个预测结果均为一个整数值：
```
{"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}
```
一组较复杂的预测结果，各包含两个与输出张量相对应的命名值，分别名为 label 和 scores。label 的值是预测的类别（“car”或“beach”），scores 包含该实例在各可能类别之间的概率列表。
```
{
  "predictions": [
    {
      "label": "beach",
      "scores": [0.1, 0.9]
    },
    {
      "label": "car",
      "scores": [0.75, 0.25]
    }
  ],
  "deployedModelId": 123456789012345678
}
```
处理输入实例出错时的响应：
```
{"error": "Divide by zero"}
```

scikit-learn

以下示例展示了一些可能的响应：

三个输入实例的一组简单预测结果，其中每个预测结果均为一个整数值：
```
{"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}
```
处理输入实例出错时的响应：
```
{"error": "Divide by zero"}
```

XGBoost

以下示例展示了一些可能的响应：

三个输入实例的一组简单预测结果，其中每个预测结果均为一个整数值：
```
{"predictions":
   [5, 4, 3],
   "deployedModelId": 123456789012345678
}
```
处理输入实例出错时的响应：
```
{"error": "Divide by zero"}
```

向端点发送请求

可通过三种方式来发送请求：

预测结果请求：向 predict 发送请求以获取在线预测结果。
原始预测结果请求：向 rawPredict 发送请求，以便使用任意 HTTP 载荷，而不是遵循本页面的设置输入格式部分中所述的准则。在以下情况下，您可能需要获取原始预测结果：
- 您使用的是自定义容器，该容器接收请求并发送与准则不同的响应。
- 需要更低延迟。rawPredict 会跳过序列化步骤并直接将请求转发到预测容器。
- 您正在使用 NVIDIA Triton 执行预测。
说明请求：向 explain 发送请求。如果您已针对 Vertex Explainable AI 配置 Model，则可以获取在线说明。在线说明请求的格式与在线预测请求的格式相同，它们返回类似的响应，唯一的区别在于在线说明响应包含特征归因和预测结果。

注意：如果将模型部署到公共端点，则每个预测请求不得超过 1.5 MB。如果您的请求较大，可以尝试以下操作：

使用专用端点，该端点速度更快、更稳定，并提供更大的载荷大小和更长的请求超时时间。
使用专用端点，该端点不会施加 1.5 MB 的限制并且提供更低的延迟。
在将请求发送到预测服务器之前，在客户端上将数据编码、调整和/或压缩为较小的格式。然后，使用预处理函数或自定义预测例程解码预测服务器上的数据。例如，您可以执行以下操作：
- 将浮点数转换为 base64 编码的字节数组，而不是作为字符串发送。
- 将图片压缩为 JPEG 或 PNG 格式，而不是发送未压缩的图片。
- 将大图片调整大小后再发送到预测服务器。

发送在线预测请求

gcloud

以下示例使用 gcloud ai endpoints predict 命令：

将以下 JSON 对象写入本地环境中的文件。文件名无关紧要，但在本示例中，请将文件命名为 request.json。
```
{
 "instances": INSTANCES
}
```
替换以下内容：
- INSTANCES：要为其获取预测的实例的 JSON 数组。每个实例的格式取决于经过训练的机器学习模型需要的输入。如需了解详情，请参阅格式化输入以进行在线预测。
运行以下命令：
```
gcloud ai endpoints predict ENDPOINT_ID \
  --region=LOCATION_ID \
  --json-request=request.json
```
替换以下内容：
- ENDPOINT_ID：端点的 ID。
- LOCATION_ID：您在其中使用 Vertex AI 的区域。

REST

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

LOCATION_ID：您在其中使用 Vertex AI 的区域。
PROJECT_ID：您的项目 ID
ENDPOINT_ID：端点的 ID。
INSTANCES：要为其获取预测的实例的 JSON 数组。每个实例的格式取决于经过训练的机器学习模型需要的输入。如需了解详情，请参阅格式化输入以进行在线预测。

HTTP 方法和网址：

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict

请求 JSON 正文：

{
  "instances": INSTANCES
}

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

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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content

如果成功，您会收到如下所示的 JSON 响应。在响应中，您会看到以下替换：

PREDICTIONS：预测结果的 JSON 数组，其中每个预测结果对应请求正文中包含的一个实例。
DEPLOYED_MODEL_ID：执行预测的 DeployedModel 的 ID。

{
  "predictions": PREDICTIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Java

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Java 设置说明执行操作。如需了解详情，请参阅 Vertex AI Java API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


import com.google.cloud.aiplatform.v1.EndpointName;
import com.google.cloud.aiplatform.v1.PredictRequest;
import com.google.cloud.aiplatform.v1.PredictResponse;
import com.google.cloud.aiplatform.v1.PredictionServiceClient;
import com.google.cloud.aiplatform.v1.PredictionServiceSettings;
import com.google.protobuf.ListValue;
import com.google.protobuf.Value;
import com.google.protobuf.util.JsonFormat;
import java.io.IOException;
import java.util.List;

public class PredictCustomTrainedModelSample {
  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String instance = "[{ “feature_column_a”: “value”, “feature_column_b”: “value”}]";
    String project = "YOUR_PROJECT_ID";
    String endpointId = "YOUR_ENDPOINT_ID";
    predictCustomTrainedModel(project, endpointId, instance);
  }

  static void predictCustomTrainedModel(String project, String endpointId, String instance)
      throws IOException {
    PredictionServiceSettings predictionServiceSettings =
        PredictionServiceSettings.newBuilder()
            .setEndpoint("us-central1-aiplatform.googleapis.com:443")
            .build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (PredictionServiceClient predictionServiceClient =
        PredictionServiceClient.create(predictionServiceSettings)) {
      String location = "us-central1";
      EndpointName endpointName = EndpointName.of(project, location, endpointId);

      ListValue.Builder listValue = ListValue.newBuilder();
      JsonFormat.parser().merge(instance, listValue);
      List<Value> instanceList = listValue.getValuesList();

      PredictRequest predictRequest =
          PredictRequest.newBuilder()
              .setEndpoint(endpointName.toString())
              .addAllInstances(instanceList)
              .build();
      PredictResponse predictResponse = predictionServiceClient.predict(predictRequest);

      System.out.println("Predict Custom Trained model Response");
      System.out.format("\tDeployed Model Id: %s\n", predictResponse.getDeployedModelId());
      System.out.println("Predictions");
      for (Value prediction : predictResponse.getPredictionsList()) {
        System.out.format("\tPrediction: %s\n", prediction);
      }
    }
  }
}

Node.js

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Node.js 设置说明执行操作。如需了解详情，请参阅 Vertex AI Node.js API 参考文档。

如需向 Vertex AI 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 * (Not necessary if passing values as arguments)
 */

// const filename = "YOUR_PREDICTION_FILE_NAME";
// const endpointId = "YOUR_ENDPOINT_ID";
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';
const util = require('util');
const {readFile} = require('fs');
const readFileAsync = util.promisify(readFile);

// Imports the Google Cloud Prediction Service Client library
const {PredictionServiceClient} = require('@google-cloud/aiplatform');

// Specifies the location of the api endpoint
const clientOptions = {
  apiEndpoint: 'us-central1-aiplatform.googleapis.com',
};

// Instantiates a client
const predictionServiceClient = new PredictionServiceClient(clientOptions);

async function predictCustomTrainedModel() {
  // Configure the parent resource
  const endpoint = `projects/${project}/locations/${location}/endpoints/${endpointId}`;
  const parameters = {
    structValue: {
      fields: {},
    },
  };
  const instanceDict = await readFileAsync(filename, 'utf8');
  const instanceValue = JSON.parse(instanceDict);
  const instance = {
    structValue: {
      fields: {
        Age: {stringValue: instanceValue['Age']},
        Balance: {stringValue: instanceValue['Balance']},
        Campaign: {stringValue: instanceValue['Campaign']},
        Contact: {stringValue: instanceValue['Contact']},
        Day: {stringValue: instanceValue['Day']},
        Default: {stringValue: instanceValue['Default']},
        Deposit: {stringValue: instanceValue['Deposit']},
        Duration: {stringValue: instanceValue['Duration']},
        Housing: {stringValue: instanceValue['Housing']},
        Job: {stringValue: instanceValue['Job']},
        Loan: {stringValue: instanceValue['Loan']},
        MaritalStatus: {stringValue: instanceValue['MaritalStatus']},
        Month: {stringValue: instanceValue['Month']},
        PDays: {stringValue: instanceValue['PDays']},
        POutcome: {stringValue: instanceValue['POutcome']},
        Previous: {stringValue: instanceValue['Previous']},
      },
    },
  };

  const instances = [instance];
  const request = {
    endpoint,
    instances,
    parameters,
  };

  // Predict request
  const [response] = await predictionServiceClient.predict(request);

  console.log('Predict custom trained model response');
  console.log(`\tDeployed model id : ${response.deployedModelId}`);
  const predictions = response.predictions;
  console.log('\tPredictions :');
  for (const prediction of predictions) {
    console.log(`\t\tPrediction : ${JSON.stringify(prediction)}`);
  }
}
predictCustomTrainedModel();

Python

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。如需了解详情，请参阅 Python API 参考文档。

def endpoint_predict_sample(
    project: str, location: str, instances: list, endpoint: str
):
    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint)

    prediction = endpoint.predict(instances=instances)
    print(prediction)
    return prediction

向专用端点发送在线预测请求

专用端点使用新的网址路径。您可以从 REST API 中的 dedicatedEndpointDns 字段或 Vertex AI SDK for Python 中的 Endpoint.dedicated_endpoint_dns 检索此路径。您还可以使用以下代码手动构建端点路径：

f"https://ENDPOINT_ID.LOCATION_ID-PROJECT_NUMBER.prediction.vertexai.goog/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"

替换以下内容：

ENDPOINT_ID：端点的 ID。
LOCATION_ID：您在其中使用 Vertex AI 的区域。
PROJECT_NUMBER：项目编号。这与项目 ID 不同。您可以在 Google Cloud 控制台中项目的项目设置页面上找到项目编号。

如需使用 Vertex AI SDK for Python 将预测结果发送到专用端点，请将 use_dedicated_endpoint 参数设置为 True：

endpoint.predict(instances=instances, use_dedicated_endpoint=True)

发送在线原始预测请求

gcloud

以下示例使用 gcloud ai endpoints raw-predict 命令：

如需使用命令行中指定的 REQUEST 中的 JSON 对象请求预测，请执行以下操作：

 gcloud ai endpoints raw-predict ENDPOINT_ID \
     --region=LOCATION_ID \
     --request=REQUEST

如需请求使用存储在文件 image.jpeg 和相应 Content-Type 标头中的图片进行预测，请执行以下操作：
```
 gcloud ai endpoints raw-predict ENDPOINT_ID \
     --region=LOCATION_ID \
     --http-headers=Content-Type=image/jpeg \
     --request=@image.jpeg
 
```
替换以下内容：
- ENDPOINT_ID：端点的 ID。
- LOCATION_ID：您在其中使用 Vertex AI 的区域。
- REQUEST：要获取预测结果的请求的内容。请求的格式取决于您的自定义容器的预期，这不一定是 JSON 对象。

Python

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。如需了解详情，请参阅 Python API 参考文档。

from google.cloud import aiplatform_v1


def sample_raw_predict():
    # Create a client
    client = aiplatform_v1.PredictionServiceClient()

    # Initialize request argument(s)
    request = aiplatform_v1.RawPredictRequest(
        endpoint="endpoint_value",
    )

    # Make the request
    response = client.raw_predict(request=request)

    # Handle the response
    print(response)

响应包括以下 HTTP 标头：

X-Vertex-AI-Endpoint-Id：提供此预测的 Endpoint 的 ID。
X-Vertex-AI-Deployed-Model-Id：提供此预测的端点的 DeployedModel 的 ID。

发送在线说明请求

gcloud

以下示例使用 gcloud ai endpoints explain 命令：

将以下 JSON 对象写入本地环境中的文件。文件名无关紧要，但在本示例中，请将文件命名为 request.json。
```
{
 "instances": INSTANCES
}
```
替换以下内容：
- INSTANCES：要为其获取预测的实例的 JSON 数组。每个实例的格式取决于经过训练的机器学习模型需要的输入。如需了解详情，请参阅格式化输入以进行在线预测。
运行以下命令：
```
gcloud ai endpoints explain ENDPOINT_ID \
  --region=LOCATION_ID \
  --json-request=request.json
```
替换以下内容：
- ENDPOINT_ID：端点的 ID。
- LOCATION_ID：您在其中使用 Vertex AI 的区域。
（可选）如果您想要向 Endpoint 中的特定 DeployedModel 发送说明请求，则可以指定 --deployed-model-id 标志：
```
gcloud ai endpoints explain ENDPOINT_ID \
  --region=LOCATION \
  --deployed-model-id=DEPLOYED_MODEL_ID \
  --json-request=request.json
```
除了上述占位符之外，还替换以下内容：
- DEPLOYED_MODEL_ID（可选）：您想要为其获取说明的已部署模型的 ID。此 ID 包含在 predict 方法的响应中。如果您需要为特定模型请求说明，并且您在同一个端点上部署了多个模型，则可以使用此 ID 来确保为该特定模型返回说明。

REST

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

LOCATION_ID：您在其中使用 Vertex AI 的区域。
PROJECT_ID：您的项目 ID
ENDPOINT_ID：端点的 ID。
INSTANCES：要为其获取预测的实例的 JSON 数组。每个实例的格式取决于经过训练的机器学习模型需要的输入。如需了解详情，请参阅格式化输入以进行在线预测。

HTTP 方法和网址：

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain

请求 JSON 正文：

{
  "instances": INSTANCES
}

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

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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain"

PowerShell

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content

如果成功，您会收到如下所示的 JSON 响应。在响应中，您会看到以下替换：

PREDICTIONS：预测结果的 JSON 数组，其中每个预测结果对应请求正文中包含的一个实例。
EXPLANATIONS：说明的 JSON 数组，其中每个说明对应一个预测结果。
DEPLOYED_MODEL_ID：执行预测的 DeployedModel 的 ID。

{
  "predictions": PREDICTIONS,
  "explanations": EXPLANATIONS,
  "deployedModelId": "DEPLOYED_MODEL_ID"
}

Python

如需了解如何安装或更新 Vertex AI SDK for Python，请参阅安装 Vertex AI SDK for Python。如需了解详情，请参阅 Python API 参考文档。

def explain_tabular_sample(
    project: str, location: str, endpoint_id: str, instance_dict: Dict
):

    aiplatform.init(project=project, location=location)

    endpoint = aiplatform.Endpoint(endpoint_id)

    response = endpoint.explain(instances=[instance_dict], parameters={})

    for explanation in response.explanations:
        print(" explanation")
        # Feature attributions.
        attributions = explanation.attributions
        for attribution in attributions:
            print("  attribution")
            print("   baseline_output_value:", attribution.baseline_output_value)
            print("   instance_output_value:", attribution.instance_output_value)
            print("   output_display_name:", attribution.output_display_name)
            print("   approximation_error:", attribution.approximation_error)
            print("   output_name:", attribution.output_name)
            output_index = attribution.output_index
            for output_index in output_index:
                print("   output_index:", output_index)

    for prediction in response.predictions:
        print(prediction)

后续步骤

了解在线预测日志记录。