Anpassa utdata i batchdistributioner

GÄLLER FÖR:Azure CLI ml extension v2 (current)Python SDK azure-ai-ml v2 (aktuell)

Den här guiden beskriver hur du skapar distributioner som genererar anpassade utdata och filer. Ibland behöver du mer kontroll över vad som skrivs som utdata från batchinferensjobb. Dessa fall omfattar följande situationer:

• Du måste styra hur förutsägelser skrivs i utdata. Du vill till exempel lägga till förutsägelsen till de ursprungliga data om data är tabellbaserade.
• Du måste skriva dina förutsägelser i ett annat filformat än det som stöds direkt av batchdistributioner.
• Din modell är en generativ modell som inte kan skriva utdata i tabellformat. Till exempel modeller som producerar bilder som utdata.
• Din modell skapar flera tabellfiler i stället för en enda. Till exempel modeller som utför prognostisering genom att överväga flera scenarier.

Med batchdistributioner kan du ta kontroll över jobbens utdata genom att låta dig skriva direkt till utdata från batchdistributionsjobbet. I den här självstudien får du lära dig hur du distribuerar en modell för att utföra batchinferens och skriva utdata i parquet-format genom att lägga till förutsägelserna till de ursprungliga indata.

Om det här exemplet

Det här exemplet visar hur du kan distribuera en modell för att utföra batchinferens och anpassa hur dina förutsägelser skrivs i utdata. Modellen är baserad på datamängden UCI Heart Disease. Databasen innehåller 76 attribut, men i det här exemplet används en delmängd av 14 av dem. Modellen försöker förutsäga förekomsten av hjärtsjukdomar hos en patient. Det är heltal som värderas från 0 (ingen närvaro) till 1 (närvaro).

Modellen tränades med en XGBBoost klassificerare och all nödvändig förbearbetning paketerades som en scikit-learn pipeline, vilket gör den här modellen till en pipeline från slutpunkt till slutpunkt som går från rådata till förutsägelser.

Exemplet i den här artikeln baseras på kodexempel som finns på lagringsplatsen azureml-examples . Om du vill köra kommandona lokalt utan att behöva kopiera/klistra in YAML och andra filer klonar du först lagringsplatsen och ändrar sedan kataloger till mappen:

Azure CLI

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli

Python

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/sdk/python

Filerna för det här exemplet finns i:

cd endpoints/batch/deploy-models/custom-outputs-parquet

Följ med i en Jupyter-anteckningsbok

Det finns en Jupyter-anteckningsbok som du kan använda för att följa det här exemplet. Öppna notebook-filen custom-output-batch.ipynb på den klonade lagringsplatsen.

Förutsättningar

Innan du följer stegen i den här artikeln kontrollerar du att du har följande förutsättningar:

• En Azure-prenumeration. Om du inte har någon Azure-prenumeration kan du skapa ett kostnadsfritt konto innan du börjar. Prova den kostnadsfria eller betalda versionen av Azure Mašinsko učenje.

• En Azure Machine Learning-arbetsyta. Om du inte har någon använder du stegen i artikeln Hantera Azure Mašinsko učenje-arbetsytor för att skapa en.

