CLI-kärnsyntax (v2) YAML

  • Artikel

GÄLLER FÖR:Azure CLI ml extension v2 (aktuell)

Varje Azure Machine Learning-entitet har en schematiserad YAML-representation. Du kan skapa en ny entitet från en YAML-konfigurationsfil med ett .yml eller .yaml ett tillägg.

Den här artikeln innehåller en översikt över grundläggande syntaxbegrepp som du kommer att stöta på när du konfigurerar dessa YAML-filer.

Referera till en Azure Machine Learning-entitet

Azure Machine Learning innehåller en referenssyntax (bestående av ett kortfattat och långt format) för att referera till en befintlig Azure Machine Learning-entitet när du konfigurerar en YAML-fil. Du kan till exempel referera till en befintlig registrerad miljö på din arbetsyta som ska användas som miljö för ett jobb.

Referera till en Azure Machine Learning-tillgång

Det finns två alternativ för att referera till en Azure Machine Learning-tillgång (miljöer, modeller, data och komponenter):

  • Referera till en explicit version av en tillgång:

    • Kortfattad syntax: azureml:<asset_name>:<asset_version>
    • Longhand-syntax, som innehåller resurs-ID:t för Azure Resource Manager (ARM) för tillgången:
    azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>

  • Referera till den senaste versionen av en tillgång:

    I vissa scenarier kanske du vill referera till den senaste versionen av en tillgång utan att uttryckligen behöva leta upp och ange själva versionssträngen. Den senaste versionen definieras som den senaste (kallas även senast) skapade versionen av en tillgång under ett givet namn.

    Du kan referera till den senaste versionen med hjälp av följande syntax: azureml:<asset_name>@latest. Azure Machine Learning löser referensen till en explicit tillgångsversion på arbetsytan.

Referera till en Azure Machine Learning-resurs

Om du vill referera till en Azure Machine Learning-resurs (till exempel beräkning) kan du använda någon av följande syntaxer:

  • Kortfattad syntax: azureml:<resource_name>
  • Longhand-syntax, som innehåller resursens ARM-resurs-ID:
azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

Referens-URI för Azure Machine Learning-data

Azure Machine Learning erbjuder ett URI-format för bekvämlighetsdatareferenser som pekar på data i en Azure-lagringstjänst. Detta kan användas för scenarier där du behöver ange en molnlagringsplats i YAML-filen, till exempel att skapa en Azure Machine Learning-modell från filer i lagring eller peka på data för att skicka som indata till ett jobb.

Om du vill använda det här data-URI-formatet måste den lagringstjänst som du vill referera till först registreras som ett datalager på din arbetsyta. Azure Machine Learning hanterar dataåtkomsten med de autentiseringsuppgifter som du angav när du skapade datalager.

Formatet består av ett datalager i den aktuella arbetsytan och sökvägen i datalagringen till den fil eller mapp som du vill peka på:

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

Till exempel:

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

Utöver referens-URI för Azure Machine Learning-data stöder Azure Machine Learning även följande URI-protokoll för direkt lagring: https, wasbs, abfssoch adlsamt offentliga http och https URI:er.

Uttryckssyntax för att konfigurera Azure Machine Learning-jobb och -komponenter

v2-jobb- och komponent-YAML-filer tillåter användning av uttryck för att binda till kontexter för olika scenarier. Det viktiga användningsfallet är att använda ett uttryck för ett värde som kanske inte är känt vid tidpunkten för redigeringen av konfigurationen, men som måste lösas vid körning.

Använd följande syntax för att instruera Azure Machine Learning att utvärdera ett uttryck i stället för att behandla det som en sträng:

${{ <expression> }}

De scenarier som stöds beskrivs nedan.

Parametrisera command med inputs kontexterna och outputs för ett jobb

Du kan ange literalvärden, URI-sökvägar och registrerade Azure Machine Learning-datatillgångar som indata till ett jobb. command Kan sedan parametriseras med referenser till dessa indata med hjälp av syntaxen${{inputs.<input_name>}}. Referenser till literalindata matchas med literalvärdet vid körning, medan referenser till dataindata matchas till nedladdningssökvägen eller monteringssökvägen (beroende på angiven mode ).

På samma sätt kan utdata till jobbet också refereras till i command. För varje namngivet outputs utdata som anges i ordlistan systemgenereras en utdataplats i standarddataarkivet där du kan skriva filer till. Utdataplatsen för varje namngiven utdata baseras på följande templaterade sökväg: <default-datastore>/azureml/<job-name>/<output_name>/. Om du parameteriserar command med syntaxen ${{outputs.<output_name>}} matchas referensen till den systemgenererade sökvägen, så att skriptet kan skriva filer till den platsen från jobbet.

I exemplet nedan för en YAML-fil command för kommandojobbet parametriseras den med två indata, en literalindata och en datainmatning och en utdata. Vid körningen matchas ${{inputs.learning_rate}} uttrycket till 0.01, och ${{inputs.iris}} uttrycket matchas till filens nedladdningssökväg iris.csv . ${{outputs.model_dir}} matchar monteringssökvägen för den systemgenererade utdataplatsen som motsvarar model_dir utdata.

$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:

Parameterisera command med kontexten för search_space ett svepjobb

Du kommer också att använda den här uttryckssyntaxen när du utför hyperparameterjustering via ett svepjobb, eftersom de faktiska värdena för hyperparametrar inte är kända under jobbredigeringstiden. När du kör ett svepjobb väljer Azure Machine Learning hyperparametervärden för varje utvärderingsversion baserat på search_space. För att få åtkomst till dessa värden i träningsskriptet måste du skicka in dem via skriptets kommandoradsargument. Om du vill göra det använder du syntaxen ${{search_space.<hyperparameter>}}trial.commandi .

