Trainieren von Modellen mit der CLI, dem SDK und der REST-API von Azure Machine Learning

Installieren Sie zur Verwendung der SDK-Informationen das Azure Machine Learning SDK v2 für Python.

Um die CLI-Informationen zu verwenden, installieren Sie die Azure CLI und die Erweiterung für maschinelles Lernen.

Um die REST-API-Informationen zu verwenden, benötigen Sie die folgenden Elemente:

• Einen Dienstprinzipal in Ihrem Arbeitsbereich. Für administrative REST-Anforderungen wird die Dienstprinzipalauthentifizierung verwendet.

• Ein Token für die Dienstprinzipalauthentifizierung. Führen Sie die Schritte unter Abrufen eines Tokens für die Dienstprinzipalauthentifizierung aus, um dieses Token abzurufen.

• Das curl-Hilfsprogramm. Das curl-Programm ist im Windows-Subsystem für Linux oder jeder beliebigen UNIX-Distribution verfügbar.

  Tipp

  In PowerShell ist curl ein Alias für Invoke-WebRequest, und curl -d "key=val" -X POST uri wird zu Invoke-WebRequest -Body "key=val" -Method POST -Uri uri.

  Die REST-API kann zwar über PowerShell aufgerufen werden, in diesem Artikel wird aber davon ausgegangen, dass Sie Bash verwenden.

• Das Hilfsprogramm jq für die Verarbeitung von JSON. Dieses Hilfsprogramm wird verwendet, um Werte aus den JSON-Dokumenten zu extrahieren, die von REST-API-Aufrufen zurückgegeben werden.

Um eine Verbindung mit dem Arbeitsbereich herzustellen, benötigen Sie Bezeichnerparameter – ein Abonnement, eine Ressourcengruppe und einen Arbeitsbereichsnamen. Sie verwenden diese Details im ML-Client (MLClient) aus dem Namespace azure.ai.ml, um ein Handle für den erforderlichen Azure Machine Learning-Arbeitsbereich zu erhalten. Zum Authentifizieren verwenden Sie die Standardauthentifizierung von Azure. Weitere Informationen zum Konfigurieren von Anmeldeinformationen und Herstellen einer Verbindung mit einem Arbeitsbereich finden Sie in diesem Beispiel.

#import required libraries
from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredential

#Enter details of your Azure Machine Learning workspace
subscription_id = '<SUBSCRIPTION_ID>'
resource_group = '<RESOURCE_GROUP>'
workspace = '<AZUREML_WORKSPACE_NAME>'

#connect to the workspace
ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)

Bei Verwendung der Azure CLI benötigen Sie Bezeichnerparameter – ein Abonnement, eine Ressourcengruppe und einen Arbeitsbereichsnamen. Sie können diese Parameter für jeden Befehl angeben, können aber auch Standardeinstellungen festlegen, die für alle Befehle verwendet werden. Verwenden Sie die folgenden Befehle, um Standardwerte festzulegen. Ersetzen Sie <subscription ID>, <Azure Machine Learning workspace name> und <resource group> durch die Werte für Ihre Konfiguration:

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

In den REST-API-Beispielen in diesem Artikel werden die Platzhalter $SUBSCRIPTION_ID, $RESOURCE_GROUP, $LOCATION und $WORKSPACE verwendet. Ersetzen Sie die Platzhalter wie folgt durch Ihre eigenen Werte:

• $SUBSCRIPTION_ID: Die ID Ihres Azure-Abonnements.
• $RESOURCE_GROUP: Die Azure-Ressourcengruppe mit Ihrem Arbeitsbereich
• $LOCATION: Die Azure-Region, in der sich Ihr Arbeitsbereich befindet
• $WORKSPACE: Der Name Ihres Azure Machine Learning-Arbeitsbereichs
• $COMPUTE_NAME: Der Name Ihres Azure Machine Learning-Computeclusters

Für administrative REST-Anforderungen wird ein Token für die Dienstprinzipalauthentifizierung angefordert. Sie können ein Token mit dem folgenden Befehl abrufen. Das Token wird in der Umgebungsvariable $TOKEN gespeichert:

TOKEN=$(az account get-access-token --query accessToken -o tsv)

Der Dienstanbieter verwendet das api-version-Argument, um Kompatibilität zu gewährleisten. Das api-version-Argument variiert von Dienst zu Dienst. Legen Sie die API-Version zur Vorbereitung für zukünftige Versionen als Variable fest:

