Installieren und Verwenden der CLI (v1)

GILT FÜR: Azure CLI-ML-Erweiterung v1

Der Azure Machine Learning-CLI ist eine Erweiterung der Azure CLI, eine plattformübergreifende Befehlszeilenschnittstelle für die Azure-Plattform. Diese Erweiterung unterstützt Befehle für die Arbeit mit Azure Machine Learning. Sie ermöglicht Ihnen die Automatisierung Ihrer Machine Learning-Aktivitäten. Die folgende Liste enthält einige Beispielaktionen, die Sie mit der CLI-Erweiterung ausführen können:

• Ausführen von Experimenten zum Erstellen von Machine Learning-Modellen

• Registrieren von Machine Learning-Modellen zur Verwendung durch Kunden

• Paketieren, Bereitstellen und Nachverfolgen des Lebenszyklus Ihrer Machine Learning-Modelle

Die CLI ist kein Ersatz für das Azure Machine Learning SDK. Sie stellt ein ergänzendes Tool dar, das für die Verarbeitung hochgradig parametrisierter Aufgaben optimiert ist, die sich gut für die Automatisierung eignen.

Voraussetzungen

• Für die Verwendung der CLI benötigen Sie ein Azure-Abonnement. Wenn Sie nicht über ein Azure-Abonnement verfügen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen. Probieren Sie die kostenlose oder kostenpflichtige Version von Azure Machine Learning noch heute aus.

• Um die CLI-Befehle in diesem Dokument aus Ihrer lokalen Umgebung zu verwenden, benötigen Sie die Azure CLI.

  Wenn Sie die Azure Cloud Shell verwenden, befindet sich die CLI in der Cloud, und der Zugriff erfolgt über den Browser.

Vollständige Referenzdokumentation

Hier finden Sie die vollständige Referenzdokumentation für die Erweiterung „azure-cli-ml“ der Azure CLI.

Herstellen einer Verbindung zwischen der CLI und Ihrem Azure-Abonnement

Ihnen stehen mehrere Möglichkeiten zur Verfügung, sich über die CLI bei Ihrem Azure-Abonnement zu authentifizieren. Die grundlegendste ist die interaktive Authentifizierung mithilfe eines Browsers. Öffnen Sie zur interaktiven Authentifizierung eine Befehlszeile oder ein Terminal, und verwenden Sie den folgenden Befehl:

az login

Die CLI öffnet Ihren Standardbrowser, sofern sie dazu in der Lage ist, und lädt eine Anmeldeseite. Andernfalls müssen Sie einen Browser öffnen und die Anweisungen in der Befehlszeile befolgen. Die Anweisungen umfassen das Navigieren zu https://aka.ms/devicelogin und Eingeben eines Autorisierungscodes.

Andere Methoden zur Authentifizierung finden Sie unter Anmelden mit der Azure CLI.

Installieren der Erweiterung

So installieren Sie die CLI-Erweiterung (v1):

az extension add -n azure-cli-ml

Aktualisieren der Erweiterung

Um die Machine Learning-CLI-Erweiterung zu aktualisieren, verwenden Sie den folgenden Befehl:

az extension update -n azure-cli-ml

Entfernen der Erweiterung

Verwenden Sie zum Entfernen der CLI-Erweiterung den folgenden Befehl:

az extension remove -n azure-cli-ml

Ressourcenverwaltung

Die folgenden Befehle veranschaulichen, wie Sie mit der CLI Ressourcen verwalten, die von Azure Machine Learning verwendet werden.

• Erstellen Sie eine Ressourcengruppe, wenn Sie noch keine haben:

  az group create -n myresourcegroup -l westus2
  

• Erstellen Sie einen Azure Machine Learning-Arbeitsbereich:

  az ml workspace create -w myworkspace -g myresourcegroup
  

  Weitere Informationen finden Sie unter az ml workspace create.

• Fügen Sie eine Arbeitsbereichskonfiguration einem Ordner hinzu, um CLI-Kontextfähigkeit zu aktivieren.

  az ml folder attach -w myworkspace -g myresourcegroup
  

  Dieser Befehl erstellt ein .azureml-Unterverzeichnis, das RUNCONFIG-Beispieldateien und Conda-Umgebungsdateien enthält. Es enthält auch eine config.json-Datei, die für die Kommunikation mit dem Azure Machine Learning-Arbeitsbereich verwendet wird.

  Weitere Informationen finden Sie unter az ml folder attach.

