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 allez apprendre à déployer votre flux sur un point de terminaison en ligne managé ou un point de terminaison en ligne Kubernetes pour une utilisation en temps réel de l’inférence avec l’interface CLI Azure Machine Learning v2.

Avant de commencer, assurez-vous que vous avez correctement testé votre flux et 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 Kit de développement logiciel (SDK) Python n’est pas abordé dans cet article. Consultez l’exemple de notebook GitHub à la place. Pour utiliser le SDK Python, vous devez disposer du SDK Python v2 pour Azure Machine Learning. Pour en savoir plus, consultez Installer le SDK Python v2 pour Azure Machine Learning.

Prérequis

• Azure CLI et l’extension Azure Machine Learning pour Azure CLI. Pour plus d’informations, consultez Installer, configurer et utiliser l’interface CLI (v2).
• Un espace de travail Azure Machine Learning. Si vous n’en avez pas, procédez comme suit dans le Guide de démarrage rapide : Créer des ressources d’espace de travail pour en créer un.
• Les contrôles d’accès en fonction du rôle Azure (Azure RBAC) sont utilisés pour accorder l’accès aux opérations dans Azure Machine Learning. Pour que vous puissiez effectuer les étapes décrites dans cet article, votre compte d’utilisateur doit avoir le rôle propriétaire ou contributeur sur l’espace de travail Azure Machine Learning ou un rôle personnalisé autorisant « Microsoft.MachineLearningServices/workspaces/onlineEndpoints/ ». Si vous utilisez Studio pour créer/gérer des points de terminaison/déploiements en ligne, le propriétaire du groupe de ressources devra vous assigner une autorisation « Microsoft.Resources/deployments/write » supplémentaire. Pour plus d’informations, consultez Gérer l’accès à un espace de travail Azure Machine Learning.

Allocation de quota du nombre 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 aux 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 (fournie avec quatre cœurs) dans un déploiement, vous devez disposer d’un quota de 48 cœurs (12 instances de quatre cœurs) disponibles. Pour afficher votre utilisation et demander des augmentations de quota, consultez Afficher votre utilisation et vos quotas dans le Portail Azure.

Préparer le flux pour le déploiement

Chaque flux aura un dossier qui contient les codes/invites, la définition et d’autres artefacts du flux. Si vous avez développé votre flux avec l’interface utilisateur, vous pouvez télécharger le dossier de flux à partir de la page de détails du flux. Si vous avez développé votre flux avec l’interface CLI ou le SDK, vous devez déjà disposer du dossier de flux.

Cet article utilise l’exemple de flux « basic-chat » comme exemple de déploiement sur le point de terminaison en ligne managé 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>

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

Dans le déploiement en ligne, vous pouvez soit faire référence à un modèle inscrit, soit spécifier le chemin du modèle (où charger les fichiers de modèle) inline. Il est recommandé d’enregistrer le modèle et de spécifier le nom et la version du modèle dans la définition de déploiement. Utilisez le formulaire model:<model_name>:<version>.

Voici un exemple de 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 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

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

Définir le point de terminaison

Pour définir un point de terminaison, vous devez spécifier :

• Nom du point de terminaison : Nom du point de terminaison. Il doit être unique au sein de la région Azure. Pour plus d’informations sur les règles de nommage, consultez limites de point de terminaison.
• Mode d’authentification : méthode d’authentification pour le point de terminaison. Choisissez entre l’authentification basée sur une clé et celle basée sur un jeton Azure Machine Learning. Une clé n’expire pas, mais un jeton expire bien. Pour plus d’informations sur l’authentification, consultez S’authentifier auprès d’un point de terminaison en ligne. Vous pouvez éventuellement ajouter une description et des étiquettes à votre point de terminaison.
• Vous pouvez éventuellement ajouter une description et des étiquettes à votre point de terminaison.
• Si vous souhaitez déployer sur un cluster Kubernetes (cluster AKS ou Arc) qui est attaché à votre espace de travail, vous pouvez déployer le flux en tant que point de terminaison en ligne Kubernetes.

Voici un exemple de définition de point de terminaison qui utilise par défaut une identité affectée par le système.

$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 supplémentaires suivants :

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

Utiliser une identité attribuée par l’utilisateur

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

Si vous souhaitez utiliser une identité attribuée par l’utilisateur, vous pouvez spécifier les attributs supplémentaires suivants dans le endpoint.yaml :

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

En outre, vous devez également spécifier la valeur Client ID de l’identité attribuée par l’utilisateur sous environment_variables et deployment.yaml comme indiqué ci-après. Vous pouvez trouver le Client ID du 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 nécessaires pour héberger le modèle qui effectue l’inférence réelle.

Voici un exemple de définition de déploiement dans lequel la section model 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, vous devez spécifier les attributs supplémentaires suivants :

Déployer votre point de terminaison en ligne dans 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érification de 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

Appeler le point de terminaison pour effectuer la notation des données avec votre modèle

Vous pouvez créer un fichier sample-request.json comme suit :

{
  "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 l’appeler avec un client HTTP, par exemple avec 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":  []}'

Vous pouvez obtenir votre clé de point de terminaison et votre URI de 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 autres que celles du développement du flux

Vous voudrez probablement remplacer les connexions du flux pendant le déploiement.

Par exemple, si votre fichier flow.dag.yaml utilise une connexion appelée my_connection, vous pouvez la remplacer en ajoutant des variables d’environnement du 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 d’affectation de noms <connection_name>_<field_name>. Par exemple, si votre flux utilise une connexion nommée my_connection avec une clé de configuration appelée chat_deployment_name, le back-end de service tentera 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, il utilisera 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 docker build pour spécifier l’environnement de votre déploiement, en supposant que vous connaissez Docker et les environnements Azure Machine Learning.

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

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

   • requirements.txt doit être hérité du dossier de flux, qui a été utilisé pour suivre les dépendances du flux.

   • Le contenu Dockerfile est le suivant :

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

2. Remplacez la section environnement du fichier yaml de définition de déploiement par le contenu suivant :

   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
   

Utiliser le moteur de service FastAPI (préversion)

Par défaut, le service de flux d’invite utilise le moteur de service FLASK. À partir du Kit de développement logiciel (SDK) de flux d’invite version 1.10.0, le moteur de service basé sur FastAPI est pris en charge. Vous pouvez utiliser le fastapi moteur de service en spécifiant une variable d’environnement PROMPTFLOW_SERVING_ENGINE.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configurer l’accès concurrentiel pour le déploiement

Lors du déploiement de votre flux vers un déploiement en ligne, vous devez configurer deux variables d’environnement pour l’accès concurrentiel : PROMPTFLOW_WORKER_NUM et PROMPTFLOW_WORKER_THREADS. En outre, vous allez également devoir définir le paramètre max_concurrent_requests_per_instance.

Voici un exemple de configuration du fichier deployment.yaml.

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étermine le nombre de Workers (processus) qui va être démarré dans un conteneur. La valeur par défaut est égale au nombre de cœurs de processeur, tandis que la valeur maximale est le double du nombre de cœurs de processeur.

• PROMPTFLOW_WORKER_THREADS : ce paramètre détermine le nombre de threads qui va être démarré dans un Worker. La valeur par défaut est 1.

  Remarque

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

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

  La valeur suggérée de max_concurrent_requests_per_instance dépend de la durée de votre requête :

  • Si la durée de votre requête est supérieure à 200 ms, définissez la valeur de max_concurrent_requests_per_instance sur PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS.
  • Si la durée de votre requête est inférieure à 200 ms, définissez la valeur de max_concurrent_requests_per_instance sur (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. Cela peut améliorer le débit total, en permettant la miss en file d’attente côté serveur de certaines requêtes.
  • Si vous envoyez des requêtes interrégions, vous pouvez modifier le seuil de 200 ms à 1 s.

Lors du réglage des paramètres ci-dessus, vous devez surveiller les métriques suivantes pour garantir des niveaux de performance et une stabilité optimales :

• Utilisation du processeur/de la mémoire par l’instance de ce déploiement
• Réponses autres que 200 (4xx, 5xx)
  • Si vous recevez une réponse 429, cela indique généralement que vous devez procéder à un réajustement de vos paramètres d’accès concurrentiel en suivant le guide ci-dessus ou mettre à l’échelle votre déploiement.
• État de la 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 également collecter des données de suivi et des métriques spécifiques au déploiement de flux d’invite (consommation de jetons, latence de flux, etc.) pendant l’inférence à l’espace de travail lié à Application Insights en ajoutant une propriété app_insights_enabled: true dans le fichier yaml de déploiement. En savoir plus sur trace et les métriques du déploiement de flux d’invite.

Les métriques et les traces spécifiques au flux d'invite peuvent être spécifiées à d'autres Application Insights que celui lié à l'espace de travail. Vous pouvez spécifier une variable d’environnement dans le fichier yaml de déploiement comme suit. Vous pouvez trouver la chaîne de connexion de votre Application Insights dans la page Présentation du Portail Microsoft Azure.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Erreurs courantes

Problème de délai d’expiration de la demande en amont lors de la consommation du point de terminaison

Cette erreur est généralement due au délai d’expiration. Par défaut, le request_timeout_ms est 5000. Vous pouvez spécifier au maximum 5 minutes, soit 300 000 ms. Voici un exemple montrant comment spécifier le délai d’expiration de la requête dans le fichier yaml de déploiement. En savoir plus sur le schéma de déploiement ici.

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é.
• En savoir plus sur la façon de tester le point de terminaison dans l’interface utilisateur et de surveiller le point de terminaison.
• En savoir plus sur la manière de résoudre les problèmes liés aux points de terminaison en ligne managés.
• Résolvez les problèmes de déploiements de flux d’invite.
• Lorsque vous avez amélioré votre flux et que vous souhaitez déployer la version améliorée avec une stratégie de déploiement sécurisé, vous pouvez vous référer à Déploiement sécurisé pour les points de terminaison en ligne.
• En savoir plus sur déployer des flux sur d’autres plateformes, telles qu’un service de développement local, un conteneur Docker, un service Azure APP, etc.