Compartilhar modelos, componentes e ambientes entre espaços de trabalhos com registros (versão prévia)

  • Artigo

O registro do Azure Machine Learning permite que você colabore em workspaces em sua organização. Você pode compartilhar modelos, componentes e ambientes usando registros.

Há dois cenários em que você deve usar o mesmo conjunto de modelos, componentes e ambientes em vários workspaces:

  • MLOps entre workspaces: você está treinando um modelo em um workspace dev e precisa implantá-lo nos workspaces test e prod. Nesse caso, a linhagem de ponta a ponta deve estar entre os pontos de extremidade nos quais o modelo é implantado nos workspaces test ou prod e o trabalho de treinamento, métricas, código, dados e ambiente usados para treinar o modelo no workspace dev.
  • Compartilhar e reutilizar modelos e pipelines em diferentes equipes: o compartilhamento e a reutilização melhoram a colaboração e produtividade. Nesse cenário, pode ser desejável publicar um modelo treinado e os componentes e ambientes associados usados para treiná-lo para um catálogo central. A partir daí, colegas de outras equipes podem pesquisar e reutilizar os ativos compartilhados em seus próprios experimentos.

Neste artigo, você aprenderá a:

  • Crie um ambiente e um componente no registro.
  • Use o componente do registro para enviar um trabalho de treinamento do modelo em um workspace.
  • Registre o modelo treinado no registro.
  • Implante o modelo do registro em um ponto de extremidade online no workspace e envie uma solicitação de inferência.

Pré-requisitos

Antes de seguir as etapas neste artigo, verifique se você tem os seguintes pré-requisitos:

  • Um registro do Azure Machine Learning para compartilhar modelos, componentes e ambientes. Para criar um registro, consulte Saiba como criar um registro.

  • Um Workspace do Azure Machine Learning. Se você não tiver um, use as etapas do artigo Início Rápido: criar recursos de workspace para criar.

    Importante

    A região do Azure (localização) em que você cria seu workspace precisa estar na lista de regiões com suporte para o registro do Azure Machine Learning

  • A CLI do Azure e a extensão mlou o SDK do Python v2 do Azure Machine Learning:

    Para instalar a extensão e a CLI do Azure, consulte Instalar, configurar e usar a CLI (v2).

    Importante

    • Os exemplos de CLI neste artigo pressupõem que você esteja usando o shell Bash (ou compatível). Por exemplo, de um sistema Linux ou Subsistema do Windows para Linux.

    • Os exemplos também pressupõem que você configurou padrões para a CLI do Azure para que você não precise especificar os parâmetros para sua assinatura, workspace, grupo de recursos ou local. Para definir as configurações padrão, use os comandos a seguir. Substitua os seguintes parâmetros pelos valores para a sua configuração:

      • Substitua <subscription> por sua ID da assinatura do Azure.
      • Substitua <workspace> pelo nome do workspace do Azure Machine Learning.
      • Substitua <resource-group> pelo grupo de recursos do Azure que contém o workspace.
      • Substitua <location> pela região do Azure que contém o workspace.
      az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

      Para ver quais são seus padrões atuais, use o comando az configure -l.

Clonar repositório de exemplos

Os exemplos de código neste artigo baseiam-se no exemplo nyc_taxi_data_regression no repositório de exemplos. Para usar esses arquivos em seu ambiente de desenvolvimento, use os seguintes comandos para clonar o repositório e alterar os diretórios para o exemplo:

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

Para o exemplo da CLI, altere os diretórios para cli/jobs/pipelines-with-components/nyc_taxi_data_regression no clone local do repositório de exemplos.

cd cli/jobs/pipelines-with-components/nyc_taxi_data_regression

Criar conexão do SDK

Dica

Essa etapa só é necessária ao usar o SDK do Python.

Crie uma conexão de cliente com o workspace do Azure Machine Learning e o registro:

ml_client_workspace = MLClient( credential=credential,
    subscription_id = "<workspace-subscription>",
    resource_group_name = "<workspace-resource-group",
    workspace_name = "<workspace-name>")
print(ml_client_workspace)

ml_client_registry = MLClient(credential=credential,
                        registry_name="<REGISTRY_NAME>",
                        registry_location="<REGISTRY_REGION>")
print(ml_client_registry)

Criar um ambiente no registro

Os ambientes definem o contêiner do Docker e as dependências do Python necessárias para executar trabalhos de treinamento ou implantar modelos. Para obter mais informações sobre ambientes, consulte os seguintes artigos:

Dica

