Udostępnij za pośrednictwem

Podstawowa składnia YAML interfejsu wiersza polecenia (wersja 2)

  • Artykuł

DOTYCZY: Rozszerzenie interfejsu wiersza polecenia platformy Azure ml w wersji 2 (bieżąca)

Każda jednostka usługi Azure Machine Learning ma schematyzowaną reprezentację YAML. Nową jednostkę można utworzyć na podstawie pliku konfiguracji YAML z .yml rozszerzeniem lub .yaml .

Ten artykuł zawiera omówienie podstawowych pojęć dotyczących składni, które można napotkać podczas konfigurowania tych plików YAML.

Odwoływanie się do jednostki usługi Azure Machine Learning

Usługa Azure Machine Learning udostępnia składnię referencyjną (składającą się z skróconego i długiego formatu) do odwoływania się do istniejącej jednostki usługi Azure Machine Learning podczas konfigurowania pliku YAML. Możesz na przykład odwołać się do istniejącego zarejestrowanego środowiska w obszarze roboczym, aby użyć go jako środowiska dla zadania.

Odwoływanie się do zasobu usługi Azure Machine Learning

Istnieją dwie opcje odwoływania się do zasobu usługi Azure Machine Learning (środowisk, modeli, danych i składników):

  • Odwoływanie się do jawnej wersji elementu zawartości:

    • Składnia skrócona: azureml:<asset_name>:<asset_version>
    • Składnia longhand obejmująca identyfikator zasobu usługi Azure Resource Manager (ARM) zasobu:
    azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/environments/<environment-name>/versions/<environment-version>

  • Odwołuj się do najnowszej wersji elementu zawartości:

    W niektórych scenariuszach możesz odwołać się do najnowszej wersji elementu zawartości bez konieczności jawnego wyszukiwania i określania rzeczywistego ciągu wersji. Najnowsza wersja jest definiowana jako najnowsza (nazywana ostatnio) utworzoną wersją elementu zawartości pod daną nazwą.

    Możesz odwołać się do najnowszej wersji przy użyciu następującej składni: azureml:<asset_name>@latest. Usługa Azure Machine Learning rozpozna odwołanie do jawnej wersji zasobu w obszarze roboczym.

Odwołanie do zasobu usługi Azure Machine Learning

Aby odwołać się do zasobu usługi Azure Machine Learning (takiego jak obliczenia), możesz użyć jednej z następujących składni:

  • Składnia skrócona: azureml:<resource_name>
  • Składnia longhand, która zawiera identyfikator zasobu ARM zasobu:
azureml:/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>/computes/<compute-name>

Identyfikator URI odwołania do danych usługi Azure Machine Learning

Usługa Azure Machine Learning oferuje wygodny format identyfikatora URI odwołania do danych w celu wskazywania danych w usłudze Azure Storage. Może to być używane w scenariuszach, w których należy określić lokalizację magazynu w chmurze w pliku YAML, taką jak tworzenie modelu usługi Azure Machine Learning z plików w magazynie lub wskazywanie danych do przekazania jako danych wejściowych do zadania.

Aby użyć tego formatu identyfikatora URI danych, należy najpierw zarejestrować usługę magazynu jako magazyn danych w obszarze roboczym. Usługa Azure Machine Learning będzie obsługiwać dostęp do danych przy użyciu poświadczeń podanych podczas tworzenia magazynu danych.

Format składa się z magazynu danych w bieżącym obszarze roboczym i ścieżki w magazynie danych do pliku lub folderu, do którego chcesz wskazać:

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

Na przykład:

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

Oprócz identyfikatora URI odwołania do danych usługi Azure Machine Learning usługa Azure Machine Learning obsługuje również następujące protokoły identyfikatorów URI magazynu bezpośredniego: https, , wasbsabfssi adl, a także publiczne i https identyfikatory http URI.

Składnia wyrażeń do konfigurowania zadań i składników usługi Azure Machine Learning

Pliki YAML zadań i składników w wersji 2 umożliwiają używanie wyrażeń do powiązania z kontekstami w różnych scenariuszach. Podstawowy przypadek użycia używa wyrażenia dla wartości, która może nie być znana w momencie tworzenia konfiguracji, ale musi zostać rozpoznana w czasie wykonywania.

Użyj następującej składni, aby poinformować usługę Azure Machine Learning o ocenie wyrażenia, a nie traktować go jako ciągu:

${{ <expression> }}

Obsługiwane scenariusze zostały omówione poniżej.

Parametryzacja parametrów command z inputs kontekstami i outputs zadania

Możesz określić wartości literału, ścieżki identyfikatora URI i zarejestrowane zasoby danych usługi Azure Machine Learning jako dane wejściowe zadania. Następnie command można je sparametryzować przy użyciu odwołań do tych danych wejściowych przy użyciu ${{inputs.<input_name>}} składni . Odwołania do danych wejściowych literału zostaną rozpoznane jako wartość literału w czasie wykonywania, podczas gdy odwołania do danych wejściowych danych zostaną rozpoznane jako ścieżka pobierania lub ścieżka instalacji (w zależności od mode określonej).

Podobnie dane wyjściowe zadania mogą być również przywołyne w elemencie command. Dla każdego nazwanego danych wyjściowych określonych w słowniku outputs usługa Azure Machine Learning wygeneruje systemową lokalizację wyjściową w domyślnym magazynie danych, w którym można zapisywać pliki. Lokalizacja wyjściowa dla każdego nazwanego danych wyjściowych jest oparta na następującej ścieżce templatized: <default-datastore>/azureml/<job-name>/<output_name>/. Parametryzacja parametru command za ${{outputs.<output_name>}} pomocą składni spowoduje rozwiązanie tego odwołania do ścieżki wygenerowanej przez system, aby skrypt mógł zapisywać pliki w tej lokalizacji z zadania.

W poniższym przykładzie pliku YAML command zadania polecenia parametr jest sparametryzowany z dwoma danymi wejściowymi, danymi wejściowymi literału i danymi wejściowymi oraz jednym wyjściem. W czasie wykonywania ${{inputs.learning_rate}} wyrażenie będzie rozpoznawane jako 0.01, a ${{inputs.iris}} wyrażenie zostanie rozpoznane jako ścieżka pobierania iris.csv pliku. ${{outputs.model_dir}} program rozpozna ścieżkę instalacji lokalizacji wyjściowej wygenerowanej przez system odpowiadającej danym wyjściowym 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:

Parametryzacja command elementu z search_space kontekstem zadania zamiatania

Ta składnia wyrażeń będzie również używana podczas wykonywania dostrajania hiperparametrów za pośrednictwem zadania zamiatania, ponieważ rzeczywiste wartości hiperparametrów nie są znane w czasie tworzenia zadania. Po uruchomieniu zadania zamiatania usługa Azure Machine Learning wybierze wartości hiperparametrów dla każdej wersji próbnej na podstawie elementu search_space. Aby uzyskać dostęp do tych wartości w skry skrycie szkoleniowym, należy przekazać je za pośrednictwem argumentów wiersza polecenia skryptu. W tym celu użyj ${{search_space.<hyperparameter>}} składni w pliku trial.command.

W poniższym przykładzie dla pliku ${{search_space.learning_rate}} YAML zadania zamiatania odwołania trial.command i ${{search_space.boosting}} zostaną rozpoznane do rzeczywistych wartości hiperparametrów wybranych dla każdej wersji próbnej, gdy zadanie wersji próbnej zostanie przesłane do wykonania.

$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

Wiązanie danych wejściowych i wyjściowych między krokami w zadaniu potoku

Wyrażenia są również używane do tworzenia powiązań danych wejściowych i wyjściowych między krokami w zadaniu potoku. Można na przykład powiązać dane wejściowe jednego zadania (zadania B) w potoku z danymi wyjściowymi innego zadania (zadanie A). To użycie sygnalizuje usłudze Azure Machine Learning przepływ zależności grafu potoku, a zadanie B zostanie wykonane po zadaniu A, ponieważ dane wyjściowe zadania A są wymagane jako dane wejściowe zadania B.

W przypadku pliku inputs YAML zadania potoku sekcje i outputs każdego zadania podrzędnego są oceniane w kontekście nadrzędnym (zadanie potoku najwyższego poziomu). Z drugiej strony element command, zostanie rozpoznany jako bieżący kontekst (zadanie podrzędne).

Istnieją dwa sposoby powiązania danych wejściowych i wyjściowych w zadaniu potoku:

Powiązywanie z danymi wejściowymi i wyjściowymi najwyższego poziomu zadania potoku

Dane wejściowe lub wyjściowe zadania podrzędnego (krok potoku) można powiązać z danymi wejściowymi/wyjściowymi zadania nadrzędnego najwyższego poziomu przy użyciu następującej składni: ${{parent.inputs.<input_name>}} lub ${{parent.outputs.<output_name>}}. Ta dokumentacja jest rozpoznawana jako parent kontekst, dlatego dane wejściowe/wyjściowe najwyższego poziomu.

W poniższym przykładzie dane wejściowe (raw_data) pierwszego prep kroku są powiązane z danymi wejściowymi potoku najwyższego poziomu za pośrednictwem metody ${{parent.inputs.input_data}}. Dane wyjściowe (model_dir) ostatniego train kroku są powiązane z danymi wyjściowymi zadania potoku najwyższego poziomu za pośrednictwem polecenia ${{parent.outputs.trained_model}}.

Powiązywanie z danymi wejściowymi i wyjściowymi innego zadania podrzędnego (krok)

Aby powiązać dane wejściowe/wyjściowe jednego kroku z danymi wejściowymi/wyjściowymi innego kroku, użyj następującej składni: ${{parent.jobs.<step_name>.inputs.<input_name>}} lub ${{parent.jobs.<step_name>.outputs.<outputs_name>}}. Ponownie to odwołanie jest rozpoznawane jako kontekst nadrzędny, więc wyrażenie musi zaczynać się od parent.jobs.<step_name>.

W poniższym przykładzie dane wejściowe (training_data) train kroku są powiązane z danymi wyjściowymi (clean_data) prep kroku za pośrednictwem metody ${{parent.jobs.prep.outputs.clean_data}}. Przygotowane dane z prep kroku będą używane jako dane treningowe train dla tego kroku.

Z drugiej strony odwołania kontekstowe we command właściwościach zostaną rozpoznane w bieżącym kontekście. Na przykład ${{inputs.raw_data}} odwołanie w prep kroku command zostanie rozpoznane jako dane wejściowe bieżącego kontekstu, czyli zadanie podrzędne prep . Wyszukiwanie zostanie wykonane w pliku prep.inputs, więc należy tam zdefiniować dane wejściowe o nazwie 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

Parametryzacja elementu command z inputs kontekstami i outputs składnika

Podobnie jak command w przypadku zadania, command element dla składnika może być również sparametryzowany przy użyciu odwołań do inputs kontekstów i outputs . W takim przypadku odwołanie dotyczy danych wejściowych i wyjściowych składnika. Po uruchomieniu składnika w zadaniu usługa Azure Machine Learning rozpozna te odwołania do wartości wejściowych i wyjściowych środowiska uruchomieniowego zadania określonych dla odpowiednich danych wejściowych i wyjściowych składnika. Poniżej przedstawiono przykład użycia składni kontekstu dla specyfikacji YAML składnika polecenia.

$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
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.5/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}}

Definiowanie opcjonalnych danych wejściowych w wierszu polecenia

Gdy dane wejściowe są ustawione jako optional = true, należy użyć $[[]] polecenia , aby objąć wiersz polecenia danymi wejściowymi. Na przykład: $[[--input1 ${{inputs.input1}}]. Wiersz polecenia w czasie wykonywania może mieć różne dane wejściowe.

  • Jeśli używasz tylko wymaganych training_data parametrów i model_output , wiersz polecenia będzie wyglądać następująco:
python train.py --training_data some_input_path --learning_rate 0.01 --learning_rate_schedule time-based --model_output some_output_path

Jeśli w czasie wykonywania nie określono żadnej wartości, learning_rate użyje learning_rate_schedule wartości domyślnej.

  • Jeśli wszystkie dane wejściowe/wyjściowe udostępniają wartości w czasie wykonywania, wiersz polecenia będzie wyglądać następująco:
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

Wyrażenia ścieżki wyjściowej

Następujące wyrażenia mogą być używane w ścieżce wyjściowej zadania:

Ważne

Następujące wyrażenia są rozpoznawane po stronie serwera , a nie po stronie klienta . W przypadku zaplanowanych zadań, w których czas tworzenia zadania i czas przesyłania zadania są różne, wyrażenia są rozwiązywane po przesłaniu zadania. Ponieważ te wyrażenia są rozpoznawane po stronie serwera, używają bieżącego stanu obszaru roboczego, a nie stanu obszaru roboczego podczas tworzenia zaplanowanego zadania. Jeśli na przykład zmienisz domyślny magazyn danych obszaru roboczego po utworzeniu zaplanowanego zadania, wyrażenie ${{default_datastore}} zostanie rozpoznane w nowym domyślnym magazynie danych, a nie domyślnym magazynie danych podczas tworzenia zaplanowanego zadania.

Expression opis Scope
${{default_datastore}} Jeśli domyślny magazyn danych potoku jest skonfigurowany, zostanie rozpoznany jako domyślna nazwa magazynu danych potoku; w przeciwnym razie jest rozpoznawana jako domyślna nazwa magazynu danych obszaru roboczego.

Domyślny magazyn danych potoku można kontrolować za pomocą polecenia pipeline_job.settings.default_datastore.		 Działa dla wszystkich zadań.

Zadania potoku mają konfigurowalny domyślny magazyn danych potoku.
${{name}} Nazwa zadania. W przypadku potoków jest to nazwa zadania kroku, a nie nazwa zadania potoku. Działa dla wszystkich zadań
${{output_name}} Nazwa danych wyjściowych zadania Działa dla wszystkich zadań

Jeśli na przykład azureml://datastores/${{default_datastore}}/paths/${{name}}/${{output_name}} jest używana jako ścieżka wyjściowa, w czasie wykonywania jest rozpoznawana jako ścieżka azureml://datastores/workspaceblobstore/paths/<job-name>/model_path.

Następne kroki