Installare e usare l'interfaccia della riga di comando (v1)

SI APPLICA A: Estensione ML dell’interfaccia della riga di comando di Azure v1

L'interfaccia della riga di comando di Azure Machine Learning è un'estensione dell'interfaccia della riga di comando di Azure, un'interfaccia della riga di comando multipiattaforma per la piattaforma Azure. Questa estensione offre i comandi per lavorare con Azure Machine Learning. Consente di automatizzare le attività di Machine Learning. L'elenco seguente fornisce alcune azioni di esempio che è possibile eseguire con l'estensione dell'interfaccia della riga di comando:

• Eseguire gli esperimenti per creare modelli di apprendimento automatico

• Registrare modelli di Machine Learning per l'uso da parte dei clienti

• Creare un pacchetto, distribuire e monitorare il ciclo di vita dei modelli di Machine Learning

L'interfaccia della riga di comando non sostituisce Azure Machine Learning SDK. Si tratta di uno strumento complementare ottimizzato per gestire attività altamente con parametri che si adattano bene all'automazione.

Prerequisiti

• Per usare l'interfaccia della riga di comando, è necessario avere una sottoscrizione di Azure. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare. Provare la versione gratuita o a pagamento di Azure Machine Learning.

• Per usare i comandi dell'interfaccia della riga di comando in questo documento dall'ambiente locale, è necessaria l'interfaccia della riga di comando di Azure.

  Se si usa Azure Cloud Shell, l'interfaccia della riga di comando è accessibile tramite il browser e si trova nel cloud.

Documentazione di riferimento completa

Trovare la documentazione di riferimento completa per l'estensione azure-cli-ml dell'interfaccia della riga di comando di Azure.

Connettere l'interfaccia della riga di comando alla sottoscrizione di Azure

È possibile eseguire l'autenticazione della sottoscrizione di Azure dall'interfaccia della riga di comando in diversi modi. Quello più semplice consiste nell'eseguire l'autenticazione interattiva tramite un browser. Per eseguire l'autenticazione in modo interattivo, aprire una riga di comando o un terminale e usare il comando seguente:

az login

Se l'interfaccia della riga di comando può aprire il browser predefinito, eseguirà questa operazione e caricherà una pagina di accesso. In caso contrario, è necessario aprire un browser e seguire le istruzioni nella riga di comando. Le istruzioni prevedono l'individuazione di https://aka.ms/devicelogin e l'immissione di un codice di autorizzazione.

Per altri metodi di autenticazione, vedere Accedere con l'interfaccia della riga di comando di Azure.

Installare l'estensione

Per installare l'estensione dell'interfaccia della riga di comando (v1):

az extension add -n azure-cli-ml

Aggiornare l'estensione

Per aggiornare l'estensione dell'interfaccia della riga di comando di Azure Machine Learning, usare il comando seguente:

az extension update -n azure-cli-ml

Rimuovere l'estensione

Per rimuovere l'estensione dell'interfaccia della riga di comando, usare il comando seguente:

az extension remove -n azure-cli-ml

Gestione delle risorse

I comandi seguenti illustrano come usare l'interfaccia della riga di comando per gestire le risorse usate da Azure Machine Learning.

• Se non è già disponibile, creare un gruppo di risorse:

  az group create -n myresourcegroup -l westus2
  

• Creare un'area di lavoro di Azure Machine Learning:

  az ml workspace create -w myworkspace -g myresourcegroup
  

  Per altre informazioni, vedere az ml workspace create.

• Allegare una configurazione di un'area di lavoro a una cartella per abilitare la consapevolezza contestuale dell'interfaccia della riga di comando.

  az ml folder attach -w myworkspace -g myresourcegroup
  

  Questo comando crea una .azureml sottodirectory che contiene i file di ambiente runconfig e conda di esempio. Contiene anche un file config.json usato per comunicare con l'area di lavoro di Azure Machine Learning.

  Per altre informazioni, vedere az ml folder attach.

• Allegare un contenitore BLOB di Azure come archivio dati.

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

  Per altre informazioni, vedere az ml datastore attach-blob.

• Caricare file in un archivio dati.

  az ml datastore upload  -n datastorename -p sourcepath
  

  Per altre informazioni, vedere az ml datastore upload.

• Allegare un cluster AKS come destinazione di calcolo.

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

  Per altre informazioni, vedere az ml computetarget attach aks

Cluster di elaborazione

• Creare un nuovo cluster di calcolo gestito.

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

• Creare un nuovo cluster di elaborazione gestito con identità gestita

  • Identità gestita assegnata dall'utente

    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>'
    

  • Identità gestita assegnata dal sistema

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

• Aggiungere un'identità gestita a un cluster esistente:

  • Identità gestita assegnata dall'utente

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

  • Identità gestita assegnata dal sistema

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

Per altre informazioni, vedere az ml computetarget create amlcompute.

Istanza di calcolo

Gestire le istanze di calcolo. In tutti gli esempi seguenti il nome dell'istanza di calcolo è cpu

• Creare una nuova istanza di calcolo.

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

  Per altre informazioni, vedere az ml computetarget create computeinstance.

• Arrestare una computeinstance.

  az ml computetarget computeinstance stop -n cpu -v
  

  Per altre informazioni, vedere az ml computetarget computeinstance stop.

• Avviare un'istanza di calcolo.

  az ml computetarget computeinstance start -n cpu -v
  

  Per altre informazioni, vedere az ml computetarget computeinstance start.

• Riavviare un'istanza di calcolo.

  az ml computetarget computeinstance restart -n cpu -v
  

  Per altre informazioni, vedere az ml computetarget computeinstance restart.

• Eliminare un'istanza di calcolo.

  az ml computetarget delete -n cpu -v
  

  Per altre informazioni, vedere az ml computetarget delete computeinstance.

Eseguire esperimenti

• Avviare un'esecuzione dell'esperimento. Quando si usa questo comando, specificare il nome del file runconfig (il testo prima di *.runconfig se si sta esaminando il file system) rispetto al parametro -c.

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

  Suggerimento

  Il comando az ml folder attach crea una sottodirectory .azureml che contiene due file runconfig di esempio.

  Se si dispone di uno script Python che crea un oggetto di configurazione di esecuzione a livello di codice, è possibile usare RunConfig.save() per salvarlo come file runconfig.

  Lo schema runconfig completo è disponibile in questo file JSON. Lo schema è autoesplicativo tramite la chiave description di ogni oggetto. Sono inoltre disponibili enumerazioni per i valori possibili e un frammento di modello alla fine.

  Per altre informazioni, vedere az ml run submit-script.

• Visualizzare un elenco di esperimenti:

  az ml experiment list
  

  Per altre informazioni, vedere az ml experiment list.

Esecuzione di HyperDrive

È possibile usare HyperDrive con l'interfaccia della riga di comando di Azure per le esecuzioni di ottimizzazione dei parametri. Prima di tutto, creare un file di configurazione di HyperDrive nel formato seguente. Per informazioni dettagliate sui parametri di ottimizzazione degli iperparametri, vedere l'articolo Ottimizzare gli iperparametri per il modello.

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

Aggiungere questo file insieme ai file della configurazione di esecuzione. Inviare quindi un'esecuzione HyperDrive usando il codice seguente:

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

Si noti la sezione argomenti in runconfig e spazio dei parametri nella configurazione di HyperDrive. Contengono gli argomenti della riga di comando da passare allo script di training. Il valore in runconfig rimane invariato per ogni iterazione, mentre l'intervallo nella configurazione di HyperDrive viene iterato. Non specificare lo stesso argomento in entrambi i file.

Gestione dei set di dati

I comandi seguenti illustrano come usare i set di dati in Azure Machine Learning:

• Registrare un set di dati:

  az ml dataset register -f mydataset.json
  

  Per informazioni sul formato del file JSON usato per definire il set di dati, usare az ml dataset register --show-template.

  Per altre informazioni, vedere az ml dataset register.

• Elencare tutti i set di dati in un'area di lavoro:

  az ml dataset list
  

  Per altre informazioni, vedere az ml dataset list.

• Ottenere dettagli su un set di dati:

  az ml dataset show -n dataset-name
  

  Per altre informazioni, vedere az ml dataset show.

• Annullare la registrazione di un set di dati:

  az ml dataset unregister -n dataset-name
  

  Per altre informazioni, vedere az ml dataset unregister.

Gestione dell'ambiente

I comandi seguenti illustrano come creare, registrare ed elencare gli ambienti di Azure Machine Learning per l'area di lavoro in uso:

• Creare file scaffolding per un ambiente:

  az ml environment scaffold -n myenv -d myenvdirectory
  

  Per altre informazioni, vedere az ml environment scaffold.

• Registrare un ambiente:

  az ml environment register -d myenvdirectory
  

  Per altre informazioni, vedere az ml environment register.

• Elencare ambienti registrati:

  az ml environment list
  

  Per altre informazioni, vedere az ml environment list.

• Scaricare un ambiente registrato:

  az ml environment download -n myenv -d downloaddirectory
  

  Per altre informazioni, vedere az ml environment download.

Schema di configurazione dell'ambiente

Se è stato usato il comando az ml environment scaffold, viene generato un file azureml_environment.json di modello che può essere modificato e usato per creare configurazioni personalizzate dell'ambiente con l'interfaccia della riga di comando. L'oggetto di livello principale viene mappato liberamente alla classe Environment in Python SDK.

