Gestire gli ambienti di Azure Machine Learning con l'interfaccia della riga di comando e l'SDK (v2)

SI APPLICA A:Estensione ML dell'interfaccia della riga di comando di Azure v2 (corrente)Python SDK azure-ai-ml v2 (corrente)

Gli ambienti di Azure Machine Learning definiscono gli ambienti di esecuzione per i processi o le distribuzioni e incapsulano le dipendenze per il codice. Azure Machine Learning usa la specifica dell'ambiente per creare il contenitore Docker in cui viene eseguito il training o il codice di assegnazione dei punteggi nella destinazione di calcolo specificata. È possibile definire un ambiente da una specifica Conda, un'immagine Docker o un contesto di compilazione Docker.

Questo articolo illustra come creare e gestire ambienti di Azure Machine Learning usando l'SDK e l'interfaccia della riga di comando (v2).

Prerequisiti

Prima di seguire la procedura descritta in questo articolo, assicurarsi di disporre dei prerequisiti seguenti:

• Un'area di lavoro di Azure Machine Learning. Se non è disponibile, seguire la procedura descritta nell'articolo Avvio rapido: Creare risorse dell'area di lavoro per crearne una.

• L'interfaccia della riga di comando di Azure e l'estensione ml oppure Python SDK v2 per Azure Machine Learning:

  • Per installare l'interfaccia della riga di comando di Azure e l'estensione, vedere Installare, configurare e usare l'interfaccia della riga di comando di Azure (v2).

    Importante

    Gli esempi dell'interfaccia della riga di comando in questo articolo presuppongono che si usi la shell Bash (o compatibile). Ad esempio, un sistema Linux o un sottosistema Windows per Linux.

  • Per installare Python SDK v2, usare il comando seguente:

    pip install azure-ai-ml azure-identity
    

    Per aggiornare un'installazione esistente di SDK alla versione più recente, usare il comando seguente:

    pip install --upgrade azure-ai-ml azure-identity
    

    Per altre informazioni, vedere Installare Python SDK v2 per Azure Machine Learning.

Suggerimento

Per un ambiente di sviluppo completo, usare Visual Studio Code e l'estensione di Azure Machine Learning per gestire le risorse di Azure Machine Learning ed eseguire il training di modelli di Machine Learning.

Clonare il repository degli esempi

Per eseguire gli esempi di training, clonare prima di tutto il repository di esempi. Per gli esempi dell'interfaccia della riga di comando, passare alla directory cli. Per gli esempi dell'SDK, passare alla directory sdk/python/assets/environment.

git clone --depth 1 https://github.com/Azure/azureml-examples

Si prega di notare che --depth 1 clona solo il commit più recente nel repository, riducendo il tempo necessario per completare l'operazione.

Connettersi all'area di lavoro

Suggerimento

Usare le schede seguenti per selezionare il metodo da usare per lavorare con gli ambienti. Se si seleziona una scheda, tutte le schede di questo articolo verranno automaticamente visualizzate nella stessa scheda. È possibile selezionare un'altra scheda in qualsiasi momento.

Interfaccia della riga di comando di Azure

Quando si usa l'interfaccia della riga di comando di Azure, sono necessari i parametri di identificatore, ovvero una sottoscrizione, un gruppo di risorse e un nome dell'area di lavoro. Sebbene sia possibile specificare questi parametri per ogni comando, è anche possibile definire le impostazioni predefinite che vengono usate per tutti i comandi. Usare i comandi seguenti per impostare i valori predefiniti. Sostituire <subscription ID>, <Azure Machine Learning workspace name> e <resource group> con i valori per la configurazione:

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

Python SDK

Per connettersi all’area di lavoro, occorrono i parametri identificatore, ovvero una sottoscrizione, un gruppo di risorse e un nome dell’area di lavoro. Questi dettagli verranno usati in MLClient dallo spazio dei nomi azure.ai.ml per ottenere un handle per l'area di lavoro di Azure Machine Learning necessaria. Per eseguire l'autenticazione, usare l'autenticazione di Azure predefinita. Per altre informazioni su come configurare le credenziali e connettersi a un'area di lavoro, vedere questo esempio.

# import required libraries
from azure.ai.ml import MLClient
from azure.ai.ml.entities import Environment, BuildContext
from azure.identity import DefaultAzureCredential

