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

In diesem Artikel erfahren Sie, wie Sie Ihren Workflow auf einem verwalteten Online-Endpunkt oder einem Kubernetes-Onlineendpunkt für die Echtzeitanalyse mit der Azure Machine Learning v2 CLI bereitstellen.

Bevor Sie beginnen, stellen Sie sicher, dass Sie ihren Flow ordnungsgemäß getestet haben, und fühlen Sie sich sicher, dass er bereit ist, in der Produktion bereitgestellt zu werden. Weitere Informationen zum Testen Ihres Flusses finden Sie unter "Testen Des Flusses". Nach dem Testen Ihres 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/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.

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, Definitionen und andere Artefakte des Flusses enthält. Wenn Sie Ihren Fluss mit ui entwickelt haben, können Sie den Flussordner von der Seite mit den Flussdetails herunterladen. Wenn Sie Ihren Flow mit CLI oder SDK entwickelt haben, sollten Sie den Flussordner bereits haben.

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. Es wird empfohlen, das Modell zu registrieren und den Modellnamen und die Version in der Bereitstellungsdefinition anzugeben. Verwenden Sie das Formular model:<model_name>:<version>.

Nachfolgend sehen Sie ein Modelldefinitionsbeispiel 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

Zum Definieren eines Endpunkts müssen Sie Folgendes angeben:

• 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. Optional können Sie Ihrem Endpunkt eine Beschreibung und Tags hinzufügen.
• Optional können Sie Ihrem Endpunkt eine Beschreibung und Tags 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.

Nachfolgend sehen Sie ein Endpunktdefinitionsbeispiel, das 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, wird standardmäßig automatisch eine systemseitig zugewiesene verwaltete Identität für Sie generiert. Sie können auch eine vorhandene vom Benutzer zugewiesene verwaltete Identität für den Endpunkt angeben.

Wenn Sie die vom Benutzer zugewiesene Identität verwenden möchten, können Sie die folgenden Attribute in der endpoint.yamlDatei angeben:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Außerdem müssen Sie Client ID der benutzerseitig zugewiesenen 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>

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.

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 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 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.

Sie können eine sample-request.json Datei wie folgt 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 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 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 Dockerfile Inhalt ä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 "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 FLASK-Portionsmodul. Ab der Eingabeaufforderungsfluss-SDK-Version 1.10.0 wird die FastAPI-basierte Dienst-Engine unterstützt. Sie können das Bereitstellungsmodul fastapi verwenden, indem Sie eine Umgebungsvariable PROMPTFLOW_SERVING_ENGINE angeben.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Konfigurieren der Gleichzeitigkeit für die Bereitstellung

Bei der Bereitstellung des Flows in der Online-Bereitstellung gibt es zwei Umgebungsvariablen, die Sie für Parallelität konfigurieren: PROMPTFLOW_WORKER_NUM und PROMPTFLOW_WORKER_THREADS. Außerdem müssen Sie den max_concurrent_requests_per_instance Parameter festlegen.

Im Folgenden finden Sie ein Beispiel für die Konfiguration in der deployment.yaml Datei.

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 ist gleich der Anzahl der CPU-Kerne, und der Maximalwert ist doppelt so viele CPU-Kerne.

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

  Hinweis

  Wenn Sie PROMPTFLOW_WORKER_THREADS auf einen Wert größer als 1 festlegen, 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. Dies kann den Gesamtdurchsatz verbessern, indem 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 oben genannten 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 429-Antwort erhalten, weist dies in der Regel darauf hin, dass Sie ihre Parallelitätseinstellungen nach dem obigen 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 auch Ablaufverfolgungsdaten und bereitstellungsspezifische Bereitstellungsmetriken (Token-Verbrauch, 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. Erfahren Sie mehr über die Ablaufverfolgung und Metriken der Bereitstellung von Prompt-Flows.

Die Spezifischen Metriken und Ablaufverfolgung der Aufforderung können für andere Application Insights angegeben werden, die nicht mit dem verknüpften Arbeitsbereich verknüpft sind. 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 der request_timeout_ms Standardwert 5000. Sie können maximal 5 Minuten angeben, was 300.000 ms beträgt. 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

• 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.
• Nachdem Sie Ihren Fluss verbessert haben und die verbesserte Version mit sicherer Rolloutstrategie bereitstellen möchten, lesen Sie "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.