O mesmo comando da CLI az ml environment create pode ser usado para criar ambientes em um workspace ou registro. A execução do comando com o comando --workspace-name cria o ambiente em um workspace, enquanto a execução do comando com --registry-name cria o ambiente no registro.

Criaremos um ambiente que usa a imagem do docker python:3.8 e instala os pacotes do Python necessários para executar um trabalho de treinamento usando a estrutura do SciKit Learn. Se você clonou o repositório de exemplos e estiver na pasta cli/jobs/pipelines-with-components/nyc_taxi_data_regression, poderá ver o arquivo de definição de ambiente env_train.yml que faz referência ao arquivo do docker env_train/Dockerfile. env_train.yml é mostrado abaixo para referência:

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: SKLearnEnv
version: 1
build:
  path: ./env_train

Criar o ambiente usando az ml environment create, da seguinte forma

az ml environment create --file env_train.yml --registry-name <registry-name>

Se você receber um erro de que um ambiente com esse nome e versão já existe no Registro, poderá editar o campo version no env_train.yml ou especificar uma versão diferente na CLI que substitua o valor da versão em env_train.yml.

# use shell epoch time as the version
version=$(date +%s)
az ml environment create --file env_train.yml --registry-name <registry-name> --set version=$version

Dica

version=$(date +%s) funciona apenas no Linux. Substitua $version por um número aleatório se isso não funcionar.

Anote o name e version do ambiente da saída do comando az ml environment create e use-os com comandos az ml environment show da seguinte maneira. Você precisará do name e version na próxima seção ao criar um componente no registro.

az ml environment show --name SKLearnEnv --version 1 --registry-name <registry-name>

Dica

Se você usou um nome ou versão de ambiente diferente, substitua os parâmetros --name e --version adequadamente.

Você também pode usar az ml environment list --registry-name <registry-name> para listar todos os ambientes no registro.

Você pode navegar por todos os ambientes no Estúdio do Azure Machine Learning. Navegue até a interface do usuário global e procure a entrada Registros.

Captura de tela de ambientes no registro.

Criar um componente no registro

Os componentes são blocos de construção reutilizáveis de pipelines do Machine Learning no Azure Machine Learning. É possível empacotar o código, o comando, o ambiente, a interface de entrada e de saída de uma etapa de pipeline individual em um componente. Em seguida, você pode reutilizar o componente em vários pipelines sem precisar se preocupar com a portabilidade de dependências e com o código sempre que gravar um pipeline diferente.

A criação de um componente em um workspace permite que você use o componente em qualquer trabalho de pipeline dentro desse workspace. A criação de um componente em um registro permite que você use o componente em qualquer pipeline em qualquer workspace na organização. A criação de componentes em um registro é uma ótima maneira de criar utilitários reutilizáveis modulares ou tarefas de treinamento compartilhadas que podem ser usadas para experimentação por equipes diferentes na organização.

Para obter mais informações sobre componentes, consulte os seguintes artigos:

Verifique se você está na pasta cli/jobs/pipelines-with-components/nyc_taxi_data_regression. Você encontrará o arquivo de definição de componente train.yml que empacota um script de treinamento do Scikit Learn train_src/train.py e o ambiente coletadoAzureML-sklearn-0.24-ubuntu18.04-py37-cpu. Usaremos o ambiente do Scikit Learn criado em etapas anteriores, em vez do ambiente coletado. Você pode editar o campo environment no train.yml para se referir ao ambiente do Scikit Learn. O arquivo train.yml de definição do componente resultante será semelhante ao seguinte exemplo:

# <component>
$schema: https://azuremlschemas.azureedge.net/latest/commandComponent.schema.json
name: train_linear_regression_model
display_name: TrainLinearRegressionModel
version: 1
type: command
inputs:
  training_data: 
    type: uri_folder
  test_split_ratio:
    type: number
    min: 0
    max: 1
    default: 0.2
outputs:
  model_output:
    type: mlflow_model
  test_data:
    type: uri_folder
code: ./train_src
environment: azureml://registries/<registry-name>/environments/SKLearnEnv/versions/1`
command: >-
  python train.py 
  --training_data ${{inputs.training_data}} 
  --test_data ${{outputs.test_data}} 
  --model_output ${{outputs.model_output}}
  --test_split_ratio ${{inputs.test_split_ratio}}

Se você usou um nome ou uma versão diferente, a representação mais genérica terá esta aparência: environment: azureml://registries/<registry-name>/environments/<sklearn-environment-name>/versions/<sklearn-environment-version>, portanto, certifique-se de substituir o <registry-name>, <sklearn-environment-name> e <sklearn-environment-version> de acordo. Em seguida, execute o comando az ml component create para criar o componente da seguinte maneira.

