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

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

Voordat u begint, moet u ervoor zorgen dat u uw stroom goed test en er zeker van bent dat deze gereed is om in productie te worden geïmplementeerd. Zie uw stroom testen voor meer informatie over het testen van uw stroom. Nadat u uw stroom hebt getest, leert u hoe u een beheerd online-eindpunt en -implementatie maakt en hoe u het eindpunt gebruikt voor realtime deductie.

• 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 om online-eindpunten en implementaties te maken en te beheren, hebt u nog een andere machtiging nodig, namelijk 'Microsoft.Resources/deployments/write', 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 flow ontwikkelt met behulp van de UI, kunt u de flowmap downloaden vanaf de detailpagina van de flow. Als u uw flow ontwikkelt met de CLI of SDK, hebt u de flowmap al.

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). Registreer het model en geef de modelnaam en versie op in de implementatiedefinitie. Gebruik het formulier model:<model_name>:<version>.

In het volgende voorbeeld ziet u 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 Azure Machine Learning studio, the endpoint Test tab uses this property to identify a 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, geeft u de volgende waarden op:

• 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.
• Voeg eventueel een beschrijving en tags toe aan uw eindpunt.
• Als u een Kubernetes-cluster (AKS- of Arc-cluster) wilt implementeren dat u aan uw werkruimte koppelt, kunt u de stroom implementeren als een Online-eindpunt van Kubernetes.

In het volgende voorbeeld ziet u 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, genereert het systeem automatisch een door het systeem toegewezen beheerde identiteit voor u. 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, geeft u de volgende kenmerken op in het endpoint.yaml bestand:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Geef ook de Client ID van de door de gebruiker toegewezen identiteit op onder environment_variables in het bestand deployment.yaml, zoals in het volgende voorbeeld. U vindt de Client ID in de Overview beheerde identiteit in de 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.

In het volgende voorbeeld ziet u een implementatiedefinitie. 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, geeft u de volgende kenmerken op:

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

sample-request.json Een 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 het eindpunt ook aanroepen met behulp van een HTTP-client, zoals 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":  []}'

Haal uw eindpuntsleutel en uw eindpunt-URI op uit de Azure Machine Learning werkruimte in Eindpunten>Verbruik>basisverbruiksgegevens.

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.

De runtime-installatiekopieën van Prompt flow zijn bevroren en ontvangen geen beveiligings- of pakketupdates meer. De latest tag in het volgende voorbeeld geeft niet aan dat de afbeelding updates ontvangt. Gebruik dit voorbeeld alleen om een bestaande implementatie te onderhouden terwijl u de migratie plant.

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

|--image_build_with_requirements
  |  |--requirements.txt
  |  |--Dockerfile
  ```
  - The `requirements.txt` file, inherited from the flow folder, tracks the dependencies of the flow. 

  - The `Dockerfile` with content similar to the following example: 

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

1. Replace the environment section in the deployment definition YAML file with the following content:

  ```yaml
  environment: 
    build:
      path: image_build_with_requirements
      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
  ```

### Use FastAPI serving engine (preview)

By default, prompt flow serving uses the Flask serving engine. Starting from prompt flow SDK version 1.10.0, FastAPI-based serving engine is supported. You can use the `fastapi` serving engine by specifying an environment variable `PROMPTFLOW_SERVING_ENGINE`.

```yaml
environment_variables:
PROMPTFLOW_SERVING_ENGINE: fastapi

Gelijktijdigheid configureren voor implementatie

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

In het volgende voorbeeld ziet u hoe u deze instellingen in het deployment.yaml bestand configureert.

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) ingesteld 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: Met deze parameter wordt het aantal threads ingesteld dat in één worker wordt gestart. De standaardwaarde is 1.

  Opmerking

  Wanneer u instelt PROMPTFLOW_WORKER_THREADS op een waarde 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. Deze instelling kan de totale doorvoer verbeteren door sommige verzoeken toe te staan aan serverzijde in de wachtrij te worden geplaatst.
  • Als u aanvragen voor meerdere regio's verzendt, kunt u de drempelwaarde wijzigen van 200 ms in 1 s.

Controleer tijdens het afstemmen van deze parameters de volgende metrische gegevens om optimale prestaties en stabiliteit te garanderen:

• CPU- en geheugengebruik van instanties voor deze implementatie
• Niet-200 antwoorden (4xx, 5xx)
  • Als u een 429-antwoord ontvangt, geeft deze statuscode meestal aan dat u de gelijktijdigheidsinstellingen moet aanpassen aan de hand van de voorgaande 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 tijdens inferentie traceringsgegevens en implementatiespecifieke metrische gegevens voor prompt flow (tokenverbruik, flowlatentie en meer) verzamelen in de aan de werkruimte gekoppelde Application Insights door een eigenschap app_insights_enabled: true toe te voegen in het deployment-YAML-bestand. Zie tracering en metrische gegevens van de implementatie van Prompt flow voor meer informatie.

U kunt specifieke metrische gegevens voor de promptstroom opgeven en traceringsgegevens naar een andere Application Insights-resource sturen in plaats van naar de resource die aan de werkruimte is gekoppeld. 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 treedt meestal op vanwege een time-out. Standaard is de waarde van request_timeout_ms 5.000 milliseconden. U kunt het instellen tot 5 minuten, wat 300.000 milliseconden is. In het volgende voorbeeld ziet u hoe u de time-out van de aanvraag opgeeft in het YAML-implementatiebestand. Zie het beheerde online-implementatieschema voor meer informatie over het implementatieschema.

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.
• Als u een verbeterde versie van uw stroom wilt implementeren met behulp van een veilige implementatiestrategie, 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 <>