Een machine learning model implementeren en scoren met behulp van een online eindpunt (preview)

Leer hoe u een online-eindpunt (preview) gebruikt om uw model te implementeren, zodat u de onderliggende infrastructuur niet hoeft te maken en beheren. U begint met het implementeren van een model op uw lokale computer om fouten op te sporen. Vervolgens implementeert en test u het in Azure.

U leert ook hoe u de logboeken kunt weergeven en de Service Level Agreement (SLA) kunt bewaken. U begint met een model en eindigt met een schaalbaar HTTPS/REST-eindpunt dat u kunt gebruiken voor online en realtime scoren.

Beheerde online eindpunten helpen u om uw ML kant-en-klare manier te implementeren. Beheerde online eindpunten werken met krachtige CPU- en GPU-machines in Azure op een schaalbare, volledig beheerde manier. Beheerde online eindpunten zorgen voor het bedienen, schalen, beveiligen en bewaken van uw modellen, en bieden u de overhead van het instellen en beheren van de onderliggende infrastructuur. In het hoofdvoorbeeld in dit document wordt gebruikgemaakt van beheerde online eindpunten voor implementatie. Als u in plaats daarvan Kubernetes wilt gebruiken, bekijkt u de opmerkingen in dit document inline met de discussie over beheerde online eindpunten. Zie Wat zijn de eindpunten Azure Machine Learning (preview)? voor meer informatie.

Belangrijk

Deze functie is momenteel beschikbaar als openbare preview-versie. Deze preview-versie wordt aangeboden zonder Service Level Agreement en wordt niet aanbevolen voor productieworkloads. Misschien worden bepaalde functies niet ondersteund of zijn de mogelijkheden ervan beperkt. Zie Supplemental Terms of Use for Microsoft Azure Previews (Aanvullende gebruiksvoorwaarden voor Microsoft Azure-previews) voor meer informatie.

Vereisten

  • Als u Azure Machine Learning, moet u een Azure-abonnement hebben. Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint. Probeer de gratis of betaalde versie van Azure Machine Learning.

  • Installeer en configureer de Azure CLI en de ml extensie voor de Azure CLI. Zie Cli (v2) installeren, instellen en gebruiken (preview)voor meer informatie.

  • U moet een Azure-resourcegroep hebben en u (of de service-principal die u gebruikt) moet inzender-toegang hebben. Er wordt een resourcegroep gemaakt in Installeren, instellen en de CLI (v2) (preview) gebruiken.

  • U moet een Azure Machine Learning hebben. Er wordt een werkruimte gemaakt in Installeren, instellen en de CLI (v2) (preview) gebruiken.

  • Als u de standaardinstellingen voor de Azure CLI nog niet hebt ingesteld, moet u de standaardinstellingen opslaan. Voer de volgende code uit om te voorkomen dat de waarden voor uw abonnement, werkruimte en resourcegroep meerdere keren worden door geven:

    az account set --subscription <subscription ID>
    az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>
    
  • (Optioneel) Als u lokaal wilt implementeren, moet u Docker Engine installeren op uw lokale computer. We raden deze optie ten zeerste aan, zodat het eenvoudiger is om problemen op te lossen.

Belangrijk

In de voorbeelden in dit document wordt ervan uitgenomen dat u de Bash-shell gebruikt. Bijvoorbeeld vanuit een Linux-systeem of Windows-subsysteem voor Linux.

Uw systeem voorbereiden

Als u dit artikel wilt volgen, kloont u eerst de opslagplaats met voorbeelden (azureml-examples). Voer vervolgens de volgende code uit om naar de map met voorbeelden te gaan:

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

Als u de naam van uw eindpunt wilt instellen, kiest u een van de volgende opdrachten, afhankelijk van uw besturingssysteem (vervang YOUR_ENDPOINT_NAME door een unieke naam).

Voer voor Unix de volgende opdracht uit:

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

Notitie

Eindpuntnamen moeten uniek zijn binnen een Azure-regio. In de Azure-regio kan er bijvoorbeeld slechts één eindpunt westus2 zijn met de naam my-endpoint .

De eindpunt- en implementatieconfiguraties controleren

In het volgende fragment ziet u het bestand endpoints/online/managed/sample/endpoint.yml:

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

Notitie

Zie YamL-referentie voor beheerde online eindpunten (preview) voor een volledige beschrijving van de YAML.

