Usare i modelli in Azure Machine Learning

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

Azure Machine Learning consente di usare diversi tipi di modelli. Questo articolo illustra l'uso di Azure Machine Learning per lavorare con diversi tipi di modello, ad esempio modelli personalizzati, di MLflow e Triton. Si apprenderà anche come registrare un modello da posizioni diverse e come usare Azure Machine Learning SDK, l'interfaccia utente e l'interfaccia della riga di comando di Azure Machine Learning per gestire i modelli.

Suggerimento

Se sono stati creati asset di modello che usano l'SDK/interfaccia della riga di comando v1, è comunque possibile usarli con SDK/interfaccia della riga di comando v2. Viene fornita la compatibilità completa con le versioni precedenti. A tutti i modelli registrati nell'SDK V1 viene assegnato il tipo custom.

Prerequisiti

• 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.
• Un'area di lavoro di Azure Machine Learning.
• Azure Machine Learning SDK v2 per Python.
• Interfaccia della riga di comando v2 di Azure Machine Learning.

Sarà inoltre necessario:

Interfaccia della riga di comando di Azure

• Installare l'interfaccia della riga di comando di Azure e l'estensione di Machine Learning nell'interfaccia della riga di comando di Azure. Per altre informazioni, vedere Installare, configurare e usare l'interfaccia della riga di comando (v2).

Python SDK

• Installare Azure Machine Learning SDK per Python

  pip install azure-ai-ml azure-identity
  

Percorsi supportati

Quando si specifica un modello da registrare, è necessario specificare un parametro path che punta ai dati o alla posizione del processo. Di seguito è riportata una tabella che mostra i diversi percorsi di dati supportati in Azure Machine Learning e include esempi per il parametro path:

Ufficio	Esempi
Percorso nel computer locale	mlflow-model/model.pkl
Percorso in un archivio dati di Azure Machine Learning	azureml://datastores/<datastore-name>/paths/<path_on_datastore>
Percorso da un processo di Azure Machine Learning	azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
Percorso da un processo di MLflow	runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
Percorso da un asset di modello nell'area di lavoro di Azure Machine Learning	azureml:<model-name>:<version>
Percorso da un asset di modello nel registro di Azure Machine Learning	azureml://registries/<registry-name>/models/<model-name>/versions/<version>

Modalità supportate

Quando si esegue un processo con input/output del modello, è possibile specificare la modalità, ad esempio per indicare se si vuole che il modello sia montato o scaricato in sola lettura nella destinazione di calcolo. La tabella seguente illustra le modalità possibili per combinazioni diverse di tipo/modalità/input/output:

Type	Input/Output	upload	download	ro_mount	rw_mount	direct
File custom	Input
custom	Input		✓	✓		✓
mlflow	Input		✓	✓
File custom	Output	✓			✓	✓
custom	Output	✓			✓	✓
mlflow	Output	✓			✓	✓

Seguire la procedura in Jupyter Notebooks

È possibile seguire questo esempio in un notebook Jupyter. Nel repository azureml-examples aprire il notebook: model.ipynb.

Creare un modello nel registro dei modelli

Con la registrazione dei modelli è possibile archiviare i modelli e creare le relative versioni nel cloud di Azure, all'interno della propria area di lavoro. Il registro dei modelli consente di organizzare i modelli sottoposti a training e tenerne traccia.

I frammenti di codice in questa sezione illustrano come:

• Registrare il modello come asset in Machine Learning usando l'interfaccia della riga di comando.
• Registrare il modello come asset in Machine Learning usando l'SDK.
• Registrare il modello come asset in Machine Learning usando l'interfaccia utente.

Questi frammenti di codice usano custom e mlflow.

• custom è un tipo che fa riferimento a un file di modello o a una cartella sottoposta a training con uno standard personalizzato non attualmente supportato da Azure Machine Learning.
• mlflow è un tipo che fa riferimento a un modello sottoposto a training con mlflow. I modelli sottoposti a training con MLflow si trovano in una cartella contenente il file MLmodel, il file del modello, il file delle dipendenze conda e il file requirements.txt.

