Dela via

Distribuera ett flöde till onlineslutpunkten för slutsatsdragning i realtid med CLI

I den här artikeln lär du dig att distribuera ditt flöde till en hanterad onlineslutpunkt eller en Kubernetes-slutpunkt online för användning i realtidsinferens med Azure Machine Learning v2 CLI.

Innan du börjar bör du kontrollera att du har testat flödet korrekt och känna dig säker på att det är redo att distribueras till produktion. Mer information om hur du testar ditt flöde finns i testa ditt flöde. När du har testat ditt flöde får du lära dig hur du skapar en hanterad onlineslutpunkt och distribution och hur du använder slutpunkten för inferens i realtid.

  • Den här artikeln beskriver hur du använder CLI-upplevelsen.
  • Python SDK beskrivs inte i den här artikeln. Se GitHub-exempelanteckningsboken i stället. Om du vill använda Python SDK måste du ha Python SDK v2 för Azure Machine Learning. Mer information finns i Installera Python SDK v2 för Azure Machine Learning.

Viktigt!

Objekt markerade (förhandsversion) i den här artikeln är för närvarande i offentlig förhandsversion. Förhandsversionen tillhandahålls utan ett serviceavtal och rekommenderas inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller kan vara begränsade. Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Förutsättningar

  • Azure CLI och Azure Machine Learning-tillägget till Azure CLI. Mer information finns i Installera, konfigurera och använda CLI (v2).
  • En Azure Machine Learning-arbetsyta. Om du inte har någon använder du stegen i artikeln Snabbstart: Skapa arbetsyteresurser för att skapa en.
  • Rollbaserade åtkomstkontroller i Azure (Azure RBAC) används för att bevilja åtkomst till åtgärder i Azure Machine Learning. Om du vill utföra stegen i den här artikeln måste ditt användarkonto tilldelas rollen ägare eller deltagare för Azure Machine Learning-arbetsytan, eller en anpassad roll som tillåter "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/". Om du använder studio för att skapa/hantera onlineslutpunkter/distributioner behöver du en annan behörighet "Microsoft.Resources/deployments/write" från resursgruppens ägare. Mer information finns i Hantera åtkomst till en Azure Machine Learning-arbetsyta.

Kommentar

Hanterad onlineslutpunkt stöder endast hanterat virtuellt nätverk. Om din arbetsyta finns i ett anpassat virtuellt nätverk kan du distribuera till Kubernetes onlineslutpunkt eller distribuera till andra plattformar som Docker.

Kvotallokering för virtuell dator för distribution

För hanterade onlineslutpunkter reserverar Azure Machine Learning 20 % av dina beräkningsresurser för att utföra uppgraderingar. Om du begär ett visst antal instanser i en distribution måste du därför ha en kvot för tillgänglig för ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU att undvika ett fel. Om du till exempel begär 10 instanser av en Standard_DS3_v2 virtuell dator (som levereras med fyra kärnor) i en distribution bör du ha en kvot för 48 kärnor (12 instanser fyra kärnor) tillgängliga. Information om hur du visar ökningar av användnings- och begärandekvoter finns i Visa din användning och dina kvoter i Azure Portal.

Förbered flödet för distribution

Varje flöde har en mapp som innehåller koder/uppmaningar, definitioner och andra artefakter i flödet. Om du har utvecklat ditt flöde med användargränssnittet kan du ladda ned flödesmappen från flödesinformationssidan. Om du har utvecklat ditt flöde med CLI eller SDK bör du redan ha flödesmappen.

I den här artikeln används exempelflödet "basic-chat" som ett exempel för att distribuera till Azure Machine Learning-hanterad onlineslutpunkt.

Viktigt!

Om du har använt additional_includes i ditt flöde måste du först använda pf flow build --source <path-to-flow> --output <output-path> --format docker för att hämta en löst version av flödesmappen.

Ange standardarbetsyta

