Trabalhar com modelos registrados no Azure Machine Learning

Artigo
09/03/2024

APLICA-SE A:Extensão de ML da CLI do Azure v2 (atual)SDK do Python azure-ai-ml v2 (atual)

Neste artigo, você aprenderá a registrar e trabalhar com modelos no Azure Machine Learning usando:

A interface do usuário do estúdio do Azure Machine Learning.
A CLI do Azure Machine Learning V2.
O SDK para Python V2 do Azure Machine Learning.

Você aprenderá como:

Crie modelos registrados no registro de modelo a partir de arquivos locais, armazenamentos de dados ou saídas de trabalho.
Trabalhe com diferentes tipos de modelos, como personalizado, MLflow e Triton.
Use modelos como entradas ou saídas em trabalhos de treinamento.
Gerencie o ciclo de vida dos ativos de modelo.

Registro do modelo

O Registro de modelos permite que você armazene e controle a versão de seus modelos no workspace na nuvem do Azure. O registro de modelos ajuda você a organizar e manter o controle sobre seus modelos treinados. Você pode registrar modelos como ativos no Azure Machine Learning usando a CLI do Azure, o SDK para Python ou a interface do usuário do estúdio do Machine Learning.

Caminhos com suporte

Para registrar um modelo, você precisa especificar um caminho que aponte para os dados ou o local do trabalho. A tabela a seguir mostra os vários locais de dados com suporte do Azure Machine Learning e a sintaxe do parâmetro path:

Localidade	Sintaxe
Computador local	`<model-folder>/<model-filename>`
Armazenamento de dados do Azure Machine Learning	`azureml://datastores/<datastore-name>/paths/<path_on_datastore>`
Trabalho do Azure Machine Learning	`azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>`
Trabalho do MLflow	`runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>`
Ativo de modelo em um workspace do Machine Learning	`azureml:<model-name>:<version>`
Ativo de modelo em um registro do Machine Learning	`azureml://registries/<registry-name>/models/<model-name>/versions/<version>`

Modos com suporte

Ao usar modelos para entradas ou saídas, você pode especificar um dos modos a seguir. Por exemplo, você pode especificar se o modelo deve ser montado como somente leitura ou baixado para o destino de computação.

ro_mount: monte os dados para o destino de computação como somente leitura.
rw_mount: monte os dados como leitura/gravação.
download: baixe os dados para o destino de computação.
upload: carregue os dados do destino de computação.
direct: passe o URI como uma cadeia de caracteres.

A tabela a seguir mostra as opções de modo disponíveis para diferentes entradas e saídas de tipo de modelo.

Tipo	`upload`	`download`	`ro_mount`	`rw_mount`	`direct`
Entrada do arquivo `custom`
Entrada de pasta `custom`		✓	✓		✓
Entrada `mlflow`		✓	✓
Saída do arquivo `custom`	✓			✓	✓
Saída da pasta `custom`	✓			✓	✓
Saída `mlflow`	✓			✓	✓

Pré-requisitos

Uma assinatura do Azure com uma versão gratuita ou paga do Azure Machine Learning. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.
Um workspace do Azure Machine Learning.

Para executar os exemplos de código neste artigo e trabalhar com a CLI do Azure Machine Learning V2 ou o SDK V2 para Python do Azure Machine Learning, você também precisa de:

CLI do Azure
SDK do Python

CLI do Azure versão 2.38.0 ou posterior instalada.
V2 da extensão ml instalada executando o comando a seguir. Para obter mais informações, confira Instalar, configurar e usar a CLI (v2).
```
az extension add -n ml
```

Observação

A V2 fornece compatibilidade total com versões anteriores. Você ainda pode usar ativos de modelo do SDK v1 ou da CLI. Todos os modelos registrados com a CLI ou o SDK v1 recebem o tipo custom.

Registrar um modelo usando a interface do usuário do estúdio

Para registrar um modelo usando a interface do usuário do estúdio do Azure Machine Learning:

