Bereitstellen eines Flows für einen Onlineendpunkt für Rückschlüsse in Echtzeit mit der CLI

In diesem Artikel erfahren Sie, wie Sie Ihren Workflow auf einem managed Onlineendpunkt oder einem Kubernetes-Onlineendpunkt für Inferenzen in Echtzeit mit Azure Machine Learning v2 CLI bereitstellen.

Stellen Sie zunächst sicher, dass Sie Ihren Flow ordnungsgemäß getestet haben und davon überzeugt sind, dass er für die Bereitstellung in der Produktion bereit ist. Weitere Informationen zum Testen Ihres Flows finden Sie unter Testen Ihres Flows. Nach dem Testen Ihres Flows erfahren Sie, wie Sie einen verwalteten Onlineendpunkt und die Bereitstellung erstellen und wie Sie den Endpunkt für Echtzeitrückschlüsse verwenden.

• In diesem Artikel wird beschrieben, wie Sie die Benutzeroberfläche der Befehlszeilenschnittstelle verwenden.
• Das Python SDK wird in diesem Artikel nicht behandelt. Sehen Sie sich stattdessen das GitHub Beispielnotizbuch an. Um das Python SDK zu verwenden, benötigen Sie das Python SDK v2 für Azure Machine Learning. Weitere Informationen finden Sie unter Installieren des Python SDK v2 für Azure Machine Learning.

Voraussetzungen

• Die Azure CLI und die Azure Machine Learning Erweiterung für die Azure CLI. Weitere Informationen finden Sie unter Installieren, Einrichten und Verwenden der CLI (v2).
• Ein Azure Machine Learning Arbeitsbereich. Wenn Sie noch keinen haben, führen Sie die Schritte im Artikel Schnellstart: Erstellen von Arbeitsbereichsressourcen aus, um Ressourcen zu erstellen.
• Azure rollenbasierte Zugriffssteuerungen (Azure RBAC) werden verwendet, um Den Zugriff auf Vorgänge in Azure Machine Learning zu gewähren. Um die Schritte in diesem Artikel auszuführen, muss Ihrem Benutzerkonto die Rolle "Besitzer" oder "Mitwirkender" für den Azure Machine Learning-Arbeitsbereich zugewiesen sein, oder eine benutzerdefinierte Rolle, die den Zugriff auf "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/" erlaubt. Wenn Sie Studio zum Erstellen/Verwalten von Onlineendpunkten/Bereitstellungen verwenden, benötigen Sie eine weitere Berechtigung "Microsoft. Ressourcen/Bereitstellungen/Schreiben" vom Ressourcengruppenbesitzer. Weitere Informationen finden Sie unter Manage-Zugriff auf einen Azure Machine Learning Arbeitsbereich.

Kontingentzuordnung für virtuelle Computer für die Bereitstellung

Für verwaltete Onlineendpunkte reserviert Azure Machine Learning 20% Ihrer Computeressourcen für die Durchführung von Upgrades. Wenn Sie also eine bestimmte Anzahl von Instanzen in einer Bereitstellung anfordern, müssen Sie über ein Kontingent für ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKUverfügen, um zu verhindern, dass Sie einen Fehler erhalten. Wenn Sie beispielsweise zehn Instanzen einer Standard_DS3_v2-VM (mit vier Kernen) in einer Bereitstellung anfordern, sollten ein Kontingent für 48 Kerne (zwölf Instanzen mit jeweils vier Kernen) verfügbar sein. Informationen zum Anzeigen Ihrer Nutzung und zum Anfordern von Kontingenterhöhungen finden Sie unter Ihre Nutzung und Kontingente im Azure-Portal anzeigen.

Bereiten Sie den Flow für die Bereitstellung vor

Jeder Flow verfügt über einen Ordner, der Codes/Prompts, Definitionen und andere Artefakte des Flows enthält. Wenn Sie Ihren Flow mit der Benutzeroberfläche entwickelt haben, können Sie den Flow-Ordner von der Seite mit den Flow-Details herunterladen. Wenn Sie Ihren Flow mit der CLI oder dem SDK entwickelt haben, sollte der Flow-Ordner bereits vorhanden sein.

In diesem Artikel wird der Beispielfluss "basic-chat" als Beispiel für die Bereitstellung an den in Azure Machine Learning verwalteten Onlineendpunkt verwendet.