Använd följande kommandon för att ange standardarbetsytan och resursgruppen för CLI.

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

Registrera flödet som en modell (valfritt)

I onlinedistributionen kan du antingen referera till en registrerad modell eller ange modellsökvägen (var modellfilerna ska laddas upp från) infogade. Vi rekommenderar att du registrerar modellen och anger modellnamnet och versionen i distributionsdefinitionen. Använd formuläret model:<model_name>:<version>.

Följande är ett modelldefinitionsexempel för ett chattflöde.

Kommentar

Om ditt flöde inte är ett chattflöde behöver du inte lägga till dessa properties.

$schema: https://azuremlschemas.azureedge.net/latest/model.schema.json
name: basic-chat-model
path: ../../../../examples/flows/chat/basic-chat
description: register basic chat flow folder as a custom model
properties:
  # In AuzreML studio UI, endpoint detail UI Test tab needs this property to know it's from prompt flow
  azureml.promptflow.source_flow_id: basic-chat
  
  # Following are properties only for chat flow 
  # endpoint detail UI Test tab needs this property to know it's a chat flow
  azureml.promptflow.mode: chat
  # endpoint detail UI Test tab needs this property to know which is the input column for chat flow
  azureml.promptflow.chat_input: question
  # endpoint detail UI Test tab needs this property to know which is the output column for chat flow
  azureml.promptflow.chat_output: answer

Använd az ml model create --file model.yaml för att registrera modellen på din arbetsyta.

Definiera slutpunkten

Om du vill definiera en slutpunkt måste du ange:

  • Slutpunktsnamn: Namnet på slutpunkten. Den måste vara unik i Azure-regionen. Mer information om namngivningsreglerna finns i slutpunktsgränser.
  • Autentiseringsläge: Autentiseringsmetoden för slutpunkten. Välj mellan nyckelbaserad autentisering och tokenbaserad autentisering i Azure Machine Learning. En nyckel upphör inte att gälla, men en token upphör att gälla. Mer information om autentisering finns i Autentisera till en onlineslutpunkt. Du kan också lägga till en beskrivning och taggar i slutpunkten.
  • Du kan också lägga till en beskrivning och taggar i slutpunkten.
  • Om du vill distribuera till ett Kubernetes-kluster (AKS- eller Arc-aktiverat kluster) som ansluter till din arbetsyta kan du distribuera flödet till en Kubernetes-slutpunkt online.

Följande är ett exempel på slutpunktsdefinition som som standard använder systemtilldelad identitet.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: basic-chat-endpoint
auth_mode: key
properties:
# this property only works for system-assigned identity.
# if the deploy user has access to connection secrets, 
# the endpoint system-assigned identity will be auto-assigned connection secrets reader role as well
  enforce_access_to_default_secret_stores: enabled
Nyckel beskrivning
$schema (Valfritt) YAML-schemat. Om du vill se alla tillgängliga alternativ i YAML-filen kan du visa schemat i föregående kodfragment i en webbläsare.
name Namnet på slutpunkten.
auth_mode Används key för nyckelbaserad autentisering. Används aml_token för tokenbaserad autentisering i Azure Machine Learning. Använd kommandot för az ml online-endpoint get-credentials att hämta den senaste token.
property: enforce_access_to_default_secret_stores (förhandsgranskning) – Som standard använder slutpunkten systemsignerad identitet. Den här egenskapen fungerar endast för systemtilldelad identitet.
– Den här egenskapen innebär att om du har behörigheten läsare av anslutningshemligheter tilldelas slutpunktens systemtilldelade identitet automatiskt rollen Azure Machine Learning Workspace Connection Secrets Reader för arbetsytan, så att slutpunkten kan komma åt anslutningarna korrekt när inferensen utförs.
– Som standard är den här egenskapen "inaktiverad".

Om du skapar en Kubernetes-slutpunkt online måste du ange följande attribut:

