CLI(v2) 핵심 YAML 구문

  • 아티클

적용 대상:Azure CLI ml 확장 v2(현재)

모든 Azure Machine Learning 엔터티에는 스키마화된 YAML 표현이 있습니다. .yml 또는 .yaml 확장을 사용하여 YAML 구성 파일에서 새 엔터티를 만들 수 있습니다.

이 문서에서는 이러한 YAML 파일을 구성하는 동안 발생하는 핵심 구문 개념에 대한 개요를 제공합니다.

Azure Machine Learning 엔터티 참조

Azure Machine Learning은 YAML 파일을 구성할 때 기존 Azure Machine Learning 엔터티를 참조하기 위한 참조 구문(약식 및 긴 형식으로 구성됨)을 제공합니다. 예를 들어 작업 영역에서 기존에 등록된 환경을 참조하여 작업 환경으로 사용할 수 있습니다.

Azure Machine Learning 자산 참조

Azure Machine Learning 자산(환경, 모델, 데이터 및 구성 요소)을 참조하는 두 가지 옵션이 있습니다.

  • 자산의 명시적 버전을 참조합니다.

    • 약식 구문: azureml:<asset_name>:<asset_version>
    • 자산의 ARM(Azure Resource Manager) 리소스 ID를 포함하는 Longhand 구문:
    azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>

  • 자산의 최신 버전을 참조합니다.

    일부 시나리오에서는 실제 버전 문자열 자체를 명시적으로 조회하고 지정하지 않고도 자산의 최신 버전을 참조할 수 있습니다. 최신 버전은 지정된 이름으로 자산의 최신 버전(가장 최근에 만든 버전이라고도 함)으로 정의됩니다.

    azureml:<asset_name>@latest 구문을 사용하여 최신 버전을 참조할 수 있습니다. Azure Machine Learning은 작업 영역에서 명시적 자산 버전에 대한 참조를 확인합니다.

Azure Machine Learning 리소스 참조

Azure Machine Learning 리소스(예: 컴퓨팅)를 참조하려면 다음 구문 중 하나를 사용할 수 있습니다.

  • 약식 구문: azureml:<resource_name>
  • 리소스의 ARM 리소스 ID를 포함하는 Longhand 구문:
azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

Azure Machine Learning 데이터 참조 URI

Azure Machine Learning은 Azure Storage 서비스의 데이터를 가리키는 편리한 데이터 참조 URI 형식을 제공합니다. 스토리지의 파일에서 Azure Machine Learning 모델을 만들거나 작업에 입력으로 전달할 데이터를 가리키는 등 YAML 파일에서 클라우드 스토리지 위치를 지정해야 하는 시나리오에 사용할 수 있습니다.

이 데이터 URI 형식을 사용하려면 참조하려는 스토리지 서비스를 먼저 작업 영역에서 데이터 저장소로 등록해야 합니다. Azure Machine Learning은 데이터 저장소를 만드는 동안 제공한 자격 증명을 사용하여 데이터 액세스를 처리합니다.

형식은 현재 작업 영역의 데이터 저장소 및 가리키려는 파일 또는 폴더에 대한 데이터 저장소의 경로로 구성됩니다.

azureml://datastores/<datastore-name>/paths/<path-on-datastore>/

예시:

  • azureml://datastores/workspaceblobstore/paths/example-data/
  • azureml://datastores/workspaceblobstore/paths/example-data/iris.csv

Azure Machine Learning 데이터 참조 URI 외에도 Azure Machine Learning은 공용 http 및 httpsadlURI뿐만 아니라 다음과 같은 직접 스토리지 URI 프로토콜httpswasbsabfss도 지원합니다.

Azure Machine Learning 작업 및 구성 요소를 구성하기 위한 식 구문

v2 작업 및 구성 요소 YAML 파일을 사용하면 식을 사용하여 다양한 시나리오의 컨텍스트에 바인딩할 수 있습니다. 필수 사용 사례는 구성을 작성할 때 알려지지 않았지만 런타임에 해결해야 하는 값에 식을 사용하는 것입니다.

