將模型匯入 Vertex AI

本指南說明如何將模型匯入 Vertex AI Model Registry。模型匯入後,就會顯示在模型登錄中。您可以從 Model Registry 將匯入的模型部署至端點,並執行預測。

必要的角色

如要取得匯入模型所需的權限,請要求管理員授予專案的「Vertex AI 使用者 」(roles/aiplatform.user) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

預先建構或自訂容器

匯入模型時,您會將模型與容器建立關聯,供 Vertex AI 執行預測要求。您可以使用 Vertex AI 提供的預先建構容器,也可以使用您自行建構並推送至 Artifact Registry 的自訂容器

如果模型符合下列規定,您可以使用預先建構的容器:

如果您要匯入先前匯出的表格 AutoML 模型,必須使用 Vertex AI 提供的特定自訂容器。

否則,請建立新的自訂容器,或使用 Artifact Registry 中現有的自訂容器。

將模型構件上傳至 Cloud Storage

您必須將模型構件儲存在 Cloud Storage 值區中,且值區的區域必須與您使用的區域端點相符。

如果 Cloud Storage 值區位於其他專案,您需要授予 Vertex AI 讀取模型構件的存取權。 Google Cloud

如果您使用預先建構的容器,請確保模型構件的檔案名稱與下列範例完全相符:

  • TensorFlow SavedModel:saved_model.pb
  • PyTorch:model.mar
  • scikit-learn:model.joblib
  • XGBoost:model.bstmodel.joblib

進一步瞭解如何匯出用於預測工作的模型構件

使用 Google Cloud 控制台匯入模型

如要使用 Google Cloud 控制台匯入模型,請按照下列步驟操作:

  1. 前往 Google Cloud 控制台的 Vertex AI「Models」頁面。

    前往「模型」頁面

  2. 按一下「匯入」

  3. 選取「匯入為新模型」,匯入新模型。

  4. 選取「匯入為新版本」,將模型匯入為現有模型的版本。 如要進一步瞭解模型版本管理,請參閱模型版本管理

  5. 名稱和區域:輸入模型名稱。選取的地區必須與 bucket 的地區和您使用的 Vertex AI 區域端點相符。按一下「繼續」

  6. 展開「Advanced options」(進階選項) 後,您可以選擇新增客戶管理的加密金鑰

請根據您使用的容器類型,選取下方的適當分頁標籤。

預先建構的容器

  1. 選取「將模型構件匯入新的預建容器」

  2. 選取您用來訓練模型的「Model framework」(模型架構) 和「Model framework version」(模型架構版本)

  3. 如要使用 GPU 提供預測服務,請將「加速器類型」設為「GPU」

    您稍後將模型部署至端點時,再選取 GPU 類型。

  4. 指定包含模型構件的目錄 Cloud Storage 路徑。

    例如:gs://BUCKET_NAME/models/

  5. 將「預測結構定義」留空。

  6. 如要匯入 Vertex Explainable AI 設定,請按一下「匯入」

    匯入完成後,模型會顯示在「模型」頁面。

    否則,請在「可解釋性」分頁中輸入可解釋性設定,繼續設定模型。進一步瞭解可解釋性設定

自訂容器

  1. 選取「匯入現有自訂容器」

  2. 設定容器映像檔 URI。

  3. 如要提供模型構件和容器映像檔,請指定包含模型構件的目錄 Cloud Storage 路徑。

    例如 gs://BUCKET_NAME/models/

  4. 為其他欄位指定值。

    進一步瞭解這些選填欄位

  5. 如要匯入 Vertex Explainable AI 設定,請按一下「匯入」

    匯入完成後,模型會顯示在「模型」頁面。

    否則,請在「可解釋性」分頁中輸入可解釋性設定,繼續設定模型。進一步瞭解可解釋性設定

