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

Um die SDK zu verwenden, installieren Sie die Azure Machine Learning SDK v2 für Python.

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

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

• Ein Dienstprinzipal in Ihrem Arbeitsbereich. Verwenden Sie die Dienstprinzipalauthentifizierung für administrative REST-Anforderungen.

• Ein Service Principal-Authentifizierungstoken. Führen Sie die Schritte unter Abrufen eines Dienstprinzipalauthentifizierungstokens aus, um dieses Token abzurufen.

• Das curl-Tool. Das curl-Programm ist in der Windows-Subsystem für Linux oder einer UNIX-Distribution verfügbar.

  Tipp

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

  Obwohl es möglich ist, die REST-API aus PowerShell aufzurufen, gehen die Beispiele in diesem Artikel davon aus, dass Sie Bash verwenden.

• Das jq-Hilfsprogramm für die Verarbeitung von JSON. Verwenden Sie dieses Hilfsprogramm, um Werte aus den JSON-Dokumenten zu extrahieren, die REST-API-Aufrufe zurückgeben.

Um eine Verbindung mit dem Arbeitsbereich herzustellen, benötigen Sie Bezeichnerparameter – ein Abonnement, eine Ressourcengruppe und einen Arbeitsbereichsnamen. Verwenden Sie diese Details im MLClient aus dem "Namespace" azure.ai.ml, um Zugriff auf den erforderlichen Azure Machine Learning Arbeitsbereich zu erhalten. Verwenden Sie zum Authentifizieren die default-Azure-Authentifizierung. Weitere Informationen zum Konfigurieren von Anmeldeinformationen und herstellen einer Verbindung mit einem Arbeitsbereich finden Sie in diesem example.

#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)

Wenn Sie die Azure CLI verwenden, benötigen Sie Bezeichnerparameter – ein Abonnement, eine Ressourcengruppe und einen Arbeitsbereichsnamen. Sie können diese Parameter zwar für jeden Befehl angeben, sie können aber auch Standardwerte festlegen, die alle Befehle verwenden. 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>

Die REST-API-Beispiele in diesem Artikel verwenden $SUBSCRIPTION_ID, , $RESOURCE_GROUP, $LOCATIONund $WORKSPACE Platzhalter. Ersetzen Sie die Platzhalter wie folgt durch Ihre eigenen Werte:

• $SUBSCRIPTION_ID: Ihre Azure-Abonnement-ID.
• $RESOURCE_GROUP: Die Azure Ressourcengruppe, die Ihren Arbeitsbereich enthält.
• $LOCATION: Die Azure-Region, in der sich Ihr Arbeitsbereich befindet.
• $WORKSPACE: Der Name Ihres Azure Machine Learning Arbeitsbereichs.
• $COMPUTE_NAME: Der Name des Azure Machine Learning Compute-Clusters.

Administrative REST-Anforderungen erfordern ein Dienstprinzipalauthentifizierungstoken. Sie können ein Token mit dem folgenden Befehl abrufen. Das Token wird in der Umgebungsvariablen $TOKEN gespeichert:

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

Der Dienstanbieter verwendet das api-version Argument, um die Kompatibilität sicherzustellen. Das api-version Argument variiert von Dienst zu Dienst.

In diesem Artikel werden Azure Resource Manager Endpunkte (management.azure.com) verwendet. Legen Sie API_VERSION auf die aktuelle Azure Machine Learning Resource Manager-Version fest:

API_VERSION="2025-09-01"

Wenn Sie Azure Machine Learning Datenebenen-APIs verwenden, können sie eine andere Version verwenden. Beispielsweise verwendet der Azure AI Assets-Datenebenenverweis 2024-04-01-preview. Weitere Informationen finden Sie in den REST-Vorgangsgruppen für Azure Machine Learning (Resource Manager) und Azure AI Assets (Data Plane).

Wenn Sie mit der REST-API trainieren, müssen Sie Daten und Schulungsskripts in ein Speicherkonto hochladen, auf das der Arbeitsbereich zugreifen kann. Das folgende Beispiel ruft die Speicherinformationen für Ihren Arbeitsbereich ab und speichert sie in Variablen, damit Sie 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"
            }
        }
    }
}'

Verwenden Sie zum Ausführen dieses Skripts eine command, die das main.py Python Skript ausführt, das sich unter ./sdk/python/jobs/single-step/lightgbm/iris/src/ befindet. Sie übermitteln den Befehl als job an Azure Machine Learning.

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 vorherigen Beispielen haben Sie Folgendes konfiguriert:

