使用自定义容器进行预测

如需自定义 Vertex AI 如何通过自定义训练的模型执行在线预测，请在创建 Model 资源时指定自定义容器，而不是预构建容器。使用自定义容器时，Vertex AI 会在每个预测节点上运行您选择的 Docker 容器。

出于以下任何原因考虑，您可能需要使用自定义容器：

从使用不是作为预构建容器提供的框架训练的机器学习模型提供预测
对预测请求进行预处理或对模型生成的预测进行后处理
运行以您选择的编程语言编写的预测服务器
安装要用于自定义预测的依赖项

本指南介绍如何创建使用自定义容器的 Model。本指南未提供有关设计和创建 Docker 容器映像的详细说明。

准备容器映像

要创建使用自定义容器的 Model，您必须提供 Docker 容器映像作为该容器的基础。此容器映像必须满足自定义容器要求中所述的要求。

如果您计划使用第三方信任的现有容器映像，则可以跳过下面的一到两个部分。

创建容器映像

设计和构建满足容器映像要求的 Docker 容器映像。

如需了解设计和构建 Docker 容器映像的基础知识，请参阅 Docker 文档快速入门

将容器映像推送到 Artifact Registry

将容器映像推送到 Artifact Registry 制品库。

了解如何将容器映像推送到 Artifact Registry。

创建 `Model`

要创建使用自定义容器的 Model，请执行以下操作之一：

以下各部分介绍了在以上述方式创建 Model 时如何配置与自定义容器相关的 API 字段。

与容器相关的 API 字段

创建 Model 时，请务必使用自定义容器详细信息（而不是预构建容器）配置 containerSpec 字段。

您必须在 Model.containerSpec 字段中指定 ModelContainerSpec 消息。在此消息中，您可以指定以下子字段：

imageUri（必需）

容器映像的 Artifact Registry URI。

如果您使用的是 gcloud ai models upload 命令，则可以使用 --container-image-uri 标志指定此字段。

command（可选）

用于替换容器的 ENTRYPOINT 的可执行文件和参数数组。如需详细了解如何设置此字段的格式以及它如何与 args 字段互动，请参阅 ModelContainerSpec 的 API 参考文档。

如果您使用的是 gcloud ai models upload 命令，则可以使用 --container-command 标志指定此字段。

args（可选）

用于替换容器的 CMD 的可执行文件和参数数组。如需详细了解如何设置此字段的格式以及它如何与 command 字段互动，请参阅 ModelContainerSpec 的 API 参考文档。

如果您使用的是 gcloud ai models upload 命令，则可以使用 --container-args 标志指定此字段。

ports（可选）

端口数组；Vertex AI 会通过列出的第一个端口或者默认的 8080 向您的容器发送活跃性检查、健康检查和预测请求。指定其他端口无效。

如果您使用的是 gcloud ai models upload 命令，则可以使用 --container-ports 标志指定此字段。

env（可选）

容器的 entrypoint 命令以及 command 和 args 字段可以引用的一组环境变量。如需详细了解其他字段如何引用这些环境变量，请参阅 ModelContainerSpec 的 API 参考文档。

如果您使用的是 gcloud ai models upload 命令，则可以使用 --container-env-vars 标志指定此字段。

healthRoute（可选）

容器 HTTP 服务器上您希望 Vertex AI 发送健康检查的路径。

如果您没有指定此字段，则在将 Model 作为 DeployedModel 部署到 Endpoint 资源时，此字段默认为 /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL，其中 ENDPOINT 替换为 Endpoint 的 name 字段的最后一部分（在 endpoints/ 后面），DEPLOYED_MODEL 替换为 DeployedModel 的 id 字段。

如果您使用的是 gcloud ai models upload 命令，则可以使用 --container-health-route 标志指定此字段。

predictRoute（可选）

容器 HTTP 服务器上您希望 Vertex AI 转发预测请求的路径。

如果您没有指定此字段，则在将 Model 作为 DeployedModel 部署到 Endpoint 资源时，此字段默认为 /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict，其中 ENDPOINT 替换为 Endpoint 的 name 字段的最后一部分（在 endpoints/ 后面），DEPLOYED_MODEL 替换为 DeployedModel 的 id 字段。

如果您使用的是 gcloud ai models upload 命令，则可以使用 --container-predict-route 标志指定此字段。