Festlegen des Standardarbeitsbereichs

Verwenden Sie die folgenden Befehle, um den Standardarbeitsbereich und die Ressourcengruppe für die CLI festzulegen.

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

Registriere den Flow als Modell (optional)

In der Onlinebereitstellung können Sie entweder auf ein registriertes Modell verweisen oder den Modellpfad (in den die Modelldateien hochgeladen werden sollen) inline angeben. Es wird empfohlen, das Modell zu registrieren und den Modellnamen und die Version in der Bereitstellungsdefinition anzugeben. Verwenden Sie das Format model:<model_name>:<version>.

Nachfolgend ein Beispiel für eine Modelldefinition für einen Chatablauf.

$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

Verwenden Sie az ml model create --file model.yaml, um das Modell in Ihrem Arbeitsbereich zu registrieren.

Definieren des Endpunkts

Um einen Endpunkt zu definieren, müssen Sie folgendes angeben:

• Endpunktname: Der Name des Endpunkts. Es muss in der Azure-Region eindeutig sein. Weitere Informationen zu den Benennungsregeln finden Sie unter Endpunktgrenzwerte.
• Authentifizierungsmodus: Die Authentifizierungsmethode für den Endpunkt. Wählen Sie zwischen schlüsselbasierter Authentifizierung und Azure Machine Learning tokenbasierter Authentifizierung aus. Ein Schlüssel läuft nicht ab, ein Token dagegen schon. Weitere Informationen zur Authentifizierung finden Sie unter Authentifizieren bei einem Onlineendpunkt. Optional können Sie eine Beschreibung und Tags zu Ihrem Endpunkt hinzufügen.
• Optional können Sie eine Beschreibung und Tags zu Ihrem Endpunkt hinzufügen.
• Wenn Sie eine Bereitstellung in einem Kubernetes-Cluster (AKS-Cluster oder Arc-fähiger Cluster) durchführen möchten, der an Ihren Arbeitsbereich angefügt ist, können Sie den Flow als Kubernetes-Onlineendpunkt bereitstellen.

Es folgt ein Beispiel für eine Endpunktdefinition, bei der standardmäßig die vom System zugewiesene Identität verwendet wird.

$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

Wenn Sie einen Kubernetes-Onlineendpunkt erstellen, müssen Sie die folgenden Attribute angeben:

Weitere Konfigurationen des Endpunkts finden Sie unter Schema für verwaltete Onlineendpunkte.

Verwenden einer benutzerseitig zugewiesenen Identität

Wenn Sie einen Onlineendpunkt erstellen, wird standardmäßig automatisch eine systemseitig zugewiesene verwaltete Identität für Sie generiert. Sie können auch eine vorhandene benutzerseitig zugewiesene verwaltete Identität für den Endpunkt angeben.

Wenn Sie eine benutzerseitig zugewiesene Identität verwenden möchten, können Sie die folgenden Attribute in endpoint.yaml angeben:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Außerdem müssen Sie das Client ID der benutzerzugewiesenen Identität wie folgt unter environment_variables in deployment.yaml angeben. Sie finden die Client ID im Overview der verwalteten Identität im Azure-Portal.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Bereitstellung definieren

Eine Bereitstellung ist ein Satz von Ressourcen, die für das Hosting des Modells erforderlich sind, das die Inferenz tatsächlich durchführt.

Nachfolgend sehen Sie ein Beispiel für die Bereitstellungsdefinition, in dem sich der model Abschnitt auf das registrierte Flussmodell bezieht. Sie können auch den Flussmodellpfad in der Zeile angeben.

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

Wenn Sie eine Kubernetes-Onlinebereitstellung erstellen, müssen Sie die folgenden Attribute angeben:

Bereitstellen Ihres Onlineendpunkts zum Azure

Führen Sie den folgenden Code aus, um den Endpunkt in der Cloud zu erstellen:

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

Führen Sie den folgenden Code aus, um die Bereitstellung mit dem Namen blue unter dem Endpunkt zu erstellen:

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

Überprüfen des Status des Endpunkts und der Bereitstellung

Führen Sie zum Überprüfen des Endpunktstatus den folgenden Code aus:

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

Führen Sie zum Überprüfen des Bereitstellungsstatus den folgenden Code aus:

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