AutoML 表格容器

  1. 選取「匯入現有自訂容器」

  2. 在「Container image」(容器映像檔) 欄位中輸入 MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1:latest

    MULTI_REGION 替換為 useuropeasia,選取要從哪個 Docker 存放區提取 Docker 映像檔。每個存放區提供的 Docker 映像檔都相同,但選擇最靠近執行 Docker 機器位置的 Artifact Registry 多地區,可能會縮短延遲時間。

  3. 在「套件位置」欄位中,指定包含模型構件的目錄 Cloud Storage 路徑。

    路徑類似下列範例:

    gs://BUCKET_NAME/models-MODEL_ID/tf-saved-model/TIMESTAMP/

  4. 將所有其他欄位留空。

  5. 按一下「匯入」

    匯入完成後,模型會顯示在「模型」頁面。您可以像使用其他 AutoML 表格模型一樣使用這個模型,但匯入的 AutoML 表格模型不支援 Vertex Explainable AI。

透過程式輔助匯入模型

以下範例說明如何使用各種工具匯入模型:

gcloud

下列範例使用 gcloud ai models upload 指令

gcloud ai models upload \
  --region=LOCATION \
  --display-name=MODEL_NAME \
  --container-image-uri=IMAGE_URI \
  --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY

更改下列內容:

  • LOCATION_ID:您使用 Vertex AI 的區域。
  • MODEL_NAMEModel 的顯示名稱。
  • IMAGE_URI:用於提供預測結果的容器映像檔 URI。例如:us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest。使用預先建構的容器自訂容器
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY:Cloud Storage 目錄的 Cloud Storage URI (開頭為 gs://),其中包含模型構件

上述範例顯示匯入大多數模型所需的所有旗標。如果沒有使用預建容器進行預測,您可能需要指定一些額外的選用標記,Vertex AI 才能使用容器映像檔。這些旗標以 --container- 開頭,對應至 ModelcontainerSpec 欄位。

REST

使用下列程式碼範例,透過 model 資源的 upload 方法上傳模型

使用任何要求資料之前,請先替換以下項目:

  • LOCATION_ID:您使用 Vertex AI 的區域。
  • PROJECT_ID:您的專案 ID
  • MODEL_NAMEModel 的顯示名稱。
  • MODEL_DESCRIPTION:選用。模型的說明。
  • IMAGE_URI:用於提供預測結果的容器映像檔 URI。例如:us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest。使用預先建構的容器自訂容器
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY:Cloud Storage 目錄的 Cloud Storage URI (開頭為 gs://),其中包含模型構件。 如果您使用自訂容器,這個變數和 artifactUri 欄位為選用。
  • labels:選用。任何一組鍵/值組合,可用於整理模型。舉例來說:
    • "env": "prod"
    • "tier": "backend"
  • 為要套用至這項訓練管道的任何標籤指定 LABEL_NAMELABEL_VALUE

HTTP 方法和網址:

POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/models:upload

JSON 要求主體:

{
  "model": {
    "displayName": "MODEL_NAME",
    "predictSchemata": {},
    "containerSpec": {
      "imageUri": "IMAGE_URI"
    },
    "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY",
    "labels": {
      "LABEL_NAME_1": "LABEL_VALUE_1",
      "LABEL_NAME_2": "LABEL_VALUE_2"
    }
  }
}

如要傳送要求,請選擇以下其中一個選項:

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/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_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/models:upload" | Select-Object -Expand Content

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 適用的 Vertex AI SDK

如要瞭解如何安裝或更新 Python 適用的 Vertex AI SDK,請參閱「安裝 Python 適用的 Vertex AI SDK」。 詳情請參閱 Vertex AI SDK for 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

如要匯入已啟用 Vertex Explainable AI 設定的模型,請參閱 Vertex Explainable AI 模型匯入範例

取得作業狀態

部分要求會啟動長時間執行的作業,需要一段時間才能完成。這些要求會傳回作業名稱,您可以使用該名稱查看作業狀態或取消作業。Vertex AI 提供輔助方法,可對長時間執行的作業發出呼叫。詳情請參閱「處理長時間執行作業」。

限制

  • 模型登錄檔支援的最大模型大小為 1 TB。

後續步驟