sharedMemorySizeMb（可选）

要在模型共享内存卷中预留的虚拟机内存量（以 MB 为单位）。

共享内存是一种进程间通信 (IPC) 机制，允许多个进程访问和操作一个通用内存块。所需的共享内存量（如果有）是容器和模型的实现细节。如需了解相关准则，请参阅模型服务器文档。

如果您使用的是 gcloud ai models upload 命令，则可以使用 --container-shared-memory-size-mb 标志指定此字段。

startupProbe（可选）

用于检查容器应用是否已启动的探测规范。

如果您使用的是 gcloud ai models upload 命令，则可以使用 --container-startup-probe-exec, --container-startup-probe-period-seconds, --container-startup-probe-timeout-seconds 标志指定此字段。

healthProbe（可选）

用于检查容器是否已准备好接受流量的探测规范。

如果您使用的是 gcloud ai models upload 命令，则可以使用 --container-health-probe-exec, --container-health-probe-period-seconds, --container-health-probe-timeout-seconds 标志指定此字段。

除了您在 Model.containerSpec.env 字段中设置的变量之外，Vertex AI 会根据您的配置设置一些其他变量。详细了解如何在这些字段中和容器的入口点命令中使用这些环境变量。

模型导入示例

以下示例展示了如何在导入模型时指定与容器相关的 API 字段。

gcloud

以下示例使用 gcloud ai models upload 命令：

gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --container-command=COMMAND \
  --container-args=ARGS \
  --container-ports=PORTS \
  --container-env-vars=ENV \
  --container-health-route=HEALTH_ROUTE \
  --container-predict-route=PREDICT_ROUTE \
  --container-shared-memory-size-mb=SHARED_MEMORY_SIZE \
  --container-startup-probe-exec=STARTUP_PROBE_EXEC \
  --container-startup-probe-period-seconds=STARTUP_PROBE_PERIOD \
  --container-startup-probe-timeout-seconds=STARTUP_PROBE_TIMEOUT \
  --container-health-probe-exec=HEALTH_PROBE_EXEC \
  --container-health-probe-period-seconds=HEALTH_PROBE_PERIOD \
  --container-health-probe-timeout-seconds=HEALTH_PROBE_TIMEOUT \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

--container-image-uri 标志是必需的；以 --container- 开头的所有其他标志都是可选的。如需了解这些字段的值，请参阅本指南的上一部分。

Java

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

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


import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.aiplatform.v1.LocationName;
import com.google.cloud.aiplatform.v1.Model;
import com.google.cloud.aiplatform.v1.ModelContainerSpec;
import com.google.cloud.aiplatform.v1.ModelServiceClient;
import com.google.cloud.aiplatform.v1.ModelServiceSettings;
import com.google.cloud.aiplatform.v1.UploadModelOperationMetadata;
import com.google.cloud.aiplatform.v1.UploadModelResponse;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class UploadModelSample {
  public static void main(String[] args)
      throws InterruptedException, ExecutionException, TimeoutException, IOException {
    // TODO(developer): Replace these variables before running the sample.
    String project = "YOUR_PROJECT_ID";
    String modelDisplayName = "YOUR_MODEL_DISPLAY_NAME";
    String metadataSchemaUri =
        "gs://google-cloud-aiplatform/schema/trainingjob/definition/custom_task_1.0.0.yaml";
    String imageUri = "YOUR_IMAGE_URI";
    String artifactUri = "gs://your-gcs-bucket/artifact_path";
    uploadModel(project, modelDisplayName, metadataSchemaUri, imageUri, artifactUri);
  }

  static void uploadModel(
      String project,
      String modelDisplayName,
      String metadataSchemaUri,
      String imageUri,
      String artifactUri)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    ModelServiceSettings modelServiceSettings =
        ModelServiceSettings.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 (ModelServiceClient modelServiceClient = ModelServiceClient.create(modelServiceSettings)) {
      String location = "us-central1";
      LocationName locationName = LocationName.of(project, location);

      ModelContainerSpec modelContainerSpec =
          ModelContainerSpec.newBuilder().setImageUri(imageUri).build();

      Model model =
          Model.newBuilder()
              .setDisplayName(modelDisplayName)
              .setMetadataSchemaUri(metadataSchemaUri)
              .setArtifactUri(artifactUri)
              .setContainerSpec(modelContainerSpec)
              .build();

      OperationFuture<UploadModelResponse, UploadModelOperationMetadata> uploadModelResponseFuture =
          modelServiceClient.uploadModelAsync(locationName, model);
      System.out.format(
          "Operation name: %s\n", uploadModelResponseFuture.getInitialFuture().get().getName());
      System.out.println("Waiting for operation to finish...");
      UploadModelResponse uploadModelResponse = uploadModelResponseFuture.get(5, TimeUnit.MINUTES);

      System.out.println("Upload Model Response");
      System.out.format("Model: %s\n", uploadModelResponse.getModel());
    }
  }
}