Nyckel beskrivning
compute Kubernetes-beräkningsmålet som slutpunkten ska distribueras till.

Fler konfigurationer av slutpunkten finns i hanterat onlineslutpunktsschema.

Viktigt!

Om ditt flöde använder Microsoft Entra ID-baserade autentiseringsanslutningar, oavsett om du använder systemtilldelad identitet eller användartilldelad identitet, måste du alltid bevilja den hanterade identiteten lämpliga roller för motsvarande resurser så att den kan göra API-anrop till den resursen. Om din Azure OpenAI-anslutning till exempel använder Microsoft Entra ID-baserad autentisering måste du bevilja din slutpunktshanterade identitet Cognitive Services OpenAI-användare eller Cognitive Services OpenAI-deltagarroll för motsvarande Azure OpenAI-resurser.

Använda användartilldelad identitet

När du skapar en onlineslutpunkt genereras som standard en systemtilldelad hanterad identitet automatiskt åt dig. Du kan också ange en befintlig användartilldelad hanterad identitet för slutpunkten.

Om du vill använda användartilldelad identitet kan du ange följande attribut i endpoint.yaml:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Dessutom måste du också ange för Client ID den användartilldelade identiteten enligt environment_variables följande deployment.yaml . Du hittar Client ID i för den Overview hanterade identiteten i Azure Portal.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Viktigt!

Du måste ge följande behörigheter till den användartilldelade identiteten innan du skapar slutpunkten så att den kan komma åt Azure-resurserna för att utföra slutsatsdragning. Läs mer om hur du beviljar behörigheter till din slutpunktsidentitet.

Omfattning Roll Varför det behövs
Azure Machine Learning-arbetsyta Azure Machine Learning Workspace Connection Secrets Reader role ELLER en anpassad roll med"Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action" Hämta arbetsyteanslutningar
Arbetsytans containerregister ACR-pull Hämta containeravbildning
Standardlagring för arbetsyta Storage Blob Data-läsare Läsa in modellen från lagring
(Valfritt) Azure Machine Learning-arbetsyta Måttskrivare för arbetsytan När du har distribuerat slutpunkten måste du ge den här behörigheten till identiteten om du vill övervaka slutpunktsrelaterade mått som CPU/GPU/disk/minnesanvändning.

Definiera distributionen

En distribution är en uppsättning resurser som krävs för att vara värd för den modell som utför den faktiska inferensen.

Följande är ett exempel på distributionsdefinition, där avsnittet model refererar till den registrerade flödesmodellen. Du kan också ange flödesmodellsökvägen i rad.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: basic-chat-endpoint
model: azureml:basic-chat-model:1
  # You can also specify model files path inline
  # path: examples/flows/chat/basic-chat
environment: 
  image: mcr.microsoft.com/azureml/promptflow/promptflow-runtime:latest
  # inference config is used to build a serving container for online deployments
  inference_config:
    liveness_route:
      path: /health
      port: 8080
    readiness_route:
      path: /health
      port: 8080
    scoring_route:
      path: /score
      port: 8080
instance_type: Standard_E16s_v3
instance_count: 1
environment_variables:
  # for pulling connections from workspace
  PRT_CONFIG_OVERRIDE: deployment.subscription_id=<subscription_id>,deployment.resource_group=<resource_group>,deployment.workspace_name=<workspace_name>,deployment.endpoint_name=<endpoint_name>,deployment.deployment_name=<deployment_name>

  # (Optional) When there are multiple fields in the response, using this env variable will filter the fields to expose in the response.
  # For example, if there are 2 flow outputs: "answer", "context", and I only want to have "answer" in the endpoint response, I can set this env variable to '["answer"]'.
  # If you don't set this environment, by default all flow outputs will be included in the endpoint response.
  # PROMPTFLOW_RESPONSE_INCLUDED_FIELDS: '["category", "evidence"]'
