Mengimpor model ke Vertex AI

Panduan ini menjelaskan cara mengimpor model ke Model Registry. Setelah diimpor, model Anda akan terlihat di Model Registry. Dari Model Registry, Anda dapat men-deploy model yang diimpor ke endpoint dan menjalankan prediksi.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengimpor model, minta administrator Anda untuk memberi Anda peran IAM Vertex AI User (roles/aiplatform.user) pada project tersebut. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Container kustom atau bawaan

Saat mengimpor model, Anda mengaitkannya dengan container agar Vertex AI dapat menjalankan permintaan prediksi. Anda dapat menggunakan container bawaan yang disediakan oleh Vertex AI, atau menggunakan container kustom sendiri yang Anda build dan kirim ke Artifact Registry.

Anda dapat menggunakan container bawaan jika model Anda memenuhi persyaratan berikut:

Jika Anda mengimpor model AutoML tabulasi yang sebelumnya diekspor, Anda harus menggunakan container kustom khusus yang disediakan oleh Vertex AI.

Jika tidak, buat container kustom baru, atau gunakan container kustom yang sudah ada dan Anda miliki di Artifact Registry.

Mengupload artefak model ke Cloud Storage

Anda harus menyimpan artefak model Anda di bucket Cloud Storage, dimana region bucketnya cocok dengan endpoint regional yang Anda gunakan.

Jika bucket Cloud Storage Anda berada di project Google Cloud lain, Anda perlu memberikan akses kepada Vertex AI untuk membaca artefak model Anda.

Jika Anda menggunakan container bawaan, pastikan artefak model Anda memiliki nama file yang sama persis dengan contoh berikut:

  • TensorFlow SavedModel: saved_model.pb
  • PyTorch: model.mar
  • scikit-learn: model.joblib atau model.pkl
  • XGBoost: model.bst, model.joblib, atau model.pkl

Pelajari lebih lanjut cara mengekspor artefak model untuk prediksi.

Mengimpor model menggunakan Konsol Google Cloud

Cara mengimpor model menggunakan Konsol Google Cloud:

  1. Di Konsol Google Cloud, buka halaman Model Vertex AI.

    Buka halaman Model

  2. Klik Import.

  3. Pilih Import as new model untuk mengimpor model baru.

  4. Pilih Import as new version untuk mengimpor model sebagai versi dari model yang sudah ada. Untuk mempelajari pembuatan versi model lebih lanjut, lihat Pembuatan versi model.

  5. Nama dan region: Masukkan nama untuk model Anda. Pilih region yang cocok dengan region bucket Anda dan endpoint regional Vertex AI yang Anda gunakan. Klik Continue.

  6. Jika memperluas Advanced options, Anda dapat memutuskan untuk menambahkan kunci enkripsi yang dikelola pelanggan atau tidak.

Bergantung pada jenis container yang Anda gunakan, pilih tab yang sesuai di bawah.

Container bawaan

  1. Pilih Import model artifacts into a new prebuilt container.

  2. Pilih Model framework dan Model framework version yang Anda gunakan untuk melatih model baru.

  3. Jika Anda ingin menggunakan GPU untuk menyalurkan prediksi, tetapkan Accelerator type ke GPU.

    Anda dapat memilih jenis GPU nanti saat men-deploy model ke endpoint.

  4. Tentukan jalur Cloud Storage ke direktori yang berisi artefak model Anda.

    Misalnya, gs://BUCKET_NAME/models/.

  5. Biarkan Predict schemata kosong.

  6. Untuk mengimpor model Anda tanpa setelan Vertex Explainable AI, klik Import.

    Setelah impor selesai, model Anda akan muncul di halaman Models.

    Jika tidak, lanjutkan mengonfigurasi model Anda dengan memasukkan setelan penjelasan di tab Explainability. Pelajari Setelan penjelasan lebih lanjut.

Container kustom

  1. Pilih Import an existing custom container.

  2. Menetapkan URI image container.

  3. Jika ingin menyediakan artefak model selain image container, tentukan jalur Cloud Storage ke direktori yang berisi artefak model Anda.

    Misalnya, gs://BUCKET_NAME/models/.

  4. Tentukan nilai untuk kolom lainnya.

    Pelajari kolom opsional ini lebih lanjut.

  5. Untuk mengimpor model Anda tanpa setelan Vertex Explainable AI, klik Import.

    Setelah impor selesai, model Anda akan muncul di halaman Models.

    Jika tidak, lanjutkan mengonfigurasi model Anda dengan memasukkan setelan penjelasan di tab Explainability. Pelajari Setelan penjelasan lebih lanjut.