• Kontrollera att du har följande behörigheter på arbetsytan:

  • Skapa eller hantera batchslutpunkter och distributioner: Använd en ägare, deltagare eller anpassad roll som tillåter Microsoft.MachineLearningServices/workspaces/batchEndpoints/*.

  • Skapa ARM-distributioner i arbetsytans resursgrupp: Använd en roll som ägare, deltagare eller anpassad som tillåter Microsoft.Resources/deployments/write i den resursgrupp där arbetsytan distribueras.

• Du måste installera följande programvara för att arbeta med Azure Mašinsko učenje:

  Azure CLI

  Azure CLI och mltillägget för Azure Mašinsko učenje.

  az extension add -n ml
  

  Kommentar

  Distributioner av pipelinekomponenter för Batch-slutpunkter introducerades i version 2.7 av ml tillägget för Azure CLI. Använd az extension update --name ml för att hämta den senaste versionen av den.

  Python

  Azure Mašinsko učenje SDK för Python.

  pip install azure-ai-ml
  

  Kommentar

  Klasser ModelBatchDeployment och PipelineComponentBatchDeployment introducerades i version 1.7.0 av SDK. Använd pip install -U azure-ai-ml för att hämta den senaste versionen av den.

Anslut till din arbetsyta

Arbetsytan är resursen på den översta nivån i Azure Machine Learning, och är en central plats där du kan arbeta med alla artefakter du skapar när du använder Azure Machine Learning. I det här avsnittet ansluter vi till arbetsytan där du ska utföra distributionsuppgifter.

Azure CLI

Skicka in värdena för ditt prenumerations-ID, arbetsyta, plats och resursgrupp i följande kod:

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

Python

1. Importera de bibliotek som krävs:

   from azure.ai.ml import MLClient, Input, load_component
   from azure.ai.ml.entities import BatchEndpoint, ModelBatchDeployment, ModelBatchDeploymentSettings, PipelineComponentBatchDeployment, Model, AmlCompute, Data, BatchRetrySettings, CodeConfiguration, Environment, Data
   from azure.ai.ml.constants import AssetTypes, BatchDeploymentOutputAction
   from azure.ai.ml.dsl import pipeline
   from azure.identity import DefaultAzureCredential
   

2. Konfigurera arbetsytans information och få ett handtag till arbetsytan:

   Skicka in värdena för ditt prenumerations-ID, arbetsyta och resursgrupp i följande kod:

   subscription_id = "<subscription>"
   resource_group = "<resource-group>"
   workspace = "<workspace>"
   
   ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group, workspace)
   

Skapa en batchdistribution med anpassade utdata

I det här exemplet skapar du en distribution som kan skriva direkt till utdatamappen för batchdistributionsjobbet. Distributionen använder den här funktionen för att skriva anpassade parquet-filer.

Registrera modellen

Du kan bara distribuera registrerade modeller med hjälp av en batchslutpunkt. I det här fallet har du redan en lokal kopia av modellen på lagringsplatsen, så du behöver bara publicera modellen till registret på arbetsytan. Du kan hoppa över det här steget om den modell som du försöker distribuera redan är registrerad.

Azure CLI

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

Python

model_name = "heart-classifier-sklpipe"
model_description = "A heart condition classifier trained with XGBoosts and Scikit-Learn for feature processing."
model_local_path = "model"

model = ml_client.models.create_or_update(
    Model(
        name=model_name,
        path=model_local_path,
        type=AssetTypes.CUSTOM_MODEL,
        tags={"framework": "scikit-learn", "estimator": "xgboost"},
    )
)

Skapa ett bedömningsskript

Du måste skapa ett bedömningsskript som kan läsa indata som tillhandahålls av batchdistributionen och returnera poängen för modellen. Du kommer också att skriva direkt till utdatamappen för jobbet. Sammanfattningsvis gör det föreslagna bedömningsskriptet följande:

1. Läser indata som CSV-filer.
2. Kör en MLflow-modellfunktion predict över indata.
3. Lägger till förutsägelserna i en pandas.DataFrame tillsammans med indata.
4. Skriver data i en fil med namnet som indatafil, men i parquet format.

kod/batch_driver.py

import os
import pickle
import glob
import pandas as pd
from pathlib import Path
from typing import List


def init():
    global model
    global output_path

    # AZUREML_MODEL_DIR is an environment variable created during deployment
    # It is the path to the model folder
    # Please provide your model's folder name if there's one:
    output_path = os.environ["AZUREML_BI_OUTPUT_PATH"]
    model_path = os.environ["AZUREML_MODEL_DIR"]
    model_file = glob.glob(f"{model_path}/*/*.pkl")[-1]

    with open(model_file, "rb") as file:
        model = pickle.load(file)


def run(mini_batch: List[str]):
    for file_path in mini_batch:
        data = pd.read_csv(file_path)
        pred = model.predict(data)

        data["prediction"] = pred

        output_file_name = Path(file_path).stem
        output_file_path = os.path.join(output_path, output_file_name + ".parquet")
        data.to_parquet(output_file_path)

    return mini_batch

Kommentarer:

• Observera hur miljövariabeln AZUREML_BI_OUTPUT_PATH används för att få åtkomst till utdatasökvägen för distributionsjobbet.
• Funktionen init() fyller i en global variabel med namnet output_path som kan användas senare för att veta var du ska skriva.
• Metoden run returnerar en lista över de bearbetade filerna. Det krävs för run att funktionen ska returnera ett list eller ett pandas.DataFrame objekt.

