예측용 커스텀 컨테이너 요구사항

커스텀 컨테이너를 사용하여 커스텀 학습 모델에서 예측을 제공하려면 Vertex AI에 HTTP 서버를 실행하는 Docker 컨테이너 이미지를 제공해야 합니다. 이 문서에서는 컨테이너 이미지가 Vertex AI과 호환되기 위해 충족해야 하는 요구사항에 대해 설명합니다. 이 문서에서는 또한 실행 시작 후 Vertex AI가 커스텀 컨테이너와 상호작용하는 방법을 설명합니다. 바꾸어 말하면, 이 문서에서는 Vertex AI에서 사용할 컨테이너 이미지를 설계할 때 고려해야 할 사항을 설명합니다.

예측 제공을 위해 커스텀 컨테이너 이미지 사용을 시작하려면 커스텀 컨테이너 사용을 참조하세요.

컨테이너 이미지 요구사항

Docker 컨테이너 이미지가 컨테이너로 실행되는 경우 컨테이너가 HTTP 서버를 실행해야 합니다. 특히 컨테이너가 활성 확인, 상태 확인, 예측 요청을 리슨하고 여기에 응답해야 합니다. 다음 하위 섹션에서는 이러한 요구사항에 대해 자세히 설명합니다.

이 섹션의 요구사항을 충족하는 한 어떤 방법으로든 모든 프로그래밍 언어를 사용하여 HTTP 서버를 구현할 수 있습니다. 예를 들어 Flask와 같은 웹 프레임워크를 사용하여 커스텀 HTTP 서버를 작성하거나, TensorFlow Serving, TorchServe, KServe Python Server와 같은 HTTP 서버를 실행하는 머신러닝(ML) 제공 소프트웨어를 사용할 수 있습니다.

HTTP 서버 실행

컨테이너 이미지를 빌드하기 위해 사용할 Dockerfile에서 ENTRYPOINT 안내나 CMD 안내 또는 두 안내를 모두 사용하여 HTTP 서버를 실행할 수 있습니다. CMD와 ENTRYPOINT 사이의 상호작용을 참조하세요.

또는 Model 리소스를 만들 때 containerSpec.command 필드와 containerSpec.args 필드를 지정하여 컨테이너 이미지의 ENTRYPOINT와 CMD를 각각 재정의할 수 있습니다. 이러한 필드 중 하나를 지정하면 호환되지 않는(또는 존재하지 않는) ENTRYPOINT 또는 CMD로 인해 요구사항을 충족하지 않는 컨테이너 이미지를 사용할 수 있게 됩니다.

하지만 시작 시 컨테이너가 실행할 명령어를 결정하여 이러한 진입점 명령어가 무기한 실행되도록 합니다. 예를 들어 백그라운드에서 HTTP 서버를 시작한 후 종료되는 명령어는 실행하지 마세요. 그렇지 않으면 실행 시작 후 컨테이너가 즉시 종료됩니다.

HTTP 서버는 0.0.0.0에서 사용자가 선택한 포트로 요청을 리슨해야 합니다. Model을 만들 때 containerSpec.ports 필드에서 이 포트를 지정합니다. 컨테이너가 이 값에 액세스하는 방법을 알아보려면 이 문서의 AIP_HTTP_PORT 환경 변수에 대한 섹션을 참조하세요.

활성 확인

Vertex AI는 서버가 실행 중인지 확인하기 위해 컨테이너가 시작될 때 활성 확인을 수행합니다. 커스텀 학습 모델을 Endpoint 리소스에 배포하면 Vertex AI는 TCP 활성 프로브를 사용하여 구성된 포트의 컨테이너에 대한 TCP 연결을 설정하려고 시도합니다. 프로브는 연결 설정을 위해 최대 4번 시도하고, 각 실패 후 10초 동안 기다립니다. 그래도 프로브로 연결이 설정되지 않았으면 Vertex AI이 컨테이너를 다시 시작합니다.

HTTP 서버는 이러한 확인을 처리하기 위해 어떤 특별한 동작도 수행할 필요가 없습니다. 구성된 포트에서 요청을 리슨하는 한 활성 프로브가 연결을 수행할 수 있습니다.

상태 점검

선택적으로 startup_probe 또는 health_probe를 지정할 수 있습니다.

시작 프로브는 컨테이너 애플리케이션이 시작되었는지 여부를 확인합니다. 시작 프로브가 제공되지 않으면 시작 프로브가 없고 상태 점검이 즉시 시작됩니다. 시작 프로브가 제공되면 시작 프로브가 성공할 때까지 상태 점검이 수행되지 않습니다.