Container tabulasi AutoML

  1. Pilih Import an existing custom container.

  2. Di kolom Container image, masukkan MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1:latest.

    Ganti MULTI_REGION dengan us, europe, atau asia untuk memilih repositori Docker mana yang ingin Anda ambil image Dockernya. Setiap repositori menyediakan image Docker yang sama, tetapi memilih multi-region Artifact Registry yang terdekat dengan mesin tempat Anda menjalankan Docker dapat mengurangi latensi.

  3. Di kolom Package location, tentukan jalur Cloud Storage ke direktori yang berisi artefak model Anda.

    Jalur tersebut terlihat mirip dengan contoh berikut:

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

  4. Biarkan kolom lain kosong.

  5. Klik Import.

    Setelah impor selesai, model Anda akan muncul di halaman Models. Anda dapat menggunakan model ini seperti model tabulasi AutoML lainnya, kecuali model tabulasi AutoML yang diimpor tidak mendukung Vertex Explainable AI.

Mengimpor model secara terprogram

Contoh berikut menunjukkan cara mengimpor model menggunakan berbagai alat:

gcloud

Contoh berikut menggunakan perintah 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

Ganti kode berikut:

  • LOCATION_ID: Region tempat Anda menggunakan Vertex AI.
  • MODEL_NAME: Nama tampilan untuk Model.
  • IMAGE_URI: URI image container yang akan digunakan untuk menampilkan prediksi. Contoh, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Gunakan container bawaan atau container kustom.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: Cloud Storage URI (dimulai dengan gs://) dari direktori di Cloud Storage yang berisi artefak model Anda.

Contoh sebelumnya menunjukkan semua flag yang diperlukan untuk mengimpor sebagian besar model. Jika tidak menggunakan container bawaan untuk prediksi, Anda mungkin perlu menentukan beberapa tanda opsional tambahan agar Vertex AI dapat menggunakan image container Anda. Tanda ini, yang dimulai dengan --container-, sesuai dengan kolom containerSpec Model Anda.

REST

Gunakan contoh kode berikut untuk mengupload model menggunakan metode upload dari resource model.

Sebelum menggunakan salah satu data permintaan, buat pengganti berikut:

  • LOCATION_ID: Region tempat Anda menggunakan Vertex AI.
  • PROJECT_ID: Project ID Anda.
  • MODEL_NAME: Nama tampilan untuk Model.
  • MODEL_DESCRIPTION: Opsional. Deskripsi model.
  • IMAGE_URI: URI image container yang akan digunakan untuk menampilkan prediksi. Contoh, us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest. Gunakan container bawaan atau container kustom.
  • PATH_TO_MODEL_ARTIFACT_DIRECTORY: Cloud Storage URI (dimulai dengan gs://) dari direktori di Cloud Storage yang berisi artefak model Anda. Variabel ini dan kolom artifactUri bersifat opsional jika Anda menggunakan container kustom.
  • labels: Opsional. Kumpulan key-value pair apa pun untuk mengatur model Anda. Contoh:
    • "env": "prod"
    • "tier": "backend"
  • Tentukan LABEL_NAME dan LABEL_VALUE untuk setiap label yang ingin Anda terapkan ke pipeline pelatihan ini.

Metode HTTP dan URL: 

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

Isi JSON permintaan: 

{
  "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"
    }
  }
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Java Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 


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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Node.js Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

/**
 * 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

Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi 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

Untuk mengimpor model dengan setelan Vertex Explainable AI yang telah diaktifkan, lihat Contoh impor model Vertex Explainable AI.

Mendapatkan status operasi

Beberapa permintaan memulai operasi yang berjalan lama, yang memerlukan waktu beberapa saat untuk selesai. Permintaan ini menampilkan nama operasi, yang dapat Anda gunakan untuk melihat status operasi atau membatalkan operasi. Vertex AI menyediakan metode helper untuk melakukan panggilan terhadap operasi yang berjalan lama. Untuk mengetahui informasi selengkapnya, lihat Menangani operasi yang berjalan lama.

Batasan

  • Ukuran model maksimum yang didukung adalah 10 GiB.

Langkah selanjutnya