Attribut Beskrivning
Name Namnet på distributionen.
Slutpunktnamn Namnet på slutpunkten som distributionen ska skapas under.
Modell Den modell som ska användas för distributionen. Det här värdet kan antingen vara en referens till en befintlig version av modellen på arbetsytan eller en infogad modellspecifikation.
Environment Miljön som ska vara värd för modellen och koden. Den innehåller:
- image
- inference_config: används för att skapa en servercontainer för onlinedistributioner, inklusive liveness route, readiness_routeoch scoring_route .
Instanstyp Den VM-storlek som ska användas för distributionen. Listan över storlekar som stöds finns i SKU-listan för hanterade onlineslutpunkter.
Antal instanser Antalet instanser som ska användas för distributionen. Basera värdet på den arbetsbelastning du förväntar dig. För hög tillgänglighet rekommenderar vi att du anger värdet till minst 3. Vi reserverar ytterligare 20 % för att utföra uppgraderingar. Mer information finns i begränsningar för onlineslutpunkter.
Miljövariabler Följande miljövariabler måste anges för slutpunkter som distribueras från ett flöde:
– (krävs) PRT_CONFIG_OVERRIDE: för att hämta anslutningar från arbetsytan
- (valfritt) PROMPTFLOW_RESPONSE_INCLUDED_FIELDS:: När det finns flera fält i svaret filtrerar den här env-variabeln fälten som ska exponeras i svaret.
Om det till exempel finns två flödesutdata: "answer", "context" och om du bara vill ha "svar" i slutpunktssvaret kan du ange den här env-variabeln till "["svar"].

Viktigt!

Om flödesmappen har en requirements.txt fil som innehåller de beroenden som krävs för att köra flödet måste du följa distributionen med en anpassad miljö för att skapa den anpassade miljön, inklusive beroendena.

Om du skapar en Kubernetes Online-distribution måste du ange följande attribut:

Attribut beskrivning
Typ Typ av distribution. Ange värdet till kubernetes.
Instanstyp Den instanstyp som du har skapat i kubernetes-klustret som ska användas för distributionen representerar distributionens beräkningsresurs för begäran/gräns. Mer information finns i Skapa och hantera instanstyp.

Distribuera din onlineslutpunkt till Azure

Kör följande kod för att skapa slutpunkten i molnet:

az ml online-endpoint create --file endpoint.yml

Kör följande kod för att skapa distributionen med namnet blue under slutpunkten:

az ml online-deployment create --file blue-deployment.yml --all-traffic

Kommentar

Den här distributionen kan ta mer än 15 minuter.

Dricks

Om du föredrar att inte blockera CLI-konsolen kan du lägga till flaggan --no-wait i kommandot. Detta stoppar dock den interaktiva visningen av distributionsstatusen.

Viktigt!

Flaggan --all-traffic i föregående az ml online-deployment create allokerar 100 % av slutpunktstrafiken till den nyligen skapade blå distributionen. Även om detta är användbart i utvecklings- och testsyfte kan det vara bra att öppna trafik till den nya distributionen via ett explicit kommando för produktion. Exempel: az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100"

Kontrollera status för slutpunkten och distributionen

Kör följande kod för att kontrollera slutpunktens status:

az ml online-endpoint show -n basic-chat-endpoint

Kör följande kod för att kontrollera distributionens status:

az ml online-deployment get-logs --name blue --endpoint basic-chat-endpoint

Anropa slutpunkten för att poängsätta data med hjälp av din modell

Du kan skapa en sample-request.json fil så här:

{
  "question": "What is Azure Machine Learning?",
  "chat_history":  []
}

az ml online-endpoint invoke --name basic-chat-endpoint --request-file sample-request.json

Du kan också anropa den med en HTTP-klient, till exempel med curl:

ENDPOINT_KEY=<your-endpoint-key>
ENDPOINT_URI=<your-endpoint-uri>

curl --request POST "$ENDPOINT_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data '{"question": "What is Azure Machine Learning?", "chat_history":  []}'

Du kan hämta slutpunktsnyckeln och slutpunkts-URI:n från Azure Machine Learning-arbetsytan i Slutpunkter>Använd>information om grundläggande förbrukning.

Avancerade konfigurationer

Distribuera med olika anslutningar från flödesutveckling

Du kanske vill åsidosätta anslutningar för flödet under distributionen.

Om din flow.dag.yaml-fil till exempel använder en anslutning med namnet my_connectionkan du åsidosätta den genom att lägga till miljövariabler i distributions-yaml som följande:

Alternativ 1: åsidosätt anslutningsnamnet

environment_variables:
  my_connection: <override_connection_name>

Om du vill åsidosätta ett specifikt fält i anslutningen kan du åsidosätta genom att lägga till miljövariabler med namngivningsmönstret <connection_name>_<field_name>. Om ditt flöde till exempel använder en anslutning med namnet my_connection med en konfigurationsnyckel med namnet chat_deployment_nameförsöker serverdelen hämta chat_deployment_name från miljövariabeln "MY_CONNECTION_CHAT_DEPLOYMENT_NAME" som standard. Om miljövariabeln inte har angetts använder den det ursprungliga värdet från flödesdefinitionen.

Alternativ 2: åsidosättning genom att referera till tillgång