다음 구문을 사용하여 Azure Machine Learning에 식을 문자열로 처리하는 대신 평가하도록 지시합니다.

${{ <expression> }}

지원되는 시나리오는 아래에서 다룹니다.

작업의 inputs 및 outputs 컨텍스트를 통해 command를 매개 변수화

리터럴 값, URI 경로 및 등록된 Azure Machine Learning 데이터 자산을 작업에 대한 입력으로 지정할 수 있습니다. 그런 다음 ${{inputs.<input_name>}} 구문을 사용하는 해당 입력에 대한 참조를 사용하여 command를 매개 변수화할 수 있습니다. 리터럴 입력에 대한 참조는 런타임에 리터럴 값으로 확인되는 반면, 데이터 입력에 대한 참조는 지정된 mode에 따라 다운로드 경로 또는 탑재 경로로 확인됩니다.

마찬가지로 작업에 대한 출력도 command에서 참조할 수 있습니다. 사전에 지정된 각 명명된 출력에 outputs 대해 Azure Machine Learning은 파일을 쓸 수 있는 기본 데이터 저장소에서 출력 위치를 시스템 생성합니다. 각 명명된 출력의 출력 위치는 <default-datastore>/azureml/<job-name>/<output_name>/의 템플릿화된 경로를 기반으로 합니다. ${{outputs.<output_name>}} 구문을 사용하여 command를 매개 변수화하면 스크립트가 작업에서 해당 위치에 파일을 쓸 수 있도록 시스템 생성된 경로에 대한 참조가 확인됩니다.

명령 작업 YAML 파일에 대한 아래 예제에서 command는 두 개의 입력, 즉 리터럴 입력과 데이터 입력 및 하나의 출력으로 매개 변수화됩니다. 런타임 시 ${{inputs.learning_rate}} 식은 0.01로 확인되고 ${{inputs.iris}} 식은 iris.csv 파일의 다운로드 경로로 확인됩니다. ${{outputs.model_dir}}는 model_dir 출력에 해당하는 시스템 생성 출력 위치의 탑재 경로로 확인됩니다.

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: ./src
command: python train.py --lr ${{inputs.learning_rate}} --training-data ${{inputs.iris}} --model-dir ${{outputs.model_dir}}
environment: azureml:AzureML-Minimal@latest
compute: azureml:cpu-cluster
inputs:
  learning_rate: 0.01
  iris:
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
    mode: download
outputs:
  model_dir:

스윕 작업의 search_space 컨텍스트를 통해 command를 매개 변수화

또한 작업 작성 시간 동안 하이퍼 매개 변수의 실제 값을 알 수 없으므로 스윕 작업을 통해 하이퍼 매개 변수 튜닝을 수행할 때도 이 식 구문을 사용합니다. 스윕 작업을 실행하면 Azure Machine Learning에서 각 평가판에 대한 search_space하이퍼 매개 변수 값을 선택합니다. 학습 스크립트에서 이러한 값에 액세스하려면 스크립트의 명령줄 인수를 통해 전달해야 합니다. 이렇게 하려면 trial.command의 ${{search_space.<hyperparameter>}} 구문을 사용합니다.

스윕 작업 YAML 파일에 대한 아래 예제에서 trial.command의 ${{search_space.learning_rate}} 및 ${{search_space.boosting}} 참조는 평가판 작업이 실행을 위해 제출될 때 각 평가판에 대해 선택된 실제 하이퍼 매개 변수 값으로 확인됩니다.

$schema: https://azuremlschemas.azureedge.net/latest/sweepJob.schema.json
type: sweep
sampling_algorithm:
  type: random
search_space:
  learning_rate:
    type: uniform
    min_value: 0.01
    max_value: 0.9
  boosting:
    type: choice
    values: ["gbdt", "dart"]
objective:
  goal: minimize
  primary_metric: test-multi_logloss
trial:
  code: ./src
  command: >-
    python train.py 
    --training-data ${{inputs.iris}}
    --lr ${{search_space.learning_rate}}
    --boosting ${{search_space.boosting}}
  environment: azureml:AzureML-Minimal@latest
