이 기존 AI Platform Prediction 버전은 지원 중단되었으며 2025년 1월 31일 이후에는 Google Cloud에서 더 이상 사용할 수 없습니다. 모든 모델, 관련 메타데이터, 배포는 2025년 1월 31일 이후에 삭제됩니다. 리소스를 Vertex AI로 마이그레이션하여 AI Platform에서 사용할 수 없는 새로운 머신러닝 기능을 사용하세요.

커스텀 컨테이너 요구사항

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

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

컨테이너 이미지 요구사항

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

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

HTTP 서버 실행

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

또는 컨테이너 이미지의 ENTRYPOINT 및 CMD를 각각 대체하도록 모델 버전을 만들 때 containerSpec.command 및 containerSpec.args 필드를 지정할 수 있습니다. 이러한 필드 중 하나를 지정하면 호환되지 않는(또는 존재하지 않는) ENTRYPOINT 또는 CMD로 인해 요구사항을 충족하지 않는 컨테이너 이미지를 사용할 수 있습니다.

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

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

활성 확인

AI Platform Prediction은 서버가 실행 중인지 확인하기 위해 컨테이너가 시작될 때 활성 확인을 수행합니다. 버전 만들기 프로세스 중 AI Platform Prediction은 TCP 활성 프로브를 사용하여 구성된 포트에서 컨테이너에 대한 TCP 연결을 설정하려고 시도합니다. 프로브는 연결 설정을 위해 최대 4번 시도하고, 각 실패 후 10초 동안 기다립니다. 그래도 프로브로 연결이 설정되지 않았으면 AI Platform Prediction이 컨테이너를 다시 시작합니다.

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

상태 확인

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

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

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

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

이 응답은 서버가 비정상임을 나타냅니다.

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

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

실용 가이드

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

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

예측 요청

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

AI Platform Prediction은 예측 요청 및 응답이 유효한지 검사하지 않으며, 각각의 예측 요청을 변경하지 않은 상태로 컨테이너에 있는 HTTP 서버로 전달하고, 서버 응답을 다시 클라이언트로 전달합니다.

각 예측 요청 및 응답은 1.5MB 이하여야 합니다. 하지만 다른 요청 본문 요구사항 및 응답 본문 요구사항을 따를 필요는 없습니다. 이러한 요구사항은 커스텀 컨테이너를 사용하지 않는 모델 버전에만 적용됩니다. 커스텀 컨테이너를 사용할 때 요청 및 응답 본문은 어떤 형식도 사용할 수 있습니다.

하지만 여전히 이전 링크에 설명된 요청 및 응답 요구사항을 따르도록 HTTP 서버를 설계하는 것이 좋습니다. 그렇지 않으면, 로깅, 모니터링, AI Explanations와 같은 다른 AI Platform Prediction 기능이 올바르게 작동한다고 보장할 수 없습니다.

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

AI Platform Prediction에 사용할 수 있으려면 Artifact Registry에 컨테이너 이미지를 푸시해야 합니다. Artifact Registry에 컨테이너 이미지를 푸시하는 방법을 알아보세요.

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

위치

저장소는 모델 버전을 만들려는 리전 엔드포인트와 일치하는 리전을 사용해야 합니다. 예를 들어 us-central1-ml.googleapis.com 엔드포인트에서 모델 버전을 만들려면 컨테이너 이미지의 전체 이름이 us-central1-docker.pkg.dev/로 시작해야 합니다.

컨테이너 이미지에 멀티 리전 저장소를 사용하지 마세요.

권한

AI Platform Prediction은 사용자가 모델 버전을 만들 때 컨테이너 이미지를 가져올 수 있는 권한이 있어야 합니다. 특히 AI Platform 서비스 에이전트에는 컨테이너 이미지의 저장소에 대한 Artifact Registry 리더 역할(roles/artifactregistry.reader) 권한이 있어야 합니다.

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

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

모델 아티팩트 액세스

커스텀 컨테이너 없이 모델 버전을 만들 때는 deploymentUri 필드로 모델 아티팩트가 포함된 Cloud Storage 디렉터리의 URI를 지정해야 합니다. 커스텀 컨테이너로 모델 버전을 만들 때, Cloud Storage에 모델 아티팩트를 제공하는 것은 선택사항입니다.

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

AIP_STORAGE_URI 환경 변수의 값은 모델 버전을 만들 때 deploymentUri 필드에 지정하는 Cloud Storage URI와 동일하지 않습니다. 대신 AIP_STORAGE_URI는 AI Platform Prediction이 관리하는 다른 Cloud Storage 버킷에 있는 모델 아티팩트 디렉터리의 복사본을 가리킵니다. AI Platform Prediction은 사용자가 모델 버전을 만들 때 이 디렉터리를 채웁니다. 디렉터리의 콘텐츠는 업데이트할 수 없습니다. 새 모델 아티팩트를 사용하고 싶으면 새 모델 버전을 만들어야 합니다.

컨테이너가 기본적으로 사용하는 서비스 계정에는 이 URI에서 읽기 권한이 포함됩니다. 반면에 모델 버전을 만들 때 커스텀 서비스 계정을 지정하면, AI Platform Prediction이 사용자가 지정한 서비스 계정에 URI의 Cloud Storage 버킷에 대한 스토리지 객체 뷰어(roles/storage.objectViewer) 역할을 부여합니다.

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

