Menggunakan container kustom untuk prediksi

Untuk menyesuaikan cara Vertex AI menyajikan prediksi online dari model yang dilatih khusus, Anda dapat menentukan container kustom, bukan container bawaan saat membuat Model resource. Saat Anda menggunakan container kustom, Vertex AI akan menjalankan container Docker pilihan Anda pada setiap node prediksi.

Anda dapat menggunakan container kustom karena salah satu alasan berikut:

  • untuk menyajikan prediksi dari model ML yang dilatih menggunakan framework yang tidak tersedia sebagai container bawaan
  • untuk melakukan pra-pemrosesan permintaan prediksi atau melakukan pascapemrosesan terhadap prediksi yang dihasilkan oleh model Anda
  • untuk menjalankan server prediksi yang ditulis dalam bahasa pemrograman pilihan Anda
  • untuk menginstal dependensi yang ingin Anda gunakan untuk menyesuaikan prediksi

Panduan ini menjelaskan cara membuat Model yang menggunakan container kustom. Bagian ini tidak memberikan petunjuk terperinci tentang mendesain dan membuat image container Docker.

Menyiapkan image container

Untuk membuat Model yang menggunakan container kustom, Anda harus menyediakan image container Docker sebagai dasar dari container tersebut. Image container ini harus memenuhi persyaratan yang dijelaskan dalam Persyaratan container kustom.

Jika berencana menggunakan image container yang sudah ada yang dibuat oleh pihak ketiga yang dipercayai, Anda mungkin dapat melewati salah satu atau kedua bagian berikut.

Membuat image container

Desain dan build image container Docker yang memenuhi persyaratan image container.

Untuk mempelajari dasar-dasar mendesain dan mem-build image container Docker, baca panduan memulai dokumentasi Docker

Mengirim container ke Artifact Registry

Kirim image container Anda ke repositori Artifact Registry.

Pelajari cara mengirim image container ke Artifact Registry.

Membuat Model

Untuk membuat Model yang menggunakan container kustom, lakukan salah satu hal berikut:

Bagian berikut menunjukkan cara mengonfigurasi kolom API yang terkait dengan container kustom saat Anda membuat Model dengan salah satu cara berikut.

Kolom API terkait container

Saat Anda membuat Model, pastikan untuk mengonfigurasi kolom containerSpec dengan detail container kustom Anda, bukan dengan container bawaan

Anda harus menentukan pesan ModelContainerSpec di kolom Model.containerSpec. Dalam pesan ini, Anda dapat menentukan subkolom berikut:

imageUri (diperlukan)

URI Artifact Registry image container Anda.

Jika menggunakan perintah gcloud ai models upload, Anda dapat menggunakan flag --container-image-uri untuk menentukan kolom ini.

command (opsional)

Array yang dapat dieksekusi dan argumen untuk mengganti ENTRYPOINT container. Untuk mempelajari lebih lanjut cara memformat kolom ini dan cara interaksinya dengan kolom args, baca Referensi API untuk ModelContainerSpec.

Jika menggunakan perintah gcloud ai models upload, Anda dapat menggunakan flag --container-command untuk menentukan kolom ini.

args (opsional)

Array yang dapat dieksekusi dan argumen untuk mengganti CMD container. Untuk mempelajari lebih lanjut cara memformat kolom ini dan cara kolom ini berinteraksi dengan command, baca referensi API untuk ModelContainerSpec.

Jika menggunakan perintah gcloud ai models upload, Anda dapat menggunakan flag --container-args untuk menentukan kolom ini.

ports (opsional)

Sebuah array port; Vertex AI mengirimkan pemeriksaan keaktifan, health check, dan permintaan prediksi ke container Anda pada port pertama yang tercantum, atau 8080 secara default. Menentukan port tambahan tidak akan berpengaruh.

Jika menggunakan perintah gcloud ai models upload, Anda dapat menggunakan flag --container-ports untuk menentukan kolom ini.

env (opsional)

Array variabel lingkungan yang dapat dirujuk oleh perintah entrypoint container, serta kolom command dan args. Untuk mempelajari lebih lanjut cara kolom lain dapat mereferensikan variabel lingkungan ini, baca referensi API untuk ModelContainerSpec.

Jika menggunakan perintah gcloud ai models upload, Anda dapat menggunakan flag --container-env-vars untuk menentukan kolom ini.

healthRoute (opsional)

Jalur di server HTTP container tempat Anda ingin Vertex AI mengirim health check.

Jika tidak menentukan kolom ini, saat Anda men-deploy Model sebagai DeployedModel ke resource Endpoint, defaultnya adalah /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL, dengan ENDPOINT diganti dengan segmen terakhir dari kolom name Endpoint (mengikuti endpoints/) dan DEPLOYED_MODEL diganti dengan kolom DeployedModel id.

Jika menggunakan perintah gcloud ai models upload, Anda dapat menggunakan flag --container-health-route untuk menentukan kolom ini.

predictRoute (opsional)

Jalur di server HTTP container tempat Anda ingin Vertex AI meneruskan permintaan prediksi.

Jika tidak menentukan kolom ini, saat Anda men-deploy Model sebagai DeployedModel ke resource Endpoint, defaultnya adalah /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict, dengan ENDPOINT diganti dengan segmen terakhir dari kolom name Endpoint (mengikuti endpoints/) dan DEPLOYED_MODEL diganti dengan kolom DeployedModel id.

Jika menggunakan perintah gcloud ai models upload, Anda dapat menggunakan flag --container-predict-route untuk menentukan kolom ini.

sharedMemorySizeMb (opsional)

Jumlah memori VM yang akan dicadangkan dalam volume memori bersama untuk model dalam megabyte.

Memori bersama adalah mekanisme komunikasi antarproses (IPC) yang memungkinkan beberapa proses mengakses dan memanipulasi blok memori umum. Jumlah memori bersama yang diperlukan, jika ada, adalah detail implementasi dari container dan model Anda. Lihat dokumentasi server model untuk mendapatkan panduan.

Jika menggunakan perintah gcloud ai models upload, Anda dapat menggunakan flag --container-shared-memory-size-mb untuk menentukan kolom ini.

startupProbe (opsional)

Spesifikasi untuk pemeriksaan yang memeriksa apakah aplikasi container telah dimulai.

Jika menggunakan perintah gcloud ai models upload, Anda dapat menggunakan flag --container-startup-probe-exec, --container-startup-probe-period-seconds, --container-startup-probe-timeout-seconds untuk menentukan kolom ini.

healthProbe (opsional)

Spesifikasi untuk pemeriksaan yang memeriksa apakah container siap menerima traffic.

Jika menggunakan perintah gcloud ai models upload, Anda dapat menggunakan flag --container-health-probe-exec, --container-health-probe-period-seconds, --container-health-probe-timeout-seconds untuk menentukan kolom ini.

Selain variabel yang Anda tetapkan di kolom Model.containerSpec.env, Vertex AI juga menetapkan beberapa variabel lainnya berdasarkan konfigurasi Anda. Pelajari lebih lanjut cara menggunakan variabel lingkungan ini di kolom ini dan di perintah titik entri container.

Contoh impor model

Contoh berikut menunjukkan cara menentukan kolom API terkait container saat Anda mengimpor model.

gcloud

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

Flag --container-image-uri diperlukan; semua flag lain yang dimulai dengan --container- bersifat opsional. Untuk mempelajari nilai kolom ini, lihat bagian sebelumnya dalam panduan ini.

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, baca 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, baca 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. 

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 mengetahui konteks selengkapnya, baca Panduan impor model.

Mengirim permintaan prediksi

Untuk mengirim permintaan prediksi online ke Model, ikuti petunjuk di bagian Mendapatkan prediksi dari model kustom yang terlatih: proses ini berfungsi sama terlepas dari apakah Anda menggunakan model container.

Baca tentang memprediksi persyaratan permintaan dan respons untuk container kustom.

Langkah selanjutnya

  • Untuk mempelajari semua hal yang perlu dipertimbangkan saat Anda mendesain container kustom untuk digunakan dengan Vertex AI, baca Persyaratan container kustom.