environment_variables:
  my_connection: ${{azureml://connections/<override_connection_name>}}

Kommentar

Du kan bara referera till en anslutning på samma arbetsyta.

Distribuera med en anpassad miljö

Det här avsnittet visar hur du använder en Docker-byggkontext för att ange miljön för distributionen, förutsatt att du har kunskaper om Docker - och Azure Machine Learning-miljöer.

  1. I din lokala miljö skapar du en mapp med namnet image_build_with_reqirements innehåller följande filer:

    |--image_build_with_reqirements
|  |--requirements.txt
|  |--Dockerfile

    • requirements.txt Bör ärvas från flödesmappen, som har använts för att spåra flödets beroenden.

    • Innehållet Dockerfile liknar följande text:

      FROM mcr.microsoft.com/azureml/promptflow/promptflow-runtime:latest
COPY ./requirements.txt .
RUN pip install -r requirements.txt

  2. ersätt miljöavsnittet i yaml-filen för distributionsdefinitionen med följande innehåll:

    environment: 
  build:
    path: image_build_with_reqirements
    dockerfile_path: Dockerfile
  # deploy prompt flow is BYOC, so we need to specify the inference config
  inference_config:
    liveness_route:
      path: /health
      port: 8080
    readiness_route:
      path: /health
      port: 8080
    scoring_route:
      path: /score
      port: 8080

Använda FastAPI-servermotorn (förhandsversion)

Som standard använder snabbflödesservern FLASK-serveringsmotorn. Från och med promptflödes-SDK version 1.10.0 stöds FastAPI-baserad servermotor. Du kan använda fastapi servermotorn genom att ange en miljövariabel PROMPTFLOW_SERVING_ENGINE.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Konfigurera samtidighet för distribution

När du distribuerar flödet till onlinedistributionen finns det två miljövariabler som du konfigurerar för samtidighet: PROMPTFLOW_WORKER_NUM och PROMPTFLOW_WORKER_THREADS. Dessutom måste du också ange parametern max_concurrent_requests_per_instance .

Nedan visas ett exempel på hur du konfigurerar i deployment.yaml filen.

request_settings:
  max_concurrent_requests_per_instance: 10
environment_variables:
  PROMPTFLOW_WORKER_NUM: 4
  PROMPTFLOW_WORKER_THREADS: 1

  • PROMPTFLOW_WORKER_NUM: Den här parametern avgör antalet arbetare (processer) som ska startas i en container. Standardvärdet är lika med antalet CPU-kärnor och det maximala värdet är dubbelt så många processorkärnor.

  • PROMPTFLOW_WORKER_THREADS: Den här parametern bestämmer antalet trådar som ska startas i en arbetare. Standardvärdet är 1.

    Kommentar

    När du anger PROMPTFLOW_WORKER_THREADS ett värde som är större än 1 kontrollerar du att flödeskoden är trådsäker.

  • max_concurrent_requests_per_instance: Det maximala antalet samtidiga begäranden per instans som tillåts för distributionen. Standardvärdet är 10.

    Det föreslagna värdet för max_concurrent_requests_per_instance beror på din begärandetid:

    • Om din begärandetid är större än 200 ms anger du max_concurrent_requests_per_instance till PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS.
    • Om din begärandetid är mindre än eller lika med 200 ms anger du max_concurrent_requests_per_instance till (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. Detta kan förbättra det totala dataflödet genom att tillåta att vissa begäranden placeras i kö på serversidan.
    • Om du skickar begäranden mellan regioner kan du ändra tröskelvärdet från 200 ms till 1 s.

När du justerar ovanstående parametrar måste du övervaka följande mått för att säkerställa optimal prestanda och stabilitet:

  • Instans-CPU/minnesanvändning för den här distributionen
  • Svar som inte är 200 (4xx, 5xx)
    • Om du får ett 429-svar indikerar detta vanligtvis att du antingen behöver ändra inställningarna för samtidighet genom att följa guiden ovan eller skala distributionen.
  • Azure OpenAI-begränsningsstatus

Övervaka slutpunkter

Samla in allmänna mått

Du kan visa allmänna mått för onlinedistribution (begärandenummer, svarstid för begäranden, nätverksbyte, PROCESSOR/GPU/disk/minnesanvändning med mera).

Samla in spårningsdata och systemmått under inferenstid

Du kan också samla in spårningsdata och distributionsspecifika mått för snabbflöde (tokenförbrukning, flödesfördröjning osv.) under inferenstiden till arbetsytans länkade Application Insights genom att lägga till en egenskap app_insights_enabled: true i yaml-filen för distribution. Läs mer om spårning och mått för distribution av promptflöde.

Specifika mått och spårningar för frågaflöde kan anges till andra Application Insights än den länkade arbetsytan. Du kan ange en miljövariabel i yaml-distributionsfilen enligt följande. Du hittar anslutningssträng för Dina Application Insights på översiktssidan i Azure Portal.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Kommentar

Om du bara anger app_insights_enabled: true men arbetsytan inte har någon länkad Application Insights misslyckas inte distributionen, men inga data samlas in. Om du anger både app_insights_enabled: true och ovanstående miljövariabel samtidigt skickas spårningsdata och mått till arbetsytans länkade Application Insights. Om du vill ange en annan Application Insights behöver du därför bara behålla miljövariabeln.

Vanliga fel

Timeout-problem med överordnad begäran när slutpunkten förbrukas

Ett sådant fel orsakas vanligtvis av timeout. Som standard request_timeout_ms är 5000. Du kan ange högst 5 minuter, vilket är 300 000 ms. Följande är ett exempel som visar hur du anger tidsgränsen för begäran i yaml-filen för distribution. Läs mer om distributionsschemat här.

request_settings:
  request_timeout_ms: 300000

Viktigt!

Tidsgränsen på 300 000 ms fungerar bara för hanterade onlinedistributioner från promptflödet. Maxvärdet för en icke-prompt-flödeshanterad onlineslutpunkt är 180 sekunder.

Du måste se till att du har lagt till egenskaper för din modell på följande sätt (antingen inline model specification in the deployment yaml or standalone model specification yaml) för att indikera att detta är en distribution från promptflöde.

properties:
  # indicate a deployment from prompt flow
  azureml.promptflow.source_flow_id: <value>

Nästa steg

  • Last updated on