Em seu workspace no estúdio, selecione Modelos na navegação à esquerda.
Na página Lista de Modelos, selecione Registrar e, em seguida, selecione um dos seguintes locais na lista suspensa:
- De arquivos locais
- De uma saída do trabalho
- Do armazenamento de dados
- De arquivos locais (com base na estrutura)
Na primeira tela de Registrar modelo:
1. Navegue até o arquivo local, o armazenamento de dados ou a saída do trabalho para o modelo.
2. Selecione o tipo de modelo de entrada: MLflow, Triton ou Tipo não especificado.
Na tela Configurações do modelo, forneça um nome e outras configurações opcionais para o modelo registrado e selecione Avançar.
Na tela Revisão, revise a configuração e selecione Registrar.

Registrar um modelo usando a CLI do Azure ou o SDK para Python

Os snippets de código a seguir abordam como registrar um modelo como um ativo no Azure Machine Learning usando a CLI do Azure ou o SDK para Python. Esses snippets de código usam os tipos de modelo custom e mlflow.

O tipo custom se refere a um arquivo ou pasta de modelo treinado com um padrão personalizado atualmente sem suporte do Azure Machine Learning.
O tipo mlflow refere-se a um modelo treinado com o MLflow. Os modelos treinados do MLflow estão em uma pasta que contém o arquivo MLmodel, o arquivo de modelo, o arquivo de dependências do conda e o arquivo requirements.txt.

Dica

Você pode acompanhar as versões do Python dos exemplos a seguir executando o notebook model.ipynb no repositório azureml-examples.

Conectar-se ao workspace

O workspace é o recurso de nível superior para o Azure Machine Learning. Ele fornece um local centralizado para trabalhar com todos os artefatos que você cria ao usar o Azure Machine Learning. Nesta seção, você se conectará ao workspace do Azure Machine Learning para criar o modelo registrado.

CLI do Azure
SDK do Python

Entre no Azure executando az login e seguindo os prompts.
Nos comandos a seguir, substitua os espaços reservados <subscription-id>, <workspace-name>, <resource-group> e <location> pelos valores do seu ambiente.
```
az account set --subscription <subscription-id>
az configure --defaults workspace=<workspace-name> group=<resource-group> location=<location>
```

