Déployer un flux sur un point de terminaison en ligne pour l’inférence en temps réel avec l’interface CLI

Dans cet article, vous apprendrez à déployer votre flux sur un point de terminaison en ligne géré ou un point de terminaison en ligne Kubernetes pour l’inférence en temps réel à l’aide de l’interface de ligne de commande Azure Machine Learning v2.

Avant de commencer, assurez-vous que vous testez correctement votre flux et êtes sûr qu’il est prêt à être déployé en production. Pour en savoir plus sur le test de votre flux, consultez tester votre flux. Après avoir testé votre flux, vous allez apprendre à créer un point de terminaison et un déploiement en ligne managés et à utiliser le point de terminaison pour l’inférence en temps réel.

• Cet article explique comment utiliser l’expérience CLI.
• Le sdk Python n'est pas abordé dans cet article. Consultez l’exemple de bloc-notes GitHub à la place. Pour utiliser le Kit de développement logiciel (SDK) Python, vous devez disposer du sdk Python v2 pour Azure Machine Learning. Pour plus d’informations, consultez Installer le sdk Python v2 pour Azure Machine Learning.

Conditions préalables

• Le Azure CLI et l’extension Azure Machine Learning au Azure CLI. Pour plus d’informations, consultez Installer, configurer et utiliser l’interface CLI (v2).
• Espace de travail Azure Machine Learning. Si vous n’en avez pas, suivez les étapes décrites dans le guide de démarrage rapide : Créer un article sur les ressources de l’espace de travail pour en créer un.
• Les contrôles d'accès en fonction d'un rôle Azure (Azure RBAC) permettent d'accorder l'accès aux opérations dans Azure Machine Learning. Pour effectuer les étapes décrites dans cet article, votre compte d’utilisateur doit être affecté au rôle propriétaire ou contributeur de l’espace de travail Azure Machine Learning, ou à un rôle personnalisé autorisant « Microsoft. MachineLearningServices/workspaces/onlineEndpoints/". Si vous utilisez Studio pour créer et gérer des points de terminaison et des déploiements en ligne, vous avez besoin d’une autre autorisation « Microsoft. Ressources/déploiements/écriture » du propriétaire du groupe de ressources. Pour plus d’informations, consultez Manage d’accès à un espace de travail Azure Machine Learning.

Allocation de quota de machines virtuelles pour le déploiement

Pour les points de terminaison en ligne managés, Azure Machine Learning réserve 20% de vos ressources de calcul pour effectuer des mises à niveau. Par conséquent, si vous demandez un nombre donné d’instances dans un déploiement, vous devez disposer d’un quota de ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU pour éviter d’obtenir une erreur. Par exemple, si vous demandez 10 instances d’une machine virtuelle Standard_DS3_v2 (qui comprend quatre cœurs) dans un déploiement, vous devez disposer d’un quota pour 48 cœurs (12 instances quatre cœurs) disponibles. Pour afficher vos augmentations d’utilisation et de demande de quota, consultez Afficher votre utilisation et vos quotas dans le portail Azure.

Préparer le flux pour le déploiement

Chaque flux a un dossier qui contient des codes, des invites, une définition et d’autres artefacts du flux. Si vous développez votre flux à l’aide de l’interface utilisateur, vous pouvez télécharger le dossier de flux à partir de la page de détails du flux. Si vous développez votre flux à l’aide de l’interface CLI ou du SDK, vous disposez déjà du dossier de flux.

Cet article utilise le flux d'exemple « basic-chat » comme exemple de déploiement sur un point de terminaison géré en ligne d'Azure Machine Learning.

Définir l’espace de travail par défaut

Utilisez les commandes suivantes pour définir l’espace de travail et le groupe de ressources par défaut pour l’interface CLI.

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

Inscrire le flux en tant que modèle (facultatif)

Pour le déploiement en ligne, vous pouvez soit référencer un modèle enregistré, soit spécifier directement le chemin d’accès au modèle (indiquant d’où téléverser les fichiers du modèle). Inscrivez le modèle et spécifiez le nom et la version du modèle dans la définition de déploiement. Utilisez le formulaire model:<model_name>:<version>.

L’exemple suivant montre une définition de modèle pour un flux de conversation.

$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

Utilisez az ml model create --file model.yaml pour inscrire le modèle dans votre espace de travail.

Définir le point de terminaison

Pour définir un point de terminaison, spécifiez les valeurs suivantes :

• Nom du point de terminaison : nom du point de terminaison. Il doit être unique dans la région Azure. Pour plus d’informations sur les règles d’affectation de noms, consultez les limites de point de terminaison.
• Mode d’authentification : méthode d’authentification pour le point de terminaison. Choisissez entre l’authentification basée sur des clés et Azure Machine Learning l’authentification basée sur les jetons. Une clé n’expire pas, mais un jeton expire. Pour plus d’informations sur l’authentification, consultez S’authentifier auprès d’un point de terminaison en ligne.
• Si vous le souhaitez, ajoutez une description et des balises à votre point de terminaison.
• Si vous souhaitez déployer sur un cluster Kubernetes (cluster AKS ou Arc activé) que vous attachez à votre espace de travail, vous pouvez déployer le flux en tant que point de terminaison en ligne Kubernetes.

L’exemple suivant montre une définition de point de terminaison qui utilise l’identité affectée par le système par défaut.

$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

Si vous créez un point de terminaison en ligne Kubernetes, vous devez spécifier les attributs suivants :

Pour plus de configurations de point de terminaison, consultez le schéma de point de terminaison en ligne managé.

Utiliser l'identification affectée par l'utilisateur

Par défaut, lorsque vous créez un point de terminaison en ligne, le système génère automatiquement une identité managée affectée par le système pour vous. Vous pouvez également spécifier une identité managée assignée par l’utilisateur existante pour le point de terminaison.

Pour utiliser une identité affectée par l’utilisateur, spécifiez les attributs suivants dans le endpoint.yaml fichier :

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Spécifiez également le Client ID de l'identité managée affectée par l'utilisateur sous environment_variables dans le fichier deployment.yaml, comme illustré dans l'exemple suivant. Vous trouverez le Client ID dans le Overview de l’identité managée dans le portail Azure.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Définir le déploiement

Un déploiement est un ensemble de ressources requises pour héberger le modèle qui effectue l’inférence réelle.

L’exemple suivant montre une définition de déploiement. La model section fait référence au modèle de flux inscrit. Vous pouvez également spécifier le chemin du modèle de flux en ligne.

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

Si vous créez un déploiement en ligne Kubernetes, spécifiez les attributs suivants :

Déployer votre point de terminaison en ligne sur Azure

Pour créer le point de terminaison dans le cloud, exécutez le code suivant :

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

Pour créer le déploiement nommé blue sous le point de terminaison, exécutez le code suivant :

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

Vérifier l’état du point de terminaison et du déploiement

Pour vérifier l’état du point de terminaison, exécutez le code suivant :

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

Pour vérifier l’état du déploiement, exécutez le code suivant :

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

Utiliser l'endpoint pour évaluer les données avec votre modèle

Créez un sample-request.json fichier :

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

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

Vous pouvez également appeler le point de terminaison à l’aide d’un client HTTP, par curlexemple :

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":  []}'

Récupérez votre clé de point de terminaison et l'URI de votre point de terminaison à partir de l'espace de travail Azure Machine Learning dans Points de terminaison>Consommer>Informations de consommation de base.

Configurations avancées

Déployer avec des connexions différentes de celles du développement du flux

Vous pouvez vouloir remplacer les connexions du flux lors du déploiement.

Par exemple, si votre fichier flow.dag.yaml utilise une connexion nommée my_connection, vous pouvez la remplacer en ajoutant des variables d’environnement du fichier yaml de déploiement comme suit :

Option 1 : remplacer le nom de la connexion

environment_variables:
  my_connection: <override_connection_name>

Si vous souhaitez remplacer un champ spécifique de la connexion, vous pouvez le remplacer en ajoutant des variables d’environnement avec le modèle <connection_name>_<field_name>d’affectation de noms. Par exemple, si votre flux utilise une connexion nommée my_connection avec une clé de configuration appelée chat_deployment_name, le serveur principal de service tente de récupérer chat_deployment_name à partir de la variable d’environnement « MY_CONNECTION_CHAT_DEPLOYMENT_NAME » par défaut. Si la variable d’environnement n’est pas définie, elle utilise la valeur d’origine de la définition de flux.

Option 2 : remplacer en faisant référence à la ressource

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

Déployer avec un environnement personnalisé

Cette section vous montre comment utiliser un contexte de build Docker pour spécifier l’environnement de votre déploiement, en supposant que vous connaissez Docker et Azure Machine Learning environnements.

Les images du runtime de Prompt flow sont figées et ne reçoivent plus de mises à jour de sécurité ni de paquets. La latest balise de l’exemple suivant n’indique pas que l’image reçoit les mises à jour. Utilisez cet exemple uniquement pour gérer un déploiement existant pendant la planification de sa migration.

1. Dans votre environnement local, créez un dossier nommé image_build_with_requirements qui contient les fichiers suivants :

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

Configurer la concurrence pour le déploiement

Lorsque vous déployez votre flux en ligne, configurez deux variables d’environnement pour la simultanéité : PROMPTFLOW_WORKER_NUM et PROMPTFLOW_WORKER_THREADS. Vous devez également définir le max_concurrent_requests_per_instance paramètre.

L’exemple suivant montre comment configurer ces paramètres dans le deployment.yaml fichier.

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

• PROMPTFLOW_WORKER_NUM: ce paramètre définit le nombre de processus qui démarrent au sein d’un conteneur. La valeur par défaut est égale au nombre de cœurs du processeur, et la valeur maximale est égale à deux fois le nombre de cœurs du processeur.

• PROMPTFLOW_WORKER_THREADS : ce paramètre définit le nombre de threads qui démarrent dans un seul worker. La valeur par défaut est 1.

  Note

  Lorsque vous définissez PROMPTFLOW_WORKER_THREADS sur une valeur supérieure à 1, vérifiez que votre code de flux est thread-safe.

• max_concurrent_requests_per_instance : nombre maximal de requêtes simultanées par instance autorisées pour le déploiement. La valeur par défaut est 10.

  La valeur max_concurrent_requests_per_instance suggérée dépend de l’heure de votre demande :

  • Si la durée de votre demande est supérieure à 200 ms, définissez max_concurrent_requests_per_instance à PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS.
  • Si le temps de votre demande est inférieur ou égal à 200 ms, définissez max_concurrent_requests_per_instance à (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. Ce paramètre peut améliorer le débit total en permettant à certaines demandes de file d’attente côté serveur.
  • Si vous envoyez des demandes interrégions, vous pouvez modifier le seuil de 200 ms à 1 s.

Lors du réglage de ces paramètres, surveillez les métriques suivantes pour garantir des performances et une stabilité optimales :

• Utilisation du processeur et de la mémoire de l’instance pour ce déploiement
• Réponses de type non-200 : (4xx, 5xx)
  • Si vous recevez une réponse 429, ce code d’état indique généralement que vous devez soit rétablir vos paramètres de concurrence en suivant le guide précédent, soit mettre à l’échelle votre déploiement.
• État de limitation Azure OpenAI

Surveiller les points de terminaison

Collecter des métriques générales

Vous pouvez afficher les métriques générales du déploiement en ligne (numéros de requête, latence de requête, octets réseau, utilisation du processeur/GPU/disque/mémoire, etc.) .

Collecter les données de suivi et les métriques système pendant le temps d’inférence

Vous pouvez collecter les données de traçage et les métriques spécifiques au modèle de déploiement du flux de requête (consommation de tokens, latence du flux, etc.) pendant l'inférence dans Application Insights lié à l'espace de travail en ajoutant une propriété app_insights_enabled: true dans le fichier YAML de déploiement. Pour plus d'informations, veuillez consulter la section Traçage et métriques du modèle de déploiement du flux de requête.

Vous pouvez envoyer les métriques et les traces spécifiques au flux de requête vers une autre instance d'Application Insights que celle liée à l'espace de travail. Vous pouvez spécifier une variable d’environnement dans le fichier yaml de déploiement comme suit. Vous trouverez la chaîne de connexion de votre Application Insights dans la page Vue d’ensemble dans Azure portail.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Erreurs courantes

Problème de délai d’expiration des requêtes en amont lors de l’utilisation du point de terminaison

Cette erreur se produit généralement en raison d’un délai d’expiration. Par défaut, la request_timeout_ms valeur est de 5 000 millisecondes. Vous pouvez le configurer jusqu’à 5 minutes, soit 300 000 millisecondes. L’exemple suivant montre comment spécifier le délai d’expiration de la requête dans le fichier YAML de déploiement. Pour plus d’informations sur le schéma de déploiement, consultez Schéma de déploiement en ligne managé.

request_settings:
  request_timeout_ms: 300000

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

Étapes suivantes

• En savoir plus sur le schéma de point de terminaison en ligne managé et le schéma de déploiement en ligne managé.
• Découvrez comment tester le point de terminaison dans l’interface utilisateur et surveiller le point de terminaison.
• En savoir plus sur la résolution des problèmes de points de terminaison en ligne managés.
• Résoudre les problèmes des déploiements Prompt Flow.
• Pour déployer une version améliorée de votre flux à l’aide d’une stratégie de déploiement sécurisée, consultez Déploiement sécurisé pour les points de terminaison en ligne.
• En savoir plus sur les flux deploy vers d’autres plateformes, comme un service de développement local, un conteneur Docker, un service APP Azure, etc.