De verwijzing voor de YAML-indeling van het eindpunt wordt beschreven in de volgende tabel. Zie het YAML-voorbeeld in Prepare your system or the online endpoint YAML reference(YamL-referentie voor het online-eindpunt voorbereiden) voor meer informatie over het opgeven van deze kenmerken. Zie Quota voor resources beheren en verhogen met Azure Machine Learning voor meer informatie over limieten met betrekking tot beheerde eindpunten.

Sleutel Beschrijving
$schema (Optioneel) Het YAML-schema. Als u alle beschikbare opties in het YAML-bestand wilt zien, kunt u het schema in het voorgaande voorbeeld in een browser bekijken.
name De naam van het eindpunt. Deze moet uniek zijn in de Azure-regio.
auth_mode Gebruiken key voor verificatie op basis van sleutels. Gebruiken aml_token voor Azure Machine Learning verificatie op basis van een token. key verloopt niet, maar aml_token verloopt wel. (Haal het meest recente token op met behulp van de az ml online-endpoint get-credentials opdracht .)

Het voorbeeld bevat alle bestanden die nodig zijn om een model op een online-eindpunt te implementeren. Als u een model wilt implementeren, hebt u het volgende nodig:

  • Modelbestanden (of de naam en versie van een model dat al is geregistreerd in uw werkruimte). In het voorbeeld hebben we een scikit-learn-model dat regressie doet.
  • De code die is vereist om het model te scoren. In dit geval hebben we een score.py bestand.
  • Een omgeving waarin uw model wordt uitgevoerd. Zoals u ziet, is de omgeving mogelijk een Docker-afbeelding met Conda-afhankelijkheden of een Dockerfile.
  • Instellingen het exemplaartype en de schaalcapaciteit op te geven.

In het volgende codefragment ziet u het bestand endpoints/online/managed/sample/blue-deployment.yml, met alle vereiste invoer:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model:
  local_path: ../../model-1/model/sklearn_regression_model.pkl
code_configuration:
  code: 
    local_path: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: 
  conda_file: ../../model-1/environment/conda.yml
  image: mcr.microsoft.com/azureml/openmpi3.1.2-ubuntu18.04:20210727.v1
instance_type: Standard_F2s_v2
instance_count: 1

In de tabel worden de kenmerken van een deployment beschreven:

Sleutel Beschrijving
name De naam van de implementatie.
model In dit voorbeeld geven we de modeleigenschappen inline op: local_path . Modelbestanden worden automatisch geüpload en geregistreerd met een automatisch gegenereerde naam. Zie de tip in de volgende sectie voor gerelateerde best practices.
code_configuration.code.local_path De map die alle Python-broncode bevat voor het scoren van het model. U kunt geneste directories en pakketten gebruiken.
code_configuration.scoring_script Het Python-bestand in de code_configuration.code.local_path scoring-map. Deze Python-code moet een functie init() en een functie run() hebben. De functie wordt aangeroepen nadat het model is gemaakt of bijgewerkt (u kunt deze bijvoorbeeld gebruiken om het model in het init() cachegeheugen op te nemen). De run() functie wordt aangeroepen bij elke aanroep van het eindpunt om de werkelijke score en voorspelling te doen.
environment Bevat de details van de omgeving voor het hosten van het model en de code. In dit voorbeeld hebben we inlinedefinities die de path bevatten. We gebruiken voor environment.docker.image de afbeelding. De conda_file afhankelijkheden worden boven op de installatie afbeelding geïnstalleerd. Zie de tip in de volgende sectie voor meer informatie.
instance_type De VM-SKU die uw implementatie-exemplaren gaat hosten. Zie Beheerde online eindpunten ondersteunde VM-SKU's voor meer informatie.
instance_count Het aantal exemplaren in de implementatie. Baseer de waarde op de workload die u verwacht. Voor hoge beschikbaarheid raden we u aan om in instance_count te stellen op ten minste 3 .

Zie de YAML-referentie voor het online-eindpunt voor meer informatie over het YAML-schema.

Notitie

Kubernetes gebruiken in plaats van beheerde eindpunten als rekendoel:

  1. Maak en koppel uw Kubernetes-cluster als een rekendoel aan uw Azure Machine Learning werkruimte met behulp van Azure Machine Learning Studio.
  2. Gebruik de eindpunt-YAML om kubernetes te targeten in plaats van de YAML van het beheerde eindpunt. U moet de YAML bewerken om de waarde van te wijzigen in de naam target van uw geregistreerde rekendoel. U kunt deze deployment.yaml gebruiken met aanvullende eigenschappen die van toepassing zijn op Kubernetes-implementatie.