# Enter details of your AML workspace
subscription_id = "<SUBSCRIPTION_ID>"
resource_group = "<RESOURCE_GROUP>"
workspace = "<AML_WORKSPACE_NAME>"

# get a handle to the workspace
ml_client = MLClient(
    DefaultAzureCredential(), subscription_id, resource_group, workspace
)

Ambienti dedicati

Esistono due tipi di ambienti in Azure Machine Learning: ambienti curati e personalizzati. Gli ambienti curati sono ambienti predefiniti contenenti framework e strumenti di Machine Learning più diffusi. Gli ambienti personalizzati sono definiti dall'utente e possono essere creati tramite az ml environment create.

Gli ambienti curati vengono forniti da Azure Machine Learning e sono disponibili per impostazione predefinita. Azure Machine Learning aggiorna regolarmente questi ambienti con le versioni più recenti del framework e le gestisce per le correzioni di bug e le patch di sicurezza. Sono supportate da immagini Docker memorizzate nella cache, riducendo i costi di preparazione dei processi e il tempo di distribuzione del modello.

È possibile usare questi ambienti predefiniti curati per il training o la distribuzione facendo riferimento a una versione specifica o alla versione più recente dell'ambiente. Usare la sintassi seguente: azureml://registries/azureml/environment/<curated-environment-name>/versions/<version-number> o azureml://registries/azureml/environment/<curated-environment-name>/labels/latest. È anche possibile usarli come riferimento per gli ambienti personalizzati modificando i Dockerfile che rispondono a questi ambienti curati.

È possibile visualizzare il set di ambienti curati disponibili nell'interfaccia utente dello studio di Azure Machine Learning o usando l'interfaccia della riga di comando (v2) tramite az ml environment list.

Suggerimento

Quando si lavora con ambienti curati nell'interfaccia della riga di comando o nell'SDK, il nome dell'ambiente inizia con AzureML- seguito dal nome dell'ambiente curato. Quando si usa Studio di Azure Machine Learning, non hanno questo prefisso. Il motivo di questa differenza è che l'interfaccia utente di Studio visualizza ambienti curati e personalizzati in schede separate, quindi il prefisso non è necessario. L'interfaccia della riga di comando e l'SDK non dispongono di questa separazione, quindi il prefisso viene usato per distinguere tra ambienti curati e personalizzati.

Creare un ambiente personalizzato

È possibile definire un ambiente da un'immagine Docker, un contesto di compilazione Docker e una specifica conda con l'immagine Docker.

Creare un ambiente da un'immagine Docker

Per definire un ambiente da un'immagine Docker, specificare l'URI immagine dell'immagine ospitata in un registro, ad esempio Docker Hub o Registro Azure Container.

Interfaccia della riga di comando di Azure

L'esempio seguente è un file di specifica YAML per un ambiente definito da un'immagine Docker. Un'immagine del repository PyTorch ufficiale nell'hub Docker viene specificata tramite la proprietà image nel file YAML.

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: docker-image-example
image: pytorch/pytorch:latest
description: Environment created from a Docker image.

Per creare l'ambiente:

az ml environment create --file assets/environment/docker-image.yml

Python SDK

L'esempio seguente crea un ambiente da un'immagine Docker. Un'immagine del repository PyTorch ufficiale nell'hub Docker viene specificata tramite la proprietà image.

env_docker_image = Environment(
    image="pytorch/pytorch:latest",
    name="docker-image-example",
    description="Environment created from a Docker image.",
)
ml_client.environments.create_or_update(env_docker_image)

Suggerimento

Azure Machine Learning gestisce un set di immagini di base basate su CPU e GPU Ubuntu basate su Linux con dipendenze di sistema comuni. Ad esempio, le immagini GPU contengono Miniconda, OpenMPI, CUDA, cuDNN e NCCL. È possibile usare queste immagini per gli ambienti o usare i Dockerfile corrispondenti come riferimento per la creazione di immagini personalizzate.

Per il set di immagini di base e i dockerfile corrispondenti, vedere il repository AzureML-Containers.

Creare un ambiente da un contesto di compilazione Docker

