Een flow implementeren naar een online-eindpunt voor realtime inference met CLI

In dit artikel leert u hoe u uw stroom implementeert in een online-eindpunt van beheer of een Kubernetes online-eindpunt voor gebruik in realtime deductie met Azure Machine Learning v2 CLI.

Voordat u begint, controleert u of u de stroom goed hebt getest en bent u ervan overtuigd dat deze gereed is om te worden geïmplementeerd in productie. Zie uw stroom testen voor meer informatie over het testen van uw stroom. Na het testen van uw workflow leert u hoe u een beheerd online-eindpunt en -uitrol maakt en hoe u het eindpunt gebruikt voor realtime inferentie.

• In dit artikel wordt beschreven hoe u de CLI-ervaring gebruikt.
• De Python SDK wordt niet behandeld in dit artikel. Zie in plaats daarvan het GitHub voorbeeldnotitieblok. Als u de Python SDK wilt gebruiken, moet u de Python SDK v2 voor Azure Machine Learning hebben. Zie Install the Python SDK v2 for Azure Machine Learning voor meer informatie.

Voorwaarden

• De Azure CLI en de Azure Machine Learning-extensie voor de Azure CLI. Zie De CLI (v2) installeren, instellen en gebruiken voor meer informatie.
• Een Azure Machine Learning werkruimte. Als u er nog geen hebt, gebruikt u de stappen in de quickstart: artikel Werkruimtebronnen maken om er een te maken.
• Azure op rollen gebaseerd toegangsbeheer (Azure RBAC) worden gebruikt om toegang te verlenen tot bewerkingen in Azure Machine Learning. Als u de stappen in dit artikel wilt uitvoeren, moet aan uw gebruikersaccount de rol 'eigenaar' of 'medewerker' worden toegewezen voor de Azure Machine Learning Workspace, of aan een aangepaste rol die "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/" toestaat. Als u Studio gebruikt voor het maken/beheren van online-eindpunten/implementaties, hebt u nog een toestemming "Microsoft.Resources/deployments/write" nodig van de eigenaar van de resourcegroep. Zie Toegang tot een Azure Machine Learning-werkruimte voor meer informatie.

Quotumtoewijzing voor virtuele machines voor implementatie

Voor beheerde online-eindpunten reserveert Azure Machine Learning 20% van uw rekenresources voor het uitvoeren van upgrades. Daarom, als u een opgegeven aantal instanties in een implementatie aanvraagt, moet er een beschikbaar quotum van ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU zijn om een fout te voorkomen. Als u bijvoorbeeld 10 exemplaren van een Standard_DS3_v2 VM aanvraagt (die wordt geleverd met vier kernen) in een implementatie, moet u een quotum hebben voor 48 kernen (12 exemplaren van vier kernen) beschikbaar. Bekijk uw gebruik en quota in de Azure-portal om uw gebruik te bekijken en quotumverhogingen aan te vragen.

De stroom voorbereiden voor implementatie

Elke stroom heeft een map die codes/prompts, definities en andere artefacten van de stroom bevat. Als u uw stroom hebt ontwikkeld met de gebruikersinterface, kunt u de stroommap downloaden vanaf de pagina met stroomdetails. Als u uw stroom hebt ontwikkeld met CLI of SDK, moet u de stroommap al hebben.

In dit artikel wordt de voorbeeldstroom "basic-chat" gebruikt als voorbeeld voor implementatie naar het Azure Machine Learning beheerd online eindpunt.

Standaardwerkruimte instellen

Gebruik de volgende opdrachten om de standaardwerkruimte en resourcegroep voor de CLI in te stellen.

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

De stroom registreren als een model (optioneel)

In de onlineimplementatie kunt u inline verwijzen naar een geregistreerd model of het modelpad opgeven (waar u de modelbestanden vandaan wilt uploaden). Het is raadzaam om het model te registreren en de modelnaam en versie op te geven in de implementatiedefinitie. Gebruik het formulier model:<model_name>:<version>.

Hieronder volgt een voorbeeld van een modeldefinitie voor een chatstroom.

$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

Gebruik az ml model create --file model.yaml om het model bij uw werkruimte te registreren.

Het eindpunt definiëren

Als u een eindpunt wilt definiëren, moet u het volgende opgeven:

• Eindpuntnaam: de naam van het eindpunt. Deze moet uniek zijn in de Azure regio. Zie eindpuntlimieten voor meer informatie over de naamgevingsregels.
• Verificatiemodus: de verificatiemethode voor het eindpunt. Kies tussen verificatie op basis van sleutels en Azure Machine Learning verificatie op basis van tokens. Een sleutel verloopt niet, maar een token verloopt wel. Zie Verifiëren bij een online-eindpunt voor meer informatie over verificatie. U kunt eventueel een beschrijving en tags toevoegen aan uw eindpunt.
• U kunt eventueel een beschrijving en tags toevoegen aan uw eindpunt.
• Als u wilt implementeren in een Kubernetes-cluster (AKS- of Arc-cluster) dat is gekoppeld aan uw werkruimte, kunt u de stroom implementeren als een Kubernetes Online-eindpunt.

