로컬에서 학습 코드 컨테이너화 및 실행

gcloud ai custom-jobs local-run 명령어를 사용하여 학습 코드를 기반으로 Docker 컨테이너 이미지를 빌드하고 로컬 컴퓨터에서 컨테이너로 이미지를 실행할 수 있습니다. 이 기능은 다음과 같은 몇 가지 이점을 제공합니다.

  • Docker에 대한 최소한의 지식으로 컨테이너 이미지를 빌드할 수 있으며, 자체 Dockerfile을 작성할 필요가 없습니다. 나중에 이 이미지를 Artifact Registry로 푸시하여 커스텀 컨테이너 학습에 사용할 수 있습니다.

    고급 사용 사례의 경우 자체 Dockerfile을 작성하는 것이 좋습니다.

  • 컨테이너 이미지는 Python 학습 애플리케이션 또는 Bash 스크립트를 실행할 수 있습니다.

    Bash 스크립트를 사용하여 다른 프로그래밍 언어로 작성된 학습 코드를 실행할 수 있습니다(단, 다른 언어를 지원하는 기본 컨테이너 이미지를 지정해야 함).

  • 컨테이너를 로컬에서 실행하면 학습 코드는 Vertex AI에서 실행되는 방식과 유사한 방식으로 실행됩니다.

    코드를 로컬에서 실행하면 Vertex AI에서 커스텀 학습을 수행하기 전에 코드 문제를 디버깅할 수 있습니다.

시작하기 전에

  1. Vertex AI 개발 환경을 설정합니다.

  2. Docker Engine을 설치합니다.

  3. Linux를 사용하는 경우 sudo 없이 실행할 수 있도록 Docker를 구성합니다.

    Docker를 사용하려면 local-run 명령어에 이 구성이 필요합니다.

local-run 명령어 사용

다음 명령어를 실행하여 학습 코드를 기반으로 컨테이너 이미지를 빌드하고 컨테이너를 로컬에서 실행합니다.

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME

다음을 바꿉니다.

  • BASE_IMAGE_URI: 컨테이너에 기본으로 사용할 Docker 이미지의 URI입니다. 학습 코드에 필요한 종속 항목이 포함된 기본 이미지를 선택합니다.

    사전 빌드된 학습 컨테이너 이미지의 URI 또는 Dockerfile FROM 명령어에 유효한 모든 값을 사용할 수 있습니다. 예를 들어 공개적으로 사용 가능한 Docker 이미지 또는 액세스할 수 있는 Artifact Registry의 Docker 이미지가 있습니다.

  • WORKING_DIRECTORY: 파일 시스템의 최하위 수준 디렉터리이며 학습에 사용해야 하는 모든 학습 코드와 로컬 종속 항목이 포함됩니다.

    기본적으로 이 명령어는 --script 플래그에 의해 지정된 파일(다음 목록 항목 참조)의 상위 디렉터리만 결과 Docker 이미지에 복사합니다. Docker 이미지는 WORKING_DIRECTORY 내의 모든 파일을 포함하지는 않습니다. 포함할 파일을 맞춤설정하려면 종속 항목 포함에 관한 이 문서의 섹션을 참조하세요.

    --local-package-path 플래그(및 이 자리표시자)를 생략하면 local-run 명령어가 이 값에 현재 작업 디렉터리를 사용합니다.

  • SCRIPT_PATH: 학습 코드의 진입점인 스크립트의 경로입니다(로컬 파일 시스템의 WORKING_DIRECTORY 기준). Python 스크립트(.py로 끝남) 또는 Bash 스크립트일 수 있습니다.

    예를 들어 /hello-world/trainer/task.py를 실행하려고 하고 WORKING_DIRECTORY가 /hello-world면 이 값에 trainer/task.py를 사용합니다.

    Python 스크립트를 지정하면 기본 이미지에 Python이 설치되어 있어야 하고 bash 스크립트를 지정하면 기본 이미지에 Bash가 설치되어 있어야 합니다. (사전 빌드된 모든 학습 컨테이너와 기타 공개적으로 사용 가능한 여러 Docker 이미지에는 두 종속 항목이 모두 포함됩니다.)

    --script 대신 --python-module 사용

    --script 플래그(및 SCRIPT_PATH)를 생략할 경우 대신 --python-module 플래그를 통해 WORKING_DIRECTORY의 Python 모듈의 이름을 지정하여 학습의 진입점으로 실행되도록 해야 합니다. 예를 들어 --script=trainer/task.py 대신 --python-module=trainer.task를 지정할 수 있습니다.

    이 경우 결과 Docker 컨테이너는 스크립트가 아닌 모듈로 코드를 로드합니다. 진입점 스크립트가 WORKING_DIRECTORY에서 다른 Python 모듈을 가져오는 경우 이 옵션을 사용하는 것이 좋습니다.

  • OUTPUT_IMAGE_NAME: 명령어로 빌드된 결과 Docker 이미지의 이름입니다. docker build의 -t 플래그에서 허용하는 모든 값을 사용할 수 있습니다.

    나중에 이미지를 Artifact Registry에 푸시하려는 경우 Artifact Registry 요구사항을 충족하는 이미지 이름을 사용하는 것이 좋습니다. 나중에 이미지를 Container Registry로 푸시하려는 경우 Container Registry 요구사항을 충족하는 이미지 이름을 사용하는 것이 좋습니다. 또는 나중에 추가 이름으로 이미지에 태그를 지정할 수 있습니다.

    --output-image-uri 플래그(및 이 자리표시자)를 생략하면 local-run 명령어가 현재 시간과 진입점 스크립트의 파일 이름을 기준으로 이미지에 태그를 지정합니다.