Connettersi all'area di lavoro

Connettersi prima di tutto all'area di lavoro di Azure Machine Learning in cui si lavorerà.

Interfaccia della riga di comando di Azure

az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

Python SDK

L'area di lavoro è la risorsa di primo livello per Azure Machine Learning, che fornisce una posizione centralizzata da cui gestire tutti gli artefatti creati quando si usa Azure Machine Learning. In questa sezione ci si connetterà all'area di lavoro in cui verranno eseguite le attività di distribuzione.

1. Importare le librerie necessarie:

   from azure.ai.ml import MLClient, Input
   from azure.ai.ml.entities import Model
   from azure.ai.ml.constants import AssetTypes
   from azure.identity import DefaultAzureCredential
   

2. Configurare i dettagli dell'area di lavoro e ottenere un handle per l'area di lavoro:

   subscription_id = "<SUBSCRIPTION_ID>"
   resource_group = "<RESOURCE_GROUP>"
   workspace = "<AML_WORKSPACE_NAME>"
   
   ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)
   

Registrare il modello come asset in Machine Learning usando l'interfaccia della riga di comando

Usare le schede seguenti per selezionare la posizione in cui si trova il modello.

Modello locale

$schema: https://azuremlschemas.azureedge.net/latest/model.schema.json
name: local-file-example
path: mlflow-model/model.pkl
description: Model created from local file.

az ml model create -f <file-name>.yml

Per un esempio completo, vedere il file YAML del modello.

Datastore

È possibile creare un modello da un percorso cloud usando uno dei formati URI supportati seguenti.

az ml model create --name my-model --version 1 --path azureml://datastores/myblobstore/paths/models/cifar10/cifar.pt

Negli esempi viene usato lo schema azureml abbreviato per puntare a un percorso in datastore usando la sintassi azureml://datastores/<datastore-name>/paths/<path_on_datastore>.

Per un esempio completo, vedere le informazioni di riferimento sull'interfaccia della riga di comando.

Output del processo

In questo caso sono disponibili due opzioni. È possibile usare il formato URI di esecuzione di MLflow oppure usare il formato URI azureml job.

MLflow

Questa opzione è ottimizzata per gli utenti di MLflow, che probabilmente hanno già familiarità con il formato URI di esecuzione di MLflow. Questa opzione consente di creare un modello dagli artefatti nella posizione predefinita dell'artefatto, in cui si trovano tutti i modelli e gli artefatti con registrazione in MLflow. In questo modo viene stabilita una derivazione tra un modello registrato e l'esecuzione da cui proviene il modello.

Formato: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>

Esempio: runs:/<run-id>/model/

az ml model create --name my-model --version 1 --path runs:/<run-id>/model/ --type mlflow_model

Processo azureml

Questa opzione è un formato URI di riferimento azureml job, che consente di registrare un modello dagli artefatti in uno degli output del processo. Questo formato è allineato al formato URI di riferimento dell'archivio dati azureml esistente e supporta anche il riferimento agli artefatti degli output denominati del processo, non solo al percorso predefinito dell'artefatto. È possibile stabilire una derivazione tra un modello registrato e il processo da cui è stato sottoposto a training, se il modello non è stato registrato direttamente nello script di training usando MLflow.

Formato: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>

Esempi:

• Percorso predefinito dell'artefatto: azureml://jobs/<run-id>/outputs/artifacts/paths/model/
  • che equivale a runs:/<run-id>/model/.
  • artifacts è la parola chiave riservata per fare riferimento all'output che rappresenta il percorso predefinito dell'artefatto.
