Trabajar con modelos registrados en Azure Machine Learning

SE APLICA A:Extensión ml de la CLI de Azure v2 (actual)SDK de Python azure-ai-ml v2 (actual)

En este artículo, obtendrá información sobre cómo registrar y trabajar con modelos en Azure Machine Learning mediante:

La interfaz de usuario de Estudio de Azure Machine Learning.
La CLI de Azure Machine Learning V2.
El SDK de Azure Machine Learning V2 para Python.

Aprenderá a:

Cree modelos registrados en el registro de modelos a partir de archivos locales, almacenes de datos o salidas de trabajo.
Trabaje con diferentes tipos de modelos, como modelos personalizados, MLflow y Triton.
Use modelos como entradas o salidas en trabajos de entrenamiento.
Administre el ciclo de vida de los recursos del modelo.

Registro de modelos

El registro del modelo le permite almacenar y versionar los modelos en el área de trabajo en la nube de Azure. El registro de modelos le permite organizar los modelos entrenados y llevar un seguimiento de los mismos. Puede registrar modelos como recursos en Azure Machine Learning mediante la CLI de Azure, el SDK de Python o la interfaz de usuario de Estudio de Machine Learning.

Rutas de acceso admitidas

Para registrar un modelo, especifique una ruta de acceso que apunte a los datos o la ubicación del trabajo. En la tabla siguiente se muestran las distintas ubicaciones de datos compatibles con Azure Machine Learning y la sintaxis del parámetro path:

Ubicación	Sintaxis
Equipo local	`<model-folder>/<model-filename>`
Almacén de datos de Azure Machine Learning	`azureml://datastores/<datastore-name>/paths/<path_on_datastore>`
Trabajo de Azure Machine Learning	`azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>`
Trabajo de MLflow	`runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>`
Recurso de modelo en un área de trabajo de Machine Learning	`azureml:<model-name>:<version>`
Recurso de modelo en un registro de Machine Learning	`azureml://registries/<registry-name>/models/<model-name>/versions/<version>`

Modos admitidos

Cuando use modelos para entradas o salidas, especifique uno de los modos siguientes. Por ejemplo, especifique si el modelo debe montarse como de solo lectura o descargarse en el destino de proceso.

ro_mount: montaje de los datos en el destino de proceso como de solo lectura.
rw_mount: montaje de los datos como de lectura y escritura.
download: descarga de los datos en el destino de proceso.
upload: carga de los datos desde el destino de proceso.
direct: pase del URI como una cadena.

En la tabla siguiente se muestran las opciones de modo disponibles para las distintas entradas y salidas del tipo de modelo.

Tipo	`upload`	`download`	`ro_mount`	`rw_mount`	`direct`
Entrada de archivo `custom`
Entrada de carpeta `custom`		✓	✓		✓
Entrada `mlflow`		✓	✓
Salida de archivo `custom`	✓			✓	✓
Salida de carpeta `custom`	✓			✓	✓
Resultado de `mlflow`	✓			✓	✓

Requisitos previos

Una suscripción de Azure con una versión gratuita o de pago de Azure Machine Learning. si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.
Un área de trabajo de Azure Machine Learning.

Para ejecutar los ejemplos de código de este artículo y trabajar con la CLI de Azure Machine Learning V2 o el SDK de Azure Machine Learning V2 de Python, también necesita lo siguiente:

CLI de Azure
SDK de Python

CLI de Azure versión 2.38.0 o posterior instalada.
V2 de la extensión ml instalada mediante la ejecución del siguiente comando. Para obtener más información, consulte Instalación, configuración y uso de la CLI (v2).
```
az extension add -n ml
```

Nota:

V2 proporciona compatibilidad completa con versiones anteriores. Todavía puede usar recursos de modelo desde el SDK v1 o la CLI. El tipo custom se asigna a todos los modelos registrados con el SDK v1 o la CLI.

Registro de un modelo mediante la interfaz de usuario de Estudio

Para registrar un modelo mediante la interfaz de usuario de Estudio de Azure Machine Learning:

En el área de trabajo de Estudio, seleccione Modelos en el panel de navegación izquierdo.
En la página Lista de modelos, seleccione Registrar y seleccione una de las siguientes ubicaciones en la lista desplegable:
- Desde archivos locales
- Desde una salida de trabajo
- Desde el almacén de datos
- Desde archivos locales (basados en el marco)
En la primera pantalla Registrar modelo:
1. Vaya al archivo local, el almacén de datos o la salida de trabajo para el modelo.
2. Seleccione el tipo de modelo de entrada: MLflow, Triton o Tipo no especificado.
En la pantalla Configuración del modelo, proporcione un nombre y otra configuración opcional para el modelo registrado y seleccione Siguiente.
En la pantalla Revisar, revise la configuración y, a continuación, seleccione Registrar.

Registro de un modelo mediante la CLI de Azure o el SDK de Python

Los fragmentos de código siguientes muestran cómo registrar un modelo como un recurso en Azure Machine Learning mediante la CLI de Azure o el SDK de Python. Estos fragmentos de código usan tipos de modelo custom y mlflow.

El tipo custom hace referencia a un archivo de modelo o carpeta entrenado con un estándar personalizado no admitido actualmente por Azure Machine Learning.
El tipo mlflow hace referencia a un modelo entrenado con MLflow. Los modelos entrenados de MLflow están en una carpeta que contiene el archivo MLmodel, el archivo del modelo, el archivo de las dependencias de Conda y el archivo requirements.txt.

Sugerencia

Puede seguir las versiones de Python de los ejemplos siguientes ejecutando el cuaderno model.ipynb en el repositorio azureml-examples.

Conexión con su área de trabajo

El área de trabajo es el recurso de nivel superior de Azure Machine Learning. Proporciona un lugar centralizado para trabajar con todos los artefactos que se crean al usar Azure Machine Learning. En esta sección, se conectará al área de trabajo de Azure Machine Learning para crear el modelo registrado.

CLI de Azure
SDK de Python

Inicie sesión en Azure ejecutando az login y siguiendo las indicaciones.
En los comandos siguientes, reemplace los marcadores <subscription-id>, <workspace-name>, <resource-group> y <location> por los valores de su entorno.
```
az account set --subscription <subscription-id>
az configure --defaults workspace=<workspace-name> group=<resource-group> location=<location>
```

Importe las bibliotecas necesarias.

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

Configure los detalles del área de trabajo y obtenga un controlador para el área de trabajo. En el siguiente fragmento de código, reemplace los marcadores de posición <subscription-id>, <resource-group> y <workspace-name> por los valores de su entorno.
```
subscription_id = "<subscription-id>"
resource_group = "<resource-group>"
workspace = "<workspace-name>"

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

Crear el modelo registrado

Puede crear un modelo registrado a partir de un modelo que:

Esté ubicado en el equipo local.
Esté ubicado en un almacén de datos de Azure Machine Learning.
Sea una salida de un trabajo de Azure Machine Learning.

Cree un archivo YAML <file-name>.yml. En el archivo, proporcione un nombre para el modelo registrado, una ruta de acceso al archivo de modelo local y una descripción. Por ejemplo:
```
$schema: https://azuremlschemas.azureedge.net/latest/model.schema.json
name: local-file-example
path: mlflow-model/model.pkl
description: Model created from local file.
```
Ejecute el siguiente comando con el nombre del archivo YAML:
```
az ml model create -f <file-name>.yml
```

Para un ejemplo completo, consulte el modelo YAML.

En el ejemplo siguiente se muestra cómo crear un modelo registrado a partir de un archivo local.

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)

Almacén de datos

Puede crear un modelo a partir de una ruta de acceso a la nube mediante cualquiera de los formatos de URI admitidos.

CLI de Azure
SDK de Python

En el ejemplo siguiente se usa el esquema abreviado azureml para apuntar a una ruta de acceso en el almacén de datos mediante la sintaxis 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

Para un ejemplo completo, consulte la referencia de la CLI.

En el ejemplo siguiente se usa el esquema abreviado azureml para apuntar a una ruta de acceso en el almacén de datos mediante la sintaxis 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)

Resultado del trabajo

Si los datos del modelo proceden de una salida de trabajo, tiene dos opciones para especificar la ruta de acceso del modelo. Puede usar el formato de URI runs: de MLflow o el formato de URI azureml://jobs.

Nota:

La palabra clave reservada artifacts representa la salida de la ubicación predeterminada del artefacto.

Ejecuciones de MLflow: formato de URI

Esta opción funciona mejor para los usuarios de MLflow, que probablemente ya estén familiarizados con el formato URI de MLflow runs: . Crea un modelo a partir de artefactos en la ubicación predeterminada del artefacto, donde están todos los modelos y artefactos registrados por MLflow. Esta opción también establece un linaje entre un modelo registrado y la ejecución de la que procede el modelo.

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

Ejemplo:
- CLI de Azure
- SDK de Python
```
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 AssetTypes

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