최초 초기화에 추가 시작 시간이 필요할 수 있는 레거시 애플리케이션은 시작 프로브를 구성해야 합니다. 예를 들어 애플리케이션이 외부 소스로부터 모델 아티팩트를 복사해야 하는 경우 초기화가 완료되었을 때 성공을 반환하도록 시작 프로브를 구성해야 합니다.

상태 프로브는 컨테이너에서 트래픽을 수락할 준비가 되었는지 확인합니다. 상태 프로브가 제공되지 않으면 Vertex AI는 기본 상태 점검에 설명된 대로 기본 상태 점검을 사용합니다.

모델이 로드되었고 트래픽을 수락할 준비가 되었음을 나타내는 200 OK를 반환하지 않는 레거시 애플리케이션은 상태 프로브를 구성해야 합니다. 예를 들어 실제 모델 로드 상태가 응답 본문에 있고 로드되지 않았을 수 있고 따라서 트래픽을 수락할 준비가 되지 않았을 경우에도 애플리케이션은 성공을 나타내기 위해 200 OK를 반환할 수 있습니다. 이 경우 모델이 로드되고 트래픽을 처리할 준비가 되었을 때만 성공을 반환하도록 상태 프로브를 구성해야 합니다.

프로브를 수행하기 위해 Vertex AI는 대상 컨테이너에서 지정된 exec 명령어를 실행합니다. 명령어가 성공하면 0이 반환되고 컨테이너가 활성 및 정상 상태인 것으로 간주됩니다.

기본 상태 점검

기본적으로 Vertex AI는 예측 요청을 처리할 준비가 되었는지 확인하기 위해 실행 중인 HTTP 서버의 상태 점검을 간헐적으로 수행합니다. 이 서비스는 상태 프로브를 사용하여 서버의 구성 가능한 상태 점검 경로로 HTTP GET 요청을 전송합니다. Model을 만들 때 containerSpec.healthRoute 필드에 이 경로를 지정하세요. 컨테이너가 이 값에 액세스하는 방법을 알아보려면 이 문서의 AIP_HEALTH_ROUTE 환경 변수에 대한 섹션을 참조하세요.

각 상태 확인 요청에 응답하도록 다음과 같이 HTTP 서버를 구성합니다.

서버가 예측 요청을 처리할 준비가 되면 상태 코드 200 OK로 상태 확인 요청에 10초 이내에 응답합니다. 응답 본문의 내용은 중요하지 않습니다. Vertex AI는 이를 무시합니다.

이 응답은 서버가 정상임을 나타냅니다.
서버가 예측 요청을 처리할 준비가 되지 않은 경우 10초 이내에 상태 점검 요청에 응답하지 않거나 200 OK를 제외한 다른 상태 코드로 응답합니다. 예를 들어 503 Service Unavailable 상태 코드로 응답합니다.

이 응답(또는 응답 없음)은 서버가 비정상임을 나타냅니다.

상태 프로브가 서버로부터 비정상 응답을 수신하면(10초 내 응답 실패 포함) 10초 간격으로 최대 3회 추가 상태 확인을 전송합니다. 이 기간 동안 Vertex AI는 아직 서버가 정상이라고 간주합니다. 프로브가 이러한 확인에 대해 정상 응답을 수신하면 프로브가 즉시 상태 확인의 간헐적 일정으로 돌아갑니다. 하지만 프로브가 4회 연속 비정상 응답을 수신하면 Vertex AI이 컨테이너에 대한 예측 트래픽 라우팅을 중지합니다. (DeployedModel 리소스가 여러 예측 노드를 사용하도록 확장된 경우 Vertex AI는 예측 요청을 다른 정상 컨테이너로 라우팅합니다.)

Vertex AI는 컨테이너를 다시 시작하지 않습니다. 대신 상태 프로브가 비정상 서버로 간헐적 상태 점검 요청을 계속 전송합니다. 정상 응답을 수신하면 해당 컨테이너를 정상으로 표시하고 이 컨테이너로 다시 예측 트래픽 라우팅을 시작합니다.

실용 가이드

일부 경우에는 컨테이너의 HTTP 서버가 상태 확인에 항상 200 OK 상태 코드로 응답하는 것으로 충분합니다. 컨테이너가 서버 시작 전 리소스를 로드하는 경우에는 시작 기간 중 그리고 HTTP 서버가 실패하는 모든 기간 중에 컨테이너가 비정상입니다. 그 밖의 모든 경우에는 정상으로 응답합니다.