컨테이너에서 AI Platform 서비스 에이전트 또는 커스텀 서비스 계정에 대해 ADC가 지원되기 때문에, 항목을 하나 지정한 경우, 서비스 계정에 권한이 있는 다른 Google Cloud 서비스에도 액세스할 수 있습니다.

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

실행 중일 때 컨테이너의 진입점 명령어는 사용자가 수동으로 구성한 환경 변수는 물론 AI Platform Prediction에서 자동으로 설정된 환경 변수도 참조할 수 있습니다. 이 섹션에서는 환경 변수를 설정하는 각 방법을 설명하고 AI Platform Prediction에서 자동으로 설정되는 환경 변수에 대해 자세히 설명합니다.

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

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

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

AI Platform Prediction에서 설정된 변수

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

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

변수 이름	기본값	값 구성 방법	세부정보
AIP_ACCELERATOR_TYPE	설정되지 않음	모델 버전을 만들 때 `acceleratorConfig.type` 필드를 설정합니다.	해당하는 경우 이 변수는 컨테이너가 실행되는 가상 머신(VM) 인스턴스에서 사용되는 가속기 유형을 지정합니다.
AIP_FRAMEWORK	`CUSTOM_CONTAINER`	구성할 수 없음
AIP_HEALTH_ROUTE	`/v1/models/MODEL/versions/VERSION` 이 문자열에서 `MODEL`을 `AIP_MODEL_NAME` 변수로 바꾸고 `VERSION`을 `AIP_VERSION_NAME` 변수의 값으로 바꿉니다.	모델 버전을 만들 때 `routes.health` 필드를 설정합니다.	이 변수는 AI Platform Prediction이 상태 확인을 전송하는 컨테이너의 HTTP 경로를 지정합니다.
AIP_HTTP_PORT	`8080`	모델 버전을 만들 때 `containerSpec.ports` 필드를 설정합니다. 이 필드의 첫 번째 항목은 `AIP_HTTP_PORT`의 값입니다.	AI Platform Prediction은 활성 확인, 상태 확인, 예측 요청을 컨테이너의 이 포트로 전송합니다. 컨테이너의 HTTP 서버는 이 포트에서 요청을 리슨해야 합니다.
AIP_MACHINE_TYPE	기본값 없음, 구성해야 함	모델 버전을 만들 때 `machineType` 필드를 설정합니다.	이 변수는 컨테이너가 실행되는 VM 유형을 지정합니다.
AIP_MODE	`PREDICTION`	구성할 수 없음	이 변수는 온라인 예측 제공을 위해 컨테이너가 AI Platform Prediction에서 실행되고 있음을 나타냅니다. 이 환경 변수를 사용하여 컨테이너에 커스텀 논리를 추가하여, 여러 컴퓨팅 환경에서 실행되지만, AI Platform Prediction에서 실행될 때 특정 코드 경로만 사용하도록 할 수 있습니다.
AIP_MODE_VERSION	`1.0.0`	구성할 수 없음	이 변수는 AI Platform Prediction에서 컨테이너가 충족하도록 요구되는 커스텀 컨테이너 요구사항(이 문서)의 버전을 지정합니다. 이 문서는 시맨틱 버전 관리에 따라 업데이트됩니다.
AIP_MODEL_NAME	기본값 없음, 구성해야 함	모델 버전을 만들 때(컨테이너를 사용하는 모델 버전의 상위), `name` 필드를 지정합니다.	이 값에는 AI Platform Training 및 Prediction API가 출력으로 생성하는 `projects/PROJECT_ID/models/` 프리픽스가 포함되지 않습니다.
AIP_PREDICT_ROUTE	`/v1/models/MODEL/versions/VERSION:predict` 이 문자열에서 `MODEL`을 `AIP_MODEL_NAME` 변수로 바꾸고 `VERSION`을 `AIP_VERSION_NAME` 변수의 값으로 바꿉니다.	모델 버전을 만들 때 `routes.predict` 필드를 설정합니다.	이 변수는 AI Platform Prediction이 예측 요청을 전달하는 컨테이너의 HTTP 경로를 지정합니다.
AIP_PROJECT_NUMBER	AI Platform Prediction을 사용 중인 Google Cloud 프로젝트의 프로젝트 번호입니다.	구성할 수 없음
AIP_STORAGE_URI	모델 버전을 만들 때 `deploymentUri` 필드를 설정하지 않는 경우: 빈 문자열 모델 버전을 만들 때 `deploymentUri` 필드를 설정하는 경우: AI Platform Prediction에서 관리되는 버킷의 디렉터리를 지정하는 Cloud Storage URI(`gs://`로 시작)	구성할 수 없음	이 변수는 모델 아티팩트의 복사본이 포함된 디렉터리(해당하는 경우)를 지정합니다.
AIP_VERSION_NAME	기본값 없음, 구성해야 함	모델 버전을 만들 때 `name` 필드를 설정합니다.	이 값에는 AI Platform Training 및 Prediction API가 출력으로 생성하는 `projects/PROJECT_ID/models/MODEL/versions/` 프리픽스가 포함되지 않습니다.

버전 리소스에 설정된 변수

모델 버전을 만들 때 container.env 필드에 추가 환경 변수를 설정할 수 있습니다.

다음 단계

커스텀 컨테이너를 사용하는 예측 제공 자세히 알아보기
특정 커스텀 컨테이너로 예측을 제공하려면 PyTorch 예측 제공 가이드를 참조하세요.