이 명령어는 구성을 기반으로 Docker 컨테이너 이미지를 빌드합니다. 이미지를 빌드한 후 명령어는 다음을 출력합니다.

A training image is built.
Starting to run ...

그러면 명령어가 이 컨테이너 이미지를 즉시 사용하여 로컬 컴퓨터에서 컨테이너를 실행합니다. 컨테이너가 종료되면 명령어는 다음을 출력합니다.

A local run is finished successfully using custom image: OUTPUT_IMAGE_NAME

추가 옵션

다음 섹션에서는 local-run 명령어의 동작을 맞춤설정하는 데 사용할 수 있는 추가 옵션을 설명합니다.

종속 항목 설치

학습 코드는 기본 이미지에 설치된 모든 종속 항목(예: 사전 빌드된 학습 컨테이너 이미지에는 많은 머신러닝용 Python 라이브러리가 포함되어 있음) 및 local-run 명령어로 만든 Docker 이미지에 포함되는 모든 파일을 사용할 수 있습니다.

--script 플래그 또는 --python-module 플래그를 사용하여 스크립트를 지정하면 명령어가 스크립트의 상위 디렉터리(및 해당 하위 디렉터리)를 Docker 이미지로 복사합니다. 예를 들어 --local-package-path=/hello-world 및 --script=trainer/task.py를 지정하면 명령어가 /hello-world/trainer/를 Docker 이미지로 복사합니다.

다음 섹션 중 하나에 설명된 추가 단계를 완료하여 파일 시스템에서 추가 Python 종속 항목 또는 임의의 파일을 포함할 수도 있습니다.

추가 Python 종속 항목 설치

여러 가지 방법으로 Docker 이미지에 추가 Python 종속 항목을 포함할 수 있습니다.

requirements.txt 파일 사용

작업 디렉터리에 requirements.txt라는 파일이 있으면 local-run 명령어가 이 파일을 pip 요구사항 파일로 취급하고 이를 사용하여 Docker 이미지에 Python 종속 항목을 설치합니다.

setup.py 파일 사용

작업 디렉터리에 setup.py라는 파일이 있으면 local-run 명령어가 이를 Python setup.py 파일로 취급하여 파일을 Docker 이미지에 복사한 뒤 이 파일이 포함된 Docker 이미지의 디렉터리에서 pip install을 실행합니다.

예를 들어 Docker 이미지에 Python 종속 항목을 설치하기 위해 setup.py에 install_requires 인수를 추가할 수 있습니다.

개별 PyPI 종속 항목 지정

--requirements 플래그를 사용하여 Docker 이미지의 PyPI에서 특정 종속 항목을 설치할 수 있습니다. 예를 들면 다음과 같습니다.

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --requirements=REQUIREMENTS

REQUIREMENTS를 쉼표로 구분된 Python 요구사항 지정자 목록으로 바꿉니다.

추가 로컬 Python 종속 항목 지정

--extra-packages 플래그를 사용하여 특정 로컬 Python 종속 항목을 설치할 수 있습니다. 이러한 Python 종속 항목은 작업 디렉터리 아래에 있어야 하며 각 종속 항목은 pip install에서 지원하는 형식이어야 합니다. 예를 들어 wheel file 또는 Python 소스 배포가 있습니다.

예를 들면 다음과 같습니다.

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-packages=LOCAL_DEPENDENCIES

LOCAL_DEPENDENCIES를 작업 디렉터리를 기준으로 표현된 쉼표로 구분된 로컬 파일 경로 목록으로 바꿉니다.

다른 파일 포함

추가 디렉터리를 Python 종속 항목으로 설치하지 않고 Docker 이미지에 복사하려면 --extra-dirs 플래그를 사용하면 됩니다. 작업 디렉터리 아래의 디렉터리만 지정할 수 있습니다. 예를 들면 다음과 같습니다.

gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --extra-dirs=EXTRA_DIRECTORIES

EXTRA_DIRECTORIES를 작업 디렉터리를 기준으로 표현된 쉼표로 구분된 로컬 디렉터리 목록으로 바꿉니다.

애플리케이션 인수 학습

