시작하기: 커스텀 컨테이너로 PyTorch 예측 제공

이 가이드에서는 커스텀 컨테이너를 사용하여 온라인 예측을 제공하는 PyTorch 머신러닝(ML) 모델을 배포하는 방법을 보여줍니다.

이 가이드에서는 MNIST 데이터 세트에서 미리 학습된 TorchServe에서 제공되는 숫자 인식 모델에서 예측을 제공하기 위해 PyTorch의 TorchServe 도구를 실행하여 컨테이너를 배포합니다. 그런 후 AI Platform Prediction을 사용하여 숫자 이미지를 분류할 수 있습니다.

시작하기 전에

  1. Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

  2. Google Cloud Console의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

    프로젝트 선택기로 이동

  3. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  4. API AI Platform Training & Prediction and Artifact Registry API 사용 설정

    API 사용 설정

    5.

  5. Google Cloud Console의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

    프로젝트 선택기로 이동

  6. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  7. API AI Platform Training & Prediction and Artifact Registry API 사용 설정

    API 사용 설정

    8.

  8. Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

    Cloud Shell 활성화

    Google Cloud 콘솔 하단에서 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.

이 가이드에서는 Google Cloud와의 상호작용을 위해 Cloud Shell을 사용하는 것이 좋습니다. Cloud Shell 대신 다른 Bash 셸을 사용하려면 다음 추가 구성을 수행합니다.

  1. Google Cloud CLI를 설치합니다.

  2. gcloud CLI를 초기화하려면 다음 명령어를 실행합니다. 

    gcloud init
  3. Artifact Registry 문서에 따라 Docker를 설치합니다.

컨테이너 이미지 빌드 및 푸시

커스텀 컨테이너를 사용하려면 커스텀 컨테이너 요구사항을 충족하는 Docker 컨테이너 이미지를 지정해야 합니다. 이 섹션에서는 컨테이너 이미지를 만들고 이를 Artifact Registry에 푸시하는 방법을 설명합니다.

모델 아티팩트 다운로드

모델 아티팩트는 예측 제공을 위해 사용할 수 있는 ML 학습으로 생성되는 파일입니다. 여기에는 최소한 학습된 ML 모델의 구조 및 가중치가 포함됩니다. 모델 아티팩트의 형식은 학습에 사용하는 ML 프레임워크에 따라 달라집니다.

이 가이드에서는 처음부터 학습을 수행하는 대신 TorchServe에서 제공되는 예시 모델 아티팩트를 다운로드합니다.

TorchServe 저장소를 클론하고 모델 아티팩트가 있는 디렉터리로 이동하려면 다음 명령어를 셸에서 실행합니다.

git clone https://github.com/pytorch/serve.git \
  --branch=v0.3.0 \
  --depth=1

cd serve/examples/image_classifier/mnist

이 디렉터리에는 컨테이너 이미지에 빌드할 세 가지 중요한 파일이 포함되어 있습니다.

  • mnist.py: 학습된 신경망의 구조를 정의합니다.
  • mnist_cnn.pt: 특성 가중치 및 기타 학습 출력이 있는 state_dict를 포함합니다.
  • mnist_handler.py: TorchServe가 예측 요청을 처리하는 방법을 확장합니다.

Artifact Registry 저장소 만들기

다음 섹션에서 만들 컨테이너 이미지를 저장할 Artifact Registry 저장소를 만듭니다. 셸에서 다음 명령어를 실행합니다.

gcloud beta artifacts repositories create getting-started-pytorch \
 --repository-format=docker \
 --location=REGION

REGION을 Artifact Registry로 컨테이너 이미지를 저장할 리전으로 바꿉니다. 나중에 이 리전과 일치하는 리전 엔드포인트에서 AI Platform Prediction 모델 리소스를 만들어야 하므로, AI Platform Prediction에 리전 엔드포인트가 포함된 리전(예: us-central1)을 선택합니다.

작업을 완료하면 이 명령어가 다음 입력을 출력합니다.

Created repository [getting-started-pytorch].

컨테이너 이미지 빌드

