Usare i modelli registrati in Azure Machine Learning

Articolo
10/16/2024

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

Questo articolo illustra come registrare e usare i modelli in Azure Machine Learning usando:

Interfaccia utente di Studio di Azure Machine Learning.
Interfaccia della riga di comando V2 di Azure Machine Learning.
The Python Azure Machine Learning V2 SDK.

Scopri come:

Creare modelli registrati nel Registro di sistema dei modelli da file, archivi dati o output del processo locali.
Lavorare con differenti tipi di modelli, ad esempio personalizzati, MLflow e Sicuramente.
Usare i modelli come input o output nei processi di training.
Gestire il ciclo di vita degli asset del modello.

Registrazione del modello

La registrazione dei modelli consente di archiviare i modelli e creare le relative versioni nel cloud di Azure, all'interno della propria area di lavoro. Il registro modelli consente di organizzare i modelli sottoposti a training e tenerne traccia. È possibile registrare i modelli come asset in Azure Machine Learning usando l'interfaccia della riga di comando di Azure, Python SDK o l'interfaccia utente di Machine Learning Studio.

Percorsi supportati

Per registrare un modello, è necessario specificare un percorso che punta ai dati o alla posizione del processo. La tabella seguente illustra le varie posizioni dei dati supportate da Azure Machine Learning e la sintassi per il parametro path:

Ufficio	Sintassi
Computer locale	`<model-folder>/<model-filename>`
Archivio dati di Azure Machine Learning	`azureml://datastores/<datastore-name>/paths/<path_on_datastore>`
Processo di Azure Machine Learning	`azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>`
Processo MLflow	`runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>`
Asset del modello in un'area di lavoro di Machine Learning	`azureml:<model-name>:<version>`
Asset del modello in un registro di Machine Learning	`azureml://registries/<registry-name>/models/<model-name>/versions/<version>`

Modalità supportate

Quando si usano modelli per input o output, è possibile specificare una delle modalità seguenti. Ad esempio, è possibile specificare se il modello deve essere montato o scaricato in sola lettura nella destinazione di calcolo.

ro_mount: montare i dati nella destinazione di calcolo come di sola lettura.
rw_mount: montaggio in lettura/scrittura dei dati.
download: scaricare i dati nella destinazione di calcolo.
upload: caricare i dati dalla destinazione di calcolo.
direct: passare l'URI come stringa.

Nella tabella seguente vengono illustrate le opzioni disponibili per input e output del tipo di modello differenti.

Type	`upload`	`download`	`ro_mount`	`rw_mount`	`direct`
Input di file `custom`
Input di cartella `custom`		✓	✓		✓
Input `mlflow`		✓	✓
Output di file `custom`	✓			✓	✓
`custom` output della cartella	✓			✓	✓
Output `mlflow`	✓			✓	✓

Prerequisiti

Una sottoscrizione di Azure con una versione gratuita o a pagamento di Azure Machine Learning. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
Un'area di lavoro di Azure Machine Learning.

Per eseguire gli esempi di codice in questo articolo e usare l'interfaccia della riga di comando di Azure Machine Learning V2 o Python Azure Machine Learning V2 SDK, è necessario:

Interfaccia della riga di comando di Azure
Python SDK

Interfaccia della riga di comando di Azure versione 2.38.0 o successive installata.
V2 dell'estensione ml installata eseguendo il comando seguente. Per altre informazioni, vedere Installare, configurare e usare l'interfaccia della riga di comando (v2).
```
az extension add -n ml
```

Nota

La versione 2 offre la compatibilità completa con le versioni precedenti. È comunque possibile usare gli asset del modello dall'SDK v1 o dall'interfaccia della riga di comando. A tutti i modelli registrati con l'interfaccia della riga di comando o SDK v1 viene assegnato il tipo custom.

Registrare un modello usando l'interfaccia utente di Studio

Per registrare un modello usando l'interfaccia utente di Studio di Azure Machine Learning:

Nell'area di lavoro in studio selezionare Modelli nel riquadro di spostamento a sinistra.
Nella pagina Elenco modelli selezionare Registra, quindi selezionare una delle posizioni seguenti nell'elenco a discesa:
- Da file locali
- Dall'output di un processo
- Da archivio dati
- Da file locali (basati sul framework)
Nella prima schermata Registra modello:
1. Passare al file locale, all'archivio dati o all'output del processo per il modello.
2. Selezionare il tipo di modello di input: MLflow, Tritono Tipo non specificato.
Nella schermata Impostazioni modello specificare un nome e altre impostazioni facoltative per il modello registrato e selezionare Avanti.
Nella schermata Rivedi prendere in esame la configurazione quindi selezionare Registra.

Registrare un modello usando l'interfaccia della riga di comando di Azure o Python SDK

I frammenti di codice seguenti illustrano come registrare un modello come asset in Azure Machine Learning usando l'interfaccia della riga di comando di Azure o Python SDK. Questi frammenti di codice usano i tipi di modello custom e mlflow.

