학습 애플리케이션 패키징

AI Platform Training으로 학습 애플리케이션을 실행하려면 먼저 Google Cloud 프로젝트에서 액세스 가능한 Cloud Storage 버킷에 코드 및 종속 항목을 업로드해야 합니다. 이 페이지에서는 클라우드에서 애플리케이션을 패키징하고 스테이징하는 방법을 설명합니다.

학습 애플리케이션을 클라우드에 업로드하기 전에 로컬에서 테스트하면 최상의 결과를 얻을 수 있습니다. AI Platform Training을 통한 학습에서 사용한 리소스 비용은 사용자의 계정에 청구됩니다.

시작하기 전에

학습 애플리케이션을 클라우드로 이전하려면 먼저 다음 단계를 완료해야 합니다.

1. 시작하기 가이드의 설명대로 개발 환경을 구성합니다.

2. AI Platform Training의 호스팅된 머신러닝 프레임워크인 TensorFlow, scikit-learn 또는 XGBoost를 사용하여 학습 애플리케이션을 개발합니다. 또는 커스텀 컨테이너를 빌드하여 학습 애플리케이션의 환경을 맞춤설정합니다. 이렇게 하면 AI Platform Training의 호스팅된 프레임워크 이외의 머신러닝 프레임워크를 사용할 수 있습니다.

   학습이 완료된 모델을 AI Platform Prediction에 배포하려면 학습 패키지에서 AI Platform Prediction이 사용할 수 있는 모델 아티팩트를 내보내야 합니다. 자세한 내용은 예측용 모델 내보내기 가이드를 참조하세요.

3. 가이드에 따라 학습 애플리케이션의 데이터와 파일을 저장할 수 있는 Cloud Storage 버킷을 설정합니다.

4. 커스텀 패키지나 PyPI를 통한 무료 사용 여부에 상관없이 학습 애플리케이션이 사용하는 모든 Python 라이브러리에 대해 파악합니다.

이 문서에서는 애플리케이션을 패키징하여 Cloud Storage로 업로드하는 방식에 영향을 미치는 아래와 같은 요인에 대해 설명합니다.

• gcloud CLI(권장)를 사용하거나 자체 솔루션을 코딩
• 필요에 따라 직접 패키지 구축
• 사용 중인 AI Platform Training 런타임으로 설치되지 않는 추가 종속 항목을 포함하는 방법

gcloud를 사용하여 애플리케이션 패키징 및 업로드(권장)

애플리케이션을 패키징한 후 종속 항목과 함께 업로드하는 가장 간편한 방법은 gcloud CLI를 사용하는 것입니다. 애플리케이션 패키징 및 업로드와 첫 번째 학습 작업 제출은 모두 한 개의 명령어(gcloud ai-platform jobs submit training)로 가능합니다.

편의를 위해 구성 값을 셸 변수로 정의하는 것이 좋습니다.

PACKAGE_PATH='LOCAL_PACKAGE_PATH'
MODULE_NAME='MODULE_NAME'
STAGING_BUCKET='BUCKET_NAME'
JOB_NAME='JOB_NAME'
JOB_DIR='JOB_OUTPUT_PATH'
REGION='REGION'

다음을 바꿉니다.

• LOCAL_PACKAGE_PATH: 로컬 환경의 Python 패키지 디렉터리 경로
• MODULE_NAME: 학습 모듈의 정규화된 이름
• BUCKET_NAME: Cloud Storage 버킷의 이름
• JOB_NAME: 학습 작업 이름
• JOB_OUTPUT_PATH: 학습 작업에서 출력을 저장할 Cloud Storage 디렉터리의 URI
• REGION: 학습 작업을 실행할 리전

이러한 값의 요구사항에 관한 자세한 내용은 다음 명령어 이후의 목록을 참조하세요.

다음은 애플리케이션을 패키징하고 학습 작업을 제출하는 gcloud ai-platform jobs submit training 명령어 예시입니다.

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket=$STAGING_BUCKET \
    --job-dir=$JOB_DIR  \
    --package-path=$PACKAGE_PATH \
    --module-name=$MODULE_NAME \
    --region=$REGION \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