Alle opdrachten die in dit artikel worden gebruikt (met uitzondering van de optionele SLA-bewaking en Azure Log Analytics-integratie) kunnen worden gebruikt met beheerde eindpunten of met Kubernetes-eindpunten.

Uw model en omgeving afzonderlijk registreren

In dit voorbeeld geven we de local_path (waar vandaan bestanden moeten worden geüpload) inline op. De CLI uploadt de bestanden automatisch en registreert het model en de omgeving. Als best practice voor productie moet u het model en de omgeving registreren en de geregistreerde naam en versie afzonderlijk opgeven in de YAML. Gebruik het formulier model: azureml:my-model:1 of environment: azureml:my-env:1 .

Voor registratie kunt u de YAML-definities van en extraheren modelenvironment in afzonderlijke YAML-bestanden en de opdrachten en az ml model createaz ml environment create gebruiken. Voer en uit voor meer informatie over az ml model create -h deze az ml environment create -h opdrachten.

Verschillende TYPEN CPU- en GPU-exemplaren gebruiken

De voorgaande YAML maakt gebruik van een algemeen type ( ) en een Docker-afbeelding die niet gpu is (zie het Standard_F2s_v2 kenmerk in de image YAML). Voor GPU-rekenkracht kiest u een GPU-rekentype-SKU en een GPU Docker-afbeelding.

Zie Beheerde online eindpunten ondersteunde VM-SKU'svoor ondersteunde typen algemene en GPU-exemplaren. Zie basisafbeeldingen voor Azure Machine Learning Azure Machine Learning CPU- en GPU-basisafbeeldingen.

Meer dan één model gebruiken

Op dit moment kunt u slechts één model per implementatie opgeven in de YAML. Als u meer dan één model hebt, kopieert u bij het registreren van het model alle modellen als bestanden of submappen naar een map die u voor registratie gebruikt. Gebruik in uw scorescript de omgevingsvariabele AZUREML_MODEL_DIR om het pad naar de hoofdmap van het model op te halen. De onderliggende mapstructuur blijft behouden.

Inzicht in het scoring-script

Tip

De indeling van het scorescript voor online eindpunten is dezelfde indeling die wordt gebruikt in de vorige versie van de CLI en in de Python SDK.

Zoals eerder vermeld, moet code_configuration.scoring_script de een functie en een functie init()run() hebben. In dit voorbeeld wordt het score.py gebruikt. De init() functie wordt aangeroepen wanneer de container wordt gestart of gestart. Initialisatie vindt doorgaans plaats kort nadat de implementatie is gemaakt of bijgewerkt. Schrijf hier logica voor globale initialisatiebewerkingen, zoals het in het geheugen in de caching van het model (zoals in dit voorbeeld). De run() functie wordt aangeroepen voor elke aanroep van het eindpunt en moet de werkelijke score en voorspelling doen. In het voorbeeld extraheren we de gegevens uit de JSON-invoer, roepen we de methode van het scikit-learn-model aan en predict() retourneren we het resultaat.

Lokaal implementeren en fouten opsporen met behulp van lokale eindpunten

Als u tijd wilt besparen op debuggen, raden we u ten zeerste aan om uw eindpunt lokaal uit te voeren. Zie Fouten in online-eindpunten lokaal opsporen inVisual Studio Code voor meer informatie.

Notitie

Belangrijk

Het doel van een implementatie van een lokaal eindpunt is het valideren en opsporen van fouten in uw code en configuratie voordat u in Azure implementeert. Lokale implementatie heeft de volgende beperkingen:

  • Lokale eindpunten bieden geen ondersteuning voor verkeersregels, verificatie of testinstellingen.
  • Lokale eindpunten ondersteunen slechts één implementatie per eindpunt.

Het model lokaal implementeren

Maak eerst het eindpunt. Optioneel kunt u voor een lokaal eindpunt deze stap overslaan en rechtstreeks de implementatie (volgende stap) maken, waarmee de vereiste metagegevens worden aangeslagen. Dit is handig voor ontwikkelings- en testdoeleinden.

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

Maak nu een implementatie met de blue naam onder het eindpunt.

az ml online-deployment create --local -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

De --local vlag stuurt de CLI naar het implementeren van het eindpunt in de Docker-omgeving.

Tip

Gebruik Visual Studio Code om uw eindpunten lokaal te testen en fouten op te sporen. Zie Fouten in online-eindpunten lokaal opsporen in Visual Studio Code voor meer informatie.

Controleer of de lokale implementatie is geslaagd