Node.js

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

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

/**
 * TODO(developer): Uncomment these variables before running the sample.\
 */

// const modelDisplayName = 'YOUR_MODEL_DISPLAY_NAME';
// const metadataSchemaUri = 'YOUR_METADATA_SCHEMA_URI';
// const imageUri = 'YOUR_IMAGE_URI';
// const artifactUri = 'YOUR_ARTIFACT_URI';
// const project = 'YOUR_PROJECT_ID';
// const location = 'YOUR_PROJECT_LOCATION';

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

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

// Instantiates a client
const modelServiceClient = new ModelServiceClient(clientOptions);

async function uploadModel() {
  // Configure the parent resources
  const parent = `projects/${project}/locations/${location}`;
  // Configure the model resources
  const model = {
    displayName: modelDisplayName,
    metadataSchemaUri: '',
    artifactUri: artifactUri,
    containerSpec: {
      imageUri: imageUri,
      command: [],
      args: [],
      env: [],
      ports: [],
      predictRoute: '',
      healthRoute: '',
    },
  };
  const request = {
    parent,
    model,
  };

  console.log('PARENT AND MODEL');
  console.log(parent, model);
  // Upload Model request
  const [response] = await modelServiceClient.uploadModel(request);
  console.log(`Long running operation : ${response.name}`);

  // Wait for operation to complete
  await response.promise();
  const result = response.result;

  console.log('Upload model response ');
  console.log(`\tModel : ${result.model}`);
}
uploadModel();

Python

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

def upload_model_sample(
    project: str,
    location: str,
    display_name: str,
    serving_container_image_uri: str,
    artifact_uri: Optional[str] = None,
    serving_container_predict_route: Optional[str] = None,
    serving_container_health_route: Optional[str] = None,
    description: Optional[str] = None,
    serving_container_command: Optional[Sequence[str]] = None,
    serving_container_args: Optional[Sequence[str]] = None,
    serving_container_environment_variables: Optional[Dict[str, str]] = None,
    serving_container_ports: Optional[Sequence[int]] = None,
    instance_schema_uri: Optional[str] = None,
    parameters_schema_uri: Optional[str] = None,
    prediction_schema_uri: Optional[str] = None,
    explanation_metadata: Optional[explain.ExplanationMetadata] = None,
    explanation_parameters: Optional[explain.ExplanationParameters] = None,
    sync: bool = True,
):

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

    model = aiplatform.Model.upload(
        display_name=display_name,
        artifact_uri=artifact_uri,
        serving_container_image_uri=serving_container_image_uri,
        serving_container_predict_route=serving_container_predict_route,
        serving_container_health_route=serving_container_health_route,
        instance_schema_uri=instance_schema_uri,
        parameters_schema_uri=parameters_schema_uri,
        prediction_schema_uri=prediction_schema_uri,
        description=description,
        serving_container_command=serving_container_command,
        serving_container_args=serving_container_args,
        serving_container_environment_variables=serving_container_environment_variables,
        serving_container_ports=serving_container_ports,
        explanation_metadata=explanation_metadata,
        explanation_parameters=explanation_parameters,
        sync=sync,
    )

    model.wait()

    print(model.display_name)
    print(model.resource_name)
    return model

如需了解详情，请参阅模型导入指南。

发送预测请求

如需向 Model 发送在线预测请求，请按照从自定义训练的模型获取预测结果中的说明操作。无论您是否使用自定义模型，此过程都一样。

了解自定义容器的预测请求和响应要求。

后续步骤

如需了解设计与 Vertex AI 搭配使用的自定义容器时要考虑的所有事项，请参阅自定义容器要求。