Implementação progressiva de modelos MLflow para endpoints online

Artigo
10/19/2023

Neste artigo, você aprenderá como atualizar e implantar progressivamente modelos MLflow em endpoints online sem causar interrupção do serviço. Você usa 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 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.

Sobre este exemplo

Os endpoints online têm o conceito de Endpoint e Deployment. Um ponto de extremidade representa a API que os clientes usam para consumir o modelo, enquanto a implantação indica a implementação específica dessa API. Essa distinção permite que os usuários desvinculem 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 interrupção do serviço.

O modelo que vamos implantar é baseado no UCI Heart Disease Data set. 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ça cardíaca em um paciente. É inteiro valorizado de 0 (sem presença) a 1 (presença). Ele foi treinado usando um XGBBoost classificador e todo o pré-processamento necessário foi empacotado como um scikit-learn pipeline, tornando este modelo um pipeline de ponta a ponta que vai de dados brutos a previsões.

As informações neste artigo são baseadas em exemplos de código contidos no repositório azureml-examples . Para executar os comandos localmente sem ter que copiar/colar arquivos, clone o repositório e, em seguida, altere os diretórios para sdk/using-mlflow/deploy.

Acompanhe em Jupyter Notebooks

Pode acompanhar este exemplo nos seguintes blocos de notas. No repositório clonado, abra o bloco de anotações: mlflow_sdk_online_endpoints_progresive.ipynb.

Pré-requisitos

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

Uma subscrição do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar. Experimente a versão gratuita ou paga do Azure Machine Learning.
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.

Além disso, você precisará:

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

Instale o pacote mlflow 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 na computação do Aprendizado de Máquina do Azure, configure o URI de rastreamento MLflow ou o URI do registro do MLflow para apontar para o espaço de trabalho no qual você está trabalhando. Saiba como configurar o MLflow para o Azure Machine Learning.

Ligar à sua área de trabalho

Primeiro, vamos nos conectar ao espaço de trabalho do Azure Machine Learning no qual vamos trabalhar.

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

A área de trabalho é o recurso de nível superior do Azure Machine Learning que proporciona um local centralizado para trabalhar com todos os artefactos que cria quando utiliza o Azure Machine Learning. Nesta seção, nos conectaremos ao espaço de trabalho 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 espaço de trabalho e obtenha um identificador para o espaço de trabalho:

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())

Registar o modelo no registo

Certifique-se de que o seu modelo está registado no registo do Azure Machine Learning. A implantação de modelos não registrados não é suportada no Azure Machine Learning. Você pode registrar um novo modelo usando o SDK 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

Pontos de extremidade online são pontos de extremidade que são usados para inferência online (em tempo real). Os pontos finais online incluem implementações prontas para receber dados dos clientes e podem enviar respostas em tempo real.

Vamos explorar essa funcionalidade implantando várias versões do mesmo modelo sob o mesmo ponto de extremidade. No entanto, a nova implantação receberá 0% do tráfego na mendicidade. Assim que tivermos certeza de que o novo modelo funcionará corretamente, vamos mover 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 garantir a criação de um que não existe:

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 deste ponto de extremidade usando um arquivo de configuração. Configuramos o modo de autenticação do ponto de extremidade para ser "chave" no exemplo a seguir:

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

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

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

Crie 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},
)

Obter 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
```
Essa funcionalidade não está disponível no SDK do MLflow. Vá para o estúdio do Azure Machine Learning, navegue até o ponto de extremidade e recupere a chave secreta de lá.

Criar uma implantação azul

Até agora, o ponto final 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 implementaçã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"

Configure os requisitos de hardware da sua 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 do modelo (visualização) 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 de sua implantação, você precisa criar um arquivo JSON com a configuração desejada:

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

Nota

A especificação completa dessa configuração pode ser encontrada em Managed online deployment schema (v2).

Escreva 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 seu ponto de extremidade não tiver conectividade de saída, use o empacotamento do modelo (visualização) incluindo o sinalizador --with-package:

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

Gorjeta

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 de seu tráfego é atribuído a ele. Vamos atribuí-lo.
Esta etapa não é necessária na CLI do Azure, pois usamos o durante a --all-traffic criação.
```
endpoint.traffic = { blue_deployment_name: 100 }
```
```
traffic_config = {"traffic": {blue_deployment_name: 100}}
```
Escreva 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))
```
Atualize a configuração do ponto final:
Esta etapa não é necessária na CLI do Azure, pois usamos o durante a --all-traffic 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 exemplifica 5 observações do conjunto de dados de treinamento, remove a target coluna (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 exemplifica 5 observações do conjunto de dados de treinamento, remove a target coluna (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)
)

Testar a implementaçã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 sob o ponto de extremidade

Vamos imaginar que existe uma nova versão do modelo criado pela equipe de desenvolvimento e ele está pronto para estar em produção. Podemos primeiro tentar voar este modelo e, uma vez que estejamos confiantes, podemos atualizar o endpoint para rotear o tráfego para ele.

Registar 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 da 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

Vamos nomear a implantação da seguinte maneira:

GREEN_DEPLOYMENT_NAME="xgboost-model-$VERSION"

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

Configure os requisitos de hardware da sua 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 do modelo (visualização) 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 de sua implantação, você precisa criar um arquivo JSON com a configuração desejada:

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

Gorjeta

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 hardware diferente para modelos diferentes, dependendo dos requisitos.

Escreva 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 seu ponto de extremidade não tiver conectividade de saída, use o empacotamento do modelo (visualização) 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},
)

Teste 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
)

Gorjeta

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

Atualizar progressivamente o tráfego

Estamos confiantes de que com a nova implantação, podemos atualizar o tráfego para rotear parte dele para a nova implantação. O tráfego é configurado no nível do ponto final:

Configure 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}}

Escreva 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 todo o tráfego 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}}

Escreva 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
)
```
Gorjeta

Observe que, neste momento, a antiga "implantação azul" foi excluída e a nova "implantação verde" substituiu a "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 sob ele.

Partilhar via

Implementação progressiva de modelos MLflow para endpoints online

Sobre este exemplo

Acompanhe em Jupyter Notebooks

Pré-requisitos

Ligar à sua área de trabalho

Registar o modelo no registo

Criar um ponto de extremidade online

Criar uma implantação azul

Criar uma implantação verde sob o ponto de extremidade

Atualizar progressivamente o tráfego

Recursos de limpeza

Próximos passos

Recursos adicionais