使用自訂容器執行推論

如要自訂 Vertex AI 從自訂訓練模型提供線上推論的方式，您可以在建立Model資源時，指定自訂容器，而非預建容器。使用自訂容器時，Vertex AI 會在每個推論節點上執行您選擇的 Docker 容器。

您可能基於下列原因而使用自訂容器：

• 使用預先建構的容器中未提供的架構訓練機器學習模型，並從中提供推論結果
• 預先處理推論要求，或後續處理模型生成的推論
• 執行以您選擇的程式設計語言編寫的推論伺服器
• 安裝要用於自訂推論的依附元件

本指南說明如何建立使用自訂容器的模型。但不會提供設計及建立 Docker 容器映像檔的詳細操作說明。

準備容器映像檔

如要建立使用自訂容器的 Model，您必須提供 Docker 容器映像檔做為該容器的基礎。這個容器映像檔必須符合自訂容器需求中所述的規定。

如果您打算使用第三方建立的現有容器映像檔 (您信任該第三方)，或許可以略過下列一或兩個章節。

建立容器映像檔

設計及建構符合容器映像檔需求的 Docker 容器映像檔。

如要瞭解設計及建構 Docker 容器映像檔的基本知識，請參閱 Docker 說明文件的快速入門導覽課程。

將容器映像檔推送至 Artifact Registry

將容器映像檔推送至 Artifact Registry 存放區。

瞭解如何將容器映像檔推送到 Artifact Registry。

建立 Model

如要建立使用自訂容器的 Model，請執行下列其中一項操作：

• 匯入自訂訓練模型。

• 建立 TrainingPipeline，執行 CustomJob 並將產生的構件匯入為 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 欄位的互動方式，請參閱 API 參考資料的 ModelContainerSpec。

如果您使用 gcloud ai models upload 指令，可以透過 --container-args 旗標指定這個欄位。

ports (選填)

通訊埠陣列；Vertex AI 會將有效性檢查、健康狀態檢查和推論要求傳送至列出的第一個通訊埠，或預設為 8080。指定其他連接埠不會產生任何影響。

如果您使用 gcloud ai models upload 指令，可以透過 --container-ports 旗標指定這個欄位。

env (選填)

容器的 ENTRYPOINT 指令以及 command 和 args 欄位可參照的環境變數陣列。如要進一步瞭解其他欄位如何參照這些環境變數，請參閱 API 參考資料。ModelContainerSpec

如果您使用 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 (選填)

要在共用記憶體磁碟區中為模型保留的 VM 記憶體量，以 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 還會根據您的設定，設定其他幾個變數。進一步瞭解如何在這些欄位和容器的 ENTRYPOINT 指令中使用這些環境變數。

模型匯入範例

以下範例說明匯入模型時，如何指定容器相關的 API 欄位。

注意： 如果您使用 TrainingPipeline 建立 Model，則必須在不同環境中指定這些欄位。您無法使用 Google Cloud CLI 建立 TrainingPipeline。進一步瞭解如何建立自訂TrainingPipeline資源。

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

在試用這個範例之前，請先按照Java使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 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

在試用這個範例之前，請先按照Node.js使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 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 參考說明文件。

from typing import Dict, Optional, Sequence

from google.cloud import aiplatform
from google.cloud.aiplatform import explain


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 使用時的所有注意事項，請參閱自訂容器規定。