Controleer de status om te zien of het model zonder fouten is geïmplementeerd:

az ml online-endpoint show -n $ENDPOINT_NAME --local

De uitvoer moet er ongeveer als volgt uit zien. Houd er rekening mee provisioning_state dat de Succeeded is.

{
  "auth_mode": "key",
  "location": "local",
  "name": "docs-endpoint",
  "properties": {},
  "provisioning_state": "Succeeded",
  "scoring_uri": "http://localhost:49158/score",
  "tags": {},
  "traffic": {}
}

Het lokale eindpunt aanroepen om gegevens te scoren met behulp van uw model

Roep het eindpunt aan om het model te scoren met behulp van de handige opdracht en door te geven van invoke queryparameters die zijn opgeslagen in een JSON-bestand:

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

Als u een REST-client (zoals curl) wilt gebruiken, moet u de scoring-URI hebben. Voer uit om de scoring-URI op te az ml online-endpoint show --local -n $ENDPOINT_NAME halen. Zoek het kenmerk in de geretourneerde scoring_uri gegevens. Voorbeeldopdrachten op basis van curl zijn later in dit document beschikbaar.

Controleer de logboeken op uitvoer van de aanroepbewerking

In het voorbeeld score.py bestand registreert de methode wat uitvoer in de console. U kunt deze uitvoer opnieuw weergeven met behulp van get-logs de opdracht :

az ml online-deployment get-logs --local -n blue --endpoint $ENDPOINT_NAME

Uw online-eindpunt implementeren in Azure

Implementeer vervolgens uw online-eindpunt in Azure.

Implementeren op Azure

Voer de volgende code uit om het eindpunt in de cloud te maken:

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

Voer de volgende code uit om de implementatie met de naam onder het eindpunt blue te maken:

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

Deze implementatie kan maximaal 15 minuten duren, afhankelijk van of de onderliggende omgeving of installatie afbeelding voor de eerste keer wordt gemaakt. Volgende implementaties die dezelfde omgeving gebruiken, worden sneller verwerkt.

Belangrijk

Met de vlag --all-traffic in het bovenstaande wordt 100% van het verkeer aan het eindpunt toegewezen az ml online-deployment create aan de zojuist gemaakte implementatie. Hoewel dit handig is voor ontwikkelings- en testdoeleinden, kunt u voor productie verkeer naar de nieuwe implementatie openen via een expliciete opdracht. Bijvoorbeeld: az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100"

Tip

De status van de implementatie controleren

De show opdracht bevat informatie in voor eindpunt en provisioning_status implementatie:

az ml online-endpoint show -n $ENDPOINT_NAME

U kunt alle eindpunten in de werkruimte in een tabelindeling opnoemen met behulp van de list opdracht :

az ml online-endpoint list --output table

De status van de cloudimplementatie controleren

Controleer de logboeken om te zien of het model zonder fouten is geïmplementeerd:

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

Standaard worden logboeken uit de deference-server gehaald. Als u de logboeken van storage-initializer wilt zien (deze voegt assets zoals model en code aan de container toe), voegt u de vlag --container storage-initializer toe.

Het eindpunt aanroepen om gegevens te scoren met behulp van uw model

U kunt de opdracht of een REST-client van uw keuze gebruiken om het eindpunt aan te roepen invoke en enkele gegevens te scoren:

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

In het volgende voorbeeld ziet u hoe u de sleutel op kunt halen die wordt gebruikt voor verificatie bij het eindpunt:

ENDPOINT_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -o tsv --query primaryKey)

Gebruik vervolgens curl om gegevens te scoren.

SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)

curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @endpoints/online/model-1/sample-request.json

U ziet dat we show - get-credentials en -opdrachten gebruiken om de verificatiereferenties op te halen. U ziet ook dat we de vlag gebruiken --query om kenmerken alleen te filteren op wat we nodig hebben. Zie Query's uitvoeren op --query--queryover .

Voer opnieuw uit om de aanroeplogboeken te get-logs zien.

(Optioneel) De implementatie bijwerken

Als u de code, het model of de omgeving wilt bijwerken, moet u het YAML-bestand bijwerken en vervolgens de opdracht az ml online-endpoint update uitvoeren.

Notitie

Als u het aantal exemplaren en andere modelinstellingen (code, model of omgeving) bij werkt in één opdracht: eerst wordt de schaalbewerking uitgevoerd en vervolgens worden de andere update updates toegepast. In de productieomgeving is het een goed idee om deze bewerkingen afzonderlijk uit te voeren.