{
    "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
}

La tabella seguente illustra in dettaglio ogni campo di primo livello nel file JSON, nel relativo tipo e in una descrizione. Se un tipo di oggetto è collegato a una classe da Python SDK, esiste una corrispondenza 1:1 debole tra ogni campo JSON e il nome della variabile pubblica nella classe Python. In alcuni casi, il campo può eseguire il mapping a un argomento del costruttore anziché a una variabile di classe. Ad esempio, il campo environmentVariables viene mappato alla variabile environment_variables nella classe Environment.

Gestione pipeline ML

I comandi seguenti illustrano come usare le pipeline di Machine Learning:

• Creare una pipeline di Machine Learning:

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

  Per altre informazioni, vedere az ml pipeline create.

  Per altre informazioni sul file YAML della pipeline, vedere Definire le pipeline di Machine Learning in YAML.

• Eseguire una pipeline:

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

  Per altre informazioni, vedere az ml run submit-pipeline.

  Per altre informazioni sul file YAML della pipeline, vedere Definire le pipeline di Machine Learning in YAML.

• Pianificare una pipeline:

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

  Per altre informazioni, vedere az ml pipeline create-schedule.

Registrazione, profilatura e distribuzione di un modello

I comandi seguenti illustrano come registrare un modello con training e quindi distribuirlo come servizio di produzione:

• Registrare un modello con Azure Machine Learning:

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

  Per altre informazioni, vedere az ml model register.

• FACOLTATIVO Profilare il modello per ottenere valori ottimali per la CPU e la memoria per la distribuzione.

  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
  

  Per altre informazioni, vedere az ml model profile.

• Distribuire il modello nel servizio Azure Kubernetes

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

  Per altre informazioni sullo schema di un file di configurazione dell'inferenza, vedere Schema di configurazione dell'inferenza.

  Per altre informazioni sullo schema di un file di configurazione della distribuzione, vedere Schema di configurazione della distribuzione.

  Per altre informazioni, vedere az ml model deploy.

Schema di configurazione dell'inferenza

Le voci del documento inferenceconfig.json vengono mappate ai parametri della classe InferenceConfig. La tabella seguente descrive il mapping tra le entità nel documento JSON e i parametri per il metodo:

Nei file di configurazione dell'inferenza è possibile includere le specifiche complete di un ambiente di Azure Machine Learning. Se l'ambiente non esiste nell'area di lavoro, Azure Machine Learning lo creerà. In caso contrario, Azure Machine Learning aggiornerà l'ambiente, se necessario. Di seguito è riportato un file JSON di esempio:

{
    "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"
    }
}

È anche possibile usare un ambiente di Azure Machine Learning esistente nei parametri dell'interfaccia della riga di comando separati e rimuovere la chiave "environment" dal file di configurazione dell'inferenza. Usare -e per il nome dell'ambiente e --ev per la versione. Se non si specifica--ev, verrà usata la versione più recente. Ecco un esempio di file di configurazione dell'inferenza:

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

Il comando seguente illustra come distribuire un modello usando il file di configurazione dell'inferenza precedente (denominato myInferenceConfig.json).

Usa inoltre la versione più recente di un ambiente di Azure Machine Learning esistente (denominato AzureML-Minimal).

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

Schema di configurazione della distribuzione

Schema di configurazione della distribuzione locale

Le voci del documento deploymentconfig.json vengono associate ai parametri di LocalWebservice.deploy_configuration. La tabella seguente descrive il mapping tra le entità nel documento JSON e i parametri per il metodo:

Il codice JSON seguente è un esempio di configurazione della distribuzione da usare con l'interfaccia della riga di comando:

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

Salvare il codice JSON come file denominato deploymentconfig.json.

Schema di configurazione della distribuzione dell'istanza di contenitore di Azure

Le voci del documento deploymentconfig.json vengono mappate ai parametri di AciWebservice.deploy_configuration. La tabella seguente descrive il mapping tra le entità nel documento JSON e i parametri per il metodo:

Il codice JSON seguente è un esempio di configurazione della distribuzione da usare con l'interfaccia della riga di comando:

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

Schema di configurazione della distribuzione rete del servizio Azure Kubernetes

Le voci del documento deploymentconfig.json vengono mappate ai parametri di AksWebservice.deploy_configuration. La tabella seguente descrive il mapping tra le entità nel documento JSON e i parametri per il metodo:

Il codice JSON seguente è un esempio di configurazione della distribuzione da usare con l'interfaccia della riga di comando:

{
    "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
    }
}

Passaggi successivi

• Riferimento ai comandi per l'estensione dell'interfaccia della riga di comando di Machine Learning.

• Eseguire il training e distribuire modelli di Machine Learning usando Azure Pipelines