Implementazione progressiva di modelli MLflow in endpoint online

Articolo
10/16/2024

In questo articolo, viene illustrato come aggiornare e distribuire in modo progressivo modelli MLflow in endpoint online senza causare interruzioni del servizio. Viene usata la distribuzione blue-green, detta anche strategia di implementazione sicura, per introdurre la nuova versione di un servizio Web in produzione. Questa strategia consentirà di implementare la nuova versione del servizio Web in un piccolo subset di utenti o di richieste prima di implementarla completamente.

Informazioni su questo esempio

Gli endpoint online comprendono il concetto di endpoint e distribuzione. Un endpoint rappresenta l'API usata dai clienti per utilizzare il modello, mentre la distribuzione indica l'implementazione specifica di tale API. Questa distinzione consente agli utenti di separare l'API dall'implementazione e di modificare l'implementazione sottostante senza influire sul consumer. Questo esempio userà tali concetti per aggiornare il modello distribuito negli endpoint senza provocare interruzioni del servizio.

Il modello che verrà distribuito si basa sul set di dati UCI Heart Disease. Il database contiene 76 attributi, ma viene usato un subset di 14 attributi. Il modello cerca di prevedere la presenza di una malattia cardiaca in un paziente. È un valore intero compreso tra 0 (assenza) e 1 (presenza). È stato eseguito il training usando un classificatore XGBBoost e tutta la pre-elaborazione necessaria è stata inserita in un pacchetto come pipeline scikit-learn, rendendo questo modello una pipeline end-to-end che va dai dati non elaborati alle previsioni.

Le informazioni contenute in questo articolo si basano sugli esempi di codice contenuti nel repository azureml-examples. Per eseguire i comandi in locale senza dover copiare o incollare file, è possibile clonare il repository e quindi modificare le directory in sdk/using-mlflow/deploy.

Seguire la procedura in Jupyter Notebooks

È possibile seguire questo esempio nei notebook seguenti. Nel repository clonato aprire, il notebook: mlflow_sdk_online_endpoints_progresive.ipynb.

Prerequisiti

Prima di seguire la procedura descritta in questo articolo, assicurarsi di disporre dei prerequisiti seguenti:

Una sottoscrizione di Azure. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare. Provare la versione gratuita o a pagamento di Azure Machine Learning.
I controlli degli accessi in base al ruolo di Azure vengono usati per concedere l'accesso alle operazioni in Azure Machine Learning. Per eseguire la procedura descritta in questo articolo, all'account utente deve essere assegnato il ruolo di proprietario o collaboratore per l'area di lavoro di Azure Machine Learning oppure un ruolo personalizzato che consenta "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/". Per altre informazioni, vedere Gestire l'accesso a un'area di lavoro di Azure Machine Learning.

Sarà inoltre necessario:

Installare l'interfaccia della riga di comando di Azure e l'estensione di Machine Learning nell'interfaccia della riga di comando di Azure. Per altre informazioni, vedere Installare, configurare e usare l'interfaccia della riga di comando (v2).

Installare il pacchetto SDK di MLflow mlflow e il plug-in di Azure Machine Learning per MLflow azureml-mlflow.
```
pip install mlflow azureml-mlflow
```
Se non si esegue codice nell'ambiente di calcolo di Azure Machine Learning, configurare l'URI di rilevamento MLflow o del registro di MLflow in modo che punti all'area di lavoro su cui si sta lavorando. Informazioni su come Configurare MLflow per Azure Machine Learning.

Connettersi all'area di lavoro

Connettersi prima di tutto all'area di lavoro di Azure Machine Learning in cui si lavorerà.

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

L'area di lavoro è la risorsa di primo livello per Azure Machine Learning, che fornisce una posizione centralizzata da cui gestire tutti gli artefatti creati quando si usa Azure Machine Learning. In questa sezione ci si connetterà all'area di lavoro in cui verranno eseguite le attività di distribuzione.

