Bereitstellen eines Flusses an einen Onlineendpunkt für die Echtzeit-Ableitung mit CLI

In diesem Artikel erfahren Sie, wie Sie Ihren Flow für einen verwalteten Online-Endpunkt oder einen Kubernetes-Online-Endpunkt bereitstellen, um ihn mithilfe der Azure Machine Learning CLI v2 für die Echtzeitinferenz zu verwenden.

Bevor Sie beginnen, stellen Sie sicher, dass Sie den Fluss ordnungsgemäß testen und sicher sind, dass er für die Bereitstellung in der Produktion bereit ist. Weitere Informationen zum Testen Ihres Flusses finden Sie unter "Testen Des Flusses". Nach dem Testen des Ablaufs erfahren Sie, wie Sie verwaltete Onlineendpunkte und -bereitstellungen erstellen und wie Sie den Endpunkt für die Echtzeit-Ableitung verwenden.

• In diesem Artikel wird beschrieben, wie Sie die CLI-Erfahrung 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 keins haben, führen Sie die Schritte in der Schnellstartanleitung aus: Erstellen eines Arbeitsbereichsressourcenartikels , um einen 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 Berechtigungen für „Microsoft.MachineLearningServices/workspaces/onlineEndpoints/“ zulässt. Wenn Sie Studio zum Erstellen und Verwalten von Onlineendpunkten und 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.

Kontingentzuweisung 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 10 Instanzen einer Standard_DS3_v2 VM (die mit vier Kernen enthalten ist) in einer Bereitstellung anfordern, sollten Sie ein Kontingent für 48 Kerne (12 Instanzen mit vier Kernen) verfügbar haben. Um Ihr Nutzungs- und Anforderungskontingent anzuzeigen und Erhöhungen zu beantragen, siehe View your usage and quotas in the Azure portal.

Bereiten Sie den Workflow für die Bereitstellung vor

Jeder Fluss verfügt über einen Ordner, der Codes, Eingabeaufforderungen, Definition und andere Artefakte des Flusses enthält. Wenn Sie Ihren Fluss mithilfe der Benutzeroberfläche entwickeln, können Sie den Flussordner von der Flussdetailseite herunterladen. Wenn Sie Ihren Fluss mithilfe von CLI oder SDK entwickeln, verfügen Sie bereits über den Flussordner.

In diesem Artikel wird der Beispiel-Flow „basic-chat“ als Beispiel für die Bereitstellung eines von Azure Machine Learning verwalteten Onlineendpunkts verwendet.

Standardarbeitsbereich festlegen

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>

Registrieren des Flusses als Modell (optional)

In der Onlinebereitstellung können Sie entweder auf ein registriertes Modell verweisen oder den Modellpfad (von dem aus die Modelldateien hochgeladen werden sollen) inline angeben. Registrieren Sie das Modell, und geben Sie den Modellnamen und die Version in der Bereitstellungsdefinition an. Verwenden Sie das Formular model:<model_name>:<version>.

Das folgende Beispiel zeigt eine Modelldefinition für einen Chatfluss.

$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, geben Sie die folgenden Werte an:

• Endpunktname: Der Name des Endpunkts. Er 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, aber ein Token läuft ab. Weitere Informationen zur Authentifizierung finden Sie unter Authentifizieren bei einem Onlineendpunkt. Fügen Sie optional eine Beschreibung und Tags zu Ihrem Endpunkt hinzu.
• Fügen Sie optional eine Beschreibung und Tags zu Ihrem Endpunkt hinzu.
• Wenn Sie für einen Kubernetes-Cluster (AKS oder Arc-fähigen Cluster), den Sie mit Ihrem Arbeitsbereich verbinden, bereitstellen möchten, können Sie den Fluss als Kubernetes-Online-Endpunkt bereitstellen.

Das folgende Beispiel zeigt eine Endpunktdefinition, die standardmäßig die vom System zugewiesene Identität verwendet.

$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 verwaltetem Onlineendpunktschema.

Verwenden der vom Benutzer zugewiesenen Identität

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

Um eine vom Benutzer zugewiesene Identität zu verwenden, geben Sie die folgenden Attribute in der endpoint.yaml Datei an:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Geben Sie außerdem die Client ID der benutzerseitig zugewiesenen Identität unter environment_variables in der Datei deployment.yaml an, wie im folgenden Beispiel gezeigt. Sie finden die Client ID in der Overview verwalteten Identität im Azure-Portal.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Definieren Sie die Bereitstellung

Bei einer Bereitstellung handelt es sich um eine Reihe von Ressourcen, die für das Hosten des Modells erforderlich sind, das die tatsächliche Ableitung durchführt.

Das folgende Beispiel zeigt eine Bereitstellungsdefinition. Der model Abschnitt bezieht sich auf das registrierte Flussmodell. Sie können auch den Flussmodellpfad in 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, geben Sie die folgenden Attribute an:

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 unter dem Endpunkt benannte blue Bereitstellung zu erstellen:

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

Überprüfen Sie den Status des Endpunkts und der Bereitstellung

Führen Sie den folgenden Code aus, um den Status des Endpunkts zu überprüfen:

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

Führen Sie den folgenden Code aus, um den Status der Bereitstellung zu überprüfen:

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

Rufen Sie den Endpunkt auf, um Daten mit Ihrem Modell zu bewerten.

Erstellen einer sample-request.json Datei:

{
  "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 den Endpunkt auch mit einem HTTP-Client aufrufen, z. B. 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":  []}'

Rufen Sie Ihren Endpunktschlüssel und Ihre Endpunkt-URI aus dem Azure Machine Learning-Arbeitsbereich unter Endpunkte>Verwenden>Grundlegende Verbrauchsinformationen ab.

Erweiterte Konfigurationen

Einsatz mit verschiedenen Verbindungen aus der Ablaufentwicklung

Möglicherweise möchten Sie die Verbindungen des Flows während der Bereitstellung außer Kraft setzen.

Wenn ihre Datei flow.dag.yaml beispielsweise eine Verbindung mit dem Namen my_connectionverwendet, können Sie sie überschreiben, indem Sie Umgebungsvariablen der Bereitstellungs-Yaml 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 außer Kraft setzen möchten, können Sie außer Kraft setzen, indem Sie Umgebungsvariablen mit Benennungsmuster <connection_name>_<field_name>hinzufügen. Wenn Ihr Flow beispielsweise eine Verbindung namens my_connection mit einem Konfigurationsschlüssel namens chat_deployment_name verwendet, versucht das bereitstellende Backend 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 Flussdefinition verwendet.

Option 2: Überschreiben durch Verweis auf Objekt

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

Mit einer benutzerdefinierten Umgebung bereitstellen

In diesem Abschnitt wird gezeigt, wie Sie einen Docker-Buildkontext verwenden, um die Umgebung für Ihre Bereitstellung anzugeben, vorausgesetzt, Sie kennen Docker und Azure Machine Learning Umgebungen.

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

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

   • Die requirements.txt-Datei, die aus dem Flow-Ordner übernommen wird, erfasst die Abhängigkeiten des Flows.

   • Das Dockerfile mit einem Inhalt ähnlich dem folgenden Beispiel:

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

2. Ersetzen Sie den Abschnitt "Umgebung" in der YAML-Datei der Bereitstellungsdefinition 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 Eingabeaufforderungsflow das FLASK-Portionsmodul. Ab Prompt Flow SDK Version 1.10.0 wird das fastAPI-basierte Bereitstellungsmodul unterstützt. Sie können das fastapi Dienstmodul verwenden, indem Sie eine Umgebungsvariable PROMPTFLOW_SERVING_ENGINEangeben.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Konfigurieren der Gleichzeitigkeit für die Bereitstellung

Wenn Sie Ihren Fluss für die Onlinebereitstellung bereitstellen, konfigurieren Sie zwei Umgebungsvariablen für Parallelität: PROMPTFLOW_WORKER_NUM und PROMPTFLOW_WORKER_THREADS. Sie müssen auch den max_concurrent_requests_per_instance Parameter festlegen.

Das folgende Beispiel zeigt, wie Sie diese Einstellungen in der deployment.yaml Datei konfigurieren.

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

• PROMPTFLOW_WORKER_NUM: Dieser Parameter legt die Anzahl der Worker (Prozesse) fest, die in einem Container beginnen. Der Standardwert entspricht der Anzahl der CPU-Kerne, und der Maximalwert ist doppelt so viele CPU-Kerne.

• PROMPTFLOW_WORKER_THREADS: Dieser Parameter legt die Anzahl der Threads fest, die in einem Worker beginnen. Der Standardwert ist 1.

  Hinweis

  Wenn Sie einen Wert festlegen PROMPTFLOW_WORKER_THREADS , der größer als 1 ist, stellen Sie sicher, dass der Ablaufcode 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 max_concurrent_requests_per_instance hängt von ihrer Anforderungszeit ab:

  • Wenn die Anforderungszeit größer als 200 ms ist, setzen Sie max_concurrent_requests_per_instance auf PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS.
  • Wenn die Anforderungszeit kleiner oder gleich 200 ms ist, setzen Sie max_concurrent_requests_per_instance auf (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. Diese Einstellung kann den Gesamtdurchsatz verbessern, indem einige Anfragen auf der Serverseite in eine Warteschlange eingereiht werden.
  • Wenn Sie regionsübergreifende Anforderungen senden, können Sie den Schwellenwert von 200 ms in 1 s ändern.

Überwachen Sie bei der Optimierung dieser Parameter die folgenden Metriken, um eine optimale Leistung und Stabilität zu gewährleisten:

• CPU- und Speicherauslastung der Instanz für diese Bereitstellung
• Von „200“ abweichende Antworten (4xx, 5xx)
  • Wenn Sie eine 429-Antwort erhalten, weist dieser Statuscode in der Regel darauf hin, dass Sie ihre Parallelitätseinstellungen nach dem vorherigen Leitfaden neu konfigurieren oder ihre Bereitstellung skalieren müssen.
• Azure OpenAI-Drosselungsstatus

Überwachen von Endpunkten

Sammeln allgemeiner Metriken

Sie können allgemeine 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 Ablaufverfolgungsdaten und bereitstellungsspezifische Bereitstellungsmetriken (Token-Verbrauch, Ablaufwartezeit und mehr) 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. Weitere Informationen finden Sie unter Ablaufverfolgung und Metriken für die Bereitstellung von Prompt Flow.

Sie können für den Eingabeaufforderungsflow spezifische Metriken festlegen und die Nachverfolgung auf andere Application Insights statt auf die mit dem Arbeitsbereich verknüpfte instanzieren. 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 tritt in der Regel aufgrund eines Timeouts auf. Standardmäßig ist der request_timeout_ms Wert 5.000 Millisekunden. Sie können es bis zu 5 Minuten einrichten, was 300.000 Millisekunden beträgt. Das folgende Beispiel zeigt, wie Sie das Anforderungstimeout in der YaML-Bereitstellungsdatei angeben. Weitere Informationen zum Bereitstellungsschema finden Sie unter Verwaltetes Onlinebereitstellungsschema.

request_settings:
  request_timeout_ms: 300000

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

Nächste Schritte

• Erfahren Sie mehr über das verwaltete Onlineendpunktschema und das verwaltete Onlinebereitstellungsschema.
• Erfahren Sie mehr darüber, wie Sie den Endpunkt in der Benutzeroberfläche testen und den Endpunkt überwachen.
• Erfahren Sie mehr darüber, wie Sie verwaltete Onlineendpunkte beheben.
• Fehlerbehebung bei prompt flow-Bereitstellungen.
• Informationen zum Bereitstellen einer verbesserten Version Ihres Flusses mithilfe einer sicheren Rolloutstrategie finden Sie unter "Sicheres Rollout für Onlineendpunkte".
• Erfahren Sie mehr darüber, wie Sie Flows auf andere Plattformen bereitstellen können, wie z.B. einen lokalen Entwicklungsdienst, Docker-Container, Azure-App-Dienste usw.