Share via

CLI (v2) alapvető YAML-szintaxis

  • Cikk

ÉRVÉNYES:Azure CLI ml-bővítmény 2-es verzió (aktuális)

Minden Azure Machine Tanulás entitáshoz sémaalapú YAML-ábrázolás tartozik. Létrehozhat egy új entitást egy YAML-konfigurációs fájlból egy .yml vagy .yaml több kiterjesztéssel.

Ez a cikk áttekintést nyújt a YAML-fájlok konfigurálása során felmerülő alapvető szintaxisfogalmakról.

Azure Machine Tanulás entitás hivatkozása

Az Azure Machine Tanulás egy hivatkozási szintaxist (rövid és hosszú formátumú) biztosít egy meglévő Azure Machine-Tanulás entitásra való hivatkozáshoz YAML-fájlok konfigurálásakor. Hivatkozhat például egy meglévő regisztrált környezetre a munkaterületen, amelyet egy feladat környezeteként használhat.

Azure Machine Tanulás-eszköz hivatkozása

Az Azure Machine Tanulás-objektumokra (környezetekre, modellekre, adatokra és összetevőkre) két lehetőség van:

  • Hivatkozás egy objektum explicit verziójára:

    • Rövidített szintaxis: azureml:<asset_name>:<asset_version>
    • Longhand szintaxis, amely tartalmazza az eszköz Azure Resource Manager (ARM) erőforrás-azonosítóját:
    azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>

  • Hivatkozás az eszköz legújabb verziójára:

    Bizonyos esetekben előfordulhat, hogy az eszköz legújabb verziójára szeretne hivatkozni anélkül, hogy explicit módon fel kellene keresnie és meg kellene adnia magát a verziósztringet. A legújabb verzió egy adott név alatt létrehozott objektum legújabb (más néven legutóbbi) verziójaként van definiálva.

    A legújabb verzióra a következő szintaxissal hivatkozhat: azureml:<asset_name>@latest. Az Azure Machine Tanulás feloldja a munkaterület explicit eszközverziójának hivatkozását.

Azure Machine Tanulás-erőforrás hivatkozása

Azure Machine-Tanulás erőforrásra (például számításra) való hivatkozáshoz az alábbi szintaxisok egyikét használhatja:

  • Rövidített szintaxis: azureml:<resource_name>
  • Longhand szintaxis, amely tartalmazza az erőforrás ARM-erőforrás-azonosítóját:
azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

Azure Machine Tanulás URI-referencia

Az Azure Machine Tanulás kényelmes adathivatkozási URI-formátumot kínál, amely egy Azure Storage-szolgáltatás adataira mutat. Ez olyan helyzetekben használható, ahol meg kell adnia egy felhőbeli tárolóhelyet a YAML-fájlban, például létrehozhat egy Azure Machine Tanulás-modellt a tárolóban lévő fájl(ok)ból, vagy olyan adatokra mutathat, amelyeket bemenetként kell továbbítania egy feladatnak.

Az adat URI-formátum használatához a hivatkozni kívánt tárolási szolgáltatást először adattárként kell regisztrálni a munkaterületen. Az Azure Machine Tanulás az adattár létrehozása során megadott hitelesítő adatokkal kezeli az adathozzáférést.

A formátum az aktuális munkaterületen található adattárból és az adattár azon fájlhoz vagy mappához vezető elérési útból áll, amelyre mutatni szeretne:

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

Például:

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

Az Azure Machine Tanulás URI-ján kívül az Azure Machine Tanulás a következő közvetlen tárolási URI protokollokat is támogatja: https, wasbs, abfss, és , valamint nyilvános http és adlhttps URI-kat.

Kifejezésszintaxis az Azure Machine Tanulás feladatok és összetevők konfigurálásához

A v2 feladat- és összetevő YAML-fájlok lehetővé teszik, hogy a kifejezések különböző forgatókönyvek környezeteihez kötődjenek. Az alapvető használati eset egy olyan érték kifejezése, amely nem feltétlenül ismert a konfiguráció létrehozásakor, de futásidőben kell feloldani.

Az alábbi szintaxissal közölheti az Azure Machine Tanulás, hogy sztring helyett értékeljen ki egy kifejezést:

${{ <expression> }}

A támogatott forgatókönyveket alább találja.

A feladat környezeteinek és outputs környezeteinek inputs paraméterezése command