Importe as bibliotecas necessárias:

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 os detalhes do workspace e obtenha um identificador para o workspace. No snippet de código a seguir, substitua os espaços reservados <subscription-id>, <resource-group> e <workspace-name> pelos valores do seu ambiente.
```
subscription_id = "<subscription-id>"
resource_group = "<resource-group>"
workspace = "<workspace-name>"

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

Criar o modelo registrado

Você pode criar um modelo registrado a partir de um modelo que:

Está no computador local.
Está em um armazenamento de dados do Azure Machine Learning.
Seja uma saída de um trabalho do Azure Machine Learning.

Crie um arquivo YAML <nome-do-arquivo>.yml. No arquivo, forneça um nome para o modelo registrado, um caminho para o arquivo de modelo local e uma descrição. Por exemplo:
```
$schema: https://azuremlschemas.azureedge.net/latest/model.schema.json
name: local-file-example
path: mlflow-model/model.pkl
description: Model created from local file.
```
Execute o seguinte comando usando o nome do arquivo YAML:
```
az ml model create -f <file-name>.yml
```

Para um exemplo completo, veja o modelo YAML.

O exemplo a seguir mostra a criação de um modelo registrado a partir de um arquivo 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)

Datastore

Você pode criar um modelo com base em um caminho de nuvem usando qualquer um dos formatos de URI com suporte.

CLI do Azure
SDK do Python

O exemplo a seguir usa o esquema de abreviação azureml para apontar para um caminho no armazenamento de dados usando a sintaxe 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 um exemplo completo, condira a Referência da CLI.

O exemplo a seguir usa o esquema de abreviação azureml para apontar para um caminho no armazenamento de dados usando a sintaxe 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)

Saída do trabalho

Se os dados do modelo forem provenientes de uma saída de trabalho, você terá duas opções para especificar o caminho do modelo. Você pode usar o formato de URI runs: do MLflow ou o formato de URI azureml://jobs.

Observação

A palavra-chave reservada de artefatos representa a saída do local do artefato padrão.

Execuções do MLflow: formato de URI

Essa opção é otimizada para usuários do MLflow que provavelmente já estão familiarizados com o formato de URI runs: do MLflow. Essa opção cria um modelo com base em artefatos do local padrão do artefato (em que todos os modelos e artefatos registrados no MLflow estão localizados). Isso estabelece uma linhagem entre um modelo registrado e a execução da qual o modelo veio.

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

Exemplo:
- CLI do Azure
- SDK do 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 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 de URI azureml://jobs

A opção URI de referência azureml://jobs permite registrar um modelo de artefatos em qualquer um dos caminhos de saída do trabalho. Esse formato se alinha ao formato de URI de referência azureml://datastores e também dá suporte à referência de artefatos de saídas nomeadas diferentes do local do artefato padrão.

Se você não registrou diretamente o modelo dentro do script de treinamento usando o MLflow, pode usar essa opção para estabelecer uma linhagem entre um modelo registrado e o trabalho por meio do qual ele foi treinado.

Formato: azureml://jobs/<run-id>/outputs/<output-name>/paths/<path-to-model>
- Local padrão do artefato: azureml://jobs/<run-id>/outputs/artifacts/paths/<path-to-model>/. Esse local é equivalente ao MLflow runs:/<run-id>/<model>.
- Pasta de saída nomeada: azureml://jobs/<run-id>/outputs/<named-output-folder>
- Arquivo específico dentro da pasta de saída nomeada: azureml://jobs/<run-id>/outputs/<named-output-folder>/paths/<model-filename>
- Caminho de pasta específico dentro da pasta de saída nomeada: azureml://jobs/<run-id>/outputs/<named-output-folder>/paths/<model-folder-name>
Exemplo:
- CLI do Azure
- SDK do Python
Salve um modelo a partir de uma pasta de saída nomeada:
```
az ml model create --name run-model-example --version 1 --path azureml://jobs/my_run_0000000000/outputs/artifacts/paths/model/
```
Para um exemplo completo, condira a Referência da CLI.
Salve um modelo a partir de uma saída nomeada:
```
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 um exemplo completo, veja o notebook de modelo.

Usar modelos para treinamento

A CLI do Azure e o SDK para Python v2 também permitem usar modelos como entradas ou saídas em trabalhos de treinamento.

Usar um modelo como entrada em um trabalho de treinamento

CLI do Azure
SDK do Python

Crie um arquivo YAML de especificação de trabalho, <nome-do-arquivo>.yml. Na seção inputs do trabalho, especifique:

O modelo type, que pode ser mlflow_model, custom_model ou triton_model.
O path em que o modelo está localizado, que pode ser qualquer um dos caminhos listados no comentário do exemplo a seguir.

$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://video2.skills-academy.com/azure/machine-learning/reference-yaml-model#yaml-syntax
    path: ../../assets/model/mlflow-model
environment: azureml://registries/azureml/environments/sklearn-1.5/labels/latest

Execute o comando a seguir, substituindo o nome do arquivo YAML.
```
az ml job create -f <file-name>.yml
```

Para obter um exemplo completo, confira o repositório de modelos do GitHub.

A classe Input permite que você defina:

O tipo de ativo de modelo, que pode ser um dos seguintes valores:
- AssetTypes.CUSTOM_MODEL
- AssetTypes.MLFLOW_MODEL
- AssetTypes.TRITON_MODEL
O path para seus dados do modelo, que podem ser um dos seguintes locais:
- Caminho local: <model-folder>/<model-filename>
- Armazenamento de dados do Azure Machine Learning: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
- Execução do MLflow: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
- Trabalho: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
- Ativo de modelo: azureml:<my_model>:<version>

O exemplo a seguir insere um modelo MLflow a partir de uma pasta 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-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

Gravar um modelo como saída para um trabalho

Seu trabalho pode gravar um modelo no armazenamento baseado em nuvem usando saídas.

CLI do Azure
SDK do Python

Crie um arquivo YAML de especificação de trabalho <nome-do-arquivo>.yml. Preencha a seção outputs com o tipo e o caminho do modelo de saída.

