학습 애플리케이션 패키징

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

학습 애플리케이션을 클라우드에 업로드하기 전에 로컬에서 테스트하면 최상의 결과를 얻을 수 있습니다. AI Platform을 사용하여 학습을 수행하면 리소스 사용량에 따라 계정에 비용이 부과됩니다.

시작하기 전에

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

  1. 시작하기 가이드의 설명에 따라 개발 환경을 구성합니다.
  2. 가이드에 따라 학습 애플리케이션의 데이터와 파일을 저장할 수 있는 Cloud Storage 버킷을 설정합니다.

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

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

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

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

    편의를 위해 구성 값을 환경 변수로 정의하는 것이 좋습니다. 다음 변수에는 애플리케이션 패키지를 스테이징하는 데 사용되는 값이 포함됩니다.

    TRAINER_PACKAGE_PATH="/path/to/your/application/sources"
    MAIN_TRAINER_MODULE="trainer.task"
    PACKAGE_STAGING_PATH="gs://your/chosen/staging/path"
    

    또한 다음 변수는 작업을 실행할 때 사용되는 값을 정의합니다.

    now=$(date +"%Y%m%d_%H%M%S")
    JOB_NAME="your_name_$now"
    JOB_DIR="gs://your/chosen/job/output/path"
    REGION="us-east1"
    

    다음 예에서는 애플리케이션을 패키징하고 학습 작업을 제출하는 gcloud ai-platform jobs submit training 명령어를 보여줍니다.

    gcloud ai-platform jobs submit training $JOB_NAME \
        --staging-bucket $PACKAGE_STAGING_PATH \
        --job-dir $JOB_DIR  \
        --package-path $TRAINER_PACKAGE_PATH \
        --module-name $MAIN_TRAINER_MODULE \
        --region $REGION \
        -- \
        --user_first_arg=first_arg_value \
        --user_second_arg=second_arg_value
    
    • --staging-bucket은 학습 및 종속 항목 패키지를 스테이징할 Cloud Storage 위치를 지정합니다. GCP 프로젝트에는 이 Cloud Storage 버킷에 대한 액세스 권한이 있어야 하며 해당 버킷은 작업을 실행하는 리전과 동일한 곳에 있어야 합니다. AI Platform 서비스에 사용 가능한 리전을 참조하세요. 스테이징 버킷을 지정하지 않으면 AI Platform이 job-dir 매개변수로 지정된 위치에 패키지를 스테이징합니다.

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

    • --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 전용 플래그는 빈 -- 플래그 앞에 와야 합니다. AI Platform 서비스는 이러한 플래그를 해석합니다.
    • --job-dir 플래그가 지정된 경우에는 이 플래그가 빈 -- 플래그 앞에 와야 합니다. AI Platform은 --job-dir을 사용하여 경로를 검증하기 때문입니다.
    • --job-dir 플래그가 지정된 경우 애플리케이션에서도 이 플래그를 처리해야 합니다. --job-dir 플래그는 빈 -- 플래그보다 앞에 나오지만 애플리케이션에 명령줄 플래그로 전달됩니다.
    • USER_ARGS는 원하는 만큼 정의할 수 있습니다. AI Platform은 --user_first_arg, --user_second_arg 등을 애플리케이션으로 전달합니다.

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

    종속 항목 작업

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

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

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

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

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

    표준(PyPI) 종속 항목 추가

    패키지의 표준 종속 항목을 setup.py 스크립트로 지정할 수 있습니다. AI Platform은 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.'
    )
    

    gcloud 명령줄 도구를 사용하여 학습 작업을 제출하는 경우 setup.py 파일을 사용해 자동으로 패키지를 만듭니다.

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

    python setup.py sdist
    

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

    커스텀 종속 항목 추가

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

    학습 작업 실행에 gcloud 도구를 사용하는 경우 로컬 디렉토리를 지정할 수 있으며 이 도구에서 클라우드에 이 디렉토리를 스테이징합니다. gcloud ai-platform jobs submit training 명령어를 실행합니다.

    • 학습 애플리케이션을 소스 코드가 저장된 디렉토리 경로나 빌드된 패키지 경로로 지정하도록 package-path 플래그를 설정합니다.

    • 쉼표로 구분된 목록에 종속 항목이 포함되도록 --packages 플래그를 설정합니다.

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

    아래의 예는 dep1.tar.gzdep2.whl(지원되는 각 패키지 유형에 따라 다름)이라는 패키징된 종속 항목과 애플리케이션 소스의 경로를 지정합니다.

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

    마찬가지로 아래의 예도 dep1.tar.gzdep2.whl(지원되는 각 패키지 유형에 따라 다름)이라는 패키징된 종속 항목을 지정하지만 빌드된 학습 애플리케이션을 사용합니다.

    gcloud ai-platform jobs submit training $JOB_NAME \
        --staging-bucket $PACKAGE_STAGING_PATH \
        --module-name $MAIN_TRAINER_MODULE \
        --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 and Prediction API를 사용하여 직접 학습 작업을 실행할 경우, 개발자가 직접 Cloud Storage 위치에 종속 항목 패키지를 스테이징한 후 해당 위치의 패키지 경로를 사용해야 합니다.

    직접 패키지 빌드

    Python 코드 패키징은 이 문서의 범위를 크게 벗어난 광범위한 주제입니다. 편의상 이 섹션에서는 Setuptools를 사용하여 패키지를 빌드하는 방법을 간략히 설명합니다. 동일한 작업에 사용할 수 있는 다른 라이브러리도 있습니다.

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

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

    2. 패키지의 루트 디렉토리(권장 패턴을 따르는 경우 trainer 디렉토리의 바로 위 디렉토리)에 다음 항목이 포함된 setup.py라는 Setuptools 파일을 포함합니다.

      • setuptools.find_packagessetuptools.setup의 import 문

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

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

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

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

        • _packages_를 find_packages()로 설정

        • _include_package_data_를 True로 설정

    3. python setup.py sdist를 실행하여 패키지를 생성합니다.

    프로젝트 구조 권장사항

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

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

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

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

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

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

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

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

    • model.py에는 모델의 로직인 텐서플로우 그래프 코드가 포함됩니다.

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

    학습 애플리케이션 프로젝트 구조의 권장사항

    애플리케이션을 패키징하기 위해 gcloud 도구를 사용하는 경우 setup.py 또는 __init__.py 파일을 만들 필요가 없습니다. gcloud ai-platform jobs submit training을 실행할 때 기본 프로젝트 디렉토리의 경로에 --package_path 플래그를 설정하거나, 이 디렉토리에서 도구를 실행하여 플래그를 모두 생략할 수도 있습니다.

    Python 모듈

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

    애플리케이션을 Python 패키지로 만들 때 네임스페이스가 생성됩니다. 예를 들어 trainer라는 패키지를 만들 때 기본 모듈 이름이 task.py이면, 패키지 이름을 trainer.task로 지정합니다. 따라서 gcloud ai-platform jobs submit training을 실행할 때 --module-name 플래그를 trainer.task로 설정합니다.

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

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

    패키지를 직접 빌드하는 경우 gcloud 도구를 사용하여 업로드할 수 있습니다. 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 $MAIN_TRAINER_MODULE \
        --region us-central1 \
        -- \
        --user_first_arg=first_arg_value \
        --user_second_arg=second_arg_value
    

    gcloud 도구를 통해 이미 클라우드에 있는 기존 패키지 사용

    패키지를 직접 빌드하고 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 $MAIN_TRAINER_MODULE \
        --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 and Prediction API를 직접 호출하여 학습 작업을 시작하려 할 때 패키지를 직접 업로드하게 됩니다. 패키지와 모든 커스텀 종속 항목을 Cloud Storage 버킷에 직접 업로드하는 가장 쉬운 방법은 gsutil 도구를 사용하는 것입니다.

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

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

    다음 단계

이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

TensorFlow용 AI Platform