Konstans értékeket, URI-útvonalakat és regisztrált Azure Machine-Tanulás adategységeket adhat meg egy feladat bemeneteként. Ezt command követően a szintaxis használatával ${{inputs.<input_name>}} paraméterezhető ezekre a bemenetekre mutató hivatkozásokkal. A konstans bemenetekre mutató hivatkozások futásidőben feloldódnak a literális értékre, míg az adatbemenetekre mutató hivatkozások feloldódnak a letöltési útvonalra vagy a csatlakoztatási útvonalra (a mode megadotttól függően).

Hasonlóképpen, a feladat kimenetei is hivatkozhatnak a command. A szótárban megadott összes elnevezett kimenet esetében az outputs Azure Machine Tanulás létrehoz egy kimeneti helyet az alapértelmezett adattárban, ahová fájlokat írhat. Az egyes elnevezett kimenetek kimeneti helye a következő templatizált elérési úton alapul: <default-datastore>/azureml/<job-name>/<output_name>/. A command szintaxissal való paraméterezés feloldja a ${{outputs.<output_name>}} rendszer által létrehozott elérési útra mutató hivatkozást, hogy a szkript fájlokat írjon erre a helyre a feladatból.

Az alábbi példában egy YAML-fájl parancsfeladatához a command paraméterezés két bemenettel, egy konstans bemenettel és egy adatbemenettel és egy kimenettel történik. Futásidőben a kifejezés a ${{inputs.learning_rate}} következőre 0.01lesz feloldva, a kifejezés pedig a ${{inputs.iris}} fájl letöltési útvonalára iris.csv kerül. ${{outputs.model_dir}} a rendszer által létrehozott kimeneti helynek a kimenetnek megfelelő csatlakoztatási útvonalára model_dir lesz feloldva.

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

A takarítási feladat környezetének paraméterezése commandsearch_space

Ezt a kifejezésszintaxist akkor is használni fogja, ha a hiperparaméter-finomhangolást takarítási feladaton keresztül hajtja végre, mivel a hiperparaméterek tényleges értékei nem ismertek a feladat létrehozása során. A takarítási feladat futtatásakor az Azure Machine Tanulás a hiperparaméter-értékeket választja ki az egyes próbaverziókhoz a search_space. A betanítási szkriptben lévő értékek eléréséhez a szkript parancssori argumentumai segítségével kell átadnia őket. Ehhez használja a ${{search_space.<hyperparameter>}} szintaxist a trial.command.

Az alábbi példában egy takarítási feladat YAML-fájljában a ${{search_space.learning_rate}} beküldött trial.command hivatkozások feloldják ${{search_space.boosting}} az egyes próbaverziókhoz kiválasztott hiperparaméter-értékeket, amikor a próbafeladatot végrehajtásra küldik.

$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

Bemenetek és kimenetek kötése a folyamatfeladat lépései között

A kifejezések a folyamatfeladat lépései közötti bemenetek és kimenetek kötésére is használhatók. Egy folyamat egyik feladatának (B feladatának) bemenetét például egy másik feladat kimenetéhez (A feladathoz) kötheti. Ez a használat jelzi az Azure Machine-nek Tanulás a folyamatgráf függőségi folyamatát, a B feladat pedig az A feladat után lesz végrehajtva, mivel az A feladat kimenete a B feladat bemeneteként szükséges.

Egy folyamatfeladat YAML-fájlja esetében az inputs egyes gyermekfeladatok és outputs -szakaszok kiértékelése a szülőkörnyezetben (a legfelső szintű folyamatfeladatban) történik. A commandfeladat viszont az aktuális környezethez (a gyermekfeladathoz) lesz feloldva.

A folyamatfeladatok bemeneteinek és kimeneteinek kötése kétféleképpen lehetséges:

Kötés a folyamatfeladat felső szintű bemeneteihez és kimeneteihez

A gyermekfeladat (folyamatlépés) bemeneteit és kimeneteit a legfelső szintű szülőfolyamat-feladat bemeneteihez/kimeneteihez kötheti a következő szintaxissal: ${{parent.inputs.<input_name>}} vagy ${{parent.outputs.<output_name>}}. Ez a hivatkozás feloldja a parent kontextust, ezért a felső szintű bemenetek/kimenetek.

Az alábbi példában az első prep lépés bemenete (raw_data) a legfelső szintű folyamat bemenetéhez ${{parent.inputs.input_data}}van kötve. Az utolsó train lépés kimenete (model_dir) a legfelső szintű folyamatfeladat kimenetéhez ${{parent.outputs.trained_model}}van kötve.

Kötés egy másik gyermekfeladat bemeneteihez és kimeneteihez (lépés)

Ha egy lépés bemeneteit/kimeneteit egy másik lépés bemeneteihez/kimeneteihez szeretné kötni, használja a következő szintaxist: ${{parent.jobs.<step_name>.inputs.<input_name>}} vagy ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. Ez a hivatkozás ismét feloldja a szülőkörnyezetet, ezért a kifejezésnek a következővel parent.jobs.<step_name>kell kezdődnie: .

Az alábbi példában a lépés bemenete (training_data) a train lépés ${{parent.jobs.prep.outputs.clean_data}}kimenetéhez (clean_data) van kötve.prep A lépés előkészített prep adatai lesznek a lépés betanítási train adatai.

Másrészt a tulajdonságokon belüli command környezeti hivatkozások az aktuális környezetre lesznek feloldva. A lépésben command szereplő prep hivatkozás például ${{inputs.raw_data}} feloldja az aktuális környezet bemeneteit, vagyis a prep gyermekfeladatot. A keresés a következőn prep.inputslesz végrehajtva, ezért egy elnevezett raw_data bemenetet kell itt definiálni.

$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

Az összetevő és outputs a inputs környezetek paraméterezése command

A feladathoz command hasonlóan az command összetevő paraméterezhető a környezetekre és outputs a inputs környezetekre mutató hivatkozásokkal is. Ebben az esetben a hivatkozás az összetevő bemeneteire és kimeneteire vonatkozik. Amikor az összetevő egy feladatban fut, az Azure Machine Tanulás feloldja a feladat futásidejű bemeneti és kimeneti értékeire vonatkozó hivatkozásokat a megfelelő összetevő bemeneteihez és kimeneteihez. Az alábbiakban egy példa látható a YAML-specifikáció parancsösszetevőjének környezetszintaxisának használatára.

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

Opcionális bemenetek definiálása a parancssorban

Ha a bemenet be optional = truevan állítva, a parancssort bemenetekkel kell $[[]] használnia. Például: $[[--input1 ${{inputs.input1}}]. A futtatókörnyezeti parancssor különböző bemenetekkel rendelkezhet.

  • Ha csak a szükséges training_data és model_output a paramétereket használja, a parancssor a következőképpen fog kinézni:
python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Ha futásidőben nincs megadva érték, learning_rate és learning_rate_schedule az alapértelmezett értéket fogja használni.

  • Ha minden bemenet/kimenet értéket ad meg futásidőben, a parancssor a következőképpen fog kinézni:
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

Kimeneti elérési út kifejezései

A feladat kimeneti útvonalában a következő kifejezések használhatók:

Fontos

A következő kifejezések a kiszolgáló oldalán vannak feloldva, nem az ügyféloldalon. Az olyan ütemezett feladatok esetében, ahol a feladatlétrehozási idő és a feladat beküldési ideje eltérő, a kifejezéseket a rendszer feloldja a feladat elküldésekor. Mivel ezek a kifejezések feloldva vannak a kiszolgáló oldalán, a munkaterület aktuális állapotát használják, nem pedig a munkaterület állapotát az ütemezett feladat létrehozásakor. Ha például egy ütemezett feladat létrehozása után módosítja a munkaterület alapértelmezett adattárát, a kifejezés ${{default_datastore}} az új alapértelmezett adattárra lesz feloldva, nem pedig az alapértelmezett adattárra az ütemezett feladat létrehozásakor.

Expression Leírás Scope
${{default_datastore}} Ha a folyamat alapértelmezett adattára konfigurálva van, a rendszer a folyamat alapértelmezett adattárneveként oldja fel; ellenkező esetben a rendszer a munkaterület alapértelmezett adattárneveként lesz feloldva.

A folyamat alapértelmezett adattára a következővel pipeline_job.settings.default_datastorevezérelhető: .		 Minden feladathoz használható.

A folyamatfeladatok konfigurálható alapértelmezett folyamatadattárval rendelkeznek.
${{name}} A feladat neve. Folyamatok esetében ez a lépésfeladat neve, nem pedig a folyamatfeladat neve. Minden feladathoz használható
${{output_name}} A feladat kimenetének neve Minden feladathoz használható

Ha például azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} kimeneti elérési útként használják, futásidőben a rendszer a következő elérési útként azureml://datastores/workspaceblobstore/paths/<job-name>/model_patholdja fel a problémát.

További lépések