Hieronder volgt een voorbeeld van een eindpuntdefinitie die standaard gebruikmaakt van door het systeem toegewezen identiteit.

$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

$schema: https://azuremlschemas.azureedge.net/latest/kubernetesOnlineEndpoint.schema.json
name: basic-chat-endpoint
compute: azureml:<Kubernetes compute name>
auth_mode: key

Als u een Kubernetes-online-eindpunt maakt, moet u de volgende kenmerken opgeven:

Zie het beheerde online-eindpuntschema voor meer configuraties van eindpunten.

Door de gebruiker toegewezen identiteit gebruiken

Wanneer u een online-eindpunt maakt, wordt standaard automatisch een door het systeem toegewezen beheerde identiteit voor u gegenereerd. U kunt ook een bestaande door de gebruiker toegewezen beheerde identiteit voor het eindpunt opgeven.

Als u een door de gebruiker toegewezen identiteit wilt gebruiken, kunt u de volgende kenmerken opgeven in:endpoint.yaml

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Bovendien moet u ook de door de gebruiker toegewezen identiteit specificeren onder Client ID de environment_variables zoals volgt. U vindt de Client ID in de Overview van de beheerde identiteit in Azure-portal.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

De implementatie definiëren

Een implementatie is een set resources die vereist is voor het hosten van het model dat de werkelijke deductie uitvoert.

Hieronder volgt een voorbeeld van een implementatiedefinitie, waarin de model sectie verwijst naar het geregistreerde stroommodel. U kunt ook het pad van het stroommodel in lijn opgeven.

$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"]'

$schema: https://azuremlschemas.azureedge.net/latest/kubernetesOnlineDeployment.schema.json
name: blue
type: kubernetes
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: <kubernetes custom instance type>
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"]'

Als u een online-implementatie van Kubernetes maakt, moet u de volgende kenmerken opgeven:

Uw online-eindpunt implementeren in Azure

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

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

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

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

De status van het eindpunt en de implementatie controleren

Voer de volgende code uit om de status van het eindpunt te controleren:

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

Voer de volgende code uit om de status van de implementatie te controleren:

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

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

U kunt als volgt een sample-request.json-bestand maken:

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

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

U kunt deze ook aanroepen met een HTTP-client, bijvoorbeeld met 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":  []}'

U kunt uw eindpuntsleutel en uw eindpunt-URI ophalen uit de Azure Machine Learning werkruimte in Endpoints>Consume>Basic consumption info.

Geavanceerde configuraties

Uitrollen met verschillende verbindingen van flow-ontwikkeling

Mogelijk wilt u tijdens de implementatie de verbindingen van de werkstroom overschrijven.

Als uw flow.dag.yaml-bestand bijvoorbeeld gebruikmaakt van een verbinding met de naam my_connection, kunt u dit overschrijven door omgevingsvariabelen van de implementatie-yaml als volgt toe te voegen:

Optie 1: verbindingsnaam overschrijven

environment_variables:
  my_connection: <override_connection_name>

Als u een specifiek veld van de verbinding wilt overschrijven, kunt u dit overschrijven door omgevingsvariabelen toe te voegen met een naamgevingspatroon <connection_name>_<field_name>. Als uw stroom bijvoorbeeld gebruikmaakt van een verbinding met de naam my_connection met een configuratiesleutel genaamd chat_deployment_name, probeert de serverback-end standaard chat_deployment_name op te halen uit de omgevingsvariabele 'MY_CONNECTION_CHAT_DEPLOYMENT_NAME'. Als de omgevingsvariabele niet is ingesteld, wordt de oorspronkelijke waarde uit de stroomdefinitie gebruikt.

Optie 2: overschrijven door te verwijzen naar asset

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

Implementeren met een aangepaste omgeving

In deze sectie wordt beschreven hoe u een docker-buildcontext gebruikt om de omgeving voor uw implementatie op te geven, ervan uitgaande dat u kennis hebt van Docker en Azure Machine Learning-omgevingen.

1. Maak in uw lokale omgeving een map met de naam image_build_with_reqirements die de volgende bestanden bevat:

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

   • Deze requirements.txt moet worden overgenomen uit de flowmap, die is gebruikt om de afhankelijkheden van de flow bij te houden.

   • De Dockerfile inhoud is vergelijkbaar met de volgende tekst:

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

2. vervang de omgevingssectie in het yaml-bestand voor de implementatiedefinitie door de volgende inhoud:

   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
   

FastAPI-serverengine gebruiken (preview)

Standaard maakt promptstromen gebruik van de FLASK-serverengine. Vanaf prompt flow SDK versie 1.10.0 wordt de fastAPI-serverengine ondersteund. U kunt de service-engine gebruiken fastapi door een omgevingsvariabele PROMPTFLOW_SERVING_ENGINEop te geven.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Gelijktijdigheid configureren voor implementatie