• Fügen Sie einen Azure-Blobcontainer als Datenspeicher an.

  az ml datastore attach-blob  -n datastorename -a accountname -c containername
  

  Weitere Informationen finden Sie unter az ml datastore attach-blob.

• Laden Sie Dateien in einen Datenspeicher hoch.

  az ml datastore upload  -n datastorename -p sourcepath
  

  Weitere Informationen finden Sie unter az ml datastore upload.

• Fügen Sie einen AKS-Cluster als Computeziel an.

  az ml computetarget attach aks -n myaks -i myaksresourceid -g myresourcegroup -w myworkspace
  

  Weitere Informationen finden Sie unter az ml computetarget attach aks.

Computecluster

• Erstellen Sie einen neuen verwalteten Computecluster.

  az ml computetarget create amlcompute -n cpu --min-nodes 1 --max-nodes 1 -s STANDARD_D3_V2
  

• Erstellen eines neuen verwalteten Computeclusters mit einer verwalteten Identität

  • Benutzerseitig zugewiesene verwaltete Identität

    az ml computetarget create amlcompute --name cpu-cluster --vm-size Standard_NC6 --max-nodes 5 --assign-identity '/subscriptions/<subcription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user_assigned_identity>'
    

  • Systemseitig zugewiesene verwaltete Identität

    az ml computetarget create amlcompute --name cpu-cluster --vm-size Standard_NC6 --max-nodes 5 --assign-identity '[system]'
    

• Hinzufügen einer verwalteten Identität zu einem vorhandenen Cluster:

  • Benutzerseitig zugewiesene verwaltete Identität

    az ml computetarget amlcompute identity assign --name cpu-cluster '/subscriptions/<subcription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user_assigned_identity>'
    

  • Systemseitig zugewiesene verwaltete Identität

    az ml computetarget amlcompute identity assign --name cpu-cluster '[system]'
    

Weitere Informationen finden Sie unter az ml computetarget create amlcompute.

Compute-Instanz

Verwalten von Computeinstanzen. In allen untenstehenden Beispielen lautet der Name der Computeinstanz cpu.

• Erstellen Sie eine neue computeinstance-Klasse.

  az ml computetarget create computeinstance -n cpu -s "STANDARD_D3_V2" -v
  

  Weitere Informationen finden Sie unter az ml computetarget create computeinstance.

• Stoppen Sie eine computeinstance-Klasse.

  az ml computetarget computeinstance stop -n cpu -v
  

  Weitere Informationen finden Sie unter az ml computetarget computeinstance stop.

• Starten Sie eine computeinstance-Klasse.

  az ml computetarget computeinstance start -n cpu -v
  

  Weitere Informationen finden Sie unter az ml computetarget computeinstance start.

• Starten Sie eine computeinstance-Klasse neu.

  az ml computetarget computeinstance restart -n cpu -v
  

  Weitere Informationen finden Sie unter az ml computetarget computeinstance restart.

• Löschen Sie eine computeinstance-Klasse.

  az ml computetarget delete -n cpu -v
  

  Weitere Informationen finden Sie unter az ml computetarget delete computeinstance.

Ausführen von Experimenten

• Starten Sie eine Ausführung Ihres Experiments. Geben Sie in diesem Befehl für den Parameter -c den Namen der runconfig-Datei an (dies ist die Zeichenfolge, die in Ihrem Dateisystem vor *.runconfig angezeigt wird).

  az ml run submit-script -c sklearn -e testexperiment train.py
  

  Tipp

  Der Befehl az ml folder attach erstellt ein .azureml-Unterverzeichnis, das zwei RUNCONFIG-Beispieldateien enthält.

  Wenn Sie ein Python-Skript haben, das programmgesteuert ein Laufzeitkonfigurationsobjekt erstellt, können Sie es mit RunConfig.save() als RUNCPNFIG-Datei speichern.

  Das vollständige RUNCONFIG-Schema finden Sie in dieser JSON-Datei. Das Schema ist durch den description-Schlüssel der einzelnen Objekte selbstdokumentierend. Zusätzlich gibt es Enumerationen für mögliche Werte und einen Vorlagencodeausschnitt am Ende.

  Weitere Informationen finden Sie unter az ml run submit-script.

• Zeigen Sie eine Liste der Experimente an:

  az ml experiment list
  

  Weitere Informationen finden Sie unter az ml experiment list.

HyperDrive-Ausführung

Sie können HyperDrive mit der Azure CLI verwenden, um Parameteroptimierungsausführungen auszuführen. Erstellen Sie zunächst eine HyperDrive-Konfigurationsdatei im folgenden Format. Weitere Informationen zu den Hyperparameter-Optimierungsparametern finden Sie im Artikel Optimieren von Hyperparametern für Ihr Modell.

