Distribuição progressiva de modelos do MLflow para pontos de extremidade online

Artigo
10/21/2023

Neste artigo, você aprenderá como atualizar e implantar progressivamente modelos do MLflow em pontos de extremidade online sem causar interrupções no serviço. Você usará a implantação azul-verde, 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. Essa estratégia permitirá que você implemente sua nova versão do serviço Web a um pequeno subconjunto de usuários ou solicitações antes de implantá-la completamente.

Sobre este exemplo

Os pontos de extremidade online têm o conceito de Ponto de Extremidade e Implantação. Um ponto de extremidade representa a API que os clientes usam para consumir o modelo, ao passo que a implantação indica a implementação específica dessa API. Essa distinção permite que os usuários desacoplem a API da implementação e alterem a implementação subjacente sem afetar o consumidor. Este exemplo usará esses conceitos para atualizar o modelo implantado em pontos de extremidade sem introduzir a interrupção do serviço.

O modelo que implantaremos é baseado no conjunto de dados UCI Heart Disease. O banco de dados contém 76 atributos, mas estamos usando um subconjunto de 14 deles. O modelo tenta prever a presença de doenças cardíacas em um paciente. Ele é inteiro com valor 0 (sem presença) a 1 (presença). Ele foi treinado usando um classificador XGBBoost e todo o pré-processamento necessário foi empacotado como um pipeline scikit-learn, tornando esse modelo um pipeline de ponta a ponta que vai de dados brutos a previsões.

As informações deste artigo se baseiam em exemplos de código contidos no repositório azureml-examples. Para executar os comandos localmente sem precisar copiar/colar arquivos, clone o repositório e altere os diretórios para sdk/using-mlflow/deploy.

Acompanhar em Jupyter Notebooks

Você pode acompanhar este exemplo nos notebooks a seguir. No repositório clonado, abra o notebook: mlflow_sdk_online_endpoints_progresive.ipynb.

Pré-requisitos

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

Uma assinatura do Azure. Caso não tenha uma assinatura do Azure, crie uma conta gratuita antes de começar. Experimente a versão gratuita ou paga do Azure Machine Learning.
O RBAC do Azure (controle de acesso baseado em função) do Azure é usado para permitir acesso a operações no Azure Machine Learning. Para executar as etapas neste artigo, sua conta de usuário deve ser atribuída com a função de proprietário ou colaborador para o workspace do Azure Machine Learning ou uma função personalizada que permita Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*. Para obter mais informações, consulte Gerenciar acesso a um workspace do Azure Machine Learning.

Além disso, será necessário:

Instale a CLI do Azure e a extensão ml na CLI do Azure. Para obter mais informações, confira Instalar, configurar e usar a CLI (v2).

Instale o pacote mlflow do SDK do Mlflow e o plug-in do Azure Machine Learning para MLflow azureml-mlflow.
```
pip install mlflow azureml-mlflow
```
Se você não estiver executando uma computação do Azure Machine Learning, configure o URI de acompanhamento do MLflow ou o URI de registro do MLflow para apontar para o workspace no qual você está trabalhando. Saiba como Configurar o MLflow para o Azure Machine Learning.

Conectar-se ao workspace

Primeiro, vamos nos conectar ao workspace do Azure Machine Learning no qual vamos trabalhar.

az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

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, nos conectaremos ao workspace no qual você executará tarefas de implantação.

Importe as bibliotecas necessárias:

from azure.ai.ml import MLClient, Input
from azure.ai.ml.entities import ManagedOnlineEndpoint, ManagedOnlineDeployment, 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:

subscription_id = "<subscription>"
resource_group = "<resource-group>"
workspace = "<workspace>"

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

Importar as bibliotecas necessárias

import json
import mlflow
import requests
import pandas as pd
from mlflow.deployments import get_deploy_client

Configure o cliente MLflow e o cliente de implantação:

mlflow_client = mlflow.MLflowClient()
deployment_client = get_deploy_client(mlflow.get_tracking_uri())

Registrar o modelo no registro

Verifique se o modelo está registrado no Registro do Azure Machine Learning. Não há suporte para a implantação de modelos não registrados no Azure Machine Learning. Você pode registrar um novo modelo usando o SDK do MLflow:

MODEL_NAME='heart-classifier'
az ml model create --name $MODEL_NAME --type "mlflow_model" --path "model"

model_name = 'heart-classifier'
model_local_path = "model"

model = ml_client.models.create_or_update(
     Model(name=model_name, path=model_local_path, type=AssetTypes.MLFLOW_MODEL)
)

model_name = 'heart-classifier'
model_local_path = "model"

registered_model = mlflow_client.create_model_version(
    name=model_name, source=f"file://{model_local_path}"
)
version = registered_model.version

Criar um ponto de extremidade online

Os pontos de extremidade online são pontos de extremidade 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.

Vamos explorar essa funcionalidade implantando várias versões do mesmo modelo no mesmo ponto de extremidade. No entanto, a nova implantação receberá 0% do tráfego no começo. Depois que tivermos certeza que o novo modelo funciona corretamente, moveremos progressivamente o tráfego de uma implantação para a outra.

Os pontos de extremidade exigem um nome, que precisa ser exclusivo na mesma região. Vamos nos certificar de criar um que não exista:

ENDPOINT_SUFIX=$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w ${1:-5} | head -n 1)
ENDPOINT_NAME="heart-classifier-$ENDPOINT_SUFIX"

import random
import string

# Creating a unique endpoint name by including a random suffix
allowed_chars = string.ascii_lowercase + string.digits
endpoint_suffix = "".join(random.choice(allowed_chars) for x in range(5))
endpoint_name = "heart-classifier-" + endpoint_suffix

print(f"Endpoint name: {endpoint_name}")

import random
import string

# Creating a unique endpoint name by including a random suffix
allowed_chars = string.ascii_lowercase + string.digits
endpoint_suffix = "".join(random.choice(allowed_chars) for x in range(5))
endpoint_name = "heart-classifier-" + endpoint_suffix

print(f"Endpoint name: {endpoint_name}")

Configurar o ponto de extremidade

endpoint.yml

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: heart-classifier-edp
auth_mode: key

endpoint = ManagedOnlineEndpoint(
    name=endpoint_name,
    description="An endpoint to serve predictions of the UCI heart disease problem",
    auth_mode="key",
)

Podemos configurar as propriedades desse ponto de extremidade usando um arquivo de configuração. Configuramos o modo de autenticação do ponto de extremidade como “chave” no exemplo a seguir:

endpoint_config = {
    "auth_mode": "key",
    "identity": {
        "type": "system_assigned"
    }
}

Vamos gravar essa configuração em um arquivo JSON:

endpoint_config_path = "endpoint_config.json"
with open(endpoint_config_path, "w") as outfile:
    outfile.write(json.dumps(endpoint_config))

Criar o ponto de extremidade:

az ml online-endpoint create -n $ENDPOINT_NAME -f endpoint.yml

ml_client.online_endpoints.begin_create_or_update(endpoint).result()

endpoint = deployment_client.create_endpoint(
    name=endpoint_name,
    config={"endpoint-config-file": endpoint_config_path},
)

Obtendo o segredo de autenticação para o ponto de extremidade.
```
ENDPOINT_SECRET_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME | jq -r ".accessToken")
```
```
endpoint_secret_key = ml_client.online_endpoints.list_keys(
    name=endpoint_name
).access_token
```
Esta funcionalidade não está disponível no SDK do MLflow. Acesse o Estúdio do Azure Machine Learning, procure o ponto de extremidade e recupere a chave secreta nele.

Criar uma implantação azul

Até agora, o ponto de extremidade está vazio. Não há implantações nele. Vamos criar o primeiro implantando o mesmo modelo em que estávamos trabalhando antes. Chamaremos essa implantação de “padrão”, representando nossa “implantação azul”.

Configurar a implantação

blue-deployment.yml

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: default
endpoint_name: heart-classifier-edp
model: azureml:heart-classifier@latest
instance_type: Standard_DS2_v2
instance_count: 1

blue_deployment_name = "default"

Configurar os requisitos de hardware da implantação:

blue_deployment = ManagedOnlineDeployment(
    name=blue_deployment_name,
    endpoint_name=endpoint_name,
    model=model,
    instance_type="Standard_DS2_v2",
    instance_count=1,
)

Se o ponto de extremidade não tiver conectividade de saída, use o empacotamento de modelo (versão prévia), incluindo o argumento with_package=True:

blue_deployment = ManagedOnlineDeployment(
    name=blue_deployment_name,
    endpoint_name=endpoint_name,
    model=model,
    instance_type="Standard_DS2_v2",
    instance_count=1,
    with_package=True,
)

blue_deployment_name = "default"

Para configurar os requisitos de hardware da implantação, é necessário criar um arquivo JSON com a configuração desejada:

deploy_config = {
    "instance_type": "Standard_DS2_v2",
    "instance_count": 1,
}

Observação

A especificação completa dessa configuração pode ser encontrada no Esquema de implantação online gerenciado (v2).

Gravar a configuração em um arquivo:

deployment_config_path = "deployment_config.json"
with open(deployment_config_path, "w") as outfile:
    outfile.write(json.dumps(deploy_config))

Criar a implantação

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

Se o ponto de extremidade não tiver conectividade de saída, use o empacotamento de modelo (versão prévia) incluindo o sinalizador --with-package:

az ml online-deployment create --with-package --endpoint-name $ENDPOINT_NAME -f blue-deployment.yml --all-traffic

Dica

Definimos o sinalizador --all-traffic no comando create, que atribuirá todo o tráfego à nova implantação.

ml_client.online_deployments.begin_create_or_update(blue_deployment).result()

blue_deployment = deployment_client.create_deployment(
    name=blue_deployment_name,
    endpoint=endpoint_name,
    model_uri=f"models:/{model_name}/{version}",
    config={"deploy-config-file": deployment_config_path},
)

Atribuir todo o tráfego à implantação

Até agora, o ponto de extremidade tem uma implantação, mas nenhum tráfego é atribuído a ele. Vamos atribuí-lo.
Esta etapa não é necessária na CLI do Azure, pois usamos --all-traffic durante a criação.
```
endpoint.traffic = { blue_deployment_name: 100 }
```
```
traffic_config = {"traffic": {blue_deployment_name: 100}}
```
Gravar a configuração em um arquivo:
```
traffic_config_path = "traffic_config.json"
with open(traffic_config_path, "w") as outfile:
    outfile.write(json.dumps(traffic_config))
```
Atualizar a configuração do ponto de extremidade:
Esta etapa não é necessária na CLI do Azure, pois usamos --all-traffic durante a criação.
```
ml_client.begin_create_or_update(endpoint).result()
```
```
deployment_client.update_endpoint(
    endpoint=endpoint_name,
    config={"endpoint-config-file": traffic_config_path},
)
```

Criar uma entrada de exemplo para testar a implantação

sample.yml

{
    "input_data": {
        "columns": [
            "age",
            "sex",
            "cp",
            "trestbps",
            "chol",
            "fbs",
            "restecg",
            "thalach",
            "exang",
            "oldpeak",
            "slope",
            "ca",
            "thal"
        ],
        "data": [
            [ 48, 0, 3, 130, 275, 0, 0, 139, 0, 0.2, 1, 0, "normal" ]
        ]
    }
}

O código a seguir amostra 5 observações do conjunto de dados de treinamento, remove a coluna target (como o modelo irá prever) e cria uma solicitação no arquivo sample.json que pode ser usada com a implantação do modelo.

samples = (
    pd.read_csv("data/heart.csv")
    .sample(n=5)
    .drop(columns=["target"])
    .reset_index(drop=True)
)

with open("sample.json", "w") as f:
    f.write(
        json.dumps(
            {"input_data": json.loads(samples.to_json(orient="split", index=False))}
        )
    )

O código a seguir amostra 5 observações do conjunto de dados de treinamento, remove a coluna target (como o modelo irá prever) e cria uma solicitação.

samples = (
    pd.read_csv("data/heart.csv")
    .sample(n=5)
    .drop(columns=["target"])
    .reset_index(drop=True)
)

Teste a implantação

az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file sample.json

ml_client.online_endpoints.invoke(
    endpoint_name=endpoint_name,
    request_file="sample.json",
)

deployment_client.predict(
    endpoint=endpoint_name, 
    df=samples
)

Criar uma implantação verde no ponto de extremidade

Vamos imaginar que há uma nova versão do modelo criado pela equipe de desenvolvimento e que ele está pronto para estar em produção. Primeiro podemos tentar usar esse modelo e, quando estivermos confiantes, podemos atualizar o ponto de extremidade para rotear o tráfego para ele.

Registrar uma nova versão do modelo

MODEL_NAME='heart-classifier'
az ml model create --name $MODEL_NAME --type "mlflow_model" --path "model"

Vamos obter o número de versão do novo modelo:

VERSION=$(az ml model show -n heart-classifier --label latest | jq -r ".version")

model_name = 'heart-classifier'
model_local_path = "model"

model = ml_client.models.create_or_update(
     Model(name=model_name, path=model_local_path, type=AssetTypes.MLFLOW_MODEL)
)
version = model.version

model_name = 'heart-classifier'
model_local_path = "model"

registered_model = mlflow_client.create_model_version(
    name=model_name, source=f"file://{model_local_path}"
)
version = registered_model.version

Configurar uma nova implantação

green-deployment.yml

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: xgboost-model
endpoint_name: heart-classifier-edp
model: azureml:heart-classifier@latest
instance_type: Standard_DS2_v2
instance_count: 1

Nomearemos a implantação da seguinte maneira:

GREEN_DEPLOYMENT_NAME="xgboost-model-$VERSION"

green_deployment_name = f"xgboost-model-{version}"

Configurar os requisitos de hardware da implantação:

green_deployment = ManagedOnlineDeployment(
    name=green_deployment_name,
    endpoint_name=endpoint_name,
    model=model,
    instance_type="Standard_DS2_v2",
    instance_count=1,
)

Se o ponto de extremidade não tiver conectividade de saída, use o empacotamento de modelo (versão prévia) incluindo o argumento with_package=True:

green_deployment = ManagedOnlineDeployment(
    name=green_deployment_name,
    endpoint_name=endpoint_name,
    model=model,
    instance_type="Standard_DS2_v2",
    instance_count=1,
    with_package=True,
)

green_deployment_name = f"xgboost-model-{version}"

Para configurar os requisitos de hardware da implantação, é necessário criar um arquivo JSON com a configuração desejada:

deploy_config = {
    "instance_type": "Standard_DS2_v2",
    "instance_count": 1,
}

Dica

Estamos usando a mesma confirmação de hardware indicada no deployment-config-file. No entanto, não há requisitos para ter a mesma configuração. Você pode configurar diferentes hardwares para diferentes modelos dependendo dos requisitos.

Gravar a configuração em um arquivo:

deployment_config_path = "deployment_config.json"
with open(deployment_config_path, "w") as outfile:
    outfile.write(json.dumps(deploy_config))

Criar a nova implantação

az ml online-deployment create -n $GREEN_DEPLOYMENT_NAME --endpoint-name $ENDPOINT_NAME -f green-deployment.yml

Se o ponto de extremidade não tiver conectividade de saída, use o empacotamento de modelo (versão prévia) incluindo o sinalizador --with-package:

az ml online-deployment create --with-package -n $GREEN_DEPLOYMENT_NAME --endpoint-name $ENDPOINT_NAME -f green-deployment.yml