API_VERSION="2022-05-01"

Wenn Sie mithilfe der REST-API trainieren, müssen Daten und Trainingsskripts in ein Speicherkonto hochgeladen werden, auf das der Arbeitsbereich zugreifen kann. Im folgenden Beispiel werden die Speicherinformationen für Ihren Arbeitsbereich abgerufen und in Variablen gespeichert, damit wir sie später verwenden können:

# Get values for storage account
response=$(curl --location --request GET "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/datastores?api-version=$API_VERSION&isDefault=true" \
--header "Authorization: Bearer $TOKEN")
AZUREML_DEFAULT_DATASTORE=$(echo $response | jq -r '.value[0].name')
AZUREML_DEFAULT_CONTAINER=$(echo $response | jq -r '.value[0].properties.containerName')
export AZURE_STORAGE_ACCOUNT=$(echo $response | jq -r '.value[0].properties.accountName')

from azure.ai.ml.entities import AmlCompute

# specify aml compute name.
cpu_compute_target = "cpu-cluster"

try:
    ml_client.compute.get(cpu_compute_target)
except Exception:
    print("Creating a new cpu compute target...")
    compute = AmlCompute(
        name=cpu_compute_target, size="STANDARD_D2_V2", min_instances=0, max_instances=4
    )
    ml_client.compute.begin_create_or_update(compute).result()

az ml compute create -n cpu-cluster --type amlcompute --min-instances 0 --max-instances 4

curl -X PUT \
  "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/computes/$COMPUTE_NAME?api-version=$API_VERSION" \
  -H "Authorization:Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location": "'$LOCATION'",
    "properties": {
        "computeType": "AmlCompute",
        "properties": {
            "vmSize": "Standard_D2_V2",
            "vmPriority": "Dedicated",
            "scaleSettings": {
                "maxNodeCount": 4,
                "minNodeCount": 0,
                "nodeIdleTimeBeforeScaleDown": "PT30M"
            }
        }
    }
}'

Um dieses Skript auszuführen, verwenden Sie einen command, welcher das Python-Skript „main.py“ ausführt, das sich unter ./sdk/python/jobs/single-step/lightgbm/iris/src/ befindet. Der Befehl wird ausgeführt, indem er als job an Azure Machine Learning übermittelt wird.

from azure.ai.ml import command, Input

# define the command
command_job = command(
    code="./src",
    command="python main.py --iris-csv ${{inputs.iris_csv}} --learning-rate ${{inputs.learning_rate}} --boosting ${{inputs.boosting}}",
    environment="AzureML-lightgbm-3.2-ubuntu18.04-py37-cpu@latest",
    inputs={
        "iris_csv": Input(
            type="uri_file",
            path="https://azuremlexamples.blob.core.windows.net/datasets/iris.csv",
        ),
        "learning_rate": 0.9,
        "boosting": "gbdt",
    },
    compute="cpu-cluster",
)

# submit the command
returned_job = ml_client.jobs.create_or_update(command_job)
# get a URL for the status of the job
returned_job.studio_url

In den obigen Beispielen haben Sie Folgendes konfiguriert:

• code: Der Pfad, in dem sich der Code zur Ausführung des Befehls befindet.
• command: Der auszuführende Befehl.
• environment: Die Umgebung, die für die Ausführung des Trainingsskripts erforderlich ist. In diesem Beispiel verwenden wir eine von Azure Machine Learning bereitgestellte kuratierte bzw. vorgefertigte Umgebung mit der Bezeichnung AzureML-lightgbm-3.2-ubuntu18.04-py37-cpu. Wir verwenden die neueste Version dieser Umgebung mithilfe der @latest-Anweisung. Sie können auch benutzerdefinierte Umgebungen verwenden, indem Sie ein Docker-Basisimage und zusätzlich Conda-YAML-Code angeben.
• inputs: Ein Wörterbuch der Eingaben mit Schlüssel-Wert-Paaren für den Befehl. Der Schlüssel ist ein Name für die Eingabe im Kontext des Auftrags, und der Wert ist der Eingabewert. Auf Eingaben wird im command mit dem Ausdruck ${{inputs.<input_name>}} verwiesen. Wenn Sie Dateien oder Ordner als Eingaben verwenden möchten, können Sie die Klasse Input verwenden. Weitere Informationen finden Sie unter SDK und CLI v2-Ausdrücke.