# hdconfig.yml
sampling: 
    type: random # Supported options: Random, Grid, Bayesian
    parameter_space: # specify a name|expression|values tuple for each parameter.
    - name: --penalty # The name of a script parameter to generate values for.
      expression: choice # supported options: choice, randint, uniform, quniform, loguniform, qloguniform, normal, qnormal, lognormal, qlognormal
      values: [0.5, 1, 1.5] # The list of values, the number of values is dependent on the expression specified.
policy: 
    type: BanditPolicy # Supported options: BanditPolicy, MedianStoppingPolicy, TruncationSelectionPolicy, NoTerminationPolicy
    evaluation_interval: 1 # Policy properties are policy specific. See the above link for policy specific parameter details.
    slack_factor: 0.2
primary_metric_name: Accuracy # The metric used when evaluating the policy
primary_metric_goal: Maximize # Maximize|Minimize
max_total_runs: 8 # The maximum number of runs to generate
max_concurrent_runs: 2 # The number of runs that can run concurrently.
max_duration_minutes: 100 # The maximum length of time to run the experiment before cancelling.

Fügen Sie diese Datei den Laufzeitkonfigurationsdateien hinzu. Übermitteln Sie dann eine HyperDrive-Ausführung:

az ml run submit-hyperdrive -e <experiment> -c <runconfig> --hyperdrive-configuration-name <hdconfig> my_train.py

Beachten Sie den Abschnitt arguments in der Laufzeitkonfiguration and parameter space in der HyperDrive-Konfiguration. Diese Abschnitte enthalten die Befehlszeilenargumente, die an das Trainingsskript übergeben werden sollen. Der Wert in der Laufzeitkonfiguration bleibt für jede Iteration gleich, während der Bereich in der HyperDrive-Konfiguration iteriert wird. Geben Sie nicht das gleiche Argument in beiden Dateien an.

Datasetverwaltung

Die folgenden Befehle veranschaulichen die Arbeit mit Datasets in Azure Machine Learning:

• Registrieren eines Datasets:

  az ml dataset register -f mydataset.json
  

  Informationen zum Format der JSON-Datei, mit der das Dataset definiert wird, finden Sie unter az ml dataset register --show-template.

  Weitere Informationen finden Sie unter az ml dataset register.

• Auflisten aller Datasets in einem Arbeitsbereich:

  az ml dataset list
  

  Weitere Informationen finden Sie unter az ml dataset list.

• Abrufen der Details zu einem Dataset:

  az ml dataset show -n dataset-name
  

  Weitere Informationen finden Sie unter az ml dataset show.

• Aufheben der Registrierung eines Datasets:

  az ml dataset unregister -n dataset-name
  

  Weitere Informationen finden Sie unter az ml dataset unregister.

Umgebungsverwaltung

Anhand der folgenden Befehle wird veranschaulicht, wie Sie Azure Machine Learning-Umgebungen für Ihren Arbeitsbereich erstellen, registrieren und auflisten:

• Erstellen Sie die Gerüstdateien für eine Umgebung:

  az ml environment scaffold -n myenv -d myenvdirectory
  

  Weitere Informationen finden Sie unter az ml environment scaffold.

• Registrieren Sie eine Umgebung:

  az ml environment register -d myenvdirectory
  

  Weitere Informationen finden Sie unter az ml environment register.

• Listen Sie die registrierten Umgebungen auf:

  az ml environment list
  

  Weitere Informationen finden Sie unter az ml environment list.

• Laden Sie eine registrierte Umgebung herunter:

  az ml environment download -n myenv -d downloaddirectory
  

  Weitere Informationen finden Sie unter az ml environment download.

Umgebungskonfigurationsschema

Wenn Sie den Befehl az ml environment scaffold verwendet haben, wird eine azureml_environment.json-Vorlagendatei generiert, die geändert und zum Erstellen von benutzerdefinierten Umgebungskonfigurationen mit der Befehlszeilenschnittstelle verwendet werden kann. Das Objekt der obersten Ebene wird lose der Environment-Klasse im Python-SDK zugeordnet.