ml_client.online_deployments.begin_create_or_update(green_deployment).result()

new_deployment = deployment_client.create_deployment(
    name=green_deployment_name,
    endpoint=endpoint_name,
    model_uri=f"models:/{model_name}/{version}",
    config={"deploy-config-file": deployment_config_path},
)

Testar a implantação sem alterar o tráfego

az ml online-endpoint invoke --name $ENDPOINT_NAME --deployment-name $GREEN_DEPLOYMENT_NAME --request-file sample.json

ml_client.online_endpoints.invoke(
    endpoint_name=endpoint_name,
    deployment_name=green_deployment_name
    request_file="sample.json",
)

deployment_client.predict(
    endpoint=endpoint_name, 
    deployment_name=green_deployment_name, 
    df=samples
)

Dica

Observe como nós agora estamos indicando o nome da implantação que queremos invocar.

Atualizar progressivamente o tráfego

Quando estivermos confiantes com a nova implantação, poderemos atualizar o tráfego para rotear parte dele para a nova implantação. O tráfego é configurado no nível do ponto de extremidade:

Configurar o tráfego:

Esta etapa não é necessária na CLI do Azure

endpoint.traffic = {blue_deployment_name: 90, green_deployment_name: 10}

traffic_config = {"traffic": {blue_deployment_name: 90, green_deployment_name: 10}}

Gravar a configuração em um arquivo:

traffic_config_path = "traffic_config.json"
with open(traffic_config_path, "w") as outfile:
    outfile.write(json.dumps(traffic_config))

Atualizar o ponto de extremidade

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "default=90 $GREEN_DEPLOYMENT_NAME=10"

ml_client.begin_create_or_update(endpoint).result()

deployment_client.update_endpoint(
    endpoint=endpoint_name,
    config={"endpoint-config-file": traffic_config_path},
)

Se você decidir alternar o tráfego inteiro para a nova implantação, atualize todo o tráfego:

Esta etapa não é necessária na CLI do Azure

endpoint.traffic = {blue_deployment_name: 0, green_deployment_name: 100}

traffic_config = {"traffic": {blue_deployment_name: 0, green_deployment_name: 100}}

Gravar a configuração em um arquivo:

traffic_config_path = "traffic_config.json"
with open(traffic_config_path, "w") as outfile:
    outfile.write(json.dumps(traffic_config))

Atualizar o ponto de extremidade

az ml online-endpoint update --name $ENDPOINT_NAME --traffic "default=0 $GREEN_DEPLOYMENT_NAME=100"

ml_client.begin_create_or_update(endpoint).result()

deployment_client.update_endpoint(
    endpoint=endpoint_name,
    config={"endpoint-config-file": traffic_config_path},
)

Como a implantação antiga não recebe tráfego, você pode excluí-la com segurança:
```
az ml online-deployment delete --endpoint-name $ENDPOINT_NAME --name default
```
```
ml_client.online_deployments.begin_delete(
    name=blue_deployment_name, 
    endpoint_name=endpoint_name
)
```
```
deployment_client.delete_deployment(
    blue_deployment_name, 
    endpoint=endpoint_name
)
```
Dica

Observe que, neste ponto, a antiga "implantação azul" foi excluída e a nova "implantação verde" tomou o lugar da "implantação azul".

Recursos de limpeza

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

ml_client.online_endpoints.begin_delete(name=endpoint_name)

deployment_client.delete_endpoint(endpoint_name)

Importante

Observe que excluir um ponto de extremidade também exclui todas as implantações nele.

Share via

Distribuição progressiva de modelos do MLflow para pontos de extremidade online

Sobre este exemplo

Acompanhar em Jupyter Notebooks

Pré-requisitos

Conectar-se ao workspace

Registrar o modelo no registro

Criar um ponto de extremidade online

Criar uma implantação azul

Criar uma implantação verde no ponto de extremidade

Atualizar progressivamente o tráfego

Recursos de limpeza

Próximas etapas

Recursos adicionais