학습 애플리케이션의 진입점 스크립트에 명령줄 인수가 필요한 경우 local-run 명령어를 실행할 때 이러한 인수를 지정할 수 있습니다. 이러한 인수는 Docker 이미지에 저장되지 않으며 오히려 이미지가 컨테이너로 실행될 때 인수로 전달됩니다.

진입점 스크립트에 인수를 전달하려면 스크립트 인수 뒤에 오는 -- 인수를 local-run 명령어(명령어의 다른 플래그 뒤에)에 전달합니다.

예를 들어 다음 명령어를 사용하여 로컬에서 실행하는 스크립트를 고려해 보겠습니다.

python /hello-world/trainer/task.py \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

local-run 명령어를 사용할 때 다음 플래그를 사용하여 동일한 인수로 컨테이너에서 스크립트를 실행할 수 있습니다.

gcloud ai custom-jobs local-run \\
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=/hello-world \
  --script=/trainer/task.py \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  -- \
  --learning_rate=0.1 \
  --input_data=gs://BUCKET/small-dataset/

GPU를 사용한 모델 학습 가속화

local-run 명령어로 생성한 Docker 이미지를 Vertex AI에 배포하고 GPU를 학습에 사용하려면 GPU를 활용하는 학습 코드를 작성하고 --executor-image-uri 플래그 값에 GPU 지원 Docker 이미지를 사용해야 합니다. 예를 들어 GPU를 지원하는 사전 빌드된 학습 컨테이너 이미지 중 하나를 사용할 수 있습니다.

로컬 컴퓨터에서 Linux를 실행하고 GPU가 있는 경우 컨테이너를 로컬에서 실행할 때 GPU를 사용하도록 local-run 명령어를 구성할 수도 있습니다. 이는 선택사항이지만 학습 코드가 GPU에서 작동하는 방식을 테스트하려는 경우 유용할 수 있습니다. 다음을 수행하세요.

  1. 아직 설치하지 않은 경우 로컬 컴퓨터에 NVIDIA Container Toolkit(nvidia-docker)을 설치합니다.

  2. local-run 명령어를 실행할 때 --gpu 플래그를 지정합니다. 예를 들면 다음과 같습니다.

    gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --gpu

커스텀 서비스 계정 지정

기본적으로 local-run 명령어가 로컬 컨테이너에서 학습 코드를 실행하면 명령어는 애플리케이션 기본 사용자 인증 정보(ADC)를 통해 로컬 환경에서 사용할 수 있는 Google Cloud 사용자 인증 정보를 컨테이너에 마운트합니다. 이로 인해 학습 코드는 동일한 사용자 인증 정보로 인증에 ADC를 사용할 수 있습니다. 즉, 로컬 셸에서 ADC를 통해 사용할 수 있는 사용자 인증 정보는 local-run 명령어를 실행할 때 코드에서도 ADC를 통해 사용할 수 있습니다.

gcloud auth application-default login 명령어를 사용하여 ADC에 사용자 계정을 사용하거나 환경 변수를 셸에서 설정하여 ADC에 서비스 계정을 사용할 수 있습니다.

컨테이너를 로컬 셸에서 ADC가 사용할 수 있는 사용자 인증 정보 이외의 Google Cloud 사용자 인증 정보로 실행하려면 다음을 수행합니다.

  1. 학습 코드에 액세스할 수 있는 권한이 있는 서비스 계정을 만들거나 선택합니다.

  2. 이 서비스 계정의 서비스 계정 키를 로컬 컴퓨터에 다운로드합니다.

  3. local-run 명령어를 실행할 때 --service-account-key-file 플래그를 지정합니다. 예를 들면 다음과 같습니다.

    gcloud ai custom-jobs local-run \
  --executor-image-uri=BASE_IMAGE_URI \
  --local-package-path=WORKING_DIRECTORY \
  --script=SCRIPT_PATH \
  --output-image-uri=OUTPUT_IMAGE_NAME \
  --service-account-key-file=KEY_PATH

    KEY_PATH를 로컬 파일 시스템의 서비스 계정 키 경로로 바꿉니다. 이 값은 절대적이거나, --local-package-path 플래그로 지정된 디렉터리 기준이 아닌 셸의 현재 작업 디렉터리를 기준으로 할 수 있습니다.

결과 컨테이너에서는 학습 코드가 ADC를 사용하여 지정된 서비스 계정 사용자 인증 정보로 인증할 수 있습니다.

Vertex AI의 학습 비교

Vertex AI에서 커스텀 학습을 수행하면 Vertex AI는 기본적으로 프로젝트에 대한 Vertex AI 커스텀 코드 서비스 에이전트를 사용하여 코드를 실행합니다. 커스텀 학습을 위해 다른 서비스 계정을 연결할 수도 있습니다.

local-run 명령어를 사용하면 Vertex AI 커스텀 코드 서비스 에이전트로 인증할 수 없지만 비슷한 권한이 있는 서비스 계정을 만들어 로컬에서 사용할 수 있습니다.

다음 단계