보다 정교한 구성을 위해서는 특정 시간에 비정상 상태로 상태 확인에 응답하도록 HTTP 서버를 의도적으로 설계할 수 있습니다. 예를 들어 컨테이너가 유지보수를 수행할 수 있도록 일정 기간 동안 노드에 대한 예측 트래픽을 차단해야 할 수 있습니다.

예측 요청

클라이언트가 projects.locations.endpoints.predict 요청을 Vertex AI API로 전송하면 Vertex AI는 이 요청을 서버의 구성 가능한 예측 경로에 HTTP POST 요청으로 전달합니다. Model을 만들 때 containerSpec.predictRoute 필드에 이 경로를 지정하세요. 컨테이너가 이 값에 액세스하는 방법을 알아보려면 이 문서의 AIP_PREDICT_ROUTE 환경 변수에 대한 섹션을 참조하세요.

요청 요구사항

모델이 공개 엔드포인트에 배포된 경우 각 예측 요청은 1.5MB 이하여야 합니다. HTTP 서버는 다음 형식의 Content-Type: application/json HTTP 헤더와 JSON 본문이 있는 예측 요청을 허용해야 합니다.

{
  "instances": INSTANCES,
  "parameters": PARAMETERS
}

이러한 요청에서,

INSTANCES는 모든 유형의 하나 이상 JSON 값의 배열입니다. 각 값은 예측을 제공할 인스턴스를 나타냅니다.
PARAMETERS는 컨테이너가 인스턴스에 예측을 제공하는 데 필요한 매개변수가 포함된 JSON 객체입니다. Vertex AI는 parameters 필드를 선택적으로 인식하므로 컨테이너가 해당 필드를 요구한 뒤 제공된 경우에만 사용하고 그 외에는 무시하도록 설계할 수 있습니다.

요청 본문 요구사항에 대해 자세히 알아보세요.

응답 요구사항

모델이 공개 엔드포인트에 배포된 경우 각 예측 응답은 1.5MB 이하여야 합니다. HTTP 서버는 다음 형식을 충족하는 JSON 본문이 포함된 응답을 보내야 합니다.

{
  "predictions": PREDICTIONS
}

이 응답에서 PREDICTIONS를 해당 요청의 각 INSTANCES에 대해 컨테이너가 생성한 예측을 나타내는 JSON 값의 배열로 바꿉니다.

HTTP 서버가 이 응답을 보내면 Vertex AI는 클라이언트에 응답을 반환하기 전에 응답에 deployedModelId 필드를 추가합니다. 이 필드는 응답을 보낼 Endpoint의 DeployedModel을 지정합니다. 응답 본문 형식에 대해 자세히 알아보세요.

컨테이너 이미지 게시 요구사항

컨테이너 이미지를 Vertex AI와 함께 사용하려면 Artifact Registry에 푸시해야 합니다. Artifact Registry에 컨테이너 이미지를 푸시하는 방법을 알아보세요.

특히 다음 위치 및 권한 요구사항을 충족하는 저장소에 컨테이너 이미지를 푸시해야 합니다.

위치

Artifact Registry를 사용하는 경우 저장소는 Model을 만들려는 리전 엔드포인트와 일치하는 리전을 사용해야 합니다. 예를 들어 us-central1-aiplatform.googleapis.com 엔드포인트에서 Model을 만들려는 경우 컨테이너 이미지의 전체 이름은 us-central1-docker.pkg.dev/로 시작해야 합니다. 컨테이너 이미지에 멀티 리전 저장소를 사용하지 마세요.

권한

Vertex AI는 Model을 만들 때 컨테이너 이미지를 가져올 수 있는 권한이 있어야 합니다. 특히 프로젝트의 Vertex AI 서비스 에이전트에는 컨테이너 이미지의 저장소에 대한 Artifact Registry 리더 역할(roles/artifactregistry.reader) 권한이 있어야 합니다.

프로젝트의 Vertex AI 서비스 에이전트는 Vertex AI가 다양한 Google Cloud 서비스와 상호작용하는 데 사용하는 Google 관리 서비스 계정입니다. 이 서비스 계정의 이메일 주소는 service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com이며 여기서 PROJECT_NUMBER는 Vertex AI 프로젝트의 프로젝트 번호입니다.

Vertex AI를 사용하는 동일한 Google Cloud 프로젝트로 컨테이너 이미지를 푸시한 경우 권한을 구성할 필요가 없습니다. Vertex AI 서비스 에이전트에 부여되는 기본 권한으로 충분합니다.