Om te begrijpen hoe update werkt:

  1. Open het bestand online/model-1/onlinescoring/score.py.

  2. Wijzig de laatste regel van de init() functie: Voeg logging.info("Init complete") na logging.info("Updated successfully") toe.

  3. Sla het bestand op.

  4. Voer deze opdracht uit:

    az ml online-deployment update -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml
    

    Notitie

    Bijwerken met behulp van YAML is declaratief. Dat wil zeggen dat wijzigingen in de YAML worden weerspiegeld in de onderliggende Azure Resource Manager resources (eindpunten en implementaties). Een declaratieve benadering faciliteert GitOps:alle wijzigingen in eindpunten en implementaties (zelfs ) gaan via de YAML. U kunt updates maken zonder de YAML te gebruiken met behulp van de --set vlag .

  5. Omdat u de functie hebt gewijzigd ( wordt uitgevoerd wanneer het eindpunt wordt gemaakt of bijgewerkt), wordt het bericht init()init() in de Updated successfully logboeken weergegeven. Haal de logboeken op door het volgende uit te uitvoeren:

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

De update opdracht werkt ook met lokale implementaties. Gebruik dezelfde az ml online-deployment update opdracht met de vlag --local .

Tip

Met de opdracht kunt u de parameter in de Azure CLI gebruiken om kenmerken in uw YAML te overschrijven of om specifieke kenmerken in te stellen zonder het update YAML-bestand door update te --set geven. Het --set gebruik van voor enkele kenmerken is vooral nuttig in ontwikkelings- en testscenario's. Als u bijvoorbeeld de waarde voor de eerste implementatie wilt instance_count opschalen, kunt u de vlag --set instance_count=2 gebruiken. Omdat de YAML echter niet wordt bijgewerkt, maakt deze techniek GitOps niet mogelijk.

Notitie

Het bovenstaande is een voorbeeld van een inplace rolling update: dat wil zeggen dat dezelfde implementatie wordt bijgewerkt met de nieuwe configuratie, met 20% knooppunten tegelijk. Als de implementatie 10 knooppunten heeft, worden 2 knooppunten tegelijk bijgewerkt. Voor productiegebruik kunt u overwegen om blauw-groene implementatiete gebruiken, wat een veiliger alternatief biedt.

(Optioneel) Automatisch schalen configureren

Automatisch schalen voert automatisch de juiste hoeveelheid resources uit om de belasting van uw toepassing te verwerken. Beheerde online eindpunten bieden ondersteuning voor automatisch schalen via integratie met de functie voor automatisch schalen van Azure Monitor. Zie How to autoscale online endpoints (Online-eindpunten automatischschalen) voor informatie over het configureren van automatisch schalen.

(Optioneel) SLA bewaken met behulp van Azure Monitor

Als u metrische gegevens wilt weergeven en waarschuwingen wilt instellen op basis van uw SLA, voltooit u de stappen die worden beschreven in Beheerde online-eindpunten bewaken.

(Optioneel) Integreren met Log Analytics

De get-logs opdracht biedt alleen de laatste paar honderd regels logboeken van een automatisch geselecteerde instantie. Log Analytics biedt echter een manier om logboeken duurzaam op te slaan en te analyseren.

Maak eerst een Log Analytics-werkruimte door de stappen in Een Log Analytics-werkruimtemaken in de Azure Portal.

Klik vervolgens in de Azure Portal:

  1. Ga naar de resourcegroep.
  2. Selecteer uw eindpunt.
  3. Selecteer de arm-resourcepagina.
  4. Selecteer Diagnostische instellingen.
  5. Selecteer Instellingen toevoegen.
  6. Selecteer deze optie om het verzenden van consolelogboeken naar de Log Analytics-werkruimte in te stellen.

Het kan een uur duren voordat de logboeken verbinding maken. Verzend na een uur een aantal scoring-aanvragen en controleer vervolgens de logboeken met behulp van de volgende stappen:

  1. Open de Log Analytics-werkruimte.
  2. Selecteer Logboeken in het menu links.
  3. Sluit het dialoogvenster Query's dat automatisch wordt geopend.
  4. Dubbelklik op AmlOnlineEndpointConsoleLog.
  5. Selecteer Uitvoeren.

Het eindpunt en de implementatie verwijderen

Als u de implementatie niet gaat gebruiken, moet u deze verwijderen door de volgende code uit te voeren (hiermee verwijdert u het eindpunt en alle onderliggende implementaties):

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

Volgende stappen

Lees voor meer informatie de volgende artikelen: