Execute a distribuição segura de novas implantações para inferência em tempo real

  • Artigo

APLICA-SE A:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (current)

Neste artigo, você aprenderá como implantar uma nova versão de um modelo de aprendizado de máquina em produção sem causar nenhuma interrupção. Você usará uma estratégia de implantação azul-verde (também conhecida como estratégia de distribuição segura) para introduzir uma nova versão de um serviço Web na produção. Essa estratégia permitirá que você implemente sua nova versão do serviço Web para um pequeno subconjunto de usuários ou solicitações antes de implementá-la completamente.

Este artigo pressupõe que você esteja usando pontos de extremidade online, ou seja, pontos de extremidade que são usados para inferência online (em tempo real). Existem dois tipos de pontos finais online: pontos finais online geridos e pontos finais online do Kubernetes. Para obter mais informações sobre pontos de extremidade e as diferenças entre pontos de extremidade online gerenciados e pontos de extremidade online do Kubernetes, consulte O que são pontos de extremidade do Azure Machine Learning?.

O exemplo principal neste artigo usa pontos de extremidade online gerenciados para implantação. Para usar pontos de extremidade do Kubernetes, consulte as notas neste documento que estão alinhadas com a discussão do endpoint online gerenciado.

Neste artigo, você aprenderá a:

  • Definir um ponto de extremidade online com uma implantação chamada "azul" para servir a versão 1 de um modelo
  • Dimensione a implantação azul para que ela possa lidar com mais solicitações
  • Implante a versão 2 do modelo (chamada de implantação "verde") no ponto de extremidade, mas envie a implantação sem tráfego ao vivo
  • Testar a implantação verde isoladamente
  • Espelhar uma porcentagem do tráfego ao vivo para a implantação verde para validá-la
  • Enviar uma pequena porcentagem do tráfego ao vivo para a implantação verde
  • Envie todo o tráfego ao vivo para a implantação verde
  • Exclua a implantação azul v1 agora não utilizada

Pré-requisitos

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

  • Os controlos de acesso baseado em funções (RBAC do Azure) são utilizados para conceder acesso às operações no Azure Machine Learning. Para executar as etapas neste artigo, sua conta de usuário deve receber a função de proprietário ou colaborador para o espaço de trabalho do Azure Machine Learning ou uma função personalizada que permita Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*. Para obter mais informações, consulte Gerenciar o acesso a um espaço de trabalho do Azure Machine Learning.

  • (Opcional) Para implantar localmente, você deve instalar o Docker Engine em seu computador local. É altamente recomendável essa opção, para que seja mais fácil depurar problemas.

Prepare o seu sistema

Definir variáveis de ambiente

Se você ainda não definiu os padrões para a CLI do Azure, salve suas configurações padrão. Para evitar passar os valores da sua assinatura, espaço de trabalho e grupo de recursos várias vezes, execute este código:

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

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

Gorjeta

Use --depth 1 para clonar apenas a confirmação mais recente para o repositório. Isso reduz o tempo para concluir a operação.

Os comandos neste tutorial estão no arquivo deploy-safe-rollout-online-endpoints.sh no cli diretório e os arquivos de configuração YAML estão no endpoints/online/managed/sample/ subdiretório.

Nota

Os arquivos de configuração YAML para pontos de extremidade online do Kubernetes estão no endpoints/online/kubernetes/ subdiretório.

Definir o ponto de extremidade e a implantação

Os pontos finais online são utilizados para inferência online (em tempo real). Os endpoints online contêm implantações que estão prontas para receber dados de clientes e enviar respostas de volta em tempo real.

Definir um ponto de extremidade

A tabela a seguir lista os principais atributos a serem especificados quando você define um ponto de extremidade.

Atributo Description
Name Necessário. Nome do ponto de extremidade. Ele deve ser exclusivo na região do Azure. Para obter mais informações sobre as regras de nomenclatura, consulte Limites de pontos finais.
Modo de autenticação O método de autenticação para o ponto de extremidade. Escolha entre a autenticação key baseada em chave e a autenticação aml_tokenbaseada em token do Azure Machine Learning. Uma chave não expira, mas um token expira. Para obter mais informações sobre autenticação, consulte Autenticar em um ponto de extremidade online.
Description Descrição do parâmetro de avaliação.
Etiquetas Dicionário de tags para o ponto de extremidade.
Trânsito Regras sobre como rotear o tráfego entre implantações. Represente o tráfego como um dicionário de pares chave-valor, onde key representa o nome da implantação e value representa a porcentagem de tráfego para essa implantação. Você pode definir o tráfego somente quando as implantações em um ponto de extremidade tiverem sido criadas. Você também pode atualizar o tráfego de um ponto de extremidade online depois que as implantações forem criadas. Para obter mais informações sobre como usar o tráfego espelhado, consulte Alocar uma pequena porcentagem do tráfego ao vivo para a nova implantação.
Tráfego espelhado Porcentagem de tráfego ao vivo para espelhar 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 CLI (v2) esquema YAML de ponto de extremidade online ou Classe SDK (v2) ManagedOnlineEndpoint.

Definir uma implantação

Uma implantação é um conjunto de recursos necessários para hospedar o modelo que faz a inferência real. A tabela a seguir descreve os principais atributos a serem especificados quando você define uma implantação.

Atributo Description
Name Necessário. Nome da implantação.
Nome do ponto final Obrigatório. Nome do ponto de extremidade sob o qual criar a implantação.
Modelo O modelo a ser usado para a implantação. Esse valor pode ser uma referência a um modelo versionado existente no espaço de trabalho ou uma especificação de modelo embutido. No exemplo, temos um modelo scikit-learn que faz regressão.
Caminho do código O caminho para o diretório no ambiente de desenvolvimento local que contém todo o código-fonte Python para pontuar o modelo. Você pode usar diretórios e pacotes aninhados.
Roteiro de pontuação Código Python que executa o modelo em uma determinada solicitação de entrada. Esse valor pode ser o caminho relativo para o arquivo de pontuação no diretório do código-fonte.
O script de pontuação recebe dados enviados a um serviço Web implantado e os passa para o modelo. Em seguida, o script executa o modelo e retorna sua resposta ao cliente. O script de pontuação é específico para o seu modelo e deve entender os dados que o modelo espera como entrada e retorna como saída.
Neste exemplo, temos um arquivo score.py . Este código Python deve ter uma init() função e uma run() função. A init() função será chamada depois que o modelo for criado ou atualizado (você pode usá-la para armazenar o modelo em cache na memória, por exemplo). A run() função é chamada a cada invocação do ponto final para fazer a pontuação e previsão reais.
Environment Obrigatório. O ambiente para hospedar o modelo e o código. Esse valor pode ser uma referência a um ambiente versionado existente no espaço de trabalho ou uma especificação de ambiente embutido. O ambiente pode ser uma imagem do Docker com dependências Conda, um Dockerfile ou um ambiente registrado.
Tipo de instância Obrigatório. O tamanho da VM a ser usado para a implantação. Para obter a lista de tamanhos suportados, consulte 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. Baseie o valor na carga de trabalho esperada. Para alta disponibilidade, recomendamos que você defina o valor como pelo menos 3. Reservamos um extra de 20% para a realização de upgrades. Para obter mais informações, consulte limites para pontos de extremidade online.

Para ver uma lista completa de atributos que você pode especificar ao criar uma implantação, consulte CLI (v2) managed online deployment YAML schema ou SDK (v2) ManagedOnlineDeployment Class.

Criar ponto de extremidade online

Primeiro, defina o nome do ponto de extremidade e, em seguida, configure-o. Neste artigo, você usará o arquivo endpoints/online/managed/sample/endpoint.yml para configurar o endpoint. O trecho a seguir mostra o conteúdo do arquivo:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key

A referência para o formato YAML do ponto de extremidade é descrita na tabela a seguir. Para saber como especificar esses atributos, consulte a referência YAML do ponto de extremidade online. Para obter informações sobre limites relacionados a pontos de extremidade online gerenciados, consulte limites para pontos de extremidade online.

Chave Description
$schema (Opcional) O esquema YAML. Para ver todas as opções disponíveis no arquivo YAML, você pode exibir o esquema no trecho de código anterior em um navegador.
name O nome do ponto de extremidade.
auth_mode Use key para autenticação baseada em chave. Use aml_token para autenticação baseada em token do Azure Machine Learning. Para obter o token mais recente, use o az ml online-endpoint get-credentials comando.

Para criar um ponto de extremidade online:

  1. Defina o nome do seu ponto final:

    Para Unix, execute este comando (substitua YOUR_ENDPOINT_NAME por 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 do Azure westus2 , pode haver apenas um ponto de extremidade com o nome my-endpoint.

  2. Crie o ponto de extremidade na nuvem:

    Execute o seguinte código para usar o endpoint.yml arquivo para configurar o ponto de extremidade:

    az ml online-endpoint create --name $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

Criar a implantação 'azul'

Neste artigo, você usará o arquivo endpoints/online/managed/sample/blue-deployment.yml para configurar os principais aspetos da implantação. O trecho a seguir mostra o conteúdo do arquivo:

$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-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

Para criar uma implantação nomeada blue para seu ponto de extremidade, execute o seguinte comando para usar o blue-deployment.yml arquivo para configurar

az ml online-deployment create --name blue --endpoint-name $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml --all-traffic

Importante

O --all-traffic sinalizador no az ml online-deployment create aloca 100% do tráfego de ponto de extremidade para a implantação azul recém-criada.

blue-deployment.yaml No arquivo, especificamos o path (de onde fazer upload de arquivos) embutido. A CLI carrega automaticamente os arquivos e registra o modelo e o ambiente. Como prática recomendada para produção, você deve registrar o modelo e o ambiente e especificar o nome registrado e a versão separadamente no YAML. Use o formulário model: azureml:my-model:1 ou environment: azureml:my-env:1.

Para o registro, você pode extrair as definições de 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 seu modelo como um ativo no Machine Learning usando a CLI. Para obter mais informações sobre como criar um ambiente, consulte Manage Azure Machine Learning environments with the CLI & SDK (v2).

Confirme sua implantação existente

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 ou do Python SDK, você pode optar por especificar o nome da implantação que receberá o tráfego de entrada.

Nota

Ao contrário da CLI ou do SDK do Python, o estúdio do Azure Machine Learning exige que você especifique uma implantação quando invoca um ponto de extremidade.

Invocar ponto de extremidade com nome de implantação

Se você invocar o ponto de extremidade com o nome da implantação que receberá tráfego, o Aprendizado de Máquina do Azure roteará o tráfego do ponto de extremidade diretamente para a implantação especificada e retornará sua saída. Você pode usar a opção para CLI v2 ou deployment_name a --deployment-name opção para SDK v2 para especificar a implantação.

Invoque o ponto de extremidade sem especificar a implantação

Se você invocar o ponto de extremidade sem especificar a implantação que receberá tráfego, o Aprendizado de Máquina do Azure encaminhará o tráfego de entrada do ponto de extremidade para a(s) implantação(õ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 de tráfego de entrada para cada implantação no ponto de extremidade. Por exemplo, se suas regras de tráfego especificarem que uma implantação específica em seu ponto de extremidade receberá tráfego de entrada 40% do tempo, o Aprendizado de Máquina do Azure encaminhará 40% do tráfego do ponto de extremidade para essa implantação.

Você pode exibir o status do ponto de extremidade e da implantação existentes executando:

az ml online-endpoint show --name $ENDPOINT_NAME 

az ml online-deployment show --name blue --endpoint $ENDPOINT_NAME

Você deve ver o ponto de extremidade identificado por $ENDPOINT_NAME e, uma implantação chamada blue.

Testar o ponto de extremidade com dados de amostra

O ponto de extremidade pode ser invocado usando o invoke comando. Enviaremos uma solicitação de exemplo usando um arquivo json .

az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

Dimensione sua implantação existente para lidar com mais tráfego

Na implantação descrita em Implantar e pontuar um modelo de aprendizado de máquina com um ponto de extremidade online, você define o instance_count para o valor 1 no arquivo yaml de implantação. Você pode expandir usando o update comando:

az ml online-deployment update --name blue --endpoint-name $ENDPOINT_NAME --set instance_count=2

Nota

Observe que no comando acima usamos --set para substituir a configuração de implantação. Como alternativa, você pode atualizar o arquivo yaml e passá-lo como uma entrada para o update comando usando a --file entrada.

Implantar um novo modelo, mas enviá-lo sem tráfego ainda

Crie 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 não alocamos explicitamente nenhum tráfego para o green, ele tem zero tráfego alocado a ele. Você pode verificar que usando o comando:

az ml online-endpoint show -n $ENDPOINT_NAME --query traffic

Testar a nova implantação

Embora green tenha 0% do tráfego alocado, você pode invocá-lo diretamente especificando o --deployment nome:

az ml online-endpoint invoke --name $ENDPOINT_NAME --deployment-name green --request-file endpoints/online/model-2/sample-request.json

Se você quiser 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 trecho de código abaixo é usado curl para invocar a implantação diretamente. O trecho de código deve funcionar em ambientes Unix/WSL:

# 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

Testar a implementação com tráfego espelhado

Depois de testar sua green implantação, você pode espelhar (ou copiar) uma porcentagem do tráfego ao vivo para ela. O espelhamento de tráfego (também chamado de sombreamento) não altera os resultados retornados aos clientes — as solicitações ainda fluem 100% para a blue implantação. A porcentagem espelhada do tráfego é copiada e enviada para a green implantação para que você possa coletar métricas e registro em log sem afetar seus clientes. O espelhamento é útil quando você deseja 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 para verificar se não há erros HTTP. O teste da nova implantação com espelhamento/sombreamento de tráfego também é conhecido como teste de sombra. A implantação que recebe o tráfego espelhado (neste caso, a green implantação) também pode ser chamada de implantação sombra.

O espelhamento tem as seguintes limitações:

  • O espelhamento é suportado para a CLI (v2) (versão 2.4.0 ou superior) e Python SDK (v2) (versão 1.0.0 ou superior). Se você usar uma versão mais antiga da CLI/SDK para atualizar um ponto de extremidade, perderá a configuração de tráfego espelhado.
  • Atualmente, o espelhamento não é suportado para endpoints online do Kubernetes.
  • Você pode espelhar o tráfego para apenas uma implantação em um ponto de extremidade.
  • A percentagem máxima de tráfego que pode espelhar é de 50%. Esse limite é para reduzir o efeito na cota de largura de banda do endpoint (padrão de 5 MBPS) — a largura de banda do endpoint é limitada se você exceder a cota alocada. Para obter informações sobre como monitorar a limitação de largura de banda, consulte Monitorar pontos de extremidade online gerenciados.

Observe também os seguintes comportamentos:

  • Uma implantação pode ser configurada para receber apenas tráfego em tempo real 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 com o nome da implantação que receberá tráfego de entrada, o Aprendizado de Máquina do Azure 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.

Agora, vamos definir a implantação verde para receber 10% do tráfego espelhado. Os clientes ainda receberão previsões apenas da implantação azul.

Diagram showing 10% traffic mirrored to one deployment.

O comando a seguir espelha 10% do tráfego para a green implantação:

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 que a porcentagem específica do tráfego foi enviada para a green implantação vendo os logs da implantação:

az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

Após o teste, você pode definir o tráfego de espelho como zero para desabilitar o espelhamento:

az ml online-endpoint update --name $ENDPOINT_NAME --mirror-traffic "green=0"

Alocar uma pequena porcentagem do tráfego ao vivo 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"

Gorjeta

A porcentagem de tráfego total deve somar 0% (para desabilitar o tráfego) ou 100% (para habilitar o tráfego).

Agora, sua implantação recebe 10% de todo o green tráfego ao vivo. Os clientes receberão previsões das implantações e green das blue implantações.

Diagram showing traffic split between deployments.

Envie todo o tráfego para sua nova implantação

Quando estiver totalmente satisfeito com sua green implantação, 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. A exclusão de uma implantação individual 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 vai usar o ponto de extremidade e a implantação, exclua-os. Ao excluir o ponto de extremidade, você também excluirá todas as suas implantações subjacentes.

az ml online-endpoint delete --name $ENDPOINT_NAME --yes --no-wait

Conteúdos relacionados