az ml component create --file train.yml --registry-name <registry-name>

Dica

O mesmo comando da CLI az ml component create pode ser usado para criar componentes em um workspace ou registro. A execução do comando com o comando --workspace-name cria o componente em um workspace, enquanto a execução do comando com --registry-name cria o componente no registro.

Se preferir não editar train.yml, você poderá substituir o nome do ambiente na CLI da seguinte maneira:

az ml component create --file train.yml --registry-name <registry-name>` --set environment=azureml://registries/<registry-name>/environments/SKLearnEnv/versions/1
# or if you used a different name or version, replace `<sklearn-environment-name>` and `<sklearn-environment-version>` accordingly
az ml component create --file train.yml --registry-name <registry-name>` --set environment=azureml://registries/<registry-name>/environments/<sklearn-environment-name>/versions/<sklearn-environment-version>

Dica

Se você receber um erro de que o nome do componente já existe no Registro, será possível editar a versão train.yml ou substituir a versão na CLI por uma versão aleatória.

Anote o name e version do componente da saída do comando az ml component create e use-os com comandos az ml component show da seguinte maneira. Você precisará do name e version na próxima seção ao criar um trabalho de treinamento no workspace.

az ml component show --name <component_name> --version <component_version> --registry-name <registry-name>

Você também pode usar az ml component list --registry-name <registry-name> para listar todos os componentes no registro.

Navegue por todos os componentes no Estúdio do Azure Machine Learning. Navegue até a interface do usuário global e procure a entrada Registros.

Captura de tela dos componentes no registro.

Executar um trabalho de pipeline em um workspace usando o componente do registro

Ao executar um trabalho de pipeline que usa um componente de um registro, os recursos de computação e os dados de treinamento são locais para o workspace. Para obter mais informações sobre trabalho em execução, consulte os seguintes artigos:

Executaremos um trabalho de pipeline com o componente de treinamento do Scikit Learn criado na seção anterior para treinar um modelo. Verifique se você está na pasta cli/jobs/pipelines-with-components/nyc_taxi_data_regression. O conjunto de dados de treinamento está localizado na pasta data_transformed. Edite a seção component na seção train_job do arquivo single-job-pipeline.yml para fazer referência ao componente de treinamento criado na seção anterior. O single-job-pipeline.yml resultante é mostrado abaixo.

$schema: https://azuremlschemas.azureedge.net/latest/pipelineJob.schema.json
type: pipeline
display_name: nyc_taxi_data_regression_single_job
description: Single job pipeline to train regression model based on nyc taxi dataset

jobs:
  train_job:
    type: command
    component: azureml://registries/<registry-name>/component/train_linear_regression_model/versions/1
    compute: azureml:cpu-cluster
    inputs:
      training_data: 
        type: uri_folder
        path: ./data_transformed
    outputs:
      model_output: 
        type: mlflow_model
      test_data:

O aspecto principal é que esse pipeline será executado em um workspace usando um componente que não está no workspace específico. O componente está em um registro que pode ser usado com qualquer workspace em sua organização. Você pode executar esse trabalho de treinamento em qualquer workspace ao qual tenha acesso sem se preocupar em disponibilizar o código de treinamento e o ambiente nesse workspace.

Aviso

  • Antes de executar o trabalho de pipeline, confirme se o workspace no qual você executará o trabalho está em uma região do Azure compatível com o registro no qual o componente foi criado.
  • Confirme se o workspace tem um cluster de cálculo com o nome cpu-cluster ou edite o campo compute em jobs.train_job.compute com o nome da computação.

Execute o trabalho de pipeline com o comando az ml job create.

az ml job create --file single-job-pipeline.yml

Dica

Se você não tiver configurado o workspace e o grupo de recursos padrão, conforme explicado na seção de pré-requisitos, será necessário especificar os parâmetros --workspace-name e --resource-group para que az ml job create funcione.

Como alternativa, você pode ignorar a edição de single-job-pipeline.yml e substituir o nome do componente usado por train_job na CLI.

az ml job create --file single-job-pipeline.yml --set jobs.train_job.component=azureml://registries/<registry-name>/component/train_linear_regression_model/versions/1

Como o componente usado no trabalho de treinamento é compartilhado por meio de um registro, você pode enviar o trabalho para qualquer workspace ao qual você tenha acesso em sua organização, mesmo em assinaturas diferentes. Por exemplo, se você tiver dev-workspace, test-workspace e prod-workspace executando o trabalho de treinamento nesses três workspaces, será tão fácil quanto executar três comandos az ml job create.

az ml job create --file single-job-pipeline.yml --workspace-name dev-workspace --resource-group <resource-group-of-dev-workspace>
az ml job create --file single-job-pipeline.yml --workspace-name test-workspace --resource-group <resource-group-of-test-workspace>
az ml job create --file single-job-pipeline.yml --workspace-name prod-workspace --resource-group <resource-group-of-prod-workspace>

No Estúdio do Azure Machine Learning, selecione o link de ponto de extremidade na saída do trabalho para ver o trabalho. Aqui você pode analisar as métricas de treinamento, verificar se o trabalho está usando o componente e o ambiente do registro e examinar o modelo treinado. Anote o name do trabalho da saída ou encontre as mesmas informações da visão geral do trabalho no Estúdio do Azure Machine Learning. Você precisará dessas informações para baixar o modelo treinado na próxima seção sobre como criar modelos no registro.

Captura de tela do pipeline no Estúdio do Azure Machine Learning.

Criar um modelo no registro

Você aprenderá a criar modelos em um registro nesta seção. Confira Gerenciar modelos para saber mais sobre o gerenciamento de modelos no Azure Machine Learning. Examinaremos duas maneiras diferentes de criar um modelo em um registro. A primeira é a partir dos arquivos locais. A segunda é copiar um modelo registrado no workspace para um registro.

Em ambas as opções, você criará um modelo com o formato MLflow, o que ajudará a implantar esse modelo para inferência sem gravar um código de inferência.

Criar um modelo no registro a partir de arquivos locais

Baixe o modelo, que está disponível como saída de train_job substituindo <job-name> pelo nome do trabalho da seção anterior. O modelo juntamente com arquivos de metadados do MLflow devem estar disponíveis no ./artifacts/model/.

# fetch the name of the train_job by listing all child jobs of the pipeline job
train_job_name=$(az ml job list --parent-job-name <job-name> --query [0].name | sed 's/\"//g')
# download the default outputs of the train_job
az ml job download --name $train_job_name 
# review the model files
ls -l ./artifacts/model/

Dica

Se você não tiver configurado o workspace e o grupo de recursos padrão, conforme explicado na seção de pré-requisitos, será necessário especificar os parâmetros --workspace-name e --resource-group para que az ml model create funcione.

Aviso

A saída de az ml job list é passada para sed. Isso só funciona em shells do Linux. Se você estiver no Windows, execute az ml job list --parent-job-name <job-name> --query [0].name e remova as aspas no nome do trabalho de treinamento.

Se você não conseguir baixar o modelo, poderá encontrar um modelo de exemplo do MLflow treinado pelo trabalho de treinamento na seção anterior na pasta cli/jobs/pipelines-with-components/nyc_taxi_data_regression/artifacts/model/.

Crie o modelo no registro:

# create model in registry
az ml model create --name nyc-taxi-model --version 1 --type mlflow_model --path ./artifacts/model/ --registry-name <registry-name>

Dica

  • Use um número aleatório para o parâmetro version se você receber um erro de que o nome e a versão do modelo existem.
  • O mesmo comando da CLI az ml model create pode ser usado para criar modelos em um workspace ou registro. A execução do comando com o comando --workspace-name cria o modelo em um workspace, enquanto a execução do comando com --registry-name cria o modelo no registro.

Compartilhar um modelo do espaço de trabalho com o registro

Neste fluxo de trabalho, primeiro você criará o modelo no espaço de trabalho e depois o compartilhará com o registro. Esse fluxo de trabalho é útil quando você deseja testar o modelo no workspace antes de compartilhá-lo. Por exemplo, implante-o em pontos de extremidade, experimente a inferência com alguns dados de teste e copie o modelo para um registro se tudo parecer correto. Esse fluxo de trabalho também pode ser útil quando você está desenvolvendo uma série de modelos usando diferentes técnicas, estruturas ou parâmetros e deseja promover apenas um deles para o registro como um candidato de produção.

Verifique se você tem o nome do trabalho de pipeline da seção anterior e substitua-o no comando para buscar o nome do trabalho de treinamento abaixo. Em seguida, você registrará o modelo na saída do trabalho de treinamento no workspace. Observe como o parâmetro --path se refere à saída train_job com a sintaxe azureml://jobs/$train_job_name/outputs/artifacts/paths/model.

# fetch the name of the train_job by listing all child jobs of the pipeline job
train_job_name=$(az ml job list --parent-job-name <job-name> --workspace-name <workspace-name> --resource-group <workspace-resource-group> --query [0].name | sed 's/\"//g')
# create model in workspace
az ml model create --name nyc-taxi-model --version 1 --type mlflow_model --path azureml://jobs/$train_job_name/outputs/artifacts/paths/model