ml_client.models.create_or_update(run_model) 
```

Formato de URI azureml://jobs

Utilice el URI de referencia azureml://jobs para registrar un modelo a partir de artefactos en cualquiera de las rutas de salida del trabajo. Este formato se alinea con el formato de azureml://datastores URI de referencia. También admite la referencia a artefactos de salidas con nombre diferentes a la ubicación predeterminada de los artefactos.

Si no registró directamente el modelo dentro del script de entrenamiento mediante MLflow, use esta opción para establecer un linaje entre un modelo registrado y el trabajo que entrenó.

Formato: azureml://jobs/<run-id>/outputs/<output-name>/paths/<path-to-model>
- Ubicación predeterminada del artefacto: azureml://jobs/<run-id>/outputs/artifacts/paths/<path-to-model>/. Esta ubicación es equivalente al runs:/<run-id>/<model> de MLflow.
- Carpeta de salida con nombre: azureml://jobs/<run-id>/outputs/<named-output-folder>
- Archivo específico dentro de la carpeta de salida con nombre: azureml://jobs/<run-id>/outputs/<named-output-folder>/paths/<model-filename>
- Ruta de acceso de la carpeta específica dentro de la carpeta de salida con nombre: azureml://jobs/<run-id>/outputs/<named-output-folder>/paths/<model-folder-name>
Ejemplo:
- CLI de Azure
- SDK de Python
Guardar un modelo desde una carpeta de salida con nombre:
```
az ml model create --name run-model-example --version 1 --path azureml://jobs/my_run_0000000000/outputs/artifacts/paths/model/
```
Para un ejemplo completo, consulte la referencia de la CLI.
Guardar un modelo desde una salida con nombre:
```
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)
```
Para un ejemplo completo, consulte el cuaderno del modelo.

Usar modelos para el entrenamiento

La CLI de Azure v2 y el SDK de Python también permiten usar modelos como entradas o salidas en trabajos de entrenamiento.

Usar un modelo como entrada en un trabajo de entrenamiento

CLI de Azure
SDK de Python

Cree un archivo YAML de especificación de trabajo, <file-name>.yml. En la sección inputs del trabajo, especifique:

El modelo type, que puede ser mlflow_model, custom_model o triton_model.
El path donde se encuentra el modelo. Puede usar cualquiera de las rutas de acceso enumeradas en el comentario del ejemplo siguiente.

$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

Ejecute el comando siguiente, sustituyendo el nombre de archivo YAML.
```
az ml job create -f <file-name>.yml
```

Para obtener un ejemplo completo, consulte el repositorio de GitHub del modelo.

La Input clase le permite definir:

El tipo de recurso de modelo, que puede ser uno de los siguientes valores:
- AssetTypes.CUSTOM_MODEL
- AssetTypes.MLFLOW_MODEL
- AssetTypes.TRITON_MODEL
path a los datos del modelo, que puede ser una de las siguientes ubicaciones:
- Ruta de acceso local: <model-folder>/<model-filename>
- Almacén de datos de Azure Machine Learning: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
- Ejecución de MLflow: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
- Trabajo: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
- Recurso de modelo: azureml:<my_model>:<version>

En el ejemplo siguiente se introduce un modelo de MLflow desde una carpeta local.

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://registries/azureml/environments/sklearn-1.5-ubuntu20.04-py310-cpu/labels/latest",
    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

Escribir un modelo como salida para un trabajo

El trabajo puede escribir un modelo en el almacenamiento basado en la nube mediante salidas.

CLI de Azure
SDK de Python

Cree un archivo YAML de especificación de trabajo <file-name>.yml. Rellene la outputs sección con el tipo de modelo de salida y la ruta de acceso.

$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

Cree un trabajo mediante la CLI:

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

Para obtener un ejemplo completo, consulte el repositorio de GitHub del modelo.

La Output clase le permite especificar:

El tipo de recurso de modelo, que puede ser uno de los siguientes valores:
- AssetTypes.CUSTOM_MODEL
- AssetTypes.MLFLOW_MODEL
- AssetTypes.TRITON_MODEL
path de los datos del modelo, que puede ser una de las siguientes ubicaciones:
- Ruta de acceso local: mlflow-model/model.pkl
- Almacén de datos de Azure Machine Learning: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
- Ejecución de MLflow: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
- Trabajo: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
- Recurso de modelo: azureml:<my_model>:<version>

En el ejemplo siguiente se crea una salida que monta el almacén de datos predeterminado en modo de lectura y escritura. El código carga el modelo MLflow local como entrada y exporta el mismo modelo como una salida del trabajo, guardado en la tienda de datos montada.

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://registries/azureml/environments/sklearn-1.5-ubuntu20.04-py310-cpu/labels/latest",
    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

Administración de modelos

Puede usar la CLI de Azure y el SDK de Python para administrar el ciclo de vida de los recursos del modelo de Azure Machine Learning.

Lista

CLI de Azure
SDK de Python

Enumerar todos los modelos del área de trabajo:

az ml model list

Enumerar todas las versiones del modelo con un nombre determinado:

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

Enumerar todos los modelos del área de trabajo:

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

Enumerar todas las versiones del modelo con un nombre determinado:

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

Presentación

Obtener los detalles de un modelo específico:

CLI de Azure
SDK de Python

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)

Actualizar

Actualizar propiedades mutables de un modelo específico:

Importante

En el caso de los modelos, solo puede actualizar las propiedades description y tags. Todas las demás propiedades son inmutables. Para cambiar estas propiedades, cree una nueva versión del modelo.

CLI de Azure
SDK de Python

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)

Archivo

El archivado de un modelo lo oculta de las consultas de lista como az ml model list de manera predeterminada. Todavía puede seguir haciendo referencia a un modelo archivado y usarlo en los flujos de trabajo.

Puede archivar todas las versiones o solo versiones específicas de un modelo. Si no especifica una versión, el comando archiva todas las versiones del modelo. Si crea una nueva versión del modelo en un contenedor de modelo archivado, la nueva versión se establece automáticamente como archivada.

CLI de Azure
SDK de Python

Archivar una versión de modelo específica:

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