Aufrufen des Endpunkts zum Bewerten von Daten mit Ihrem Modell

Sie können eine „sample-request.json“-Datei wie die folgende erstellen:

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

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

Sie können sie auch mit einem HTTP-Client aufrufen, z. B. mit 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":  []}'

Sie können Ihren Endpunktschlüssel und Ihren Endpunkt-URI aus dem Azure Machine Learning Arbeitsbereich in Endpoints>Consume>Basic consumption info abrufen.

Erweiterte Konfigurationen

Einsatz mit verschiedenen Verbindungen aus der Ablaufentwicklung

Möglicherweise möchten Sie die Verbindungen des Prozessablaufs während der Bereitstellung überschreiben.

Wenn Ihre flow.dag.yaml-Datei zum Beispiel eine Verbindung mit dem Namen my_connection verwendet, können Sie diese überschreiben, indem Sie Umgebungsvariablen in der Deployment-Yaml-Datei wie folgt hinzufügen:

Option 1: Verbindungsname außer Kraft setzen

environment_variables:
  my_connection: <override_connection_name>

Wenn Sie ein bestimmtes Feld der Verbindung überschreiben möchten, können Sie dies tun, indem Sie Umgebungsvariablen, die dem Benennungsmuster <connection_name>_<field_name> folgen, hinzufügen. Wenn Ihr Flow beispielsweise eine Verbindung namens my_connection mit dem Konfigurationsschlüssel chat_deployment_name verwendet, versucht das bereitstellende Back-End standardmäßig, chat_deployment_name aus der Umgebungsvariable „MY_CONNECTION_CHAT_DEPLOYMENT_NAME“ abzurufen. Wenn die Umgebungsvariable nicht festgelegt ist, wird der ursprüngliche Wert aus der Flowdefinition verwendet.

Option 2: Überschreiben mittels Verweis auf Ressource

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

Bereitstellung mit einer benutzerdefinierten Umgebung

In diesem Abschnitt wird erläutert, wie Sie einen Docker-Buildkontext verwenden, um die Umgebung für Ihre Bereitstellung anzugeben, vorausgesetzt, Sie verfügen über Kenntnisse in Docker und Azure Machine Learning Umgebungen.

1. Erstellen Sie in Ihrer lokalen Umgebung einen Ordner mit dem Namen image_build_with_reqirements, der folgende Dateien enthält:

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

   • Der requirements.txt sollte vom Flow-Ordner geerbt werden, der zur Verfolgung der Abhängigkeiten des Flows verwendet wurde.

   • Der Inhalt von Dockerfile ähnelt dem folgenden Text:

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

2. Ersetzen Sie den Abschnitt environment in der Datei deployment definition yaml durch den folgenden Inhalt:

   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
   

Verwenden des FastAPI-Bereitstellungsmoduls (Vorschau)

Standardmäßig verwendet der Prompt Flow die FLASK-Serving-Engine. Ab der Version 1.10.0 des Prompt Flow SDK wird der auf FastAPI basierende Servicemotor unterstützt. Sie können fastapi-Dienstmodul verwenden, indem Sie eine Umgebungsvariable PROMPTFLOW_SERVING_ENGINEangeben.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Konfigurieren der Parallelität für die Bereitstellung

Bei der Bereitstellung des Flows in der Onlinebereitstellung gibt es zwei Umgebungsvariablen, die Sie für Parallelität konfigurieren: PROMPTFLOW_WORKER_NUM und PROMPTFLOW_WORKER_THREADS. Darüber hinaus müssen Sie auch den Parameter max_concurrent_requests_per_instance festlegen.

Im Anschluss sehen Sie ein Beispiel für die Konfiguration in der Datei deployment.yaml:

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

• PROMPTFLOW_WORKER_NUM: Dieser Parameter bestimmt die Anzahl der Worker (Prozesse), die in einem Container gestartet werden. Der Standardwert entspricht der Anzahl der CPU-Kerne, und der Höchstwert ist das Doppelte der CPU-Kerne.

• PROMPTFLOW_WORKER_THREADS: Dieser Parameter bestimmt die Anzahl der Threads, die in einem Worker gestartet werden. Der Standardwert ist 1.

  Hinweis

  Stellen Sie beim Festlegen von PROMPTFLOW_WORKER_THREADS auf einen höheren Wert als 1 sicher, dass der Flowcode threadsicher ist.

