Gerenciar ambientes do Azure Machine Learning com a CLI e o SDK (v2)

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

Os ambientes do Azure Machine Learning definem os ambientes de execução para seus trabalhos ou implantações e encapsulam as dependências para seu código. O Azure Machine Learning usa a especificação de ambiente para criar o contêiner do Docker no qual o código de treinamento ou de pontuação é executado no destino de computação especificado. Você pode definir um ambiente de uma especificação de Conda, uma imagem do Docker ou um contexto de build do Docker.

Neste artigo, saiba como criar e gerenciar ambientes do Azure Machine Learning usando o SDK e a CLI (v2).

Pré-requisitos

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

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

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

  • Para instalar o SDK do Python v2, use o seguinte comando:

    pip install azure-ai-ml azure-identity
    

    Para atualizar uma instalação do SDK existente para a versão mais recente, use o seguinte comando:

    pip install --upgrade azure-ai-ml azure-identity
    

    Para saber mais, confira Instalar o SDK do Python v2 para Azure Machine Learning.

Dica

Para um ambiente de desenvolvimento completo, use o Visual Studio Code e a extensão do Azure Machine Learning para gerenciar recursos do Azure Machine Learning e treinar modelos de machine learning.

Clonar repositório de exemplos

Para executar os exemplos de treinamento, primeiro clone o repositório de exemplos. Para os exemplos da CLI, altere para o diretório cli. Para os exemplos do SDK, altere para o diretório sdk/python/assets/environment:

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

Observe que --depth 1 clona apenas a confirmação mais recente para o repositório, o que reduz o tempo para concluir a operação.

Conectar-se ao workspace

Dica

Use as guias a seguir para selecionar o método que você deseja usar para trabalhar com ambientes. A seleção de uma guia alternará automaticamente todas as guias deste artigo para a mesma guia. É possível selecionar outra guia a qualquer momento.

CLI do Azure

Ao usar a CLI do Azure, você precisa de parâmetros de identificador, uma assinatura, um grupo de recursos e um nome de espaço de trabalho. Embora você possa especificar esses parâmetros para cada comando, você também pode definir padrões usados para todos os comandos. Use os comandos a seguir para definir os valores padrão. Substitua <subscription ID>, <Azure Machine Learning workspace name> e <resource group> pelos valores da sua configuração:

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

SDK do Python

Para se conectar ao espaço de trabalho, você precisa de parâmetros de identificador, uma assinatura, um grupo de recursos e um nome de espaço de trabalho. Você usará esses detalhes no MLClient do namespace azure.ai.ml para obter um identificador para o espaço de trabalho do Azure Machine Learning necessário. Para autenticar, use a autenticação padrão do Azure. Verifique este exemplo para obter mais detalhes sobre como configurar credenciais e se conectar a um espaço de trabalho.

# import required libraries
from azure.ai.ml import MLClient
from azure.ai.ml.entities import Environment, BuildContext
from azure.identity import DefaultAzureCredential

# Enter details of your AML workspace
subscription_id = "<SUBSCRIPTION_ID>"
resource_group = "<RESOURCE_GROUP>"
workspace = "<AML_WORKSPACE_NAME>"

# get a handle to the workspace
ml_client = MLClient(
    DefaultAzureCredential(), subscription_id, resource_group, workspace
)

Ambientes selecionados

Há dois tipos de ambientes no Azure Machine Learning: ambientes coletados e personalizados. Os ambientes selecionados são ambientes predefinidos que contêm estruturas e ferramentas populares de ML. Os ambientes personalizados são definidos pelo usuário e podem ser criados através do az ml environment create.

Os ambientes selecionados são fornecidos pelo Azure Machine Learning e estão disponíveis por padrão. O Azure Machine Learning atualiza rotineiramente esses ambientes com as últimas versões da estrutura e realiza a manutenção neles para correções de bugs e atualizações de segurança. Eles são respaldados por imagens do Docker armazenadas em cache, o que reduz o custo de preparação do trabalho e o tempo de implantação do modelo.

Você pode usar esses ambientes selecionados prontos para uso para treinamento ou implantação, referenciando uma versão específica ou a versão mais recente do ambiente. Use a seguinte sintaxe: azureml://registries/azureml/environment/<curated-environment-name>/versions/<version-number> ou azureml://registries/azureml/environment/<curated-environment-name>/labels/latest. Você também pode usá-los como referência para seus próprios ambientes personalizados, modificando os Dockerfiles que suportam esses ambientes selecionados.

Veja o conjunto de ambientes coletados disponíveis na interface do usuário do Estúdio do Azure Machine Learning ou usando a CLI (v2) por meio de az ml environment list.

Dica

Ao trabalhar com ambientes coletados na CLI ou no SDK, o nome do ambiente começa com AzureML- seguido pelo nome do ambiente coletado. Ao usar o estúdio do Azure Machine Learning, eles não têm esse prefixo. O motivo dessa diferença é que a interface do usuário do estúdio exibe ambientes personalizados e coletados em guias separadas, portanto, o prefixo não é necessário. A CLI e o SDK não têm essa separação, portanto, o prefixo é usado para diferenciar entre ambientes personalizados e coletados.

Criar um ambiente personalizado

Você pode definir um ambiente de uma imagem do Docker, um contexto de build do Docker e uma especificação do Conda com a imagem do Docker.

Criar um ambiente com base em uma imagem do Docker

Para definir um ambiente com base em uma imagem do Docker, forneça o URI da imagem hospedada em um registro, como o Hub do Docker ou o Registro de Contêiner do Azure.

CLI do Azure

O exemplo a seguir é um arquivo de especificação YAML para um ambiente definido por meio de uma imagem do Docker. Uma imagem do repositório oficial do PyTorch no Hub do Docker é especificada através da propriedade imageno arquivo YAML.

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: docker-image-example
image: pytorch/pytorch:latest
description: Environment created from a Docker image.

Para criar o ambiente:

az ml environment create --file assets/environment/docker-image.yml

SDK do Python

O exemplo a seguir cria um ambiente de uma imagem do Docker. Uma imagem do repositório oficial do PyTorch no Docker Hub é especificada através da propriedade image.

env_docker_image = Environment(
    image="pytorch/pytorch:latest",
    name="docker-image-example",
    description="Environment created from a Docker image.",
)
ml_client.environments.create_or_update(env_docker_image)

Dica

O Azure Machine Learning mantém um conjunto de imagens base baseadas no Ubuntu Linux de CPU e GPU com dependências comuns do sistema. Por exemplo, as imagens de GPU contêm Miniconda, OpenMPI, CUDA, cuDNN e NCCL. Você pode usar essas imagens para seus ambientes ou usar seus Dockerfiles correspondentes como referência ao criar suas próprias imagens personalizadas.

Para o conjunto de imagens base e seus Dockerfiles correspondentes, consulte AzureML-Repositório de contêineres.

Criar um ambiente com base em um contexto de build do Docker

Em vez de definir um ambiente de uma imagem predefinida, você também pode definir de um contexto de build do Docker. Para fazer isso, especifique o diretório que serve como o contexto de build. Esse diretório deve conter um Dockerfile (com não mais de 1 MB) e quaisquer outros arquivos necessários para criar a imagem.

CLI do Azure

O exemplo a seguir é um arquivo de especificação YAML para um ambiente definido por meio de um contexto de build. O caminho local para a pasta do contexto de build está especificado no campo build.path, e o caminho relativo para o Dockerfile dentro dessa pasta do contexto de build está especificado no campo build.dockerfile_path. Se build.dockerfile_path for omitido no arquivo YAML, o Azure Machine Learning procurará um Dockerfile nomeado Dockerfile na raiz do contexto de build.

Neste exemplo, o contexto de build contém um Dockerfile chamado Dockerfile e um arquivo requirements.txt que é referenciado dentro do Dockerfile para instalar pacotes do Python.

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: docker-context-example
build:
  path: docker-contexts/python-and-pip

Para criar o ambiente:

az ml environment create --file assets/environment/docker-context.yml

SDK do Python

No exemplo a seguir, o caminho local para a pasta de contexto de build é especificado no parâmetro path. O Azure Machine Learning procura um Dockerfile nomeado Dockerfile na raiz do contexto de build.

env_docker_context = Environment(
    build=BuildContext(path="docker-contexts/python-and-pip"),
    name="docker-context-example",
    description="Environment created from a Docker context.",
)
ml_client.environments.create_or_update(env_docker_context)

O Azure Machine Learning começa a compilar a imagem a partir do contexto de build quando o ambiente é criado. Você pode monitorar o status do build e exibir os logs de build na interface do usuário do estúdio.

Criar um ambiente a partir de uma especificação de Conda

Você pode definir um ambiente usando um arquivo de configuração padrão YAML do Conda que inclui as dependências para o ambiente do Conda. Consulte Como criar um ambiente manualmente para obter informações sobre esse formato padrão.

Você também deve especificar uma imagem base do Docker para esse ambiente. O Azure Machine Learning cria o ambiente conda sobre a imagem do Docker fornecida. Se você instalar algumas dependências do Python em sua imagem do Docker, esses pacotes não estarão no ambiente de execução, causando falhas na execução. Por padrão, o Azure Machine Learning cria um ambiente conda com dependências especificadas e executa o trabalho nesse ambiente em vez de usar as bibliotecas python instaladas na imagem base.

CLI do Azure

O exemplo a seguir é um arquivo de especificação YAML para um ambiente definido por meio de uma especificação do Conda. Aqui, o caminho relativo para o arquivo Conda do arquivo YAML do ambiente do Azure Machine Learning é especificado pela propriedade conda_file. Como alternativa, você pode definir a especificação embutida de Conda usando a propriedade conda_file, em vez de defini-la em um arquivo separado.

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: docker-image-plus-conda-example
image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04
conda_file: conda-yamls/pydata.yml
description: Environment created from a Docker image plus Conda environment.

Para criar o ambiente:

az ml environment create --file assets/environment/docker-image-plus-conda.yaml

SDK do Python

O caminho relativo para o arquivo do Conda é especificado usando o parâmetro conda_file.

env_docker_conda = Environment(
    image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04",
    conda_file="conda-yamls/pydata.yml",
    name="docker-image-plus-conda-example",
    description="Environment created from a Docker image plus Conda environment.",
)
ml_client.environments.create_or_update(env_docker_conda)

O Azure Machine Learning cria a imagem final do Docker com base nessa especificação de ambiente quando o ambiente é usado em um trabalho ou implantação. Você também pode disparar manualmente um build do ambiente na interface do usuário do estúdio.

Gerenciar ambientes

O SDK e a CLI (v2) também permitem que você gerencie o ciclo de vida dos ativos de ambiente do Azure Machine Learning.

Lista

Liste todos os ambientes em seu workspace:

CLI do Azure

az ml environment list

SDK do Python

envs = ml_client.environments.list()
for env in envs:
    print(env.name)

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

CLI do Azure

az ml environment list --name docker-image-example

SDK do Python

envs = ml_client.environments.list(name="docker-image-example")
for env in envs:
    print(env.version)

Mostrar

Obtenha os detalhes de um ambiente específico:

CLI do Azure

az ml environment show --name docker-image-example --version 1

SDK do Python

env = ml_client.environments.get(name="docker-image-example", version="1")
print(env)

Atualizar

Atualize as propriedades mutáveis de um ambiente específico:

CLI do Azure

az ml environment update --name docker-image-example --version 1 --set description="This is an updated description."

SDK do Python

env.description="This is an updated description."
ml_client.environments.create_or_update(environment=env)

Importante

Somente o description e o tags podem ser atualizados para ambientes. Todas as outras propriedades são imutáveis; Se você precisar alterar qualquer uma dessas propriedades, crie uma nova versão do ambiente.

Arquivos

O arquivamento de um ambiente o oculta por padrão de consultas de lista (az ml environment list). Você ainda pode continuar a referenciar e usar um ambiente Arquivado em seus fluxos de trabalho. Você pode arquivar todas as versões de um ambiente ou apenas uma versão específica.

Se você não especificar uma versão, todas as versões do ambiente com esse nome determinado serão arquivadas. Se você criar uma nova versão de ambiente em um contêiner de ambiente arquivado, essa nova versão também será definida automaticamente como arquivada.

Arquive todas as versões de um ambiente:

CLI do Azure

az ml environment archive --name docker-image-example

SDK do Python

ml_client.environments.archive(name="docker-image-example")

Arquivar uma versão específica do ambiente:

CLI do Azure

az ml environment archive --name docker-image-example --version 1

SDK do Python

ml_client.environments.archive(name="docker-image-example", version="1")

Importante

Arquivar uma versão de um ambiente não exclui a imagem armazenada em cache no registro de contêiner. Se quiser excluir a imagem armazenada em cache associada a um ambiente específico, você poderá usar o comando az acr repository delete no repositório associado do ambiente.

Usar ambientes para treinamento

CLI do Azure

Para usar um ambiente personalizado para um trabalho de treinamento, especifique o campo environment da configuração YAML do trabalho. Referencie um ambiente registrado existente do Azure Machine Learning por meio de environment: azureml:<environment-name>:<environment-version> ou environment: azureml:<environment-name>@latest (para referenciar a última versão de um ambiente) ou defina uma especificação de ambiente em linha. Se estiver definindo um ambiente embutido, não especifique os campos name e version, pois esses ambientes são tratados como ambientes "não registrado" e não são rastreados no registro de ativos do ambiente.

SDK do Python

Para usar um ambiente para um trabalho de treinamento, especifique a propriedade environment do comando.

Para obter exemplos de envio de trabalhos, confira os exemplos em https://github.com/Azure/azureml-examples/tree/main/sdk/python/jobs.

Quando você envia um trabalho de treinamento, a criação de um ambiente pode levar vários minutos. A duração depende do tamanho das dependências necessárias. Os ambientes são armazenados em cache pelo serviço. Assim, desde que a definição do ambiente permaneça inalterada, você incorrerá no tempo de configuração completa apenas uma vez.

---

Para obter mais informações sobre como usar ambientes em trabalhos, consulte Treinar modelos.

Usar ambientes para implantações de modelo

CLI do Azure

Você também pode usar ambientes para suas implantações de modelo para Pontuação online e do lote. Para fazer isso, especifique o campo environment na configuração de implantação do YAML.

Para obter mais informações sobre como usar ambientes em implantações, consulte Implantar e pontuar um modelo de machine learning usando um ponto de extremidade online.

SDK do Python

Você também pode usar ambientes para suas implantações de modelo. Para mais informações, confira Implantar e pontuar um modelo de machine learning.

Próximas etapas

• Treinar modelos (criar trabalhos)
• Implantar e pontuar um modelo de aprendizado de máquina usando um ponto de extremidade online
• Referência do esquema YAML do ambiente