Anziché definire un ambiente da un'immagine predefinita, è anche possibile definirne uno da un docker contesto di compilazione. A tal riguardo, specificare la directory che funge da contesto di compilazione. Questa directory deve contenere un Dockerfile (non superiore a 1 MB) ed eventuali altri file necessari per compilare l'immagine.

Interfaccia della riga di comando di Azure

L'esempio seguente è un file di specifica YAML per un ambiente definito da un contesto di compilazione. Il percorso locale della cartella del contesto di compilazione viene specificato nel campo build.path e il percorso relativo al Dockerfile all'interno della cartella del contesto di compilazione viene specificato nel campo build.dockerfile_path. Se build.dockerfile_path viene omesso nel file YAML, Azure Machine Learning cerca un Dockerfile denominato Dockerfile nella radice del contesto di compilazione.

In questo esempio il contesto di compilazione contiene un Dockerfile denominato Dockerfile e un file requirements.txt a cui viene fatto riferimento all'interno del Dockerfile per l'installazione dei pacchetti Python.

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: docker-context-example
build:
  path: docker-contexts/python-and-pip

Per creare l'ambiente:

az ml environment create --file assets/environment/docker-context.yml

Python SDK

Nell'esempio seguente il percorso locale della cartella del contesto di compilazione viene specificato nel parametro path. Azure Machine Learning cerca un Dockerfile denominato Dockerfile nella radice del contesto di compilazione.

env_docker_context = Environment(
    build=BuildContext(path="docker-contexts/python-and-pip"),
    name="docker-context-example",
    description="Environment created from a Docker context.",
)
ml_client.environments.create_or_update(env_docker_context)

Azure Machine Learning inizia a compilare l'immagine dal contesto di compilazione quando viene creato l'ambiente. È possibile monitorare lo stato della compilazione e visualizzare i log di compilazione nell'interfaccia utente di Studio.

Creare un ambiente da una specifica conda

È possibile definire un ambiente usando un file di configurazione YAML conda standard che include le dipendenze per l'ambiente conda. Per informazioni su questo formato standard, vedere Creazione manuale di un ambiente.

È anche necessario specificare un'immagine Docker di base per questo ambiente. Azure Machine Learning crea l'ambiente conda sopra l'immagine Docker fornita. Se si installano alcune dipendenze Python nell'immagine Docker, tali pacchetti non esistono nell'ambiente di esecuzione causando quindi errori di runtime. Per impostazione predefinita, Azure Machine Learning crea un ambiente Conda con le dipendenze specificate ed esegue il processo in tale ambiente anziché usare tutte le librerie Python installate nell'immagine di base.

Interfaccia della riga di comando di Azure

L'esempio seguente è un file di specifica YAML per un ambiente definito da una specifica conda. Qui il percorso relativo del file conda dal file YAML dell'ambiente Azure Machine Learning viene specificato tramite la proprietà conda_file. In alternativa, è possibile definire la specifica conda inline usando la proprietà conda_file anziché definirla in un file separato.

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: docker-image-plus-conda-example
image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04
conda_file: conda-yamls/pydata.yml
description: Environment created from a Docker image plus Conda environment.

Per creare l'ambiente:

az ml environment create --file assets/environment/docker-image-plus-conda.yaml

Python SDK

Il percorso relativo del file conda viene specificato usando il parametro conda_file.

env_docker_conda = Environment(
    image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04",
    conda_file="conda-yamls/pydata.yml",
    name="docker-image-plus-conda-example",
    description="Environment created from a Docker image plus Conda environment.",
)
ml_client.environments.create_or_update(env_docker_conda)

Azure Machine Learning crea l'immagine Docker finale da questa specifica di ambiente quando l'ambiente viene usato in un processo o in una distribuzione. È anche possibile attivare manualmente una compilazione dell'ambiente nell'interfaccia utente di Studio.

Gestione degli ambienti

L'SDK e l'interfaccia della riga di comando (v2) consentono anche di gestire il ciclo di vita degli asset dell’ambiente di Azure Machine Learning.

List

Elencare tutti gli ambienti nell'area di lavoro:

Interfaccia della riga di comando di Azure

az ml environment list

Python SDK

envs = ml_client.environments.list()
for env in envs:
    print(env.name)

Elencare tutte le versioni dell'ambiente con un nome specificato:

Interfaccia della riga di comando di Azure

az ml environment list --name docker-image-example

Python SDK