• Da una directory di output denominata: azureml://jobs/<run-id>/outputs/trained-model
• Da un percorso di file o cartella specifico all'interno della directory di output denominata:
  • azureml://jobs/<run-id>/outputs/trained-model/paths/cifar.pt
  • azureml://jobs/<run-id>/outputs/checkpoints/paths/model/

Salvataggio del modello da un output denominato:

az ml model create --name my-model --version 1 --path azureml://jobs/<run-id>/outputs/trained-model

Per un esempio completo, vedere le informazioni di riferimento sull'interfaccia della riga di comando.

Registrare il modello come asset in Machine Learning usando l'SDK

Usare le schede seguenti per selezionare la posizione in cui si trova il modello.

Modello locale

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

file_model = Model(
    path="mlflow-model/model.pkl",
    type=AssetTypes.CUSTOM_MODEL,
    name="local-file-example",
    description="Model created from local file.",
)
ml_client.models.create_or_update(file_model)

Datastore

È possibile creare un modello da un percorso cloud usando uno dei formati URI supportati seguenti.

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

cloud_model = Model(
    path=file_model.path,
    # The above line basically provides a path in the format "azureml://subscriptions/XXXXXXXXXXXXXXXX/resourceGroups/XXXXXXXXXXX/workspaces/XXXXXXXXXXX/datastores/workspaceblobstore/paths/model.pkl"
    # Users could also use,"azureml://datastores/workspaceblobstore/paths/model.pkl" as a shorthand to the same location
    name="cloud-path-example",
    type=AssetTypes.CUSTOM_MODEL,
    description="Model created from cloud path.",
)
ml_client.models.create_or_update(cloud_model)

Negli esempi viene usato lo schema azureml abbreviato per puntare a un percorso in datastore usando la sintassi azureml://datastores/${{datastore-name}}/paths/${{path_on_datastore}}.

Output del processo

In questo caso sono disponibili due opzioni. È possibile usare il formato URI di esecuzione di MLflow oppure usare il formato URI azureml job.

MLflow

Questa opzione è ottimizzata per gli utenti di MLflow, che probabilmente hanno già familiarità con il formato URI di esecuzione di MLflow. Questa opzione consente di creare un modello dagli artefatti nella posizione predefinita dell'artefatto, in cui si trovano tutti i modelli e gli artefatti con registrazione in MLflow. In questo modo viene stabilita una derivazione tra un modello registrato e l'esecuzione da cui proviene il modello.

Formato: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>

Esempio: runs:/<run-id>/model/

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

run_model = Model(
    path="runs:/<run-id>/model/"
    name="run-model-example",
    description="Model created from run.",
    type=ModelType.MLFLOW
)

ml_client.models.create_or_update(run_model) 

Processo azureml

Questa opzione è un formato URI di riferimento azureml job, che consente di registrare un modello dagli artefatti in uno degli output del processo. Questo formato è allineato al formato URI di riferimento dell'archivio dati azureml esistente e supporta anche il riferimento agli artefatti degli output denominati del processo, non solo al percorso predefinito dell'artefatto. È possibile stabilire una derivazione tra un modello registrato e il processo da cui è stato sottoposto a training, se il modello non è stato registrato direttamente nello script di training usando MLflow.

Formato: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>

Esempi:

• Percorso predefinito dell'artefatto: azureml://jobs/<run-id>/outputs/artifacts/paths/model/
  • che equivale a runs:/<run-id>/model/.
  • artifacts è la parola chiave riservata per fare riferimento all'output che rappresenta il percorso predefinito dell'artefatto.
• Da una directory di output denominata: azureml://jobs/<run-id>/outputs/trained-model
• Da un percorso di file o cartella specifico all'interno della directory di output denominata:
  • azureml://jobs/<run-id>/outputs/trained-model/paths/cifar.pt
  • azureml://jobs/<run-id>/outputs/checkpoints/paths/model/

Salvataggio del modello da un output denominato:

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

job_name = "<JOB_NAME>"

run_model = Model(
    path=f"azureml://jobs/{job_name}/outputs/artifacts/paths/model/",
    name="run-model-example",
    description="Model created from run.",
    type=AssetTypes.MLFLOW_MODEL,
)
# Uncomment after adding required details above
# ml_client.models.create_or_update(run_model)

Per un esempio completo, vedere il notebook del modello.

Registrare il modello come asset in Machine Learning usando l'interfaccia utente

Per creare un modello in Machine Learning, aprire la pagina Modelli dall'interfaccia utente. Selezionare Registra modello e selezionare la posizione in cui si trova il modello. Compilare i campi obbligatori e quindi selezionare Registra.

---

Gestire i modelli

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

List

Elencare tutti i modelli nell'area di lavoro:

Interfaccia della riga di comando di Azure

az ml model list

Python SDK

models = ml_client.models.list()
for model in models:
    print(model.name)

Elencare tutte le versioni del modello con un determinato nome:

Interfaccia della riga di comando di Azure

az ml model list --name run-model-example

Python SDK

models = ml_client.models.list(name="run-model-example")
for model in models:
    print(model.version)

Mostra

Ottenere i dettagli di un modello specifico:

Interfaccia della riga di comando di Azure

az ml model show --name run-model-example --version 1

Python SDK

model_example = ml_client.models.get(name="run-model-example", version="1")
print(model_example)

Aggiornamento

Aggiornare le proprietà modificabili di un modello specifico:

Interfaccia della riga di comando di Azure

az ml model update --name  run-model-example --version 1 --set description="This is an updated description." --set tags.stage="Prod"

Python SDK

model_example.description="This is an updated description."
model_example.tags={"stage":"Prod"}
ml_client.models.create_or_update(model=model_example)

Importante

Per il modello è 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 del modello.

Archivio

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

Se non si specifica una versione, verranno archiviate tutte le versioni del modello con tale nome specificato. Se si crea una nuova versione del modello in un contenitore di modelli archiviati, anche la nuova versione verrà impostata automaticamente come archiviata.

Archiviare tutte le versioni di un modello:

Interfaccia della riga di comando di Azure

az ml model archive --name run-model-example

Python SDK

ml_client.models.archive(name="run-model-example")

Archiviare una versione specifica del modello:

Interfaccia della riga di comando di Azure

az ml model archive --name run-model-example --version 1

Python SDK

ml_client.models.archive(name="run-model-example", version="1")

Usare il modello per il training

L'SDK e l'interfaccia della riga di comando (v2) consentono anche di usare un modello in un processo di training come input o output.

Usare il modello come input in un processo

Interfaccia della riga di comando di Azure

Creare un file YAML di specifica del processo (<file-name>.yml). Specificare nella sezione inputs del processo:

1. Il valore per type, che indica se il modello è mlflow_model,custom_model o triton_model.
2. Il valore per path che indica la posizione in cui si trovano i dati. Può corrispondere a uno dei percorsi indicati nella sezione Percorsi supportati.

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json

# Possible Paths for models:
# AzureML Datastore: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
# MLflow run: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
# Job: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
# Model Asset: azureml:<my_model>:<version>

command: |
  ls ${{inputs.my_model}}
inputs:
  my_model:
    type: mlflow_model # List of all model types here: https://learn.microsoft.com/azure/machine-learning/reference-yaml-model#yaml-syntax
    path: ../../assets/model/mlflow-model
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

Eseguire quindi quanto segue nell'interfaccia della riga di comando

az ml job create -f <file-name>.yml

Per un esempio completo, vedere il repository GitHub del modello.

Python SDK

La classe Input consente di scrivere quanto segue:

1. Il valore per type, che indica se il modello è mlflow_model,custom_model o triton_model.
2. Il valore per path che indica la posizione in cui si trovano i dati. Può corrispondere a uno dei percorsi indicati nella sezione Percorsi supportati.