$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

Crie um trabalho usando a CLI:

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

Para obter um exemplo completo, confira o repositório de modelos do GitHub.

A classe Output permite que você defina:

O tipo de ativo de modelo, que pode ser um dos seguintes valores:
- AssetTypes.CUSTOM_MODEL
- AssetTypes.MLFLOW_MODEL
- AssetTypes.TRITON_MODEL
O path para seus dados do modelo, que podem ser um dos seguintes locais:
- Caminho local: mlflow-model/model.pkl
- Armazenamento de dados do Azure Machine Learning: azureml://datastores/<datastore-name>/paths/<path_on_datastore>
- Execução do MLflow: runs:/<run-id>/<path-to-model-relative-to-the-root-of-the-artifact-location>
- Trabalho: azureml://jobs/<job-name>/outputs/<output-name>/paths/<path-to-model-relative-to-the-named-output-location>
- Ativo de modelo: azureml:<my_model>:<version>

O exemplo a seguir cria uma saída que monta seu armazenamento de dados padrão no modo de leitura/gravação. O código simplesmente carrega o modelo do MLflow local como entrada e exporta o mesmo modelo como uma saída do trabalho salvo no armazenamento de dados montado.

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

Gerenciar modelos

A CLI do Azure e o SDK para Python também permitem gerenciar o ciclo de vida dos ativos de modelo do Azure Machine Learning.

Lista

CLI do Azure
SDK do Python

Liste todos os modelos em seu workspace:

az ml model list

Listar todas as versões de modelo em um determinado nome:

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

Liste todos os modelos em seu workspace:

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

Listar todas as versões de modelo em um determinado nome:

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

Mostrar

Obtenha os detalhes de um modelo específico:

CLI do Azure
SDK do 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)

Atualizar

Atualizar propriedades mutáveis de um modelo específico:

Importante

Para modelos, apenas description e tags podem ser atualizados. Todas as outras propriedades são imutáveis e, se você precisar alterá-las, deverá criar uma nova versão do modelo.

CLI do Azure
SDK do 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)

Arquivos

O arquivamento de um modelo o oculta de consultas de lista como az ml model list por padrão. Você ainda pode continuar a referenciar e usar um modelo arquivado em seus fluxos de trabalho.

Você pode arquivar todas as versões ou apenas versões específicas de um modelo. Se você não especificar uma versão, todas as versões do modelo serão arquivadas. Se você criar uma nova versão de modelo em um contêiner de modelos arquivados, essa nova versão será automaticamente definida como arquivada também.

CLI do Azure
SDK do Python

Arquivar todas as versões de um modelo:

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

Arquivar um modelo de versão específico:

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

Arquivar todas as versões de um modelo:

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

Arquivar um modelo de versão específico:

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

Compartilhar via

Trabalhar com modelos registrados no Azure Machine Learning

Registro do modelo

Caminhos com suporte

Modos com suporte

Pré-requisitos

Registrar um modelo usando a interface do usuário do estúdio

Registrar um modelo usando a CLI do Azure ou o SDK para Python

Conectar-se ao workspace

Criar o modelo registrado

Arquivo ou pasta local

Datastore

Saída do trabalho

Usar modelos para treinamento

Usar um modelo como entrada em um trabalho de treinamento

Gravar um modelo como saída para um trabalho

Gerenciar modelos

Lista

Mostrar

Atualizar

Arquivos

Comentários

Recursos adicionais

Compartilhar via

Trabalhar com modelos registrados no Azure Machine Learning

Registro do modelo

Caminhos com suporte

Modos com suporte

Pré-requisitos

Registrar um modelo usando a interface do usuário do estúdio

Registrar um modelo usando a CLI do Azure ou o SDK para Python

Conectar-se ao workspace

Criar o modelo registrado

Arquivo ou pasta local

Datastore

Saída do trabalho

Usar modelos para treinamento

Usar um modelo como entrada em um trabalho de treinamento

Gravar um modelo como saída para um trabalho

Gerenciar modelos

Lista

Mostrar

Atualizar

Arquivos

Conteúdo relacionado

Comentários

Recursos adicionais