예측용 커스텀 컨테이너 사용

Vertex AI가 커스텀 학습 모델로 온라인 예측을 제공하는 방법을 맞춤설정하려면 Model 리소스를 만들 때 사전 빌드된 컨테이너 대신에 커스텀 컨테이너를 지정할 수 있습니다. 커스텀 컨테이너를 사용하면 Vertex AI가 각 예측 노드에서 원하는 Docker 컨테이너를 실행합니다.

커스텀 컨테이너를 사용해야 할 수 있는 이유는 다음과 같습니다.

• 사전 빌드된 컨테이너로 사용할 수 없는 프레임워크를 사용하여 학습된 ML 모델로부터 예측을 제공합니다.
• 예측 요청을 사전 처리하거나 모델로 생성된 예측을 사후 처리합니다.
• 사용자가 선택한 프로그래밍 언어로 작성된 예측 서버를 실행합니다.
• 예측 맞춤설정을 위해 사용하려는 종속 항목을 설치합니다.

이 가이드에서는 커스텀 컨테이너를 사용하는 모델을 만드는 방법을 설명합니다. Docker 컨테이너 이미지를 만들고 설계하는 방법에 대해서는 자세히 설명하지 않습니다.

컨테이너 이미지 준비

커스텀 컨테이너를 사용하는 Model을 만들려면 이 컨테이너의 기반으로 Docker 컨테이너 이미지를 제공해야 합니다. 이 컨테이너 이미지는 커스텀 컨테이너 요구사항에 설명된 요구사항을 충족해야 합니다.

신뢰하는 제3자가 만든 기존 컨테이너 이미지를 사용하려는 경우, 다음 섹션 중 하나 또는 둘 다 건너뛸 수도 있습니다.

컨테이너 이미지 만들기

컨테이너 이미지 요구사항을 충족하는 Docker 컨테이너 이미지를 설계하고 빌드합니다.

Docker 컨테이너 이미지 설계 및 빌드에 대한 기초를 알아보려면 Docker 문서의 빠른 시작을 참조하세요.

컨테이너 이미지를 Artifact Registry에 푸시

컨테이너 이미지를 Artifact Registry 저장소로 푸시합니다.

Artifact Registry에 컨테이너 이미지를 푸시하는 방법을 알아보세요.

Model 만들기

커스텀 컨테이너를 사용하는 Model을 만들려면 다음 중 하나를 수행합니다.

• 커스텀 학습 모델을 가져옵니다.

• CustomJob을 실행하고 결과 아티팩트를 Model로 가져오는 TrainingPipeline을 만듭니다.

다음 섹션에서는 이러한 방법 중 하나로 Model을 만들 때 커스텀 컨테이너와 관련된 API 필드를 구성하는 방법을 설명합니다.

컨테이너 관련 API 필드

Model을 만들 때, 사전 빌드된 컨테이너보다는 커스텀 컨테이너 세부사항으로 containerSpec 필드를 구성하도록 합니다.

Model.containerSpec 필드에 ModelContainerSpec 메시지를 지정해야 합니다. 이 메시지 내에서 다음 하위 필드를 지정할 수 있습니다.

imageUri(필수)

컨테이너 이미지의 Artifact Registry URI입니다.

gcloud ai models upload 명령어를 사용하는 경우 --container-image-uri 플래그를 사용하여 이 필드를 지정할 수 있습니다.

command(선택사항)

컨테이너의 ENTRYPOINT 안내를 우선 적용하기 위한 실행 파일 및 인수의 배열입니다. 이 필드의 형식을 지정하는 방법과 args 필드와 상호작용하는 방법을 자세히 알아보려면 ModelContainerSpec API 참조를 확인하세요.

gcloud ai models upload 명령어를 사용하는 경우 --container-command 플래그를 사용하여 이 필드를 지정할 수 있습니다.

args(선택사항)

컨테이너의 CMD를 우선 적용하기 위한 실행 파일 및 인수의 배열입니다. 이 필드의 형식을 지정하고 command 필드와 상호작용하는 방법을 자세히 알아보려면 ModelContainerSpec API 참조를 확인하세요.

gcloud ai models upload 명령어를 사용하는 경우 --container-args 플래그를 사용하여 이 필드를 지정할 수 있습니다.

ports(선택사항)

포트 배열입니다. Vertex AI는 나열된 첫 번째 포트 또는 8080(기본값)으로 컨테이너에 활성 확인, 상태 확인, 예측 요청을 전송합니다. 추가 포트를 지정해도 효과가 없습니다.

gcloud ai models upload 명령어를 사용하는 경우 --container-ports 플래그를 사용하여 이 필드를 지정할 수 있습니다.

env(선택사항)

컨테이너의 ENTRYPOINT 안내뿐 아니라 command 및 args 필드가 참조할 수 있는 환경 변수의 배열입니다. 다른 필드가 이러한 환경 변수를 참조할 수 있는 방법을 자세히 알아보려면 ModelContainerSpec API 참조를 확인하세요.