Il tipo custom si riferisce a un file di modello o a una cartella sottoposta a training con uno standard personalizzato non attualmente supportato da Azure Machine Learning.
Il tipo mlflow 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.

Suggerimento

È possibile seguire le versioni Python degli esempi seguenti eseguendo il notebook model.ipynb nel repository azureml-examples.

Connettersi all'area di lavoro

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 connette all'area di lavoro di Azure Machine Learning per creare il modello registrato.

Interfaccia della riga di comando di Azure
Python SDK

Accedere ad Azure eseguendo az login e seguendo le istruzioni.

Nei comandi seguenti sostituire i segnaposto <subscription-id>, <workspace-name>, <resource-group> e <location> con i valori per l'ambiente.

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

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

Configurare i dettagli e ottenere un handle per l'area di lavoro. Nel frammento di codice seguente sostituire i segnaposto <subscription-id>, <resource-group> e <workspace-name> con i valori per l'ambiente.
```
subscription_id = "<subscription-id>"
resource_group = "<resource-group>"
workspace = "<workspace-name>"

ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)
```

Creare il modello registrato

È possibile creare un modello registrato da un modello che è:

Situato nel computer locale.
Situato in un archivio dati di Azure Machine Learning.
Output da un processo di Azure Machine Learning.

File o cartella locale

Interfaccia della riga di comando di Azure
Python SDK

Creare un file YAML <file-name>.yml. Nel file specificare un nome per il modello registrato, un percorso del file del modello locale e una descrizione. Ad esempio:

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

Eseguire il comando seguente usando il nome del file YAML:
```
az ml model create -f <file-name>.yml
```

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

Nell'esempio seguente viene illustrata la creazione di un modello registrato da un file 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.

Interfaccia della riga di comando di Azure
Python SDK

Nell'esempio seguente viene usato lo schema azureml abbreviato per puntare a un percorso nell'archivio dati tramite la sintassi azureml://datastores/<datastore-name>/paths/<path_on_datastore>.

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

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

Nell'esempio seguente viene usato lo schema azureml abbreviato per puntare a un percorso nell'archivio dati tramite la sintassi azureml://datastores/${{datastore-name}}/paths/${{path_on_datastore}}.

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)

Output del processo

Se i dati del modello provengono da un output del processo, sono disponibili due opzioni per specificare il percorso del modello. È possibile usare il formato URI MLflow runs: o il formato URI azureml://jobs.

Nota

La parola chiave riservata artefatti rappresenta l'output dal percorso predefinito dell'artefatto.

Esecuzioni di MLflow: formato URI

Questa opzione è ottimizzata per gli utenti di MLflow, che probabilmente hanno già familiarità con il formato URI runs: MLflow. Questa opzione crea un modello dagli artefatti nella posizione predefinita dell'artefatto, in cui si trovano tutti i modelli e gli artefatti con registrazione in MLflow. Questa opzione stabilisce anche 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:
- Interfaccia della riga di comando di Azure
- Python SDK
```
az ml model create --name my-registered-model --version 1 --path runs:/my_run_0000000000/model/ --type mlflow_model
```
```
from azure.ai.ml.entities import Model
from azure.ai.ml.constants import ModelType

run_model = Model(
    path="runs:/my_run_0000000000/model/"
    name="my-registered-model",
    description="Model created from run.",
    type=ModelType.MLFLOW_MODEL
)

ml_client.models.create_or_update(run_model) 
```

formato URI azureml://jobs

L'opzione URI di riferimento azureml://jobs consente di registrare un modello dagli artefatti in uno dei percorsi di output del processo. Questo formato è allineato al formato URI di riferimento azureml://datastores e supporta anche il riferimento agli artefatti da output denominati diversi dal percorso predefinito dell'artefatto.

Se non si ha registrato direttamente il modello nello script di training usando MLflow, è possibile usare questa opzione per stabilire una derivazione tra un modello registrato e il processo da cui è stato sottoposto a training.

Formato: azureml://jobs/<run-id>/outputs/<output-name>/paths/<path-to-model>
- Percorso predefinito dell'artefatto: azureml://jobs/<run-id>/outputs/artifacts/paths/<path-to-model>/. Questa posizione equivale a MLflow runs:/<run-id>/<model>.
- Cartella output denominata: azureml://jobs/<run-id>/outputs/<named-output-folder>
- File specifico all'interno della cartella di output denominata: azureml://jobs/<run-id>/outputs/<named-output-folder>/paths/<model-filename>
- Percorso di cartella specifico all'interno della cartella di output denominata: azureml://jobs/<run-id>/outputs/<named-output-folder>/paths/<model-folder-name>
Esempio:
- Interfaccia della riga di comando di Azure
- Python SDK
Salvare un modello da una cartella di output denominata:
```
az ml model create --name run-model-example --version 1 --path azureml://jobs/my_run_0000000000/outputs/artifacts/paths/model/
```
Per un esempio completo, vedere le informazioni di riferimento sull'interfaccia della riga di comando.
Salvare un 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.

Usare i modelli per il training

L'interfaccia della riga di comando di Azure v2 e Python SDK consentono anche di usare i modelli come input o output nei processi di training.

Usare un modello come input in un processo di training

Interfaccia della riga di comando di Azure
Python SDK

Creare un file YAML di specifica del processo, <file-name>.yml. Nella sezione inputs del processo specificare:

Modello type, che può essere mlflow_model, custom_model o triton_model.
Oggetto path in cui si trova il modello, che può essere uno dei percorsi elencati nel commento dell'esempio seguente.

$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.5/labels/latest

Eseguire il comando seguente sostituendo il nome file YAML.
```
az ml job create -f <file-name>.yml
```

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

La classe Input consente di scrivere quanto segue:

Tipo di asset del modello, che può essere uno dei valori seguenti:
- AssetTypes.CUSTOM_MODEL
- AssetTypes.MLFLOW_MODEL
- AssetTypes.TRITON_MODEL
path per i dati del modello, che possono essere una delle posizioni seguenti:
- Percorso locale: <model-folder>/<model-filename>
- Archivio dati di Azure Machine Learning: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
- Esecuzione di MLflow: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
- Processo: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
- Asset del modello: azureml:<my_model>:<version>

Nell'esempio seguente viene immesso un modello MLflow da una cartella locale.

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

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

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

Scrivere un modello come output per un processo

Il processo può scrivere un modello nell'archiviazione basata sul cloud usando gli output.

Interfaccia della riga di comando di Azure
Python SDK

Creare un file YAML di specifica del processo <file-name>.yml. Popolare la sezione outputs con il tipo e il percorso del modello di output.

$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.5/labels/latest

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

La classe Output consente di scrivere quanto segue:

Tipo di asset del modello, che può essere uno dei valori seguenti:
- AssetTypes.CUSTOM_MODEL
- AssetTypes.MLFLOW_MODEL
- AssetTypes.TRITON_MODEL
path per i dati del modello, che possono essere una delle posizioni seguenti:
- Percorso locale: mlflow-model/model.pkl
- Archivio dati di Azure Machine Learning: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
- Esecuzione di MLflow: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
- Processo: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
- Asset del modello: azureml:<my_model>:<version>

Nell'esempio seguente viene creato un output che monta l'archivio dati predefinito in modalità lettura/scrittura. Il codice carica semplicemente il modello MLflow locale come input ed esporta lo stesso modello di un output del processo salvato nell'archivio dati montato.

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

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

Gestire i modelli

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

List

Interfaccia della riga di comando di Azure
Python SDK

Elencare tutti i modelli nell'area di lavoro:

az ml model list

Elencare tutte le versioni del modello con un determinato nome:

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

Elencare tutti i modelli nell'area di lavoro:

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

Elencare tutte le versioni del modello con un determinato nome:

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
Python SDK

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

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

Aggiornamento

Aggiornare le proprietà modificabili di un modello specifico:

Importante

Per i modelli è possibile aggiornare solo description e tags. Tutte le altre proprietà non sono modificabili e, se è necessario modificarle, è necessario creare una nuova versione del modello.

Interfaccia della riga di comando di Azure
Python SDK

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

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

Archivio

Per impostazione predefinita, l'archiviazione di un modello lo nasconde alle query di elenco come az ml model list. È possibile continuare a fare riferimento e usare un modello archiviato nei flussi di lavoro.

È possibile archiviare tutte le versioni o solo versioni specifiche di un modello. Se non si specifica una versione, tutte le versioni del modello vengono archiviate. Se si crea una nuova versione del modello in un contenitore di modelli archiviati, anche la nuova versione viene impostata automaticamente come archiviata.

Interfaccia della riga di comando di Azure
Python SDK

Archiviare tutte le versioni di un modello:

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

Archiviare una versione specifica del modello:

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

Archiviare tutte le versioni di un modello:

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

Archiviare una versione specifica del modello:

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

Condividi tramite

Usare i modelli registrati in Azure Machine Learning

Registrazione del modello

Percorsi supportati

Modalità supportate

Prerequisiti

Registrare un modello usando l'interfaccia utente di Studio

Registrare un modello usando l'interfaccia della riga di comando di Azure o Python SDK

Connettersi all'area di lavoro

Creare il modello registrato

File o cartella locale

Datastore

Output del processo

Usare i modelli per il training

Usare un modello come input in un processo di training

Scrivere un modello come output per un processo

Gestire i modelli

List

Mostra

Aggiornamento

Archivio

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Usare i modelli registrati in Azure Machine Learning

Registrazione del modello

Percorsi supportati

Modalità supportate

Prerequisiti

Registrare un modello usando l'interfaccia utente di Studio

Registrare un modello usando l'interfaccia della riga di comando di Azure o Python SDK

Connettersi all'area di lavoro

Creare il modello registrato

File o cartella locale

Datastore

Output del processo

Usare i modelli per il training

Usare un modello come input in un processo di training

Scrivere un modello come output per un processo

Gestire i modelli

List

Mostra

Aggiornamento

Archivio

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive