Menggunakan container kustom untuk prediksi

Untuk menyesuaikan cara Vertex AI menyajikan prediksi online dari model terlatih kustom, Anda dapat menentukan container kustom sebagai ganti container saat Anda membuat Model resource Anda 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:

• menginferensi prediksi dari model ML yang dilatih menggunakan framework yang 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. Ini tidak memberikan petunjuk terperinci tentang cara mendesain dan membuat Docker image container.

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 Anda berencana menggunakan image container yang ada yang dibuat oleh pihak ketiga dipercaya, Anda mungkin dapat melewatkan 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 Artifact Registry.

Pelajari cara mengirim image container ke Artifact Registry.

Membuat Model

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

• Impor model kustom yang dilatih.

• Buat TrainingPipeline yang menjalankan CustomJob dan mengimpor artefak yang dihasilkan sebagai Model.

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 dari image container Anda.

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

command (opsional)

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

Jika Anda menggunakan 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 Anda menggunakan 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 Anda menggunakan gcloud ai models upload, Anda dapat menggunakan flag --container-ports untuk menentukan kolom ini.

env (opsional)

Array variabel lingkungan yang oleh instruksi ENTRYPOINT container, serta kolom command dan args, dapat mereferensikan. Untuk mempelajari lebih lanjut tentang bagaimana kolom lain dapat mereferensikan variabel lingkungan ini, baca Referensi API untuk ModelContainerSpec.

Jika Anda menggunakan 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 Anda menggunakan 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 Anda menggunakan 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 antar proses (IPC) yang memungkinkan beberapa proses untuk mengakses dan memanipulasi blok memori yang sama. Tujuan jumlah memori bersama yang dibutuhkan, jika ada, adalah detail implementasi container dan model. Lihat dokumentasi server model Anda untuk mendapatkan panduan.

Jika Anda menggunakan 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 dimulai.

Jika Anda menggunakan 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 pemeriksaan yang memeriksa apakah kontainer siap untuk menerima traffic.

Jika Anda menggunakan 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 tersebut dan dalam petunjuk ENTRYPOINT penampung.

Contoh impor model

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

Catatan: Jika menggunakan TrainingPipeline untuk membuat Model, Anda harus menentukan {i>field<i} ini dalam konteks yang berbeda. Anda tidak dapat menggunakan Google Cloud CLI untuk membuat TrainingPipeline. Baca selengkapnya tentang cara membuat TrainingPipeline kustom referensi.

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 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 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 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 berikutnya

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