I exemplet nedan för en YAML-fil för svepjobb matchas referenserna ${{search_space.learning_rate}} och ${{search_space.boosting}} i trial.command till de faktiska hyperparametervärden som valts för varje utvärderingsversion när utvärderingsjobbet skickas för körning.

$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

Binda indata och utdata mellan steg i ett pipelinejobb

Uttryck används också för att binda indata och utdata mellan steg i ett pipelinejobb. Du kan till exempel binda indata för ett jobb (jobb B) i en pipeline till utdata från ett annat jobb (jobb A). Den här användningen signalerar till Azure Machine Learning beroendeflödet i pipelinediagrammet och jobb B körs efter jobb A, eftersom utdata från jobb A krävs som indata för jobb B.

För en YAML-fil för pipelinejobb utvärderas avsnitten inputs och outputs i varje underordnat jobb i den överordnade kontexten (pipelinejobbet på den översta nivån). Å commandandra sidan matchas den aktuella kontexten (det underordnade jobbet).

Det finns två sätt att binda indata och utdata i ett pipelinejobb:

Binda till toppnivåindata och utdata för pipelinejobbet

Du kan binda indata eller utdata för ett underordnat jobb (ett pipelinesteg) till indata/utdata för det överordnade pipelinejobbet på den översta nivån med hjälp av följande syntax: ${{parent.inputs.<input_name>}} eller ${{parent.outputs.<output_name>}}. Den här referensen matchar kontexten parent , därav indata/utdata på den översta nivån.

I exemplet nedan är indata (raw_data) för det första prep steget bundna till pipelineindata på den översta nivån via ${{parent.inputs.input_data}}. Utdata (model_dir) för det sista train steget är bundna till pipelinejobbet på den översta nivån via ${{parent.outputs.trained_model}}.

Binda till indata och utdata för ett annat underordnat jobb (steg)

Om du vill binda indata/utdata från ett steg till indata/utdata i ett annat steg använder du följande syntax: ${{parent.jobs.<step_name>.inputs.<input_name>}} eller ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. Återigen matchar den här referensen den överordnade kontexten, så uttrycket måste börja med parent.jobs.<step_name>.

I exemplet nedan är indata () för train steget bundna till utdata (clean_data) för prep steget via ${{parent.jobs.prep.outputs.clean_data}}.training_data Förberedda data från prep steget används som träningsdata för train steget.

Å andra sidan matchas kontextreferenserna i egenskaperna med den aktuella kontexten command . Referensen ${{inputs.raw_data}}prep i steget command matchar till exempel indata för den aktuella kontexten, som är det prep underordnade jobbet. Sökningen görs på prep.inputs, så en indata med namnet raw_data måste definieras där.

$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

Parametrisera command med kontexten inputs och outputs för en komponent

På samma sätt som command för ett jobb command kan för en komponent också parametriseras med referenser till kontexterna inputs och outputs . I det här fallet är referensen till komponentens indata och utdata. När komponenten körs i ett jobb löser Azure Machine Learning dessa referenser till de indata- och utdatavärden för jobbkörning som angetts för respektive komponentindata och utdata. Nedan visas ett exempel på hur du använder kontextsyntaxen för en YAML-specifikation för kommandokomponenten.

$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}}

Definiera valfria indata på kommandoraden

När indata anges som optional = truemåste du använda $[[]] för att omfamna kommandoraden med indata. Till exempel $[[--input1 ${{inputs.input1}}]. Kommandoraden vid körning kan ha olika indata.

  • Om du bara använder de obligatoriska training_data parametrarna och model_output parametrarna ser kommandoraden ut så här:
python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Om inget värde anges vid körning learning_rate och learning_rate_schedule använder standardvärdet.

  • Om alla indata/utdata ger värden under körningen ser kommandoraden ut så här:
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

Utdatasökvägsuttryck

Följande uttryck kan användas i utdatasökvägen för jobbet:

Viktigt!

Följande uttryck matchas på serversidan , inte på klientsidan . För schemalagda jobb där jobbskapandetidenoch tiden för jobböverföring är olika löses uttrycken när jobbet skickas. Eftersom dessa uttryck matchas på serversidan använder de arbetsytans aktuella tillstånd, inte arbetsytans tillstånd när det schemalagda jobbet skapades. Om du till exempel ändrar standarddatalagringen för arbetsytan när du har skapat ett schemalagt jobb matchas uttrycket ${{default_datastore}} till det nya standarddataarkivet, inte standarddatalagringen när det schemalagda jobbet skapades.

Uttryck beskrivning Definitionsområde
${{default_datastore}} Om standarddatalager för pipelinen har konfigurerats matchas det som standardnamn för pipelinedatalager. annars matchas som standardnamn för arbetsytans datalager.

Standarddatalager för pipeline kan styras med hjälp av pipeline_job.settings.default_datastore.		 Fungerar för alla jobb.

Pipelinejobb har ett konfigurerbart standarddatalager för pipeline.
${{name}} Jobbnamnet. För pipelines är det stegets jobbnamn, inte namnet på pipelinejobbet. Fungerar för alla jobb
${{output_name}} Jobbets utdatanamn Fungerar för alla jobb

Om azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} den till exempel används som utdatasökväg löses den vid körning som en sökväg till azureml://datastores/workspaceblobstore/paths/<job-name>/model_path.

Nästa steg