반면에 Vertex AI를 사용하는 프로젝트와 다른 Google Cloud 프로젝트에 컨테이너 이미지를 푸시한 경우에는 Vertex AI 서비스 에이전트에 Artifact Registry 저장소에 대한 Artifact Registry 리더 역할을 부여해야 합니다.

모델 아티팩트에 액세스

커스텀 컨테이너 없이 커스텀 학습 Model을 만들 때는 모델 아티팩트가 있는 Cloud Storage 디렉터리의 URI를 artifactUri 필드로 지정해야 합니다. 커스텀 컨테이너로 Model을 만드는 경우 Cloud Storage에서 모델 아티팩트를 제공하는 것은 선택사항입니다.

컨테이너 이미지에 예측 제공을 위해 필요한 모델 아티팩트가 포함된 경우 Cloud Storage에서 파일을 로드할 필요가 없습니다. 하지만 artifactUri 필드를 지정하여 모델 아티팩트를 제공할 경우에는 실행 시작 시 컨테이너가 이러한 아티팩트를 로드해야 합니다. Vertex AI가 컨테이너를 시작하면 gs://로 시작하는 AIP_STORAGE_URI 환경 변수를 Cloud Storage URI로 설정합니다. 컨테이너의 진입점 명령어는 모델 아티팩트에 액세스하기 위해 이 URI로 지정된 디렉터리를 다운로드할 수 있습니다.

AIP_STORAGE_URI 환경 변수의 값은 Model 생성 시 artifactUri 필드에 지정하는 Cloud Storage URI와 다릅니다. 대신 AIP_STORAGE_URI는 Vertex AI가 관리하는 다른 Cloud Storage 버킷에 있는 모델 아티팩트 디렉터리의 사본을 가리킵니다. Model을 만들면 Vertex AI가 이 디렉터리를 채웁니다. 디렉터리의 콘텐츠는 업데이트할 수 없습니다. 새 모델 아티팩트를 사용하려면 새 Model을 만들어야 합니다.

컨테이너가 기본적으로 사용하는 서비스 계정에는 이 URI에서 읽을 수 있는 권한이 포함됩니다.

반면 Endpoint에 Model을 배포할 때 커스텀 서비스 계정을 지정한 경우에는 Vertex AI가 지정된 서비스 계정에 URI의 Cloud Storage 버킷에 대한 스토리지 객체 뷰어(roles/storage.objectViewer) 역할을 자동으로 부여합니다.

애플리케이션 기본 사용자 인증 정보(ADC)를 지원하는 모든 라이브러리를 사용하여 모델 아티팩트를 로드합니다. 인증을 명시적으로 구성할 필요는 없습니다.

컨테이너에서 사용 가능한 환경 변수

실행 시 컨테이너의 진입점 명령어는 수동으로 구성한 환경 변수와 Vertex AI에서 자동으로 설정된 환경 변수를 참조할 수 있습니다. 이 섹션에서는 환경 변수를 설정할 수 있는 각 방법을 설명하고 Vertex AI에서 자동으로 설정된 변수에 대한 세부정보를 제공합니다.

컨테이너 이미지에 설정된 변수

빌드할 때 컨테이너 이미지에 환경 변수를 설정하려면 Docker의 ENV 안내를 따릅니다. AIP_ 프리픽스로 시작하는 환경 변수는 설정하지 마세요.

컨테이너의 진입점 명령어는 이러한 환경 변수를 사용할 수 있지만, Model의 모든 API 필드에서 이를 참조할 수 없습니다.

Vertex AI에서 설정된 변수

Vertex AI는 컨테이너 실행을 시작할 때 컨테이너 환경에 다음 환경 변수를 설정합니다. 각 변수는 AIP_ 프리픽스로 시작합니다. 이 프리픽스를 사용하는 환경 변수를 수동으로 설정하지 마세요.

컨테이너의 진입점 명령어는 이러한 변수에 액세스할 수 있습니다. 이러한 변수를 참조할 수 있는 Vertex AI API 필드를 알아보려면 ModelContainerSpec API 참조를 확인하세요.