envs = ml_client.environments.list(name="docker-image-example")
for env in envs:
    print(env.version)

Mostra

Ottenere i dettagli di un ambiente specifico:

Interfaccia della riga di comando di Azure

az ml environment show --name docker-image-example --version 1

Python SDK

env = ml_client.environments.get(name="docker-image-example", version="1")
print(env)

Aggiornamento

Aggiornare le proprietà modificabili di un ambiente specifico:

Interfaccia della riga di comando di Azure

az ml environment update --name docker-image-example --version 1 --set description="This is an updated description."

Python SDK

env.description="This is an updated description."
ml_client.environments.create_or_update(environment=env)

Importante

Per gli ambienti, è possibile aggiornare solo description e tags. Tutte le altre proprietà non sono modificabili. Se è necessario modificare una di queste proprietà, occorre creare una nuova versione dell’ambiente.

Archivio

L'archiviazione di un ambiente lo nasconde per impostazione predefinita dalle query di elenco (az ml environment list). È comunque possibile continuare a fare riferimento e usare un ambiente archiviato nei flussi di lavoro. È possibile archiviare tutte le versioni di un ambiente o solo una versione specifica.

Se non si specifica una versione, tutte le versioni dell'ambiente con tale nome specificato vengono archiviate. Se si crea una nuova versione dell'ambiente in un contenitore di ambiente archiviato, tale nuova versione viene impostata automaticamente come archiviata.

Archiviare tutte le versioni di un ambiente:

Interfaccia della riga di comando di Azure

az ml environment archive --name docker-image-example

Python SDK

ml_client.environments.archive(name="docker-image-example")

Archiviare una versione specifica dell'ambiente:

Interfaccia della riga di comando di Azure

az ml environment archive --name docker-image-example --version 1

Python SDK

ml_client.environments.archive(name="docker-image-example", version="1")

Importante

L'archiviazione della versione di un ambiente non elimina l'immagine memorizzata nella cache nel registro contenitori. Se si desidera eliminare l'immagine memorizzata nella cache associata a un ambiente specifico, è possibile usare il comando az acr repository delete nel repository associato dell'ambiente.

Usare gli ambienti per il training

Interfaccia della riga di comando di Azure

Per usare un ambiente personalizzato per un processo di training, specificare il campo environment della configurazione YAML del processo. È possibile fare riferimento a un ambiente Azure Machine Learning registrato esistente tramite environment: azureml:<environment-name>:<environment-version> o environment: azureml:<environment-name>@latest (per fare riferimento alla versione più recente di un ambiente) o definire una specifica di ambiente inline. Se si definisce un ambiente inline, non specificare i campi name e version, poiché questi ambienti vengono considerati come ambienti non registrati e non vengono rilevati nel registro degli asset dell'ambiente.

Python SDK

Per usare un ambiente per un processo di training, specificare la proprietà environment del comando.

Per esempi di invio di processi, vedere gli esempi in https://github.com/Azure/azureml-examples/tree/main/sdk/python/jobs.

Quando si invia un processo di training, la compilazione di un nuovo ambiente può richiedere alcuni minuti. La durata dipende dalle dimensioni delle dipendenze richieste. Gli ambienti vengono memorizzati nella cache dal servizio. Finché la definizione dell'ambiente rimane invariata, la configurazione completa verrà eseguita una sola volta.

---

Per altre informazioni su come usare gli ambienti nei processi, vedere Eseguire il training dei modelli.

Usare gli ambienti per le distribuzioni di modelli

Interfaccia della riga di comando di Azure

È anche possibile usare gli ambienti per le distribuzioni di modelli per l'assegnazione dei punteggi online e batch. A tale scopo, specificare il campo environment nella configurazione YAML di distribuzione.

Per altre informazioni su come usare gli ambienti nelle distribuzioni, vedere Distribuire e assegnare un punteggio a un modello di Machine Learning usando un endpoint online.

Python SDK

È anche possibile usare gli ambienti per le distribuzioni di modelli. Per altre informazioni, vedere Distribuire e assegnare un punteggio a un modello di Machine Learning.

Passaggi successivi

• Eseguire il training di modelli (creare processi)
• Distribuire e assegnare un punteggio a un modello di Machine Learning usando un endpoint online
• Riferimento dello scherma YAML dell’ambiente