gcloud ai models upload 명령어를 사용하는 경우 --container-env-vars 플래그를 사용하여 이 필드를 지정할 수 있습니다.

healthRoute(선택사항)

Vertex AI가 상태 확인을 전송할 컨테이너의 HTTP 서버 경로입니다.

이 필드를 지정하지 않으면 Model을 DeployedModel 리소스에 Endpoint로서 배포할 때 기본값은 /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL입니다. 여기서 ENDPOINT는 Endpoint의 name 필드(endpoints/ 뒤)의 마지막 세그먼트로 대체되며, DEPLOYED_MODEL는 DeployedModel의 id 필드로 대체됩니다.

gcloud ai models upload 명령어를 사용하는 경우 --container-health-route 플래그를 사용하여 이 필드를 지정할 수 있습니다.

predictRoute(선택사항)

Vertex AI가 예측 요청을 전달하려는 컨테이너의 HTTP 서버 경로입니다.

이 필드를 지정하지 않으면 Model을 DeployedModel 리소스에 Endpoint로서 배포할 때 기본값은 /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict입니다. 여기서 ENDPOINT는 Endpoint의 name 필드(endpoints/ 뒤)의 마지막 세그먼트로 대체되며, DEPLOYED_MODEL는 DeployedModel의 id 필드로 대체됩니다.

gcloud ai models upload 명령어를 사용하는 경우 --container-predict-route 플래그를 사용하여 이 필드를 지정할 수 있습니다.

sharedMemorySizeMb(선택사항)

모델의 공유 메모리 볼륨에 예약할 VM 메모리 양(MB)입니다.

공유 메모리는 여러 프로세스가 공통 메모리 블록을 액세스 및 조작하도록 허용하는 프로세스 간 커뮤니케이션(IPC) 메커니즘입니다. 필요한 공유 메모리 양은 컨테이너 및 모델에 대한 구현 세부정보입니다. 가이드라인은 해당 모델 서버 문서를 참조하세요.

gcloud ai models upload 명령어를 사용하는 경우 --container-shared-memory-size-mb 플래그를 사용하여 이 필드를 지정할 수 있습니다.

startupProbe(선택사항)

컨테이너 애플리케이션이 시작되었는지 여부를 확인하는 프로브 사양입니다.

gcloud ai models upload 명령어를 사용하는 경우 --container-startup-probe-exec, --container-startup-probe-period-seconds, --container-startup-probe-timeout-seconds 플래그를 사용하여 이 필드를 지정할 수 있습니다.

healthProbe(선택사항)

컨테이너가 트래픽을 수락할 준비가 되었는지 확인하는 프로브 사양입니다.

gcloud ai models upload 명령어를 사용하는 경우 --container-health-probe-exec, --container-health-probe-period-seconds, --container-health-probe-timeout-seconds 플래그를 사용하여 이 필드를 지정할 수 있습니다.

Vertex AI는 Model.containerSpec.env 필드에 설정한 변수 외에 구성에 따라 여러 개의 다른 변수를 설정합니다. 이러한 필드 및 컨테이너의 ENTRYPOINT 안내에서 이러한 환경 변수를 사용하는 방법에 대해 자세히 알아보세요.

모델 가져오기 예시

다음 예시는 모델을 가져올 때 컨테이너 관련 API 필드를 지정하는 방법을 보여 줍니다.

참고: TrainingPipeline을 사용하여 Model을 만드는 경우 다른 컨텍스트에서 이러한 필드를 지정해야 합니다. Google Cloud CLI를 사용하여 TrainingPipeline을 만들 수는 없습니다. 커스텀 TrainingPipeline 리소스 만들기에 대해 자세히 알아보세요.

gcloud

다음 예시에서는 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

--container-image-uri 플래그는 필수입니다. --container-로 시작되는 다른 모든 플래그는 선택사항입니다. 이러한 필드의 값에 대해 자세히 알아보려면 이 가이드의 이전 섹션을 참고하세요.

Java

이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 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

이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 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 for Python을 설치하거나 업데이트하는 방법은 Vertex AI SDK for Python 설치를 참조하세요. 자세한 내용은 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

자세한 내용은 모델 가져오기 가이드를 참조하세요.

예측 요청 전송

온라인 예측 요청을 Model에 전송하려면 커스텀 학습 모델에서 예측 수행의 안내를 따르세요. 이 프로세스는 커스텀 컨테이너 사용 여부에 관계없이 동일하게 작동합니다.

커스텀 컨테이너의 예측 요청 및 응답 요구사항에 대해 알아보세요.

다음 단계

• Vertex AI에 사용할 커스텀 컨테이너를 설계할 때 고려해야 할 모든 사항을 자세히 알아보려면 커스텀 컨테이너 요구사항을 참고하세요.