Weitere Informationen finden Sie in der Referenzdokumentation.

Wenn Sie den Auftrag übermitteln, wird eine URL an den Auftragsstatus in Azure Machine Learning Studio zurückgegeben. Verwenden Sie die Studio-Benutzeroberfläche, um den Auftragsfortschritt anzuzeigen. Sie können auch returned_job.status verwenden, um den aktuellen Status des Auftrags zu überprüfen.

Der in diesem Beispiel verwendete Befehl az ml job create erfordert eine YAML-Auftragsdefinitionsdatei. Der Inhalt der in diesem Beispiel verwendeten Datei lautet wie folgt:

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json
code: src
command: >-
  python main.py
  --iris-csv ${{inputs.iris_csv}}
inputs:
  iris_csv:
    type: uri_file
    path: https://azuremlexamples.blob.core.windows.net/datasets/iris.csv
environment: azureml:AzureML-lightgbm-3.3@latest
compute: azureml:cpu-cluster
display_name: lightgbm-iris-example
experiment_name: lightgbm-iris-example
description: Train a LightGBM model on the Iris dataset.

Im obigen Code haben Sie Folgendes konfiguriert:

• code: Der Pfad, in dem sich der Code zur Ausführung des Befehls befindet.
• command: Der auszuführende Befehl.
• inputs: Ein Wörterbuch der Eingaben mit Schlüssel-Wert-Paaren für den Befehl. Der Schlüssel ist ein Name für die Eingabe im Kontext des Auftrags, und der Wert ist der Eingabewert. Auf Eingaben wird im command mit dem Ausdruck ${{inputs.<input_name>}} verwiesen. Weitere Informationen finden Sie unter SDK und CLI v2-Ausdrücke.
• environment: Die Umgebung, die für die Ausführung des Trainingsskripts erforderlich ist. In diesem Beispiel verwenden wir eine von Azure Machine Learning bereitgestellte kuratierte bzw. vorgefertigte Umgebung mit der Bezeichnung AzureML-lightgbm-3.3. Wir verwenden die neueste Version dieser Umgebung mithilfe der @latest-Anweisung. Sie können auch benutzerdefinierte Umgebungen verwenden, indem Sie ein Docker-Basisimage und zusätzlich Conda-YAML-Code angeben. Verwenden Sie den folgenden Befehl zum Übermitteln des Auftrags. Die Ausführungs-ID (Name) des Trainingsauftrags wird in der Variablen $run_id gespeichert:

run_id=$(az ml job create -f jobs/single-step/lightgbm/iris/job.yml --query name -o tsv)

Sie können die gespeicherte Ausführungs-ID verwenden, um Informationen zum Auftrag zurückzugeben. Der Parameter --web öffnet die Azure Machine Learning Studio-Webbenutzeroberfläche, auf der Sie Details zum Auftrag anzeigen können:

az ml job show -n $run_id --web

Im Rahmen der Auftragsübermittlung müssen die Trainingsskripts und -daten in einen Cloudspeicherort hochgeladen werden, auf den Ihr Azure Machine Learning-Arbeitsbereich zugreifen kann.

1. Verwenden Sie den folgenden Azure CLI-Befehl, um das Trainingsskript hochzuladen. Der Befehl gibt das Verzeichnis an, das die für das Training erforderlichen Dateien enthält, nicht eine einzelne Datei. Wenn Sie stattdessen REST zum Hochladen der Daten verwenden möchten, sehen Sie sich die Referenz Put Blob an:

   az storage blob upload-batch -d $AZUREML_DEFAULT_CONTAINER/testjob -s cli/jobs/single-step/lightgbm/iris/src/ --account-name $AZURE_STORAGE_ACCOUNT
   

2. Erstellen Sie einen Verweis mit Versionsangabe für die Trainingsdaten. In diesem Beispiel befinden sich die Daten bereits in der Cloud und unter https://azuremlexamples.blob.core.windows.net/datasets/iris.csv. Weitere Informationen zum Verweisen auf Daten finden Sie unter Daten in Azure Machine Learning:

   DATA_VERSION=$RANDOM
   curl --location --request PUT "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/data/iris-data/versions/$DATA_VERSION?api-version=$API_VERSION" \
   --header "Authorization: Bearer $TOKEN" \
   --header "Content-Type: application/json" \
   --data-raw "{
           \"properties\": {
           \"description\": \"Iris dataset\",
           \"dataType\": \"uri_file\",
           \"dataUri\": \"https://azuremlexamples.blob.core.windows.net/datasets/iris.csv\"
       }
   }"
   

3. Registrieren Sie einen Verweis mit Versionsangabe für das Trainingsskript zur Verwendung mit einem Auftrag. In diesem Beispiel ist der Skriptspeicherort das Standardspeicherkonto und der Standardcontainer, in den Sie in Schritt 1 hochgeladen haben. Die ID des Trainingscodes mit Versionsangabe wird zurückgegeben und in der Variablen $TRAIN_CODE gespeichert:

   TRAIN_CODE=$(curl --location --request PUT "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/codes/train-lightgbm/versions/1?api-version=$API_VERSION" \
   --header "Authorization: Bearer $TOKEN" \
   --header "Content-Type: application/json" \
   --data-raw "{
           \"properties\": {
           \"description\": \"Train code\",
           \"codeUri\": \"https://$AZURE_STORAGE_ACCOUNT.blob.core.windows.net/$AZUREML_DEFAULT_CONTAINER/testjob\"
       }
   }" | jq -r '.id')
   

4. Erstellen Sie die Umgebung, die der Cluster zum Ausführen des Trainingsskripts verwendet. In diesem Beispiel verwenden wir eine von Azure Machine Learning bereitgestellte kuratierte bzw. vorgefertigte Umgebung mit der Bezeichnung AzureML-lightgbm-3.2-ubuntu18.04-py37-cpu. Der folgende Befehl ruft eine Liste der Umgebungsversionen ab, wobei die neueste am Anfang der Auflistung steht. jq wird zum Abrufen der ID der aktuellen Version ([0]) verwendet, die dann in der Variablen $ENVIRONMENT gespeichert wird.

   ENVIRONMENT=$(curl --location --request GET "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/environments/AzureML-lightgbm-3.2-ubuntu18.04-py37-cpu?api-version=$API_VERSION" --header "Authorization: Bearer $TOKEN" | jq -r .id)
   

5. Übermitteln Sie schließlich den Auftrag. Das folgende Beispiel zeigt, wie Sie den Auftrag übermitteln und auf die Trainingscode-ID, die Umgebungs-ID, die URL für die Eingabedaten und die ID des Computeclusters verweisen. Der Speicherort der Auftragsausgabe wird in der Variablen $JOB_OUTPUT gespeichert:

   Tipp

   Der Auftragsname muss eindeutig sein. In diesem Beispiel wird uuidgen verwendet, um einen eindeutigen Wert für den Namen zu generieren.

   Hinweis

   Wenn Sie serverloses Computing verwenden möchten, löschen Sie die Zeile \"computeId\": in diesem Code.

   run_id=$(uuidgen)
   curl --location --request PUT "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/jobs/$run_id?api-version=$API_VERSION" \
   --header "Authorization: Bearer $TOKEN" \
   --header "Content-Type: application/json" \
   --data-raw "{
       \"properties\": {
           \"jobType\": \"Command\",
           \"codeId\": \"$TRAIN_CODE\",
           \"command\": \"python main.py --iris-csv \$AZURE_ML_INPUT_iris\",
           \"environmentId\": \"$ENVIRONMENT\",
           \"inputs\": {
               \"iris\": {
                   \"jobInputType\": \"uri_file\",
                   \"uri\": \"https://azuremlexamples.blob.core.windows.net/datasets/iris.csv\"
               }
           },
           \"experimentName\": \"lightgbm-iris\",
           \"computeId\": \"/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/computes/$COMPUTE_NAME\"
       }
   }"
   

from azure.ai.ml.entities import Model
from azure.ai.ml.constants import AssetTypes

run_model = Model(
    path="azureml://jobs/{}/outputs/artifacts/paths/model/".format(returned_job.name),
    name="run-model-example",
    description="Model created from run.",
    type=AssetTypes.MLFLOW_MODEL
)

ml_client.models.create_or_update(run_model)

az ml model create -n sklearn-iris-example -v 1 -p runs:/$run_id/model --type mlflow_model

curl --location --request PUT "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/models/sklearn/versions/1?api-version=$API_VERSION" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" \
--data-raw "{
    \"properties\": {
        \"modelType\": \"mlflow_model\",
        \"modelUri\":\"runs:/$run_id/model\"
    }
}"