TorchServe는 TorchServe를 실행하는 컨테이너 이미지 빌드를 위해 Dockerfile을 제공합니다. 하지만 이 Dockerfile을 사용하여 모든 TorchServe 종속 항목을 설치하는 대신, TorchServe팀이 Docker Hub에 푸시한 TorchServe 이미지 중 하나로부터 컨테이너 이미지를 파생하여 빌드 프로세스 속도를 단축시킬 수 있습니다.

  1. 모델 아티팩트가 있는 디렉터리에서 셸에서 다음 명령어를 실행하여 새 Dockerfile을 만듭니다.

    cat > Dockerfile <<END
FROM pytorch/torchserve:0.3.0-cpu

COPY mnist.py mnist_cnn.pt mnist_handler.py /home/model-server/

USER root
RUN printf "\nservice_envelope=json" >> /home/model-server/config.properties
USER model-server

RUN torch-model-archiver \
  --model-name=mnist \
  --version=1.0 \
  --model-file=/home/model-server/mnist.py \
  --serialized-file=/home/model-server/mnist_cnn.pt \
  --handler=/home/model-server/mnist_handler.py \
  --export-path=/home/model-server/model-store

CMD ["torchserve", \
     "--start", \
     "--ts-config=/home/model-server/config.properties", \
     "--models", \
     "mnist=mnist.mar"]
END

    이러한 Docker 명령어는 다음 작업을 수행합니다.

    • FROM 명령어는 기존 TorchServe 이미지로부터 현재 컨테이너 이미지를 파생합니다.

    • COPY 명령어는 모델 아티팩트와 예측 핸들러를 로컬 디렉터리의 컨테이너 이미지 /home/model-server/ 디렉터리에 복사합니다.

    • 첫 번째 RUN 명령어는 상위 이미지의 구성 파일을 수정하여 AI Platform Prediction에서 예측을 위한 선호하는 입력 형식을 지원합니다.

      특히 이 명령어는 예측 요청에 대한 JSON 서비스 봉투를 예상하도록 TorchServe를 구성합니다.

      이 구성 파일을 수정하려면 model-server 사용자(상위 이미지에서 생성됨)에게 없는 권한이 필요합니다. 이 안내에서는 Docker에게 root 사용자로 실행하여 구성 파일을 수정하도록 지시한 후 다음 안내에 따라 model-server 사용자를 계속 사용합니다.

    • 두 번째 RUN 명령어는 컨테이너 이미지에 이미 설치된 Torch 모델 archiver를 사용하여 사용자가 이미지로 복사한 파일로부터 모델 아카이브를 만듭니다. 파일 이름이 mnist.mar인 /home/model-server/model-store/ 디렉터리에 이 모델 아카이브를 저장합니다.

      (요청 핸들러에서 커스텀 전처리 또는 후처리를 수행하는 등의 목적으로 컨테이너 이미지를 수정해야 하는 경우, 추가적인 RUN 명령어를 사용하여 종속 항목을 설치할 수 있습니다.)

    • CMD 명령어는 TorchServe HTTP 서버를 시작합니다. 상위 이미지의 구성 파일을 참조하고 이름이 mnist인 모델에 대한 제공을 지원합니다. 이 모델은 RUN 명령어로 생성된 mnist.mar 파일을 로드합니다.

      이 명령어는 상위 이미지의 CMD 명령어보다 우선 적용됩니다. 상위 이미지의 ENTRYPOINT 스크립트가 CMD에 전달된 명령어를 실행하고 Docker 종료를 방지하기 위해 추가 논리를 추가하기 때문에 ENTRYPOINT 명령어가 아니라 CMD 명령어를 우선 적용하는 것이 중요합니다.

  2. 새 Dockerfile을 기반으로 컨테이너 이미지를 빌드하고 Artifact Registry 저장소와 호환되는 이름으로 태그 지정하려면 셸에서 다음 명령어를 실행합니다.

    docker build \
  --tag=REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist \
  .

    다음을 바꿉니다.

    • REGION: 이전 섹션에 지정된 대로 Artifact Registry 저장소의 리전입니다.
    • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.

    이 명령어는 몇 분 동안 실행될 수 있습니다.