Wanneer u uw stroom implementeert in onlineimplementatie, zijn er twee omgevingsvariabelen die u configureert voor gelijktijdigheid: PROMPTFLOW_WORKER_NUM en PROMPTFLOW_WORKER_THREADS. Bovendien moet u ook de max_concurrent_requests_per_instance parameter instellen.

Hieronder ziet u een voorbeeld van het configureren in het deployment.yaml bestand.

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

• PROMPTFLOW_WORKER_NUM: Met deze parameter wordt het aantal werkrollen (processen) bepaald dat in één container wordt gestart. De standaardwaarde is gelijk aan het aantal CPU-kernen en de maximumwaarde is tweemaal het aantal CPU-kernen.

• PROMPTFLOW_WORKER_THREADS: deze parameter bepaalt het aantal threads dat in één worker zullen worden gestart. De standaardwaarde is 1.

  Opmerking

  Wanneer u een PROMPTFLOW_WORKER_THREADS waarde instelt die groter is dan 1, moet u ervoor zorgen dat uw stroomcode thread-safe is.

• max_concurrent_requests_per_instance: het maximum aantal gelijktijdige aanvragen per exemplaar dat is toegestaan voor de implementatie. De standaardwaarde is 10.

  De voorgestelde waarde voor max_concurrent_requests_per_instance is afhankelijk van uw aanvraagtijd.

  • Als uw aanvraagtijd groter is dan 200 ms, stelt u deze in max_concurrent_requests_per_instance op PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS.
  • Als uw aanvraagtijd kleiner is dan of gelijk is aan 200 ms, stelt u deze in max_concurrent_requests_per_instance op (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. Dit kan de totale doorvoer verbeteren door toe te staan dat sommige aanvragen in de wachtrij worden geplaatst aan de serverzijde.
  • Als u aanvragen voor meerdere regio's verzendt, kunt u de drempelwaarde wijzigen van 200 ms in 1 s.

Tijdens het afstemmen van bovenstaande parameters moet u de volgende metrische gegevens bewaken om optimale prestaties en stabiliteit te garanderen:

• CPU-/geheugengebruik van het exemplaar van deze implementatie
• Niet-200 antwoorden (4xx, 5xx)
  • Als u een 429-antwoord ontvangt, geeft dit meestal aan dat u de gelijktijdigheidsinstellingen moet aanpassen aan de hand van de bovenstaande handleiding of de implementatie moet schalen.
• Azure OpenAI-beperkingsstatus

Eindpunten bewaken

Algemene metrische gegevens verzamelen

U kunt algemene metrische gegevens van onlineimplementatie bekijken (aanvraagnummers, latentie van aanvragen, netwerkbytes, CPU/GPU/schijf/geheugengebruik en meer).

Tijdens inferentietijd traceringsgegevens en systeemmetriek verzamelen

U kunt ook traceringsgegevens verzamelen en specifieke metrieken van stroomimplementatie (tokenverbruik, stroomlatentie, enzovoort) tijdens inferentietijd naar Application Insights die aan de werkruimte gekoppeld zijn door een eigenschap app_insights_enabled: true toe te voegen in het yaml-implementatiebestand. Meer informatie over tracering en metrische gegevens van promptstroomimplementatie.

Promptflow-specifieke metrieken en tracering kunnen worden gespecificeerd voor andere Application Insights dan alleen de gekoppelde werkruimte. U kunt als volgt een omgevingsvariabele opgeven in het yaml-bestand voor de implementatie. U vindt de verbindingsreeks van uw Application Insights op de pagina Overzicht in Azure portal.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Veelvoorkomende fouten

Time-outprobleem voor upstream-aanvragen bij gebruik van het eindpunt

Deze fout wordt meestal veroorzaakt door een time-out. request_timeout_ms De standaardwaarde is 5000. U kunt maximaal 5 minuten opgeven, wat 300.000 ms is. Hieronder ziet u een voorbeeld van het opgeven van een time-out voor aanvragen in het yaml-implementatiebestand. Meer informatie over het implementatieschema vindt u hier.

request_settings:
  request_timeout_ms: 300000

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

Volgende stappen

• Meer informatie over het beheerde online-eindpuntschema en het beheerde online-implementatieschema.
• Meer informatie over het testen van het eindpunt in de gebruikersinterface en het bewaken van het eindpunt.
• Meer informatie over het oplossen van problemen met beheerde online-eindpunten.
• Problemen met promptstroomimplementaties oplossen.
• Zodra u uw stroom hebt verbeterd en u de verbeterde versie met een veilige implementatiestrategie wilt implementeren, raadpleegt u Veilige implementatie voor online-eindpunten.
• Meer informatie over deploy-stromen naar andere platforms, zoals een lokale ontwikkelingsservice, Docker-container, Azure APP-service, enzovoort <>