CLI(v2) 핵심 YAML 구문

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

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

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

Azure ML 엔터티 참조

Azure ML에서는 YAML 파일을 구성할 때 기존 Azure ML 엔터티를 참조하기 위해 약식 및 정식으로 구성된 참조 구문을 제공합니다. 예를 들어 작업 영역에서 기존에 등록된 환경을 참조하여 작업 환경으로 사용할 수 있습니다.

Azure ML 자산 참조

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

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

    • 약식 구문: 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 ML은 작업 영역의 명시적 자산 버전에 대한 참조를 확인합니다.

Azure ML 리소스 참조

Azure ML 리소스(예: 컴퓨팅)를 참조하려면 다음 구문 중 하나를 사용하면 됩니다.

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

Azure ML 데이터 참조 URI

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

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

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

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

다음은 그 예입니다.

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

Azure ML 데이터 참조 URI 외에도 Azure ML에서는 퍼블릭 httphttps URI뿐만 아니라 https, wasbs, abfss, adl과 같은 직접 스토리지 URI 프로토콜도 지원합니다.

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

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

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

${{ <expression> }}

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

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

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

마찬가지로 작업에 대한 출력도 command에서 참조할 수 있습니다. outputs 사전에 지정된 각 명명된 출력에 대해 Azure ML에서는 파일을 쓸 수 있는 기본 데이터 저장소의 출력 위치를 시스템 생성합니다. 각 명명된 출력의 출력 위치는 <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 ML에서는 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 ML에 신호하고, 작업 A의 출력이 작업 B에 대한 입력으로 필요하기 때문에 작업 B는 작업 A 이후에 실행됩니다.

파이프라인 작업 YAML 파일의 경우 각 자식 작업의 inputsoutputs 섹션이 부모 컨텍스트(최상위 파이프라인 작업) 내에서 평가됩니다. 반면에 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

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

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

$schema: https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json
type: command
code: ./src
command: python train.py --lr ${{inputs.learning_rate}} --training-data ${{inputs.iris}} --model-dir ${{outputs.model_dir}}
environment: azureml:AzureML-Minimal@latest
inputs:
  learning_rate:
    type: number
    default: 0.01
  iris:
    type: uri_file
outputs:
  model_dir:
    type: uri_folder

다음 단계