from azure.ai.ml import command
from azure.ai.ml.entities import Model
from azure.ai.ml import Input
from azure.ai.ml.constants import AssetTypes
from azure.ai.ml import MLClient

# Possible Asset Types for Data:
# AssetTypes.MLFLOW_MODEL
# AssetTypes.CUSTOM_MODEL
# AssetTypes.TRITON_MODEL

# Possible Paths for Model:
# Local path: mlflow-model/model.pkl
# Azure Machine Learning Datastore: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
# MLflow run: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
# Job: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
# Model Asset: azureml:<my_model>:<version>

my_job_inputs = {
    "input_model": Input(type=AssetTypes.MLFLOW_MODEL, path="mlflowmodel")
}

job = command(
    code="./src",  # local path where the code is stored
    command="ls ${{inputs.input_model}}",
    inputs=my_job_inputs,
    environment="AzureML-sklearn-0.24-ubuntu18.04-py37-cpu:9",
    compute="cpu-cluster",
)

# submit the command
returned_job = ml_client.jobs.create_or_update(job)
# get a URL for the status of the job
returned_job.services["Studio"].endpoint

Usare il modello come output in un processo

Nel processo è possibile scrivere un modello nell'archiviazione basata sul cloud usando output.

Interfaccia della riga di comando di Azure

Creare un file YAML di specifica del processo (<file-name>.yml), con la sezione outputs popolata con il tipo e il percorso in cui si vogliono scrivere i dati:

$schema: https://azuremlschemas.azureedge.net/latest/commandJob.schema.json

# Possible Paths for Model:
# Local path: mlflow-model/model.pkl
# AzureML Datastore: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
# MLflow run: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
# Job: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
# Model Asset: azureml:<my_model>:<version>

code: src
command: >-
  python hello-model-as-output.py 
  --input_model ${{inputs.input_model}} 
  --custom_model_output ${{outputs.output_folder}}
inputs:
  input_model: 
    type: mlflow_model # mlflow_model,custom_model, triton_model
    path: ../../assets/model/mlflow-model
outputs:
  output_folder: 
    type: custom_model # mlflow_model,custom_model, triton_model
environment: azureml://registries/azureml/environments/sklearn-1.0/labels/latest

Creare quindi un processo usando l'interfaccia della riga di comando:

az ml job create --file <file-name>.yml

Per un esempio completo, vedere il repository GitHub del modello.

Python SDK

from azure.ai.ml import command
from azure.ai.ml.entities import Model
from azure.ai.ml import Input, Output
from azure.ai.ml.constants import AssetTypes

# Possible Asset Types for Model:
# AssetTypes.MLFLOW_MODEL
# AssetTypes.CUSTOM_MODEL
# AssetTypes.TRITON_MODEL

# Possible Paths for Model:
# Local path: mlflow-model/model.pkl
# Azure Machine Learning Datastore: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
# MLflow run: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
# Job: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
# Model Asset: azureml:<my_model>:<version>

my_job_inputs = {
    "input_model": Input(type=AssetTypes.MLFLOW_MODEL, path="mlflow-model"),
    "input_data": Input(type=AssetTypes.URI_FILE, path="./mlflow-model/input_example.json"),
}

my_job_outputs = {
    "output_folder": Output(type=AssetTypes.CUSTOM_MODEL)
}

job = command(
    code="./src",  # local path where the code is stored
    command="python load_write_model.py --input_model ${{inputs.input_model}} --output_folder ${{outputs.output_folder}}",
    inputs=my_job_inputs,
    outputs=my_job_outputs,
    environment="AzureML-sklearn-0.24-ubuntu18.04-py37-cpu:9",
    compute="cpu-cluster",
)

# submit the command
returned_job = ml_client.create_or_update(job)
# get a URL for the status of the job
returned_job.services["Studio"].endpoint

Passaggi successivi

• Installare e configurare Python SDK v2
• Distribuzione senza codice per i modelli di MLflow
• Altre informazioni su MLflow e Azure Machine Learning