• max_concurrent_requests_per_instance: Die maximale Anzahl gleichzeitiger Anforderungen pro Instanz, die für die Bereitstellung zulässig sind. Der Standardwert ist 10.

  Der vorgeschlagene Wert für max_concurrent_requests_per_instance hängt von der Anforderungszeit ab:

  • Wenn die Anforderungszeit mehr als 200 ms beträgt, legen Sie max_concurrent_requests_per_instance auf PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS fest.
  • Wenn Ihre Anforderungszeit weniger als oder gleich 200 ms ist, setzen Sie max_concurrent_requests_per_instance auf (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. Dies kann den Gesamtdurchsatz verbessern, da einige Anforderungen auf der Serverseite in die Warteschlange gestellt werden können.
  • Wenn Sie regionsübergreifende Anforderungen senden, können Sie den Schwellenwert von 200 ms in 1 s ändern.

Bei der Optimierung der obigen Parameter müssen Sie die folgenden Metriken überwachen, um eine optimale Leistung und Stabilität zu gewährleisten:

• CPU-/Speicherauslastung der Instanz in dieser Bereitstellung
• Von „200“ abweichende Antworten (4xx, 5xx)
  • Wenn Sie eine Antwort vom Typ „429“ erhalten, bedeutet dies in der Regel, dass Sie die Parallelitätseinstellungen gemäß dem obigen Leitfaden erneut optimieren oder die Bereitstellung skalieren müssen.
• Azure OpenAI-Drosselungsstatus

Überwachen von Endpunkten

Sammeln allgemeiner Metriken

Sie können allgemeinen Metriken der Onlinebereitstellung anzeigen (Anforderungsnummern, Anforderungslatenz, Netzwerkbytes, CPU/GPU/Datenträger/Arbeitsspeicherauslastung usw.).

Erfassen von Ablaufverfolgungsdaten und Systemmetriken während der Ableitungszeit

Sie können auch Ablaufverfolgungsdaten und bereitstellungsspezifische Bereitstellungsmetriken (Tokenverbrauch, Ablaufwartezeit usw.) während der Rückschlusszeit auf arbeitsbereichsverknüpfte Application Insights sammeln, indem Sie eine Eigenschaft app_insights_enabled: true in der Yaml-Bereitstellungsdatei hinzufügen. Verstehen Sie den Tracing und die Metriken der Prompt-Flow-Bereitstellung besser.

Spezifische Metriken und Ablaufverfolgungen von Prompt Flow können für andere Application Insights als den verknüpften Arbeitsbereich angegeben werden. Sie können eine Umgebungsvariable in der Yaml-Bereitstellungsdatei wie folgt angeben. Sie finden die Verbindungszeichenfolge Ihrer Application Insights auf der Seite "Übersicht" im Azure-Portal.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Häufige Fehler

Problem beim Timeout der Upstream-Anforderung beim Verbrauch des Endpunkts

Dieser Fehler wird in der Regel durch Timeout verursacht. Standardmäßig ist request_timeout_ms auf 5000 festgelegt. Sie können maximal 5 Minuten (also 300.000 ms) angeben. Im folgenden Beispiel wird gezeigt, wie Sie das Anforderungstimeout in der Yaml-Bereitstellungsdatei angeben. Weitere Informationen zum Bereitstellungsschema finden Sie hier.

request_settings:
  request_timeout_ms: 300000

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

Nächste Schritte

• Informationen zum Schema für verwaltete Onlineendpunkte und Schema für verwaltete Onlinebereitstellungen
• Erfahren Sie mehr darüber, wie man den Endpunkt in UI testet und den Endpunkt überwacht.
• Mehr erfahren über die Problembehandlung bei verwalteten Onlineendpunkten.
• Fehlerbehebung bei der Bereitstellung von Prompt-Flows
• Wenn Sie Ihren Flow verbessert haben und die verbesserte Version mit einer sicheren Rolloutstrategie bereitstellen möchten, finden Sie weitere Informationen unter Sicherer Rollout für Onlineendpunkte.
• Erfahren Sie mehr über Bereitstellungsabläufe auf andere Plattformen, wie zum Beispiel einen lokalen Entwicklungsdienst, Docker-Container, Azure-App-Service usw.