Varning

Ta hänsyn till att alla batchexekutorer har skrivåtkomst till den här sökvägen samtidigt. Det innebär att du måste ta hänsyn till samtidighet. I det här fallet kontrollerar du att varje köre skriver sin egen fil med hjälp av indatafilens namn som namn på utdatamappen.

Skapa slutpunkten

Nu skapar du en batchslutpunkt med namnet heart-classifier-batch där modellen distribueras.

1. Bestäm namnet på slutpunkten. Namnet på slutpunkten visas i den URI som är associerad med slutpunkten, så batchslutpunktsnamn måste vara unika i en Azure-region. Det kan till exempel bara finnas en batchslutpunkt med namnet mybatchendpoint i westus2.

   Azure CLI

   I det här fallet placerar du namnet på slutpunkten i en variabel så att du enkelt kan referera till den senare.

   ENDPOINT_NAME="heart-classifier-custom"
   

   Python

   I det här fallet placerar du namnet på slutpunkten i en variabel så att du enkelt kan referera till den senare.

   endpoint_name = "heart-classifier-custom"

2. Konfigurera batchslutpunkten.

   Azure CLI

   Följande YAML-fil definierar en batchslutpunkt:

   endpoint.yml

   $schema: https://azuremlschemas.azureedge.net/latest/batchEndpoint.schema.json
   name: heart-classifier-batch
   description: A heart condition classifier for batch inference
   auth_mode: aad_token
   

   Python

   endpoint = BatchEndpoint(
       name=endpoint_name,
       description="A heart condition classifier for batch inference",
   )

3. Skapa slutpunkten:

   Azure CLI

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

   Python

   ml_client.batch_endpoints.begin_create_or_update(endpoint).result()

Skapa distributionen

Följ nästa steg för att skapa en distribution med hjälp av föregående bedömningsskript:

1. Skapa först en miljö där bedömningsskriptet kan köras:

   Azure CLI

   Inget extra steg krävs för Azure Mašinsko učenje CLI. Miljödefinitionen ingår i distributionsfilen.

   environment:
     name: batch-mlflow-xgboost
     image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
     conda_file: environment/conda.yaml
   

   Python

   Hämta en referens till miljön:

   environment = Environment(
       name="batch-mlflow-xgboost",
       conda_file="environment/conda.yaml",
       image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest",
   )

2. Skapa distributionen. Observera att output_action nu är inställt på SUMMARY_ONLY.

   Kommentar

   Det här exemplet förutsätter att du har ett beräkningskluster med namnet batch-cluster. Ändra namnet i enlighet med detta.

   Azure CLI

   Skapa en YAML-konfiguration som följande för att skapa en ny distribution under den skapade slutpunkten. Du kan kontrollera YAML-schemat för den fullständiga batchslutpunkten för extra egenskaper.

   $schema: https://azuremlschemas.azureedge.net/latest/modelBatchDeployment.schema.json
   endpoint_name: heart-classifier-batch
   name: classifier-xgboost-custom
   description: A heart condition classifier based on XGBoost and Scikit-Learn pipelines that append predictions on parquet files.
   type: model
   model: azureml:heart-classifier-sklpipe@latest
   environment:
     name: batch-mlflow-xgboost
     image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
     conda_file: environment/conda.yaml
   code_configuration:
     code: code
     scoring_script: batch_driver.py
   compute: azureml:batch-cluster
   resources:
     instance_count: 2
   settings:
     max_concurrency_per_instance: 2
     mini_batch_size: 2
     output_action: summary_only
     retry_settings:
       max_retries: 3
       timeout: 300
     error_threshold: -1
     logging_level: info
   

   Skapa sedan distributionen med följande kommando:

   az ml batch-deployment create --file deployment.yml --endpoint-name $ENDPOINT_NAME --set-default
   

   Python

   Om du vill skapa en ny distribution under den skapade slutpunkten använder du följande skript:

   deployment = ModelBatchDeployment(
       name="classifier-xgboost-custom",
       description="A heart condition classifier based on XGBoost which writes outputs in parquet format.",
       endpoint_name=endpoint.name,
       model=model,
       environment=environment,
       code_configuration=CodeConfiguration(
           code="code",
           scoring_script="batch_driver.py",
       ),
       compute=compute_name,
       settings=ModelBatchDeploymentSettings(
           mini_batch_size=2,
           instance_count=2,
           max_concurrency_per_instance=2,
           output_action=BatchDeploymentOutputAction.SUMMARY_ONLY,
           retry_settings=BatchRetrySettings(max_retries=3, timeout=300),
           logging_level="info",
       ),
   )

   Skapa sedan distributionen med följande kommando:

   ml_client.batch_deployments.begin_create_or_update(deployment).result()