• code - Pfad, in dem sich der Code zum Ausführen des Befehls befindet.
• command - Befehl, der ausgeführt werden muss.
• environment – die Umgebung, die zum Ausführen des Schulungsskripts erforderlich ist. Verwenden Sie in diesem Beispiel eine kuratierte oder vorgefertigte Umgebung, die von Azure Machine Learning namens AzureML-lightgbm-3.3@latest bereitgestellt wird. Sie können auch benutzerdefinierte Umgebungen verwenden, indem Sie ein Basis-Docker-Image angeben und darüber ein Conda-Yaml angeben.
• inputs - Wörterbuch der Eingaben mit Name-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. Beziehen Sie sich auf Eingaben in der command mithilfe des ${{inputs.<input_name>}} Ausdrucks. Verwenden Sie die Input Klasse, um Dateien oder Ordner als Eingaben zu verwenden. Weitere Informationen finden Sie unter SDK- und CLI v2-Ausdrücke.

Weitere Informationen finden Sie in der Referenzdokumentation.

Wenn Sie den Auftrag übermitteln, gibt der Dienst eine URL zum Auftragsstatus im Azure Machine Learning Studio zurück. Verwenden Sie die Studio-Benutzeroberfläche, um den Auftragsfortschritt anzuzeigen. Auch können Sie returned_job.status verwenden, um den aktuellen Status des Auftrags zu überprüfen.

Der az ml job create Befehl in diesem Beispiel erfordert eine YAML-Auftragsdefinitionsdatei. Die in diesem Beispiel verwendete Datei enthält den folgenden Inhalt:

$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 vorherigen YAML haben Sie Folgendes konfiguriert:

• code - Pfad, in dem sich der Code zum Ausführen des Befehls befindet.
• command - Befehl, der ausgeführt werden muss.
• inputs - Wörterbuch der Eingaben mithilfe von Namenswertpaaren zum Befehl. Der Schlüssel ist ein Name für die Eingabe im Kontext des Auftrags, und der Wert ist der Eingabewert. Auf Eingaben wird mithilfe command des ${{inputs.<input_name>}} Ausdrucks verwiesen. Weitere Informationen finden Sie unter SDK- und CLI v2-Ausdrücke.
• environment – die Umgebung, die zum Ausführen des Schulungsskripts erforderlich ist. Verwenden Sie in diesem Beispiel eine kuratierte oder vorgefertigte Umgebung, die von Azure Machine Learning namens AzureML-lightgbm-3.3@latest bereitgestellt wird. Sie können auch benutzerdefinierte Umgebungen verwenden, indem Sie ein Basis-Docker-Image angeben und darüber ein Conda-Yaml angeben. Um den Auftrag zu übermitteln, verwenden Sie den folgenden Befehl. Die Run-ID (Name) des Schulungsauftrags wird in der $run_id Variablen gespeichert:

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

Verwenden Sie die gespeicherte Ausführungs-ID, um Informationen zum Auftrag zurückzugeben. Der Parameter --web öffnet die Azure Machine Learning Studio Web-UI, auf der Sie Details zum Auftrag ausführen können:

az ml job show -n $run_id --web

Wenn Sie einen Auftrag übermitteln, müssen Sie die Schulungsskripts und -daten an einen Cloudspeicherort hochladen, auf den Ihr Azure Machine Learning Arbeitsbereich zugreifen kann.

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

   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 versionierten Verweis auf die Schulungsdaten. In diesem Beispiel befinden sich die Daten bereits in der Cloud und befinden sich unter https://azuremlexamples.blob.core.windows.net/datasets/iris.csv. Weitere Informationen zum Verweisen auf Daten finden Sie unter Data 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 eine versionierte Referenz auf das Trainingsskript zur Nutzung mit einem Job. In diesem Beispiel ist der Skriptspeicherort das Standardspeicherkonto und der Container, in den Sie in Schritt 1 hochgeladen haben. Die ID des versionsierten Schulungscodes wird zurückgegeben und in der $TRAIN_CODE Variablen 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 Schulungsskripts verwendet. Verwenden Sie in diesem Beispiel eine kuratierte oder vorgefertigte Umgebung, die von Azure Machine Learning namens AzureML-lightgbm-3.3 bereitgestellt wird.

Azure Resource Manager unterstützt keinen @latest-Kurzbefehl für Umgebungs-IDs. Der folgende Befehl listet die Umgebungsversionen auf und wählt die zuletzt geänderte Versions-ID aus, die dann in der $ENVIRONMENT Variablen gespeichert wird.

ENVIRONMENT_NAME="AzureML-lightgbm-3.3"
ENVIRONMENT=$(curl --location --request GET "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.MachineLearningServices/workspaces/$WORKSPACE/environments/$ENVIRONMENT_NAME/versions?api-version=$API_VERSION" \
    --header "Authorization: Bearer $TOKEN" | jq -r '.value | sort_by(.systemData.lastModifiedAt) | last | .id')

1. Reichen Sie schließlich den Auftrag ein. Das folgende Beispiel zeigt, wie Sie den Auftrag übermitteln, auf die Schulungscode-ID, die Umgebungs-ID, die URL für die Eingabedaten und die ID des Computeclusters verweisen. Der Auftragsausgabespeicherort wird in der $JOB_OUTPUT Variablen gespeichert:

   Tipp

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

   Hinweis

   Um serverlose Berechnung zu verwenden, löschen Sie die \"computeId\": Zeile 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\"
    }
}"