Dica

  • Use um número aleatório para o parâmetro version se você receber um erro de que o nome e a versão do modelo existem.
  • Se você não tiver configurado o workspace e o grupo de recursos padrão, conforme explicado na seção de pré-requisitos, será necessário especificar os parâmetros --workspace-name e --resource-group para que az ml model create funcione.

Anote o nome e a versão do modelo. Você pode validar se o modelo está registrado no workspace procurando por ele na interface do usuário do Estúdio ou usando o comando az ml model show --name nyc-taxi-model --version $model_version.

Em seguida, você agora compartilhará o modelo do espaço de trabalho com o registro.

# share model registered in workspace to registry
az ml model share --name nyc-taxi-model --version 1 --registry-name <registry-name> --share-with-name <new-name> --share-with-version <new-version>

Dica

  • Use o nome e a versão do modelo corretos se você o alterou no comando az ml model create.
  • O comando acima tem dois parâmetros opcionais "--share-with-name" e "--share-with-version". Se eles não forem fornecidos, o novo modelo terá o mesmo nome e versão que o modelo que está sendo compartilhado. Anote o name e version do componente da saída do modelo az ml model create e use-os com comandos az ml model show da seguinte maneira. Você precisará de name e version na próxima seção quando implantar o modelo em um ponto de extremidade online para inferência.
az ml model show --name <model_name> --version <model_version> --registry-name <registry-name>

Você também pode usar az ml model list --registry-name <registry-name> para listar todos os modelos do registro ou navegar por todos os componentes na interface do usuário do Estúdio do Azure Machine Learning. Navegue até a interface do usuário global e procure o hub de Registros.

A captura de tela a seguir mostra um modelo em um registro do Estúdio do Azure Machine Learning. Se você criou um modelo a partir da saída do trabalho e copiou o modelo do workspace no registro, o modelo terá um link para o trabalho que treinou o modelo. Esse link pode ser usado para navegar até o trabalho de treinamento para examinar o código, o ambiente e os dados usados para treinar o modelo.

Captura de tela dos modelos no registro.

Implantar o modelo do registro para o ponto de extremidade online no workspace

Na última seção, você implantará um modelo do registro em um ponto de extremidade online em um workspace. Você pode optar por implantar qualquer workspace ao qual tenha acesso na organização, desde que a localização do workspace seja um dos locais com suporte do registro. Essa funcionalidade é útil se você treinou um modelo em um workspace dev e agora precisa implantar o modelo no workspace test ou prod, preservando as informações de linhagem em torno do código, ambiente e dados usados para treinar o modelo.

Os pontos de extremidade online permitem implantar modelos e enviar solicitações de inferência por meio das APIs REST. Para mais informações, confira Como implantar e classificar um modelo de machine learning usando um ponto de extremidade online.

Crie um ponto de extremidade online.

az ml online-endpoint create --name reg-ep-1234

Atualize a linha model:deploy.yml disponível na pasta cli/jobs/pipelines-with-components/nyc_taxi_data_regression para consultar o nome do modelo e a versão da etapa anterior. Crie uma implantação online para o ponto de extremidade online. deploy.yml é mostrado abaixo para referência.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: demo
endpoint_name: reg-ep-1234
model: azureml://registries/<registry-name>/models/nyc-taxi-model/versions/1
instance_type: Standard_DS2_v2
instance_count: 1

Crie a implantação online. A implantação leva vários minutos para ser concluída.

az ml online-deployment create --file deploy.yml --all-traffic

Busque o URI de pontuação e envie uma solicitação de pontuação de exemplo. Os dados de exemplo para a solicitação de pontuação estão disponíveis no scoring-data.json na pasta cli/jobs/pipelines-with-components/nyc_taxi_data_regression.

ENDPOINT_KEY=$(az ml online-endpoint get-credentials -n reg-ep-1234 -o tsv --query primaryKey)
SCORING_URI=$(az ml online-endpoint show -n reg-ep-1234 -o tsv --query scoring_uri)
curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @./scoring-data.json

Dica

  • O comando curl funciona somente no Linux.
  • Se você não tiver configurado o workspace e o grupo de recursos padrão, conforme explicado na seção de pré-requisitos, será necessário especificar os parâmetros --workspace-name e --resource-group para que os comandos az ml online-endpoint e az ml online-deployment funcionem.

Limpar os recursos

Se você não estiver usando a implantação, exclua-a para reduzir custos. O exemplo a seguir exclui o ponto de extremidade e todas as implantações subjacentes:

az ml online-endpoint delete --name reg-ep-1234 --yes --no-wait

Próximas etapas