변수 이름	기본값	값 구성 방법	세부정보
AIP_ACCELERATOR_TYPE	설정되지 않음	`Endpoint` 리소스에 `DeployedModel`로 `Model`을 배포할 때 `dedicatedResources.machineSpec.acceleratorType` 필드를 설정합니다.	해당하는 경우 이 변수는 컨테이너가 실행되는 가상 머신(VM) 인스턴스에서 사용되는 가속기 유형을 지정합니다.
AIP_DEPLOYED_MODEL_ID	이 컨테이너의 `Model`이 배포된 `DeployedModel`을 식별하는 숫자 문자열입니다.	구성할 수 없음	이 값은 `DeployedModel`의 `id` 필드입니다.
AIP_ENDPOINT_ID	컨테이너의 `Model`이 배포된 `Endpoint`를 식별하는 숫자 문자열입니다.	구성할 수 없음	이 값은 `Endpoint`의 `name` 필드(`endpoints/` 이후)의 마지막 세그먼트입니다.
AIP_FRAMEWORK	`CUSTOM_CONTAINER`	구성할 수 없음
AIP_HEALTH_ROUTE	`/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL` 이 문자열에서 `ENDPOINT`를 `AIP_ENDPOINT_ID` 변수의 값으로 바꾸고 `DEPLOYED_MODEL`을 `AIP_DEPLOYED_MODEL_ID` 변수의 값으로 바꿉니다.	`Model`을 만들 때 `containerSpec.healthRoute` 필드를 설정합니다.	이 변수는 Vertex AI가 상태 확인을 전송하는 컨테이너의 HTTP 경로를 지정합니다.
AIP_HTTP_PORT	`8080`	`Model`을 만들 때 `containerSpec.ports` 필드를 설정합니다. 이 필드의 첫 번째 항목은 `AIP_HTTP_PORT`의 값입니다.	Vertex AI는 컨테이너의 해당 포트에 활성 확인, 상태 확인, 예측 요청을 전송합니다. 컨테이너의 HTTP 서버는 이 포트에서 요청을 리슨해야 합니다.
AIP_MACHINE_TYPE	기본값 없음, 구성해야 함	`Endpoint` 리소스에 `DeployedModel`로 `Model`을 배포할 때 `dedicatedResources.machineSpec.machineType` 필드를 설정합니다.	이 변수는 컨테이너가 실행되는 VM 유형을 지정합니다.
AIP_MODE	`PREDICTION`	구성할 수 없음	이 변수는 온라인 예측 제공을 위해 컨테이너가 Vertex AI에서 실행되고 있음을 나타냅니다. 이 환경 변수를 사용하여 컨테이너에 커스텀 논리를 추가하여 여러 컴퓨팅 환경에서 실행되지만 Vertex AI에서 실행될 때 특정 코드 경로만 사용하도록 할 수 있습니다.
AIP_MODE_VERSION	`1.0.0`	구성할 수 없음	이 변수는 Vertex AI에서 컨테이너가 충족하도록 요구되는 커스텀 컨테이너 요구사항(이 문서)의 버전을 지정합니다. 이 문서는 시맨틱 버전 관리에 따라 업데이트됩니다.
AIP_MODEL_NAME	`AIP_ENDPOINT_ID` 변수값입니다.	구성할 수 없음	`AIP_ENDPOINT_ID` 행을 참조하세요. 이 변수는 호환성을 이유로 존재합니다.
AIP_PREDICT_ROUTE	`/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict` 이 문자열에서 `ENDPOINT`를 `AIP_ENDPOINT_ID` 변수의 값으로 바꾸고 `DEPLOYED_MODEL`을 `AIP_DEPLOYED_MODEL_ID` 변수의 값으로 바꿉니다.	`Model`을 만들 때 `containerSpec.predictRoute` 필드를 설정합니다.	이 변수는 Vertex AI가 예측 요청을 전달하는 컨테이너의 HTTP 경로를 지정합니다.
AIP_PROJECT_NUMBER	Vertex AI를 사용하는 Google Cloud 프로젝트의 프로젝트 번호	구성할 수 없음
AIP_STORAGE_URI	`Model`을 만들 때 `artifactUri` 필드를 설정하지 않는 경우: 빈 문자열 `Model`을 만들 때 `artifactUri` 필드를 설정하는 경우: Vertex AI에서 관리하는 버킷의 디렉터리를 지정하는 Cloud Storage URI(`gs://`로 시작)	구성할 수 없음	이 변수는 모델 아티팩트의 복사본이 포함된 디렉터리(해당하는 경우)를 지정합니다.
AIP_VERSION_NAME	`AIP_DEPLOYED_MODEL_ID` 변수값입니다.	구성할 수 없음	`AIP_DEPLOYED_MODEL_ID` 행을 참조하세요. 이 변수는 호환성을 이유로 존재합니다.

`Model` 리소스에서 설정된 변수

Model을 만들 때 containerSpec.env 필드에서 추가 환경 변수를 설정할 수 있습니다.

다음 단계

모델을 가져올 때 컨테이너 관련 API 필드를 지정하는 방법을 비롯하여 커스텀 컨테이너를 사용한 예측 제공에 대해 자세히 알아보세요.