{
    "name": "testenv",
    "version": null,
    "environmentVariables": {
        "EXAMPLE_ENV_VAR": "EXAMPLE_VALUE"
    },
    "python": {
        "userManagedDependencies": false,
        "interpreterPath": "python",
        "condaDependenciesFile": null,
        "baseCondaEnvironment": null
    },
    "docker": {
        "enabled": false,
        "baseImage": "mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:20210615.v1",
        "baseDockerfile": null,
        "sharedVolumes": true,
        "shmSize": "2g",
        "arguments": [],
        "baseImageRegistry": {
            "address": null,
            "username": null,
            "password": null
        }
    },
    "spark": {
        "repositories": [],
        "packages": [],
        "precachePackages": true
    },
    "databricks": {
        "mavenLibraries": [],
        "pypiLibraries": [],
        "rcranLibraries": [],
        "jarLibraries": [],
        "eggLibraries": []
    },
    "inferencingStackVersion": null
}

In der folgenden Tabelle ist jedes Feld der obersten Ebene in der JSON-Datei, sein Typ und eine Beschreibung aufgeführt. Wenn ein Objekttyp mit einer Klasse aus dem Python-SDK verknüpft ist, gibt es eine lose 1:1-Übereinstimmung zwischen den einzelnen JSON-Feldern und dem öffentlichen Variablennamen in der Python-Klasse. In einigen Fällen wird das Feld möglicherweise eher einem Konstruktorargument als einer Klassenvariablen zugeordnet. Das Feld environmentVariables wird z. B. der Variablen environment_variables in der Environment-Klasse zugeordnet.

Verwaltung von ML-Pipelines

Die folgenden Befehle veranschaulichen, wie mit Machine Learning-Pipelines gearbeitet wird.

• Erstellen Sie eine Machine Learning-Pipeline:

  az ml pipeline create -n mypipeline -y mypipeline.yml
  

  Weitere Informationen finden Sie unter az ml pipeline create.

  Weitere Informationen zur Pipeline-YAML-Datei finden Sie unter Definieren von Machine Learning-Pipelines in YAML.

• Führen Sie eine Pipeline aus:

  az ml run submit-pipeline -n myexperiment -y mypipeline.yml
  

  Weitere Informationen finden Sie unter az ml run submit-pipeline.

  Weitere Informationen zur Pipeline-YAML-Datei finden Sie unter Definieren von Machine Learning-Pipelines in YAML.

• Planen Sie eine Pipeline:

  az ml pipeline create-schedule -n myschedule -e myexperiment -i mypipelineid -y myschedule.yml
  

  Weitere Informationen finden Sie unter az ml pipeline create-schedule.

Registrierung von Modellen, Profilerstellung und Bereitstellung

Die folgenden Befehle veranschaulichen, wie ein trainiertes Modell registriert und dann als Produktionsdienst bereitgestellt wird:

• Hiermit registrieren Sie ein Modell bei Azure Machine Learning:

  az ml model register -n mymodel -p sklearn_regression_model.pkl
  

  Weitere Informationen finden Sie unter az ml model register.

• OPTIONAL Erstellen Sie ein Profil für Ihr Modell, um optimale CPU- und Arbeitsspeicherwerte für die Bereitstellung zu erzielen.

  az ml model profile -n myprofile -m mymodel:1 --ic inferenceconfig.json -d "{\"data\": [[1,2,3,4,5,6,7,8,9,10],[10,9,8,7,6,5,4,3,2,1]]}" -t myprofileresult.json
  

  Weitere Informationen finden Sie unter az ml model profile.

• Bereitstellen Ihrer Modelldatei für AKS

  az ml model deploy -n myservice -m mymodel:1 --ic inferenceconfig.json --dc deploymentconfig.json --ct akscomputetarget
  

  Weitere Informationen zum Rückschlusskonfigurationsdatei-Schema finden Sie unter Inference configuration schema (Rückschlusskonfigurationsschema).

  Weitere Informationen zum Bereitstellungskonfigurationsdatei-Schema finden Sie unter Deployment configuration schema (Bereitstellungskonfigurationsschema).

  Weitere Informationen finden Sie unter az ml model deploy.

Rückschlusskonfigurationsschema

Die Einträge im inferenceconfig.json-Dokument werden den Parametern für die InferenceConfig-Klasse zugeordnet. In der folgenden Tabelle wird die Zuordnung zwischen den Entitäten im JSON-Dokument und den Parametern für die Methode beschrieben:

Sie können die vollständigen Spezifikationen einer Azure Machine Learning-Umgebung in die Rückschlusskonfigurationsdatei aufnehmen. Wenn diese Umgebung in Ihrem Arbeitsbereich nicht vorhanden ist, erstellt Azure Machine Learning sie. Andernfalls aktualisiert Azure Machine Learning die Umgebung bei Bedarf. Nachfolgend finden Sie ein JSON-Beispiel:

{
    "entryScript": "score.py",
    "environment": {
        "docker": {
            "arguments": [],
            "baseDockerfile": null,
            "baseImage": "mcr.microsoft.com/azureml/intelmpi2018.3-ubuntu18.04",
            "enabled": false,
            "sharedVolumes": true,
            "shmSize": null
        },
        "environmentVariables": {
            "EXAMPLE_ENV_VAR": "EXAMPLE_VALUE"
        },
        "name": "my-deploy-env",
        "python": {
            "baseCondaEnvironment": null,
            "condaDependencies": {
                "channels": [
                    "conda-forge"
                ],
                "dependencies": [
                    "python=3.7",
                    {
                        "pip": [
                            "azureml-defaults",
                            "azureml-telemetry",
                            "scikit-learn==0.22.1",
                            "inference-schema[numpy-support]"
                        ]
                    }
                ],
                "name": "project_environment"
            },
            "condaDependenciesFile": null,
            "interpreterPath": "python",
            "userManagedDependencies": false
        },
        "version": "1"
    }
}

Sie können auch eine vorhandene Azure Machine Learning-Umgebung in getrennten CLI-Parametern verwenden und den Schlüssel „Environment“ aus der Rückschlusskonfigurationsdatei entfernen. Verwenden Sie „-e“ für den Umgebungsnamen und „--ev“ für die Umgebungsversion. Wenn Sie „--ev“ nicht angeben, wird die neueste Version verwendet. Hier sehen Sie ein Beispiel für eine Rückschlusskonfigurationsdatei:

{
    "entryScript": "score.py",
    "sourceDirectory": null
}

Der folgende Befehl veranschaulicht, wie Sie ein Modell mithilfe der vorherigen Rückschlusskonfigurationsdatei (namens „myInferenceConfig.json“) bereitstellen.

Außerdem wird die neueste Version einer vorhandenen Azure Machine Learning-Umgebung (namens „AzureML-Minimal“) verwendet.

az ml model deploy -m mymodel:1 --ic myInferenceConfig.json -e AzureML-Minimal --dc deploymentconfig.json

Bereitstellungskonfigurationsschema

Konfigurationsschema zur lokalen Bereitstellung

Die Einträge im Dokument deploymentconfig.json werden den Parametern für LocalWebservice.deploy_configuration zugeordnet. In der folgenden Tabelle wird die Zuordnung zwischen den Entitäten im JSON-Dokument und den Parametern für die Methode beschrieben:

Dieser JSON-Code ist ein Beispiel für eine Bereitstellungskonfiguration für die Verwendung mit der CLI:

{
    "computeType": "local",
    "port": 32267
}

Speichern Sie diese JSON-Datei unter dem Namen deploymentconfig.json.

Konfigurationsschema zur Bereitstellung einer Azure-Containerinstanz

Die Einträge im Dokument deploymentconfig.json werden den Parametern für AciWebservice.deploy_configuration zugeordnet. In der folgenden Tabelle wird die Zuordnung zwischen den Entitäten im JSON-Dokument und den Parametern für die Methode beschrieben:

Der folgende JSON-Code ist ein Beispiel für eine Bereitstellungskonfiguration für die Verwendung mit der CLI:

{
    "computeType": "aci",
    "containerResourceRequirements":
    {
        "cpu": 0.5,
        "memoryInGB": 1.0
    },
    "authEnabled": true,
    "sslEnabled": false,
    "appInsightsEnabled": false
}

Konfigurationsschema zur Bereitstellung von Azure Kubernetes Service

Die Einträge im Dokument deploymentconfig.json werden den Parametern für AksWebservice.deploy_configuration zugeordnet. In der folgenden Tabelle wird die Zuordnung zwischen den Entitäten im JSON-Dokument und den Parametern für die Methode beschrieben:

Der folgende JSON-Code ist ein Beispiel für eine Bereitstellungskonfiguration für die Verwendung mit der CLI:

{
    "computeType": "aks",
    "autoScaler":
    {
        "autoscaleEnabled": true,
        "minReplicas": 1,
        "maxReplicas": 3,
        "refreshPeriodInSeconds": 1,
        "targetUtilization": 70
    },
    "dataCollection":
    {
        "storageEnabled": true
    },
    "authEnabled": true,
    "containerResourceRequirements":
    {
        "cpu": 0.5,
        "memoryInGB": 1.0
    }
}

Nächste Schritte

• Befehlsreferenz für die Machine Learning-CLI-Erweiterung

• Trainieren und Bereitstellen von Machine Learning-Modellen mit Azure Pipelines