Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
APLICA-SE A:
Extensão de ML da CLI do Azure v2 (atual)SDK do Python azure-ai-ml v2 (atual)
Neste artigo, você verá como implantar uma nova versão de um modelo de machine learning em produção sem causar nenhuma interrupção. Você usa uma estratégia de implantação azul-verde, que também é conhecida como uma estratégia de distribuição segura, para introduzir uma nova versão de um serviço Web em produção. Ao usar essa estratégia, você pode distribuir sua nova versão do serviço Web para um pequeno subconjunto de usuários ou solicitações antes de distribuí-la completamente.
Este artigo pressupõe que você use pontos de extremidade online ou pontos de extremidade usados para inferência online (em tempo real). Há dois tipos de pontos de extremidade online: pontos de extremidade online gerenciados e pontos de extremidade online do Kubernetes. Para obter mais informações sobre pontos de extremidade e as diferenças entre os tipos de ponto de extremidade, consulte pontos de extremidade online gerenciados versus pontos de extremidade online do Kubernetes.
Este artigo usa pontos de extremidade online gerenciados para implantação. Mas também inclui anotações que explicam como usar pontos de extremidade do Kubernetes em vez de pontos de extremidade online gerenciados.
Neste artigo, você verá como:
- Defina um ponto de extremidade online com uma implantação chamada
bluepara atender à primeira versão de um modelo. - Dimensione a implantação
bluepara que ela possa lidar com mais solicitações. - Implante a segunda versão do modelo, que é chamada de implantação
green, no ponto de extremidade, mas envie a implantação sem tráfego dinâmico. - Teste a implantação de
greenisoladamente. - Espelhe uma porcentagem de tráfego dinâmico para a implantação
greenpara validá-la. - Envie uma pequena porcentagem de tráfego dinâmico para a implantação
green. - Envie todo o tráfego ao vivo para a implantação
green. - Exclua a implantação não utilizada
blue.
Pré-requisitos
A CLI do Azure e a extensão
mlpara a CLI do Azure, instalada e configurada. Para obter mais informações, consulte Instalar e configurar a CLI (v2).Um shell bash ou um shell compatível, por exemplo, um shell em um sistema Linux ou Subsistema do Windows para Linux. Os exemplos da CLI do Azure neste artigo pressupõem que você use esse tipo de shell.
Um Workspace do Azure Machine Learning. Para obter instruções para criar um workspace, consulte Configurar.
Uma conta de usuário que tem pelo menos uma das seguintes funções de RBAC (controle de acesso baseado em função) do Azure:
- Uma função de proprietário para o workspace do Azure Machine Learning
- Uma função de Colaborador para o workspace do Azure Machine Learning
- Uma função personalizada que tem permissões
Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*
Para obter mais informações, consulte Gerenciar acesso a workspaces do Azure Machine Learning.
Opcionalmente, o Mecanismo do Docker, instalado e em execução localmente. Esse pré-requisito é altamente recomendado. Você precisa dele para implantar um modelo localmente e isso é útil para depuração.
Preparar seu sistema
Definir variáveis de ambiente
Você pode configurar valores padrão a serem usados com a CLI do Azure. Para evitar a passagem de valores para a sua assinatura, workspace e grupo de recursos várias vezes, execute o seguinte código:
az account set --subscription <subscription-ID>
az configure --defaults workspace=<Azure-Machine-Learning-workspace-name> group=<resource-group-name>
Clone o repositório de exemplos
Para acompanhar este artigo, primeiro clone o repositório de exemplos (azureml-examples). Em seguida, vá para o diretório do cli/ repositório:
git clone --depth 1 https://github.com/Azure/azureml-examples
cd azureml-examples
cd cli
Dica
Use --depth 1 para clonar apenas a confirmação mais recente para o repositório, o que reduz o tempo necessário para concluir a operação.
Os comandos neste tutorial estão no arquivo deploy-safe-rollout-online-endpoints.sh no diretório da CLI (Interface de Linha de Comando), e os arquivos de configuração YAML estão no subdiretório endpoints/online/managed/sample.
Observação
Os arquivos de configuração YAML para endpoints online do Kubernetes estão no subdiretório endpoints/online/kubernetes/.
Definir o ponto de extremidade e a implantação
Os pontos de extremidade online são usados para inferência online (em tempo real). Os pontos de extremidade online contêm implantações que estão prontas para receber dados de clientes e podem retornar respostas em tempo real.
Definir um ponto de extremidade
A tabela a seguir lista os atributos de chave a serem especificados quando você define um ponto de extremidade.
| Atributo | Obrigatório ou opcional | Descrição |
|---|---|---|
| Nome | Obrigatório | O nome do ponto de extremidade. Ela deve ser exclusiva em sua região do Azure. Para obter mais informações sobre regras de nomenclatura, confira Pontos de extremidade online e pontos de extremidade em lote do Azure Machine Learning. |
| Modo de autenticação | Opcional | O método de autenticação para o ponto de extremidade. Você pode escolher entre a autenticação baseada em chave e a autenticação keyaml_tokenbaseada em token do Azure Machine Learning. Uma chave não expira, mas um token sim. Para obter mais informações sobre autenticação, confira Autenticar clientes para pontos de extremidade online. |
| Descrição | Opcional | A descrição do ponto de extremidade. |
| Marcas | Opcional | Um dicionário de etiquetas para o endpoint. |
| Tráfego | Opcional | Regras sobre como rotear o tráfego entre implantações. Você representa o tráfego como um dicionário de pares chave-valor, em que a chave representa o nome da implantação e o valor representa o percentual de tráfego para essa implantação. Você pode definir o tráfego somente depois que as implantações em um ponto de extremidade forem criadas. Você também pode atualizar o tráfego para um ponto de extremidade online após a criação das implantações. Para obter mais informações sobre como usar o tráfego espelhado, confira Alocar uma pequena porcentagem de tráfego dinâmico para a nova implantação. |
| Tráfego espelho | Opcional | O percentual de tráfego dinâmico a ser espelhado em uma implantação. Para obter mais informações sobre como usar o tráfego espelhado, consulte Testar a implantação com tráfego espelhado. |
Para ver uma lista completa de atributos que você pode especificar ao criar um ponto de extremidade, consulte o esquema YAML do ponto de extremidade online da CLI (v2). Para a versão 2 do SDK do Azure Machine Learning para Python, consulte ManagedOnlineEndpoint Class.
Definir uma implantação
Uma implantação é um conjunto de recursos necessários para hospedar o modelo que faz a inferência propriamente dita. A tabela a seguir descreve os principais atributos a serem especificados quando você define uma implantação.
| Atributo | Obrigatório ou opcional | Descrição |
|---|---|---|
| Nome | Obrigatório | O nome da implementação. |
| Nome do ponto de extremidade | Obrigatório | O nome do ponto de extremidade no qual criar a implantação. |
| Modelar | Opcional | O modelo a ser usado para a implantação. Esse valor pode ser uma referência a um modelo com versão existente no workspace ou uma especificação de modelo embutida. Nos exemplos deste artigo, um scikit-learn modelo faz regressão. |
| Caminho do código | Opcional | O caminho para a pasta no ambiente de desenvolvimento local que contém todo o código-fonte Python para avaliar o modelo. Você pode usar diretórios e pacotes aninhados. |
| Script de pontuação | Opcional | O código executa o modelo em uma determinada solicitação de entrada. Esse valor pode ser o caminho relativo para o arquivo de pontuação na pasta do código-fonte. Este script de pontuação recebe os dados enviados para um serviço Web implantado e os transmite ao modelo. Em seguida, o script executa o modelo e retorna sua resposta ao cliente. O script de pontuação é específico para seu modelo e deve compreender os dados que o modelo espera como entrada e retorna como saída. Os exemplos deste artigo usam um arquivo score.py. Esse código Python precisa ter uma função init e uma função run. A init função é chamada depois que o modelo é criado ou atualizado. Você pode usá-lo para armazenar o modelo em cache na memória, por exemplo. A função run é chamada em cada invocação do ponto de extremidade para fazer a pontuação e previsão real. |
| Ambiente | Obrigatório | Contém os detalhes do ambiente para hospedar o modelo e o código. Esse valor pode ser uma referência para um ambiente com versão existente no espaço de trabalho ou uma especificação de ambiente embutido. O ambiente pode ser uma imagem do Docker com dependências do Conda, um Dockerfile ou um ambiente registrado. |
| Tipo de instância | Obrigatório | O tamanho da máquina virtual a ser usado para a implantação. Para obter uma lista de tamanhos com suporte, confira a Lista de SKU de pontos de extremidade online gerenciados. |
| Contagem de instâncias | Obrigatório | O número de instâncias a serem usadas para a implantação. Você baseia o valor na carga de trabalho esperada. Para alta disponibilidade, recomendamos que você use pelo menos três instâncias. O Azure Machine Learning reserva 20% a mais para executar atualizações. Para obter mais informações, confira Pontos de extremidade online e pontos de extremidade em lote do Azure Machine Learning. |
Para ver uma lista completa de atributos que você pode especificar ao criar uma implantação, consulte o esquema YAML de implantação online gerenciada da CLI (v2). Para a versão 2 do SDK do Python, consulte ManagedOnlineDeployment Class.
Criar um ponto de extremidade online
Primeiro, defina o nome do ponto de extremidade e configure-o. Neste artigo, você usará o arquivo endpoints/online/managed/sample/endpoint.yml para configurar o endpoint. Esse arquivo contém as seguintes linhas:
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key
A tabela a seguir descreve as chaves usadas pelo formato YAML do ponto de extremidade. Para saber como especificar esses atributos, consulte o esquema YAML do endpoint online da CLI (v2). Para obter informações sobre limites relacionados a pontos de extremidade online gerenciados, consulte pontos de extremidade online do Azure Machine Learning e pontos de extremidade em lote.
| Chave | Descrição |
|---|---|
$schema |
(Opcional) O esquema YAML. Para ver todas as opções disponíveis no arquivo YAML, você pode exibir o esquema no bloco de código anterior em um navegador. |
name |
O nome do ponto de extremidade. |
auth_mode |
O modo de autenticação. Use key para autenticação baseada em chave. Use aml_token para autenticação baseada em chave do Azure Machine Learning. Para obter um token mais recente, use o comando az ml online-endpoint get-credentials. |
Para criar um ponto de extremidade online:
Defina o nome do ponto de extremidade executando o comando Unix a seguir. Substitua
YOUR_ENDPOINT_NAMEpor um nome exclusivo.export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"Importante
Os nomes de ponto de extremidade devem ser exclusivos dentro de uma região do Azure. Por exemplo, na região
westus2do Azure, pode haver apenas um ponto de extremidade com o nomemy-endpoint.Crie o ponto de extremidade na nuvem executando o código a seguir. Esse código usa o endpoint.yml para configurar o endpoint.
az ml online-endpoint create --name $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml
Criar a implantação azul
Você pode usar o arquivo endpoints/online/managed/sample/blue-deployment.yml para configurar os principais aspectos de uma implantação chamada blue. Esse arquivo contém as seguintes linhas:
$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model:
path: ../../model-1/model/
code_configuration:
code: ../../model-1/onlinescoring/
scoring_script: score.py
environment:
conda_file: ../../model-1/environment/conda.yaml
image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu22.04:latest
instance_type: Standard_DS3_v2
instance_count: 1
Para usar o arquivo blue-deployment.yml para criar a implantação blue para o ponto de extremidade, execute o seguinte comando:
az ml online-deployment create --name blue --endpoint-name $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml --all-traffic
Importante
O sinalizador --all-traffic no comando az ml online-deployment create aloca 100% do tráfego do ponto de extremidade para a implantação recém-criada blue.
No arquivo blue-deployment.yaml, a path linha especifica de onde carregar arquivos. A CLI do Azure Machine Learning usa essas informações para carregar os arquivos e registrar o modelo e o ambiente. Como prática recomendada para produção, você deve registrar o modelo e o ambiente e especificar o nome e a versão registrados separadamente no código YAML. Use o formato model: azureml:<model-name>:<model-version> para o modelo, por exemplo, model: azureml:my-model:1. Para o ambiente, use o formato environment: azureml:<environment-name>:<environment-version>, por exemplo, environment: azureml:my-env:1.
Para fazer o registro, você pode extrair as definições do YAML de model e environment em arquivos YAML separados e usar os comandos az ml model create e az ml environment create. Para saber mais sobre esses comandos, execute az ml model create -h e az ml environment create -h.
Para obter mais informações sobre como registrar seu modelo como um ativo, consulte Registrar um modelo usando a CLI do Azure ou o SDK do Python. Para obter mais informações sobre como criar um ambiente, consulte Criar um ambiente personalizado.
Confirme sua implantação
Uma maneira de confirmar sua implantação existente é invocar seu ponto de extremidade para que ele possa pontuar seu modelo para uma determinada solicitação de entrada. Ao invocar seu endpoint por meio da CLI do Azure ou do SDK do Python, você pode optar por especificar o nome da implantação para receber tráfego de entrada.
Observação
Ao contrário da CLI do Azure ou do SDK do Python, o Estúdio do Azure Machine Learning exige que você especifique uma implantação ao invocar um ponto de extremidade.
Invocar um ponto de extremidade com um nome de implantação
Ao chamar um endpoint, você pode especificar o nome de uma implantação para a qual deseja direcionar o tráfego. Nesse caso, o Azure Machine Learning roteia o tráfego do ponto de extremidade diretamente para a implantação especificada e retorna a sua saída. Você pode usar a opção --deployment-namepara a CLI do Azure Machine Learning v2 ou a opção deployment_namedo SDK do Python v2 para especificar a implantação.
Chamar o endpoint sem especificar uma implantação
Se você invocar o ponto de extremidade sem especificar a implantação que deseja receber tráfego, o Azure Machine Learning roteia o tráfego de entrada do ponto de extremidade para as implantações no ponto de extremidade com base nas configurações de controle de tráfego.
As configurações de controle de tráfego alocam porcentagens especificadas do tráfego de entrada em cada implantação no ponto de extremidade. Por exemplo, se as regras de tráfego especificam que uma implantação específica no ponto de extremidade deve receber tráfego de entrada 40% do tempo, o Azure Machine Learning roteia 40% do tráfego do ponto de extremidade para essa implantação.
Para visualizar o status do seu endpoint e da implantação existente, execute os seguintes comandos:
az ml online-endpoint show --name $ENDPOINT_NAME
az ml online-deployment show --name blue --endpoint $ENDPOINT_NAME
A saída lista informações sobre o ponto de extremidade $ENDPOINT_NAME e a implantação blue.
Testar o ponto de extremidade usando dados de exemplo
Você pode invocar o ponto de extremidade usando o invoke comando. O comando a seguir usa o arquivo JSON sample-request.json para enviar uma solicitação de exemplo:
az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json
Escalar a implantação existente para lidar com mais tráfego
Na implantação descrita em Implantar e pontuar um modelo de machine learning usando um ponto de extremidade online, defina o valor instance_count como 1 no arquivo YAML de implantação. Você pode escalar horizontalmente usando o comando update:
az ml online-deployment update --name blue --endpoint-name $ENDPOINT_NAME --set instance_count=2
Observação
No comando anterior, a opção --set substitui a configuração de implantação. Como alternativa, você pode atualizar o arquivo YAML e passá-lo como entrada para o update comando usando a opção --file .
Implantar um novo modelo, mas não enviar tráfego a ele
Criar uma nova implantação chamada green:
az ml online-deployment create --name green --endpoint-name $ENDPOINT_NAME -f endpoints/online/managed/sample/green-deployment.yml
Como você não aloca explicitamente nenhum tráfego para a implantação green, ela não tem nenhum tráfego alocado. Você pode verificar esse fato usando o seguinte comando:
az ml online-endpoint show -n $ENDPOINT_NAME --query traffic
Testar a nova implantação
Embora a implantação green tenha 0% do tráfego alocado para ela, você pode invocá-la diretamente usando a opção --deployment:
az ml online-endpoint invoke --name $ENDPOINT_NAME --deployment-name green --request-file endpoints/online/model-2/sample-request.json
Caso deseje usar um cliente REST para invocar a implantação diretamente sem passar pelas regras de tráfego, defina o seguinte cabeçalho HTTP: azureml-model-deployment: <deployment-name>. O código a seguir usa o Cliente para URL (cURL) para invocar a implantação diretamente. Você pode executar o código em um ambiente do Unix ou do Subsistema do Windows para Linux (WSL). Para obter instruções para recuperar o $ENDPOINT_KEY valor, consulte Obter a chave ou o token para operações de plano de dados.
# get the scoring uri
SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)
# use curl to invoke the endpoint
curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --header "azureml-model-deployment: green" --data @endpoints/online/model-2/sample-request.json
Teste a implantação com tráfego espelhado
Depois de testar a sua implantação green, você pode espelhar uma porcentagem do tráfego dinâmico para o ponto de extremidade copiando esse percentual de tráfego e enviando-o para a implantação green. O espelhamento de tráfego, que também é chamado de sombreamento, não altera os resultados retornados aos clientes — 100% das solicitações ainda fluem para a implantação blue. O percentual espelhado do tráfego é copiado e também enviado para a implantação green para que você possa coletar métricas e registro em log sem afetar os seus clientes.
O espelhamento é útil ao desejar validar uma nova implantação sem afetar os clientes. Por exemplo, você pode usar o espelhamento para verificar se a latência está dentro dos limites aceitáveis ou verificar se não há erros HTTP. O uso de espelhamento de tráfego ou sombreamento para testar uma nova implantação também é conhecido como teste de sombra. A implantação que recebe o tráfego espelhado, neste caso a implantação green, também pode ser chamada de implantação de sombra.
O espelhamento tem as seguintes limitações:
- Há suporte para espelhamento para as versões 2.4.0 e posteriores da CLI do Azure Machine Learning e versões 1.0.0 e posteriores do SDK do Python. Se você usar uma versão mais antiga da CLI do Azure Machine Learning ou do SDK do Python para atualizar um ponto de extremidade, a configuração de tráfego espelho será perdida.
- Atualmente, não há suporte para o espelhamento nos pontos de extremidade online do Kubernetes.
- Você pode espelhar o tráfego apenas para uma implantação em um ponto de extremidade.
- O percentual máximo de tráfego que você pode espelhar é de 50%. Essa restrição limita o efeito na cota de largura de banda do endpoint, que tem um valor padrão de 5 MBps. A largura de banda do ponto de extremidade será limitada se você exceder a cota alocada. Para obter informações sobre como monitorar a limitação da largura de banda, consulte Limitação de largura de banda.
Observe também o seguinte comportamento:
- Você pode configurar uma implantação para receber apenas tráfego dinâmico ou tráfego espelhado, não ambos.
- Ao invocar um ponto de extremidade, você pode especificar o nome de qualquer uma de suas implantações, até mesmo uma implantação de sombra, para retornar a previsão.
- Quando você invoca um ponto de extremidade e especifica o nome de uma implantação para receber tráfego de entrada, o Azure Machine Learning não espelha o tráfego para a implantação de sombra. O Azure Machine Learning espelha o tráfego para a implantação de sombra do tráfego enviado para o ponto de extremidade quando você não especifica uma implantação.
Se você definir a implantação green para receber 10% do tráfego espelhado, os clientes ainda receberão previsões somente da implantação blue.
Use o seguinte comando para espelhar 10% do tráfego e enviá-lo para a implantação green:
az ml online-endpoint update --name $ENDPOINT_NAME --mirror-traffic "green=10"
Você pode testar o tráfego espelhado invocando o ponto de extremidade várias vezes sem especificar uma implantação para receber o tráfego de entrada:
for i in {1..20} ; do
az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json
done
Você pode confirmar se o percentual especificado do tráfego é enviado para a green implantação verificando os logs da implantação:
az ml online-deployment get-logs --name green --endpoint $ENDPOINT_NAME
Após o teste, você pode definir o tráfego espelho como zero para desabilitar o espelhamento:
az ml online-endpoint update --name $ENDPOINT_NAME --mirror-traffic "green=0"
Aloque um pequeno percentual de tráfego dinâmico para a nova implantação
Depois de testar sua green implantação, aloque uma pequena porcentagem de tráfego para ela:
az ml online-endpoint update --name $ENDPOINT_NAME --traffic "blue=90 green=10"
Dica
O percentual total de tráfego deve ser de 0%, para desabilitar o tráfego ou 100%, para habilitar o tráfego.
A sua implantação green agora recebe 10% de todo o tráfego dinâmico. Os clientes recebem previsões das implantações blue e green.
Enviar todo o tráfego para a nova implantação
Quando estiver totalmente satisfeito com a sua implantação green, alterne todo o tráfego para ela.
az ml online-endpoint update --name $ENDPOINT_NAME --traffic "blue=0 green=100"
Remover a implantação antiga
Use as etapas a seguir para excluir uma implantação individual de um ponto de extremidade online gerenciado. Excluir uma implantação individual não afeta as outras implantações no ponto de extremidade online gerenciado:
az ml online-deployment delete --name blue --endpoint $ENDPOINT_NAME --yes --no-wait
Excluir o ponto de extremidade e a implantação
Se você não estiver usando a implantação, exclua-a para reduzir custos. Quando você exclui um ponto de extremidade, todas as suas implantações subjacentes também são excluídas.
az ml online-endpoint delete --name $ENDPOINT_NAME --yes --no-wait