inputs:
  iris:
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
    mode: download
compute: azureml:cpu-cluster

파이프라인 작업의 단계 간에 입력 및 출력 바인딩

식은 파이프라인 작업의 단계 간에 입력 및 출력을 바인딩하는 데도 사용됩니다. 예를 들어 파이프라인의 한 작업(작업 B)의 입력을 다른 작업(작업 A)의 출력에 바인딩할 수 있습니다. 이 사용은 Azure Machine Learning에 파이프라인 그래프의 종속성 흐름을 알리고 작업 B는 작업 A의 출력이 작업 B에 대한 입력으로 필요하므로 작업 A 후에 실행됩니다.

파이프라인 작업 YAML 파일의 경우 각 자식 작업의 inputs 및 outputs 섹션이 부모 컨텍스트(최상위 파이프라인 작업) 내에서 평가됩니다. 반면에 command는 현재 컨텍스트(자식 작업)로 확인됩니다.

파이프라인 작업에서 입력 및 출력을 바인딩하는 방법에는 두 가지가 있습니다.

파이프라인 작업의 최상위 입력 및 출력에 바인딩

${{parent.inputs.<input_name>}} 또는 ${{parent.outputs.<output_name>}} 구문을 사용하여 자식 작업(파이프라인 단계)의 입력 또는 출력을 최상위 부모 파이프라인 작업의 입출력에 바인딩할 수 있습니다. 이 참조는 parent 컨텍스트로 확인됩니다. 따라서 최상위 입출력입니다.

아래 예제에서 첫 번째 prep 단계의 입력(raw_data)은 ${{parent.inputs.input_data}}를 통해 최상위 파이프라인 입력에 바인딩됩니다. 최종 train 단계의 출력(model_dir)은 ${{parent.outputs.trained_model}}을 통해 최상위 파이프라인 작업 출력에 바인딩됩니다.

다른 자식 작업(단계)의 입력 및 출력에 바인딩

한 단계의 입출력을 다른 단계의 입출력에 바인딩하려면 ${{parent.jobs.<step_name>.inputs.<input_name>}} 또는 ${{parent.jobs.<step_name>.outputs.<outputs_name>}} 구문을 사용합니다. 다시 말하지만, 이 참조는 부모 컨텍스트로 확인되므로 식은 parent.jobs.<step_name>으로 시작해야 합니다.

아래 예제에서 train 단계의 입력(training_data)은 ${{parent.jobs.prep.outputs.clean_data}}를 통해 prep 단계의 출력(clean_data)에 바인딩됩니다. prep 단계의 준비된 데이터는 train 단계의 학습 데이터로 사용됩니다.

반면에 command 속성 내의 컨텍스트 참조는 현재 컨텍스트로 확인됩니다. 예를 들어 prep 단계의 command에 있는 ${{inputs.raw_data}} 참조는 prep 자식 작업인 현재 컨텍스트의 입력으로 확인됩니다. 조회는 prep.inputs에서 수행되므로 raw_data라는 입력을 정의해야 합니다.

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline
inputs:
  input_data: 
    type: uri_folder
    path: https://azuremlexamples.blob.core.windows.net/datasets/cifar10/
outputs:
  trained_model:
jobs:
  prep:
    type: command
    inputs:
      raw_data: ${{parent.inputs.input_data}}
    outputs:
      clean_data:
    code: src/prep
    environment: azureml:AzureML-Minimal@latest
    command: >-
      python prep.py 
      --raw-data ${{inputs.raw_data}} 
      --prep-data ${{outputs.clean_data}}
    compute: azureml:cpu-cluster
  train:
    type: command
    inputs: 
      training_data: ${{parent.jobs.prep.outputs.clean_data}}
      num_epochs: 1000
    outputs:
      model_dir: ${{parent.outputs.trained_model}}
    code: src/train
    environment: azureml:AzureML-Minimal@latest
    command: >-
      python train.py 
      --epochs ${{inputs.num_epochs}}
      --training-data ${{inputs.training_data}} 
      --model-output ${{outputs.model_dir}}
    compute: azureml:gpu-cluster