• --staging-bucket은 학습 및 종속 항목 패키지를 스테이징할 Cloud Storage 버킷을 지정합니다. Google Cloud 프로젝트에는 이 Cloud Storage 버킷에 대한 액세스 권한이 있어야 하며 해당 버킷은 작업을 실행하는 리전과 동일한 리전에 있어야 합니다. AI Platform Training 서비스에 사용 가능한 리전을 참조하세요. 스테이징 버킷을 지정하지 않으면 AI Platform Training이 job-dir 매개변수로 지정된 위치에 패키지를 스테이징합니다.

• --job-dir은 학습 작업의 출력 파일에 사용할 Cloud Storage 위치를 지정합니다. Google Cloud 프로젝트에는 이 Cloud Storage 버킷에 대한 액세스 권한이 있어야 하며 해당 버킷은 작업을 실행하는 곳과 동일한 리전에 있어야 합니다. AI Platform Training 서비스에 사용 가능한 리전을 참조하세요.

• --package-path는 애플리케이션 디렉터리에 대한 로컬 경로를 지정합니다. gcloud CLI는 --package-path로 지정된 항목의 상위 디렉터리에 있는 setup.py파일을 기반으로 코드에서 .tar.gz 배포 패키지를 빌드합니다. 그런 다음 이 .tar.gz 파일을 Cloud Storage로 업로드한 후 이 파일을 사용하여 학습 작업을 실행합니다.

  예상 위치에 setup.py 파일이 없으면 gcloud CLI가 간단한 임시 setup.py를 만들고, 빌드하는 .tar.gz 파일에 --package-path로 지정된 디렉터리만 포함합니다.

• --module-name은 패키지의 네임스페이스 점 표기법을 사용하여 애플리케이션의 기본 모듈 이름을 지정합니다. 이 모듈은 애플리케이션을 시작하기 위해 실행하는 Python 파일입니다. 예를 들어 기본 모듈이 .../my_application/trainer/task.py(권장 프로젝트 구조 참조)이면 모듈 이름은 trainer.task입니다.

• 구성 파일(config.yaml)과 명령줄 플래그 모두에 옵션을 지정하면 명령줄에 있는 값이 구성 파일에 있는 값보다 우선 적용됩니다.
• 빈 -- 플래그는 애플리케이션에 전달하려는 gcloud 관련 플래그의 끝과 USER_ARGS의 시작을 표시합니다.
• --module-name, --runtime-version, --job-dir 등의 AI Platform Training 관련 플래그는 빈 -- 플래그보다 앞에 와야 합니다. AI Platform Training 서비스가 이러한 플래그를 해석합니다.
• --job-dir 플래그가 지정된 경우 AI Platform Training이 --job-dir을 사용하여 경로를 검증하므로 이 플래그가 빈 -- 플래그보다 앞에 와야 합니다.
• --job-dir 플래그가 지정된 경우 애플리케이션에서도 이 플래그를 처리해야 합니다. 또한 플래그가 빈 --보다 앞에 오더라도, --job-dir이 애플리케이션에 명령줄 플래그로 전달됩니다.
• USER_ARGS는 원하는 만큼 정의할 수 있습니다. AI Platform Training은 --user_first_arg, --user_second_arg 등을 애플리케이션으로 전달합니다.

작업 제출 플래그에 대한 자세한 내용은 학습 작업 실행 가이드에서 확인할 수 있습니다.

종속 항목 작업

종속 항목은 코드에서 import를 사용해 가져오는 패키지입니다. 애플리케이션에는 작업에 필요한 여러 종속 항목이 포함될 수 있습니다.

AI Platform Training에서 학습 작업을 실행할 때는 많은 공통 Python 패키지가 이미 설치된 학습 인스턴스(특별히 구성된 가상 머신)에서 작업이 실행됩니다. 학습에 사용하는 런타임 버전에 포함된 패키지를 확인하고 아직 설치되지 않은 모든 종속 항목을 기록합니다.

추가해야 하는 종속 항목에는 다음 2가지 유형이 있습니다.

• PyPI에서 사용 가능한 공통 Python 패키지인 표준 종속 항목
• 사용자가 직접 개발한 패키지나 조직 내부의 패키지와 같은 커스텀 패키지

아래 섹션에서는 각 유형별 절차를 설명합니다.

표준(PyPI) 종속 항목 추가

