Vertex AI로 모델 가져오기

이 가이드에서는 모델을 Model Registry로 가져오는 방법을 설명합니다. 모델을 가져오면 Model Registry에 표시됩니다. Model Registry에서 가져온 모델을 엔드포인트에 배포하고 예측을 실행할 수 있습니다.

필요한 역할

모델을 가져오는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Vertex AI 사용자(roles/aiplatform.user) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

사전 빌드 또는 커스텀 컨테이너

모델을 가져올 때 Vertex AI의 컨테이너와 연결하여 예측 요청을 실행합니다. Vertex AI에서 제공하는 사전 빌드된 컨테이너를 사용하거나, 빌드하여 Artifact Registry로 푸시하는 자체 커스텀 컨테이너를 사용할 수 있습니다.

모델이 다음 요구사항을 충족하는 경우 사전 빌드된 컨테이너를 사용할 수 있습니다.

Python 3.7 이상에서 학습
TensorFlow, PyTorch, scikit-learn 또는 XGBoost를 사용하여 학습
사전 빌드된 예측 컨테이너 중 하나의 프레임워크별 요구사항을 충족하도록 내보내기

이전에 내보낸 테이블 형식 AutoML 모델을 가져오는 경우 Vertex AI에서 제공하는 특정 커스텀 컨테이너를 사용해야 합니다.

그렇지 않으면 새 커스텀 컨테이너를 만들거나 Artifact Registry에 있는 기존 커스텀 컨테이너를 사용합니다.

Cloud Storage에 모델 아티팩트 업로드

버킷의 리전이 사용 중인 리전 엔드포인트와 일치하는 Cloud Storage 버킷에 모델 아티팩트를 저장해야 합니다.

Cloud Storage 버킷이 다른 Google Cloud 프로젝트에 있는 경우 모델 아티팩트를 읽을 수 있는 Vertex AI 액세스 권한을 부여해야 합니다.

사전 빌드된 컨테이너를 사용하는 경우 모델 아티팩트의 파일 이름이 다음 예시와 정확히 일치해야 합니다.

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

예측용 모델 아티팩트 내보내기 자세히 알아보기

Google Cloud 콘솔을 사용한 모델 가져오기

Google Cloud 콘솔을 사용하여 모델을 가져오려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 Vertex AI 모델 페이지로 이동합니다.

모델 페이지로 이동
가져오기를 클릭합니다.
새 모델로 가져오기를 선택하여 새 모델을 가져옵니다.
기존 버전으로 가져오기를 선택하여 모델을 기존 모델의 버전으로 가져옵니다. 모델 버전 관리에 대한 자세한 내용은 모델 버전 관리를 참조하세요.
이름 및 리전: 모델 이름을 입력합니다. 버킷 리전 및 사용 중인 Vertex AI 리전 엔드포인트와 일치하는 리전을 선택합니다. 계속을 클릭합니다.
고급 옵션을 펼치면 선택적으로 고객 관리 암호화 키를 추가할 수 있습니다.

사용 중인 컨테이너의 유형에 따라 다음에서 적절한 탭을 선택합니다.

사전 빌드된 컨테이너

사전 빌드된 새 컨테이너로 모델 아티팩트 가져오기를 선택합니다.
모델 학습에 사용된 모델 프레임워크 및 모델 프레임워크 버전을 선택합니다.
예측 제공에 GPU를 사용하려면 가속기 유형을 GPU로 설정합니다.

나중에 모델을 엔드포인트에 배포할 때 GPU 유형을 선택합니다.
모델 아티팩트가 포함된 디렉터리의 Cloud Storage 경로를 지정합니다.

예를 들면 gs://BUCKET_NAME/models/입니다.
schemata 예측은 비워 둡니다.
Vertex Explainable AI 설정을 사용하지 않고 모델을 가져오려면 가져오기를 클릭합니다.

가져오기가 완료되면 모델 페이지에 모델이 나타납니다.

그렇지 않으면 설명 기능 탭에 설명 기능 설정을 입력하여 모델을 계속 구성하세요. 설명 기능 설정에 대해 자세히 알아보세요.

커스텀 컨테이너

기존 커스텀 컨테이너 가져오기를 선택합니다.
컨테이너 이미지 URI를 설정합니다.
컨테이너 이미지 외에 모델 아티팩트를 제공하려면 모델 아티팩트가 포함된 디렉터리의 Cloud Storage 경로를 지정합니다.

예를 들면 gs://BUCKET_NAME/models/입니다.
다른 필드의 값을 지정합니다.

이러한 선택적 필드에 대해 자세히 알아보세요.
Vertex Explainable AI 설정을 사용하지 않고 모델을 가져오려면 가져오기를 클릭합니다.

가져오기가 완료되면 모델 페이지에 모델이 나타납니다.

그렇지 않으면 설명 기능 탭에 설명 기능 설정을 입력하여 모델을 계속 구성하세요. 설명 기능 설정에 대해 자세히 알아보세요.

AutoML 테이블 형식 컨테이너

기존 커스텀 컨테이너 가져오기를 선택합니다.
컨테이너 이미지 필드에 MULTI_REGION-docker.pkg.dev/vertex-ai/automl-tabular/prediction-server-v1:latest를 입력합니다.

MULTI_REGION을 us, europe 또는 asia로 바꿔 Docker 이미지를 가져올 Docker 저장소를 선택합니다. 각 저장소에서 동일한 Docker 이미지를 제공하지만 Docker를 실행하는 머신에 가장 가까운 Artifact Registry 멀티 리전을 선택하면 지연 시간이 줄어들 수 있습니다.
패키지 위치 필드에서 모델 아티팩트가 포함된 디렉터리의 Cloud Storage 경로를 지정합니다.

경로는 다음 예시와 비슷합니다.

gs://BUCKET_NAME/models-MODEL_ID/tf-saved-model/TIMESTAMP/
다른 모든 필드를 비워둡니다.
가져오기를 클릭합니다.

가져오기가 완료되면 모델 페이지에 모델이 나타납니다. 이 모델을 다른 AutoML 테이블처럼 사용할 수 있습니다. 단, 가져온 AutoML 테이블 형식 모델에서는 Vertex Explainable AI를 지원하지 않습니다.

프로그래매틱 방식으로 모델 가져오기

다음 예시에서는 다양한 도구를 사용하여 모델을 가져오는 방법을 보여줍니다.

gcloud

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

다음을 바꿉니다.

LOCATION_ID: Vertex AI를 사용하는 리전
MODEL_NAME: Model의 표시 이름입니다.
IMAGE_URI: 예측 제공에 사용할 컨테이너 이미지의 URI입니다. 예를 들면 us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest입니다. 사전 빌드된 컨테이너 또는 커스텀 컨테이너를 사용합니다.
PATH_TO_MODEL_ARTIFACT_DIRECTORY: 모델 아티팩트가 포함된 Cloud Storage에 있는 디렉터리의 Cloud Storage URI(gs://로 시작)입니다.

앞의 예시는 대부분의 모델을 가져오는 데 필요한 모든 플래그를 보여줍니다. 예측을 위해 사전 빌드된 컨테이너를 사용하지 않는 경우 Vertex AI가 컨테이너 이미지를 사용할 수 있도록 몇 가지 추가 선택적 플래그를 지정해야 할 수도 있습니다. --container-로 시작하는 이러한 플래그는 Model의 containerSpec 필드에 해당합니다.

REST

model 리소스의 upload 메서드를 사용하여 모델을 업로드하려면 다음 코드 샘플을 사용하세요.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

LOCATION_ID: Vertex AI를 사용하는 리전
PROJECT_ID: 프로젝트 ID
MODEL_NAME: Model의 표시 이름입니다.
MODEL_DESCRIPTION: 선택사항. 모델에 대한 설명입니다.
IMAGE_URI: 예측 제공에 사용할 컨테이너 이미지의 URI입니다. 예를 들면 us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-1:latest입니다. 사전 빌드된 컨테이너 또는 커스텀 컨테이너를 사용합니다.
PATH_TO_MODEL_ARTIFACT_DIRECTORY: 모델 아티팩트가 포함된 Cloud Storage에 있는 디렉터리의 Cloud Storage URI(gs://로 시작)입니다. 커스텀 컨테이너를 사용하는 경우 이 변수 및 artifactUri 필드는 선택사항입니다.
labels: 선택사항. 모델을 구성할 모든 키-값 쌍 세트입니다. 예를 들면 다음과 같습니다.
- "env": "prod"
- "tier": "backend"
학습 파이프라인에 적용할 라벨의 LABEL_NAME 및 LABEL_VALUE를 지정합니다.

HTTP 메서드 및 URL:

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

JSON 요청 본문:

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

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

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

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$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

응답

{
"name": "projects/PROJECT_ID/locations/LOCATION/models/MODEL_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UploadModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2020-11-10T23:44:21.777760Z",
      "updateTime": "2020-11-10T23:44:21.777760Z"
    }
  }
}

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

Python용 Vertex AI SDK를 설치하거나 업데이트하는 방법은 Python용 Vertex AI SDK 설치를 참조하세요. 자세한 내용은 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

Vertex Explainable AI 설정이 사용 설정된 모델을 가져오려면 Vertex Explainable AI 모델 가져오기 예시를 참조하세요.

작업 상태 가져오기

일부 요청은 완료하는 데 시간이 걸리는 장기 실행 작업을 시작합니다. 이러한 요청은 작업 상태를 보거나 작업을 취소하는 데 사용할 수 있는 작업 이름을 반환합니다. Vertex AI는 장기 실행 작업을 호출하는 도우미 메서드를 제공합니다. 자세한 내용은 장기 실행 작업 다루기를 참조하세요.

제한사항

지원되는 최대 모델 크기는 10GiB입니다.

다음 단계

프로그래매틱 방식 또는 Google Cloud 콘솔을 사용하여 엔드포인트에 모델을 배포합니다.