구성 요소의 inputs 및 outputs 컨텍스트를 통해 command를 매개 변수화

작업에 대한 command와 마찬가지로 구성 요소에 대한 command는 inputs 및 outputs 컨텍스트에 대한 참조를 사용하여 매개 변수화할 수도 있습니다. 이 경우 참조는 구성 요소의 입력 및 출력에 대한 것입니다. 구성 요소가 작업에서 실행되면 Azure Machine Learning은 해당 구성 요소 입력 및 출력에 대해 지정된 작업 런타임 입력 및 출력 값에 대한 참조를 확인합니다. 다음은 명령 구성 요소 YAML 사양에 대한 컨텍스트 구문을 사용하는 예제입니다.

$schema: https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json
name: train_data_component_cli
display_name: train_data
description: A example train component
tags:
  author: azureml-sdk-team
version: 9
type: command
inputs:
  training_data: 
    type: uri_folder
  max_epocs:
    type: integer
    optional: true
  learning_rate: 
    type: number
    default: 0.01
    optional: true
  learning_rate_schedule: 
    type: string
    default: time-based
    optional: true
outputs:
  model_output:
    type: uri_folder
code: ./train_src
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest
command: >-
  python train.py 
  --training_data ${{inputs.training_data}} 
  $[[--max_epocs ${{inputs.max_epocs}}]]
  $[[--learning_rate ${{inputs.learning_rate}}]]
  $[[--learning_rate_schedule ${{inputs.learning_rate_schedule}}]]
  --model_output ${{outputs.model_output}}

명령줄에서 선택적 입력 정의

입력이 optional = true로 설정된 경우 $[[]]를 사용하여 입력이 있는 명령줄을 수용해야 합니다. (예: $[[--input1 ${{inputs.input1}}]) 런타임 시 명령줄에는 다른 입력이 있을 수 있습니다.

  • 필수 training_data 및 model_output 매개 변수만 사용하는 경우 명령줄은 다음과 같습니다.
python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

런타임 시 값이 지정되지 않으면 learning_rate 및 learning_rate_schedule은 기본값을 사용합니다.

  • 런타임 중에 모든 입력/출력이 값을 제공하는 경우 명령줄은 다음과 같습니다.
python train.py --training_data some_input_path --max_epocs 10 --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

출력 경로 식

작업의 출력 경로에 다음 식을 사용할 수 있습니다.

Important

다음 식은 클라이언트 측이 아닌 서버 측에서 확인됩니다. 작업 만들기 시간과 작업 제출 시간이 다른 예약된 작업의 경우 작업이 제출되면 식이 해결됩니다. 이러한 식은 서버 쪽에서 확인되므로 예약된 작업이 만들어졌을 때 작업 영역의 상태가 아닌 작업 영역의 현재 상태를 사용합니다. 예를 들어, 예약된 작업을 만든 후 작업 영역의 기본 데이터 저장소를 변경하면 ${{default_datastore}} 식은 예약된 작업이 만들어질 때의 기본 데이터 저장소가 아닌 새 기본 데이터 저장소로 확인됩니다.

식 설명 범위
${{default_datastore}} 파이프라인 기본 데이터 저장소가 구성된 경우 파이프라인 기본 데이터 저장소 이름으로 확인됩니다. 그렇지 않으면 작업 영역 기본 데이터 저장소 이름으로 확인됩니다.

파이프라인 기본 데이터 저장소는 pipeline_job.settings.default_datastore를 사용하여 제어할 수 있습니다.		 모든 직업에 적용됩니다.

파이프라인 작업에는 구성 가능한 파이프라인 기본 데이터 저장소가 있습니다.
${{name}} 작업 이름입니다. 파이프라인의 경우 파이프라인 작업 이름이 아닌 단계 작업 이름입니다. 모든 직업에 적용 가능
${{output_name}} 작업 출력 이름 모든 직업에 적용 가능

예를 들어, azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}}이 출력 경로로 사용되면 런타임 시 azureml://datastores/workspaceblobstore/paths/<job-name>/model_path의 경로로 확인됩니다.

다음 단계