패키지의 표준 종속 항목을 setup.py 스크립트로 지정할 수 있습니다. AI Platform Training은 pip를 사용하여 작업용으로 할당된 학습 인스턴스에 패키지를 설치합니다. pip install 명령어는 구성된 종속 항목을 찾아 설치합니다.

애플리케이션의 루트 디렉터리(권장 패턴을 따르는 경우 trainer 디렉터리의 바로 위 디렉터리)에 setup.py라는 파일을 만듭니다.

setup.py에 다음 스크립트를 입력하되, 각 항목에 사용자 값을 입력합니다.

from setuptools import find_packages
from setuptools import setup

REQUIRED_PACKAGES = ['some_PyPI_package>=1.0']

setup(
    name='trainer',
    version='0.1',
    install_requires=REQUIRED_PACKAGES,
    packages=find_packages(),
    include_package_data=True,
    description='My training application package.'
)

Google Cloud CLI를 사용하여 학습 작업을 제출하는 경우 자동으로 setup.py 파일을 사용하여 패키지를 만듭니다.

gcloud를 사용하지 않고 학습 작업을 제출하는 경우에는 다음 명령어를 사용하여 스크립트를 실행합니다.

python setup.py sdist

자세한 내용은 학습 애플리케이션 수동 패키징 섹션을 참조하세요.

커스텀 종속 항목 추가

작업 구성에 경로를 포함해 애플리케이션의 커스텀 종속 항목을 지정할 수 있습니다. 이를 위해서는 각 종속 항목 패키지의 URI가 필요합니다. 커스텀 종속 항목은 Cloud Storage 위치에 있어야 합니다. AI Platform Training은 pip install을 사용하여 커스텀 종속 항목을 설치하므로 해당 setup.py 스크립트에 자체 표준 종속 항목이 포함될 수 있습니다.

gcloud CLI를 사용하여 학습 작업을 실행하는 경우, 로컬 머신과 Cloud Storage의 종속 항목을 지정할 수 있으며, 도구가 이를 클라우드에 스테이징합니다. gcloud ai-platform jobs submit training 명령어를 실행할 때 --packages 플래그를 설정하여 쉼표로 구분된 목록에 종속 항목을 포함합니다.

포함되는 각 URI는 tarball(.tar.gz) 또는 wheel(.whl)로 형식이 지정된 배포 패키지 경로입니다. AI Platform Training은 pip install을 사용하여 학습 작업용으로 할당된 모든 가상 머신에 각 패키지를 설치합니다.

아래의 예시는 애플리케이션 소스의 경로와 함께 dep1.tar.gz 및 dep2.whl(지원되는 각 패키지 유형에 해당)이라는 패키징된 종속 항목을 지정합니다.

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --package-path /Users/mluser/models/faces/trainer \
    --module-name $MODULE_NAME \
    --packages dep1.tar.gz,dep2.whl \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

마찬가지로 아래의 예시는 dep1.tar.gz 및 dep2.whl(지원되는 각 패키지 유형에 해당)이라는 패키징된 종속 항목을 지정하지만 구성된 학습 애플리케이션을 사용합니다.

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --module-name $MODULE_NAME \
    --packages trainer-0.0.1.tar.gz,dep1.tar.gz,dep2.whl
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

AI Platform Training 및 Prediction API를 직접 사용하여 학습 작업을 실행하는 경우에는 Cloud Storage 위치에 종속 항목 패키지를 직접 스테이징한 후 해당 위치의 패키지 경로를 사용해야 합니다.

직접 패키지 빌드

Python 코드 패키징은 이 문서의 주제를 넘어서는 매우 광범위한 주제입니다. 따라서 이 섹션에서는 Setuptools를 사용하여 패키지를 빌드하는 방법에 대해서만 간략하게 설명합니다. 다른 라이브러리에서도 이와 같은 방법을 설명하고 있습니다.

참고: 애플리케이션 패키지를 설치할 때 일부 설정 작업이 필요한 경우에도 패키지를 반드시 직접 빌드할 필요는 없습니다. 대신 패키지의 루트 디렉터리에 커스텀 __init__.py 파일을 포함하고 Google Cloud CLI를 사용하여 패키지를 만들어 업로드할 수 있습니다. gcloud ai-platform jobs submit 명령어를 실행할 때 --package-path를 포함하면 도구에서 자동으로 사용할 __init__.py 파일을 찾습니다.

패키지를 직접 빌드하려면 다음 단계를 따르세요.

1. 애플리케이션 패키지의 각 디렉터리에 __init__.py라는 파일을 포함합니다. 이 파일은 비어 있거나 해당 패키지(해당 디렉터리의 모든 모듈)를 가져올 때 실행되는 코드를 포함할 수 있습니다.

2. .tar.gz 배포 패키지에 포함하려는 모든 코드의 상위 디렉터리(권장 패턴을 따르는 경우 trainer 디렉터리의 바로 위 디렉터리)에 다음 항목을 포함하는 setup.py라는 Setuptools 파일을 포함합니다.

   • setuptools.find_packages와 setuptools.setup의 import 문

   • 최소한 다음과 같은 매개변수가 설정된 setuptools.setup에 대한 호출

     • _name_을 패키지 네임스페이스의 이름으로 설정

     • _version_을 이 패키지 빌드의 버전 번호로 설정

     • _install_requires_는 'docutils>=0.3'과 같은 버전 요구사항과 함께 애플리케이션에 필요한 패키지 목록으로 설정

     • _packages_를 find_packages()로 설정. 이렇게 하면 Setuptools에 __init__.py 파일을 '가져오기 패키지'(from trainer import util과 같은 문을 통해 Python으로 여기서 모듈을 import)로 포함하는 상위 디렉터리의 모든 하위 디렉터리를 '배포 패키지'(모든 코드가 포함된 `.tar.gz 파일)에 포함하도록 지시합니다.

     • _include_package_data_를 True로 설정.

3. python setup.py sdist를 실행하여 .tar.gz 배포 패키지를 만듭니다.

프로젝트 구조 권장사항

학습 애플리케이션은 원하는 방식으로 구성할 수 있지만, AI Platform Training 샘플에서 일반적으로 사용되는 구조와 유사하게 프로젝트를 구성하면 샘플을 더 쉽게 따라할 수 있습니다. 일반적으로 사용되는 구조는 다음과 같습니다.

• setup.py 파일이 포함된 기본 프로젝트 디렉터리를 사용합니다.

  setup.py 파일의 setuptools에서 find_packages() 함수를 사용하여 모든 하위 디렉터리가 빌드하는 .tar.gz 배포 패키지에 포함되도록 합니다.

• trainer라는 하위 디렉터리를 사용하여 기본 애플리케이션 모듈을 저장합니다.

• 기본 애플리케이션 모듈 task.py의 이름을 지정합니다.

• 애플리케이션을 구현하는 데 필요한 다른 하위 디렉터리를 기본 프로젝트 디렉터리에 만듭니다.

• 모든 하위 디렉터리에 __init__.py 파일을 만듭니다. 이러한 파일은 패키징할 코드가 있는 디렉터리를 식별하기 위해 Setuptools에서 사용되며 비어 있을 수도 있습니다.

AI Platform Training 샘플에서 trainer 디렉터리에는 일반적으로 다음과 같은 소스 파일이 포함됩니다.

• task.py에는 학습 작업을 관리하는 애플리케이션 로직이 포함됩니다.

• model.py에는 모델의 로직이 포함됩니다.

• util.py가 있는 경우 여기에는 학습 애플리케이션을 실행하는 코드가 포함됩니다.

gcloud ai-platform jobs submit training을 실행할 때 --package-path를 trainer로 설정합니다. 그러면 gcloud CLI에서 기본 프로젝트 디렉터리인 trainer의 상위 요소에서 setup.py 파일을 찾습니다.

Python 모듈

애플리케이션 패키지에는 여러 모듈(Python 파일)이 포함될 수 있습니다. 사용자는 애플리케이션 진입점이 포함된 모듈을 파악해야 합니다. 학습 서비스는 사용자가 로컬에서 실행할 때와 마찬가지로 Python을 호출하여 모듈을 실행합니다.

예를 들어 이전 섹션의 구조 권장사항을 따르는 경우 기본 모듈은 task.py입니다. 이는 trainer라는 가져오기 패키지(__init__.py 파일이 있는 디렉터리)에 있으므로 이 모듈의 정규화된 이름은 trainer.task입니다. 따라서 gcloud ai-platform jobs submit training으로 작업을 제출하는 경우 --module-name 플래그를 trainer.task로 설정합니다.

모듈에 대한 자세한 내용은 Python 패키지 가이드를 참조하세요.

gcloud CLI를 사용하여 기존 패키지 업로드

패키지를 직접 빌드하는 경우 gcloud CLI를 사용하여 업로드할 수 있습니다. gcloud ai-platform jobs submit training 명령어를 실행합니다.

• --packages 플래그를 패키징된 애플리케이션 경로로 설정합니다.

• --module-name 플래그를 패키지의 네임스페이스 점 표기법을 사용하여 애플리케이션의 기본 모듈 이름으로 설정합니다. 이 모듈은 애플리케이션을 시작하기 위해 실행하는 Python 파일입니다. 예를 들어 기본 모듈이 .../my_application/trainer/task.py(권장 프로젝트 구조 참조)이면 모듈 이름은 trainer.task입니다.

아래의 예시에서는 명령어를 실행하는 디렉터리에 있는 압축된 tarball 패키지(여기서는 trainer-0.0.1.tar.gz)를 사용하는 방법을 보여줍니다. 기본 함수는 task.py:라는 모듈에 있습니다.

gcloud ai-platform jobs submit training $JOB_NAME \
    --staging-bucket $PACKAGE_STAGING_PATH \
    --job-dir $JOB_DIR \
    --packages trainer-0.0.1.tar.gz \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

gcloud CLI를 사용하여 이미 클라우드에 있는 기존 패키지 활용

패키지를 직접 빌드하고 Cloud Storage 위치로 업로드하는 경우 gcloud를 사용할 수 있습니다. gcloud ai-platform jobs submit training 명령어를 실행합니다.

• --packages 플래그를 패키징된 애플리케이션 경로로 설정합니다.

• --module-name 플래그를 패키지의 네임스페이스 점 표기법을 사용하여 애플리케이션의 기본 모듈 이름으로 설정합니다. 이 모듈은 애플리케이션을 시작하기 위해 실행하는 Python 파일입니다. 예를 들어 기본 모듈이 .../my_application/trainer/task.py(권장 프로젝트 구조 참조)이면 모듈 이름은 trainer.task입니다.

아래의 예시에서는 Cloud Storage 버킷 내에 있는 압축된 tarball 패키지를 사용하는 방법을 보여줍니다.

gcloud ai-platform jobs submit training $JOB_NAME \
    --job-dir $JOB_DIR \
    --packages $PATH_TO_PACKAGED_TRAINER \
    --module-name $MODULE_NAME \
    --region us-central1 \
    -- \
    --user_first_arg=first_arg_value \
    --user_second_arg=second_arg_value

여기서 $PATH_TO_PACKAGED_TRAINER는 이미 클라우드에 있는 기존 패키지의 경로를 나타내는 환경 변수입니다. 예를 들어 이 경로는 trainer-0.0.1.tar.gz라는 압축된 tarball 패키지를 포함하는 다음 Cloud Storage 위치를 가리킬 수 있습니다.

PATH_TO_PACKAGED_TRAINER=gs://$CLOUD_STORAGE_BUCKET_NAME/trainer-0.0.0.tar.gz

직접 패키지 업로드

필요하다면 직접 패키지를 업로드할 수 있습니다. 가장 흔한 이유는 AI Platform Training 및 Prediction API를 직접 호출하여 학습 작업을 시작하려는 경우입니다. 패키지와 모든 커스텀 종속 항목을 Cloud Storage 버킷에 직접 업로드하는 가장 쉬운 방법은 gcloud storage 명령어 도구를 사용하는 것입니다.

gcloud storage cp /local/path/to/package.tar.gz  gs://bucket/path/

하지만 이 작업에 명령줄을 사용할 수 있다면 학습 작업을 설정할 때 gcloud ai-platform jobs submit training을 사용하여 패키지를 업로드하기만 하면 됩니다. 명령줄을 사용할 수 없는 경우에는 Cloud Storage 클라이언트 라이브러리를 사용하여 프로그래매틱 방식으로 업로드합니다.

다음 단계

• 학습 작업 구성 및 실행
• 실행 중인 학습 작업 모니터링
• 학습 작동 방식에 대해 자세히 알아보기