Sintaks YAML inti CLI (v2)

BERLAKU UNTUK:ekstensi ml Azure CLI v2 (saat ini)

Setiap entitas Azure Machine Learning memiliki representasi YAML yang diberi skema. Anda dapat membuat entitas baru dari file konfigurasi YAML dengan ekstensi .yml atau .yaml.

Artikel ini memberikan gambaran umum tentang konsep sintaks inti yang akan Anda temui saat mengonfigurasi file YAML ini.

Mereferensikan entitas Azure Pembelajaran Mesin

Azure Pembelajaran Mesin menyediakan sintaks referensi (terdiri dari format singkat dan panjang) untuk mereferensikan entitas Azure Pembelajaran Mesin yang ada saat mengonfigurasi file YAML. Misalnya, Anda dapat mereferensikan lingkungan terdaftar yang ada di ruang kerja untuk digunakan di lingkungan tersebut bagi pekerjaan.

Mereferensikan aset Azure Pembelajaran Mesin

Ada dua opsi untuk mereferensikan aset Pembelajaran Mesin Azure (lingkungan, model, data, dan komponen):

  • Referensikan versi eksplisit aset:

    • Sintaks pintasan: azureml:<asset_name>:<asset_version>
    • Sintaks penuh, yang mencakup ID sumber daya Azure Resource Manager (ARM) dari aset:
    azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>
    
  • Referensi versi terbaru dari aset:

    Dalam beberapa skenario Anda mungkin ingin mereferensikan versi terbaru aset tanpa harus secara eksplisit mencari dan menentukan string versi sebenarnya itu sendiri. Versi terbaru didefinisikan sebagai versi aset yang dibuat terbaru (juga dikenal sebagai yang terkini) dengan nama tertentu.

    Anda dapat mereferensikan versi terbaru menggunakan sintaks berikut: azureml:<asset_name>@latest. Azure Pembelajaran Mesin akan menyelesaikan referensi ke versi aset eksplisit di ruang kerja.

Mereferensikan sumber daya Azure Pembelajaran Mesin

Untuk mereferensikan sumber daya Azure Pembelajaran Mesin (seperti komputasi), Anda bisa menggunakan salah satu sintaks berikut:

  • Sintaks pintasan: azureml:<resource_name>
  • Sintaks penuh, yang mencakup ID sumber daya ARM dari sumber daya:
azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

URI referensi data Azure Pembelajaran Mesin

Azure Pembelajaran Mesin menawarkan format URI referensi data yang nyaman untuk mengarahkan ke data dalam layanan penyimpanan Azure. Ini dapat digunakan untuk skenario di mana Anda perlu menentukan lokasi penyimpanan cloud dalam file YAML Anda, seperti membuat model Azure Pembelajaran Mesin dari file di penyimpanan, atau menunjuk ke data untuk diteruskan sebagai input ke pekerjaan.

Untuk menggunakan format URI data ini, layanan penyimpanan yang ingin Anda referensikan harus terlebih dahulu terdaftar sebagai datastore di ruang kerja. Azure Pembelajaran Mesin akan menangani akses data menggunakan kredensial yang Anda berikan selama pembuatan datastore.

Format terdiri dari datastore di ruang kerja saat ini dan jalur pada datastore ke file atau folder yang ingin Anda arahkan:

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

Contohnya:

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

Selain URI referensi data Azure Pembelajaran Mesin, Azure Pembelajaran Mesin juga mendukung protokol URI penyimpanan langsung berikut: https, , wasbs, abfssdan adl, serta URI publik http dan https URI.

Sintaks ekspresi untuk mengonfigurasi pekerjaan dan komponen Azure Pembelajaran Mesin

pekerjaan v2 dan file YAML komponen memungkinkan penggunaan ekspresi mengikat konteks untuk skenario yang berbeda. Kasus penggunaan penting adalah menggunakan ekspresi untuk nilai yang mungkin tidak dikenal pada saat penulisan konfigurasi, tetapi harus diselesaikan saat runtime.

Gunakan sintaks berikut untuk memberi tahu Azure Pembelajaran Mesin mengevaluasi ekspresi daripada memperlakukannya sebagai string:

${{ <expression> }}

Skenario yang didukung tercakup di bawah ini.

Memberikan parameter command dengan konteks inputs dan outputs dari pekerjaan

Anda dapat menentukan nilai harfiah, jalur URI, dan aset data Azure Pembelajaran Mesin terdaftar sebagai input ke pekerjaan. command kemudian dapat diberi parameter dengan referensi ke input tersebut menggunakan sintaks ${{inputs.<input_name>}}. Referensi ke input harfiah akan diselesaikan ke nilai harfiah saat runtime, sementara referensi ke input data akan diselesaikan ke jalur pengunduhan atau jalur pemasangan (bergantung pada mode yang ditentukan).

Selain itu, output ke pekerjaan juga dapat direferensikan di command. Untuk setiap output bernama yang ditentukan dalam outputs kamus, Azure Pembelajaran Mesin akan menghasilkan lokasi output pada datastore default tempat Anda dapat menulis file. Lokasi output untuk setiap output bernama didasarkan pada jalur bertemplat berikut: <default-datastore>/azureml/<job-name>/<output_name>/. Memberikan parameter command dengan sintaks ${{outputs.<output_name>}} akan menyelesaikan referensi tersebut ke jalur yang dihasilkan sistem, sehingga skrip Anda dapat menulis file ke lokasi tersebut dari pekerjaan.

Dalam contoh di bawah untuk file YAML pekerjaan perintah, command diberi parameter dengan dua input, input harfiah dan input URI, dan satu output. Saat runtime, ekspresi ${{inputs.learning_rate}} akan berubah menjadi 0.01, dan ekspresi ${{inputs.iris}} akan berubah menjadi jalur pengunduhan file iris.csv. ${{outputs.model_dir}} akan menyelesaikan ke jalur pemasangan lokasi output yang dihasilkan sistem yang sesuai dengan output 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:

Pemberian parameter command dengan konteks search_space dari pekerjaan pembersihan

Anda juga akan menggunakan sintaks ekspresi ini saat melakukan penyetelan hyperparameter melalui pekerjaan pembersihan, karena nilai aktual dari hyperparameter tidak dikenal selama waktu penulisan pekerjaan. Saat Anda menjalankan pekerjaan pembersihan, Azure Pembelajaran Mesin akan memilih nilai hyperparameter untuk setiap percobaan berdasarkan search_space. Untuk mengakses nilai-nilai ini dalam skrip pelatihan, Anda harus meneruskannya melalui argumen baris perintah skrip. Untuk melakukannya, gunakan sintaks ${{search_space.<hyperparameter>}} di trial.command.

Dalam contoh di bawah ini untuk file YAML pekerjaan pembersihan, referensi ${{search_space.learning_rate}} dan ${{search_space.boosting}} di trial.command akan ditentukan ke nilai hyperparameter aktual yang dipilih untuk setiap percobaan saat pekerjaan percobaan dikirimkan untuk dieksekusi.

$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

Mengikat input dan output di antara langkah-langkah dalam pekerjaan alur

Ekspresi juga digunakan untuk mengikat input dan output di antara langkah-langkah dalam pekerjaan alur. Misalnya, Anda dapat mengikat input dari satu pekerjaan (pekerjaan B) dalam alur ke output dari pekerjaan lain (pekerjaan A). Penggunaan ini akan memberi sinyal ke Azure Pembelajaran Mesin alur dependensi grafik alur, dan pekerjaan B akan dijalankan setelah pekerjaan A, karena output pekerjaan A diperlukan sebagai input untuk pekerjaan B.

Untuk file YAML pekerjaan alur, bagian inputs dan outputs dari setiap pekerjaan turunan dievaluasi dalam konteks induk (pekerjaan alur tingkat atas). command, di sisi lain, akan menentukan konteks saat ini (pekerjaan turunan).

Ada dua cara untuk mengikat input dan output dalam pekerjaan alur:

​​Mengikat ke input dan output tingkat atas dari pekerjaan alur

Anda dapat mengikat input atau output dari pekerjaan turunan (langkah alur) ke input/output dari pekerjaan alur induk tingkat atas menggunakan sintaks berikut: ${{parent.inputs.<input_name>}} atau ${{parent.outputs.<output_name>}}. Referensi ini menjadi konteks parent; oleh karena itu, input/output tingkat atas.

Pada contoh di bawah ini, input (raw_data) dari langkah prep pertama terikat ke output alur tingkat atas melalui ${{parent.inputs.input_data}}. Output (model_dir) dari langkah train terakhir terikat ke output pekerjaan alur tingkat atas melalui ${{parent.outputs.trained_model}}.