로컬로 컨테이너 실행(선택사항)

AI Platform Prediction에 사용하기 위해 Artifact Registry에 컨테이너 이미지를 푸시하기 전에 로컬 환경에서 컨테이너로 실행하여 서버가 예상한 대로 작동하는지 확인할 수 있습니다.

  1. 컨테이너 이미지를 로컬에서 컨테이너로서 실행하려면 셸에서 다음 명령어를 실행합니다.

    docker run -d -p 8080:8080 --name=local_mnist \
  REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist

    이전 섹션에서 한 것처럼 다음을 바꿉니다.

    • REGION: 이전 섹션에 지정된 대로 Artifact Registry 저장소의 리전
    • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.

    이 명령어는 컨테이너의 포트 8080을 로컬 환경의 포트 8080으로 매핑하여 분리 모드에서 컨테이너를 실행합니다. (컨테이너 이미지를 파생한 상위 이미지는 포트 8080을 사용하도록 TorchServe를 구성합니다.)

  2. 컨테이너 서버에 상태 확인을 보내려면 셸에서 다음 명령어를 실행합니다.

    curl localhost:8080/ping

    성공하면 서버가 다음 응답을 반환합니다.

    {
  "status": "Healthy"
}

  3. 컨테이너 서버에 예측 요청을 보내려면 셸에서 다음 명령어를 실행합니다.

    cat > instances.json <<END
{
  "instances": [
    {
      "data": {
        "b64": "$(base64 --wrap=0 test_data/3.png)"
      }
    }
  ]
}
END

curl -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @instances.json \
  localhost:8080/predictions/mnist

    이 요청은 TorchServe 예시에 포함된 테스트 이미지 중 하나를 사용합니다.

    성공하면 서버가 다음 예측을 반환합니다.

    {"predictions": [3]}

  4. 컨테이너를 중지하려면 셸에서 다음 명령어를 실행합니다.

    docker stop local_mnist

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

Artifact Registry에 액세스하도록 Docker를 구성합니다. 그런 후 컨테이너 이미지를 Artifact Registry 저장소에 푸시합니다.

  1. 선택한 리전의 Artifact Registry로 푸시할 수 있도록 로컬 Docker에 설치 권한을 제공하려면 셸에서 다음 명령어를 실행합니다.

    gcloud auth configure-docker REGION-docker.pkg.dev

    REGION을 이전 섹션에서 저장소를 만든 리전으로 바꿉니다.

  2. Artifact Registry에 바로 전에 빌드한 컨테이너 이미지를 푸시하려면 셸에서 다음 명령어를 실행합니다.

    docker push REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist

    이전 섹션에서 한 것처럼 다음을 바꿉니다.

    • REGION: 이전 섹션에 지정된 대로 Artifact Registry 저장소의 리전
    • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.

컨테이너 배포

이 섹션에서는 예측 제공을 위해 AI Platform Prediction에서 모델 및 모델 버전을 만듭니다. 모델 버전은 예측 제공을 위해 컨테이너 이미지를 컨테이너로서 실행합니다.

이 가이드에서는 모델 및 모델 버전을 만들 때 사용할 몇 가지 구성 옵션을 제공합니다. 여러 구성 옵션에 대해 자세히 알아보려면 모델 배포를 참조하세요.

모델 만들기

모델 리소스를 만들려면 셸에서 다음 명령어를 실행합니다.

gcloud beta ai-platform models create getting_started_pytorch \
  --region=REGION \
  --enable-logging \
  --enable-console-logging

REGION을 이전 섹션에서 Artifact Registry 저장소를 만든 동일한 리전으로 바꿉니다.

모델 버전 만들기

모델 버전 리소스를 만들려면 셸에서 다음 명령어를 실행합니다.

gcloud beta ai-platform versions create v1 \
  --region=REGION \
  --model=getting_started_pytorch \
  --machine-type=n1-standard-4 \
  --image=REGION-docker.pkg.dev/PROJECT_ID/getting-started-pytorch/serve-mnist \
  --ports=8080 \
  --health-route=/ping \
  --predict-route=/predictions/mnist

다음을 바꿉니다.

  • REGION: 이전 섹션에서 Artifact Registry 저장소 및 AI Platform Prediction 모델을 만든 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.

이 명령어의 컨테이너 관련 플래그는 다음을 수행합니다.

  • --image: 컨테이너 이미지의 URI입니다.

  • --ports: 컨테이너의 HTTP 서버가 요청을 리슨하는 포트입니다. (컨테이너 이미지를 파생한 상위 이미지는 포트 8080을 사용하도록 TorchServe를 구성합니다.)

  • --health-route: 컨테이너의 HTTP 서버가 상태 확인을 리슨하는 경로입니다. TorchServe는 항상 /ping 경로에서 상태 확인을 리슨합니다.

  • --predict-route: 컨테이너의 HTTP 서버가 예측 요청을 리슨하는 경로입니다. TorchServe는 항상 /predictions/MODEL 경로의 예측 요청을 리슨합니다.

    MODEL은 TorchServe를 시작할 때 지정한 모델의 이름입니다. 이 경우 이름은 mnist이며 이전 섹션의 이 Docker 명령어로 설정되었습니다.

    CMD ["torchserve", \
  "--start", \
  "--ts-config=/home/model-server/config.properties", \
  "--models", \
  "mnist=mnist.mar"]

예측 가져오기

이전 섹션에서 다운로드한 TorchServe 예시 파일에는 테스트 이미지가 포함되어 있습니다. 컨테이너의 TorchServe 구성은 JSON 형식의 예측 요청을 수신할 것으로 예상합니다. 이미지는 각 인스턴스의 data.b64 필드에 base64로 인코딩된 문자열로 표시됩니다.

예를 들어 test_data/3.png를 분류하려면 셸에서 다음 명령어를 실행합니다.

cat > instances.json <<END
{
 "instances": [
   {
     "data": {
       "b64": "$(base64 --wrap=0 test_data/3.png)"
     }
   }
 ]
}
END

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @instances.json \
  https://REGION-ml.googleapis.com/v1/projects/PROJECT_ID/models/getting_started_pytorch/versions/v1:predict

다음을 바꿉니다.

  • REGION: 이전 섹션에서 AI Platform Prediction 모델을 만든 리전입니다.
  • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.

성공하면 모델 버전이 다음 예측을 반환합니다.

{"predictions": [3]}

삭제

AI Platform Prediction 비용 및 Artifact Registry 비용이 계속 부과되지 않도록 하려면 이 가이드에서 만든 Google Cloud 리소스를 삭제합니다.

  1. 모델 버전을 삭제하려면 셸에서 다음 명령어를 실행합니다.

    gcloud ai-platform versions delete v1 \
  --region=REGION \
  --model=getting_started_pytorch \
  --quiet

    REGION을 이전 섹션에서 모델을 만든 리전으로 바꿉니다.

  2. 모델을 삭제하려면 셸에서 다음 명령어를 실행합니다.

    gcloud ai-platform models delete getting_started_pytorch \
  --region=REGION \
  --quiet

    REGION을 이전 섹션에서 모델을 만든 리전으로 바꿉니다.

  3. Artifact Registry 저장소 및 그 안의 컨테이너 이미지를 삭제하려면 셸에서 다음 명령어를 실행합니다.

    gcloud beta artifacts repositories delete getting-started-pytorch \
  --location=REGION \
  --quiet

    REGION을 이전 섹션에서 Artifact Registry 저장소를 만든 리전으로 바꿉니다.

다음 단계

  • 처음부터 새롭게 또는 기존 제3자 컨테이너 이미지로부터 파생하는 방식으로 고유한 컨테이너 이미지를 설계하기 위해서는 커스텀 컨테이너 요구사항을 참조하세요.

  • 배포 중 컨테이너에 지정할 수 있는 다른 AI Platform Prediction 특성 및 구성 옵션과의 호환성을 포함하여 예측을 위한 커스텀 컨테이너 사용에 대해 자세히 알아보세요.