3. Nu är vår batchslutpunkt redo att användas.

Testa distributionen

Om du vill testa slutpunkten använder du ett exempel på omärkta data som finns på den här lagringsplatsen, som kan användas med modellen. Batch-slutpunkter kan bara bearbeta data som finns i molnet och som är tillgängliga från Azure Mašinsko učenje-arbetsytan. I det här exemplet laddar du upp den till ett Azure-Mašinsko učenje datalager. Du ska skapa en datatillgång som kan användas för att anropa slutpunkten för bedömning. Observera dock att batchslutpunkter accepterar data som kan placeras på flera typer av platser.

1. Anropa slutpunkten med data från ett lagringskonto:

   Azure CLI

   JOB_NAME = $(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data --query name -o tsv)
   

   Kommentar

   Verktyget jq kanske inte installeras på varje installation. Du kan få instruktioner på GitHub.

   Python

   Dricks

   Vad är skillnaden mellan inputs och input när du anropar en slutpunkt?

   I allmänhet kan du använda en ordlista inputs = {} med invoke metoden för att ange ett godtyckligt antal obligatoriska indata till en batchslutpunkt som innehåller en modelldistribution eller en pipelinedistribution.

   För en modelldistribution kan du använda input som ett kortare sätt att ange indataplatsen för distributionen, eftersom en modelldistribution alltid bara tar en datainmatning.

   Konfigurera indata:

   input = Input(
       type=AssetTypes.URI_FOLDER,
       path="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data",
   )

   Skapa ett jobb:

   job = ml_client.batch_endpoints.invoke(
       endpoint_name=endpoint.name, deployment_name=deployment.name, input=input
   )

2. Ett batchjobb startas så snart kommandot returnerar. Du kan övervaka statusen för jobbet tills det har slutförts:

   Azure CLI

   az ml job show -n $JOB_NAME --web
   

   Python

   ml_client.jobs.get(job.name)

Analysera utdata

Jobbet genererar ett namngivet utdata som heter score där alla genererade filer placeras. Eftersom du skrev till katalogen direkt, en fil per indatafil, kan du förvänta dig att ha samma antal filer. I det här exemplet namnger du utdatafilerna på samma sätt som indata, men de har ett parquet-tillägg.

Kommentar

Observera att en fil predictions.csv också ingår i utdatamappen. Den här filen innehåller sammanfattningen av de bearbetade filerna.

Du kan ladda ned resultatet av jobbet med hjälp av jobbnamnet:

Azure CLI

Om du vill ladda ned förutsägelserna använder du följande kommando:

az ml job download --name $JOB_NAME --output-name score --download-path ./

Python

ml_client.jobs.download(name=scoring_job.name, download_path=".", output_name="score")

När filen har laddats ned kan du öppna den med hjälp av ditt favoritverktyg. I följande exempel läses förutsägelserna in med hjälp av Pandas dataramen.

import pandas as pd
import glob

output_files = glob.glob("named-outputs/score/*.parquet")
score = pd.concat((pd.read_parquet(f) for f in output_files))
score

Utdata ser ut så här:

ålder	Sex	...	thal	prognos
63	1	...	fast	0
67	1	...	normal	1
67	1	...	vändbar	0
37	1	...	normal	0

Rensa resurser

Azure CLI

Kör följande kod för att ta bort batchslutpunkten och alla underliggande distributioner. Batchbedömningsjobb tas inte bort.

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

Python

Kör följande kod för att ta bort batchslutpunkten och alla underliggande distributioner. Batchbedömningsjobb tas inte bort.

ml_client.batch_endpoints.begin_delete(endpoint_name).result()

Relaterat innehåll

• Avbildningsbearbetning med distributioner av batchmodeller
• Distribuera språkmodeller i batchslutpunkter