Mengikat ke input dan output dari pekerjaan turunan lainnya (langkah)

Untuk mengikat input/output dari satu langkah ke input/output dari langkah lain, gunakan sintaks berikut: ${{parent.jobs.<step_name>.inputs.<input_name>}} atau ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. Sekali lagi, referensi ini menjadi konteks induk, jadi konteksnya dimulai dengan parent.jobs.<step_name>.

Pada contoh di bawah, input (training_data) dari langkah train terikat dengan output (clean_data) dari langkah prep melalui ${{parent.jobs.prep.outputs.clean_data}}. Data yang disiapkan dari langkah prep akan digunakan sebagai data pelatihan untuk langkah train.

Di sisi lain, referensi konteks dalam properti command akan menjadi konteks saat ini. Misalnya, referensi ${{inputs.raw_data}} di prep langkah command akan menjadi input dari konteks saat ini, yang merupakan pekerjaan turunan prep. Pencarian akan dilakukan pada prep.inputs, jadi input bernama raw_data harus ditentukan di sana.

$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

Berikan parameter command dengan konteks inputs dan outputs dari komponen

Mirip dengan command untuk pekerjaan, command untuk komponen juga dapat diberi parameter dengan referensi ke konteks inputs dan outputs. Dalam kasus ini referensi adalah untuk input dan output komponen. Ketika komponen dijalankan dalam pekerjaan, Azure Pembelajaran Mesin akan menyelesaikan referensi tersebut ke nilai input dan output runtime pekerjaan yang ditentukan untuk input dan output komponen masing-masing. Di bawah ini adalah contoh penggunaan sintaks konteks untuk spesifikasi YAML komponen perintah.

$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: 7
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:AzureML-sklearn-1.0-ubuntu20.04-py38-cpu:1
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}}

Menentukan input opsional dalam baris perintah

Ketika input diatur sebagai optional = true, Anda perlu menggunakan $[[]] untuk merangkul baris perintah dengan input. Contoh: $[[--input1 ${{inputs.input1}}]. Baris perintah pada runtime mungkin memiliki input yang berbeda.

  • Jika Anda hanya menggunakan parameter dan model_output yang diperlukantraining_data, baris perintah akan terlihat seperti:
python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Jika tidak ada nilai yang ditentukan pada runtime, learning_rate dan learning_rate_schedule akan menggunakan nilai default.

  • Jika semua input/output memberikan nilai selama runtime, baris perintah akan terlihat seperti:
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

Ekspresi jalur output

Ekspresi berikut dapat digunakan dalam jalur output pekerjaan Anda:

Penting

Ekspresi berikut diselesaikan di sisi server , bukan sisi klien . Untuk pekerjaan terjadwal di mana waktu pembuatan pekerjaan dan waktu pengiriman pekerjaan berbeda, ekspresi diselesaikan saat pekerjaan dikirimkan. Karena ekspresi ini diselesaikan di sisi server, ekspresi menggunakan status ruang kerja saat ini , bukan status ruang kerja saat pekerjaan terjadwal dibuat. Misalnya, jika Anda mengubah datastore default ruang kerja setelah Anda membuat pekerjaan terjadwal, ekspresi ${{default_datastore}} diselesaikan ke datastore default baru, bukan datastore default saat pekerjaan terjadwal dibuat.

Expression Deskripsi Scope
${{default_datastore}} Jika datastore default alur dikonfigurasi, diselesaikan sebagai nama datastore default alur; jika tidak diselesaikan sebagai nama penyimpanan data default ruang kerja.

Datastore default alur dapat dikontrol menggunakan pipeline_job.settings.default_datastore.
Bekerja untuk semua pekerjaan.

Pekerjaan alur memiliki datastore default alur yang dapat dikonfigurasi.
${{name}} Nama pekerjaan. Untuk alur, ini adalah nama pekerjaan langkah, bukan nama pekerjaan alur. Bekerja untuk semua pekerjaan
${{output_name}} Nama output pekerjaan Bekerja untuk semua pekerjaan

Misalnya, jika azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} digunakan sebagai jalur output, pada runtime diselesaikan sebagai jalur .azureml://datastores/workspaceblobstore/paths/<job-name>/model_path

Langkah berikutnya