Menggunakan container kustom untuk inferensi

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

Anda dapat menggunakan container kustom karena salah satu alasan berikut:

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

Panduan ini menjelaskan cara membuat model yang menggunakan container kustom. Dokumen ini tidak memberikan petunjuk terperinci tentang cara 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 Anda berencana menggunakan image container yang ada yang dibuat oleh pihak ketiga yang Anda percayai, Anda mungkin dapat melewati 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 image container ke Artifact Registry

Kirim image container Anda ke repositori an 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 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 petunjuk container ENTRYPOINT. 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 container CMD Untuk mempelajari lebih lanjut cara memformat kolom ini dan cara kolom ini berinteraksi dengan kolom 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; Agent Platform mengirimkan pemeriksaan keaktifan, health check, dan permintaan inferensi 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 petunjuk 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 Agent Platform 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 Endpoint's name kolom (mengikuti endpoints/) dan DEPLOYED_MODEL diganti dengan DeployedModel's id kolom.

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 Agent Platform meneruskan permintaan inferensi.

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 Endpoint's name kolom (mengikuti endpoints/) dan DEPLOYED_MODEL diganti dengan DeployedModel's id kolom.

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

invokeRoutePrefix (opsional)

Awalan rute pemanggilan untuk container kustom. Menetapkan kolom ini ke "/*" akan mengaktifkan perutean arbitrer untuk model. Setelah di-deploy, rute non-root apa pun di server model akan dapat diakses dengan panggilan HTTP pemanggilan. Misalnya, "/invoke/foo/bar" akan diteruskan sebagai "/foo/bar" ke server model. Fitur ini berada dalam tahap pratinjau publik. Untuk membuat model yang mengaktifkan pemanggilan, ikuti petunjuk untuk menggunakan rute kustom arbitrer.

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 mengakses dan memanipulasi blok memori umum. Jumlah memori bersama yang diperlukan, jika ada, adalah detail implementasi container dan model Anda. Lihat dokumentasi server model Anda untuk mengetahui panduannya.

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, Agent Platform juga menetapkan beberapa variabel lainnya berdasarkan konfigurasi Anda. Pelajari lebih lanjut cara menggunakan variabel lingkungan ini di kolom ini dan di petunjuk ENTRYPOINT container.

Contoh impor model

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

Catatan: Jika Anda menggunakan TrainingPipeline untuk membuat Model, Anda harus menentukan kolom ini dalam konteks yang berbeda. Anda tidak dapat menggunakan Google Cloud CLI untuk membuat TrainingPipeline. Baca lebih lanjut cara membuat TrainingPipeline resource kustom.

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 Agent Platform menggunakan library klien.

Untuk melakukan autentikasi ke Agent Platform, 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 Agent Platform menggunakan library klien.

Untuk melakukan autentikasi ke Agent Platform, 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 Python dokumentasi referensi 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 mengetahui konteks selengkapnya, baca Panduan impor model.

Mengirim permintaan inferensi

Untuk mengirim permintaan inferensi online ke Model, ikuti petunjuk di bagian Mendapatkan inferensi 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 Agent Platform, baca Persyaratan container kustom.