Importare le librerie necessarie:

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

Configurare i dettagli e ottenere un handle per l'area di lavoro:

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

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

Importare le librerie necessarie

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

Configurare il client MLflow e il client di distribuzione:

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

Registrazione del modello nel registro

Verificare che il modello sia registrato nel registro di Azure Machine Learning. La distribuzione di modelli non registrati non è supportata in Azure Machine Learning. È possibile registrare un nuovo modello usando l'SDK di 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

Creare un endpoint online

Gli endpoint online sono endpoint usati per l'inferenza online (in tempo reale). Gli endpoint online contengono distribuzioni pronte a ricevere dati dai client e in grado di inviare risposte in tempo reale.

Questa funzionalità verrà sfruttata se si distribuiscono più versioni dello stesso modello nello stesso endpoint. Tuttavia, la nuova distribuzione riceverà lo 0% del traffico in corrispondenza dell'assegnazione di tag. Una volta verificato il corretto funzionamento del nuovo modello, il traffico verrà spostato progressivamente da una distribuzione all'altra.

Gli endpoint richiedono un nome, che deve essere univoco nella stessa area. Assicurarsi di crearne uno che non esista già:

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}")

Configurare l'endpoint

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",
)

È possibile configurare le proprietà di questo endpoint usando un file di configurazione. La modalità di autenticazione dell'endpoint viene configurata come "chiave" nell'esempio seguente:

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

Scrivere questa configurazione in un file JSON:

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

Creare l'endpoint:

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

Recupero del segreto di autenticazione per l'endpoint.
```
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
```
Questa funzionalità non è ancora disponibile nell'SDK di MLflow. Passare a studio di Azure Machine Learning, spostarsi all'endpoint e recuperare la chiave privata da questa posizione.

Creare una distribuzione blu

Finora l'endpoint è vuoto. Non sono presenti distribuzioni. Si creerà la prima distribuendo lo stesso modello su cui si stava lavorando in precedenza. Questa distribuzione verrà denominata "default", che rappresenta la distribuzione blu.

Configurare la distribuzione

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"

Configurare i requisiti hardware della distribuzione:

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

Se l'endpoint non dispone di connettività in uscita, usare la creazione di pacchetti di modelli (anteprima) includendo l'argomento 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"

Per configurare i requisiti hardware della distribuzione, occorre creare un file JSON con la configurazione desiderata:

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

Nota

La specifica completa di questa configurazione è disponibile in Schema di distribuzione online gestito (v2).

Scrivere la configurazione in un file:

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

Creare la distribuzione

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

Se l'endpoint non dispone di connettività in uscita, usare la creazione di pacchetti di modelli (anteprima) includendo il flag --with-package:

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

Suggerimento

Si imposta il flag --all-traffic nel comando Crea, che assegnerà tutto il traffico alla nuova distribuzione.

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

Assegnare tutto il traffico alla distribuzione

Finora, l'endpoint dispone di una distribuzione, ma il traffico non viene assegnato ad esso. Assegnarlo.
Questo passaggio non è necessario nell'interfaccia della riga di comando di Azure, poiché è stato usato --all-traffic durante la creazione.
```
endpoint.traffic = { blue_deployment_name: 100 }
```
```
traffic_config = {"traffic": {blue_deployment_name: 100}}
```
Scrivere la configurazione in un file:
```
traffic_config_path = "traffic_config.json"
with open(traffic_config_path, "w") as outfile:
    outfile.write(json.dumps(traffic_config))
```
Aggiornare la configurazione dell'endpoint:
Questo passaggio non è necessario nell'interfaccia della riga di comando di Azure, poiché è stato usato --all-traffic durante la creazione.
```
ml_client.begin_create_or_update(endpoint).result()
```
```
deployment_client.update_endpoint(
    endpoint=endpoint_name,
    config={"endpoint-config-file": traffic_config_path},
)
```

Creare un input di esempio per testare la distribuzione

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" ]
        ]
    }
}

L'esempio di codice seguente illustra 5 osservazioni dal set di dati di training, rimuove la colonna target (come prevederà il modello) e crea una richiesta nel file sample.json che può essere usata con la distribuzione modello.

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

L'esempio di codice seguente illustra 5 osservazioni dal set di dati di training, rimuove la colonna target (come prevederà il modello) e crea una richiesta.

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

Testare la distribuzione

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
)

Creare una distribuzione verde nell'endpoint:

Si supponga di avere una nuova versione del modello creata dal team di sviluppo e che sia pronta per essere prodotta. È prima possibile provare a utilizzare questo modello e, una volta ottenuta familiarità, è possibile aggiornare l'endpoint per instradare il traffico a esso.

Registrare una nuova versione del modello

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

Ottenere il numero di versione del nuovo modello:

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

Configurare una nuova distribuzione

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

Denominare la distribuzione come indicato di seguito:

GREEN_DEPLOYMENT_NAME="xgboost-model-$VERSION"

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

Configurare i requisiti hardware della distribuzione:

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

Se l'endpoint non dispone di connettività in uscita, usare la creazione di pacchetti di modelli (anteprima) includendo il flag 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}"

Per configurare i requisiti hardware della distribuzione, occorre creare un file JSON con la configurazione desiderata:

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

Suggerimento

Viene usata la stessa conferma hardware indicata in deployment-config-file. Non sono tuttavia previsti requisiti con la stessa configurazione. È possibile configurare hardware diverso per modelli diversi a seconda dei requisiti.

Scrivere la configurazione in un file:

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

Creare la nuova distribuzione

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

Se l'endpoint non dispone di connettività in uscita, usare la creazione di pacchetti di modelli (anteprima) includendo il flag --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},
)

Testare la distribuzione senza modificare il traffico

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
)

Suggerimento

Si noti come ora si indica il nome della distribuzione che si vuole richiamare.

Aggiornare progressivamente il traffico

Una volta che si è acquisita familiarità con la nuova distribuzione, è possibile aggiornare il traffico per instradarne alcuni alla nuova distribuzione. Il traffico viene configurato a livello di endpoint:

Configurare il traffico:

Questo passaggio non è necessario nell'interfaccia della riga di comando di Azure

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

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

Scrivere la configurazione in un file:

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

Aggiornare l'endpoint

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 si decide di passare l'intero traffico alla nuova distribuzione, aggiornare tutto il traffico:
Questo passaggio non è necessario nell'interfaccia della riga di comando di Azure
```
endpoint.traffic = {blue_deployment_name: 0, green_deployment_name: 100}
```
```
traffic_config = {"traffic": {blue_deployment_name: 0, green_deployment_name: 100}}
```
Scrivere la configurazione in un file:
```
traffic_config_path = "traffic_config.json"
with open(traffic_config_path, "w") as outfile:
    outfile.write(json.dumps(traffic_config))
```

Aggiornare l'endpoint

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

Poiché la distribuzione precedente non riceve traffico, è possibile eliminarla in modo sicuro:
```
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
)
```
Suggerimento

Si noti che a questo punto, la precedente "distribuzione blu" è stata eliminata e la nuova "distribuzione verde" ha preso il posto della "distribuzione blu".

Pulire le risorse

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

Si noti che l'eliminazione di un endpoint elimina anche tutte le distribuzioni al suo interno.

Condividi tramite

Implementazione progressiva di modelli MLflow in endpoint online

Informazioni su questo esempio

Seguire la procedura in Jupyter Notebooks

Prerequisiti

Connettersi all'area di lavoro

Registrazione del modello nel registro

Creare un endpoint online

Creare una distribuzione blu

Creare una distribuzione verde nell'endpoint:

Aggiornare progressivamente il traffico

Pulire le risorse

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive