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 managed online endpoint ou un Kubernetes online endpoint pour l'inférence en temps réel avec l’interface CLI d'Azure Machine Learning v2.

Avant de commencer, assurez-vous que vous avez testé votre flux correctement 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 SDK Python, vous devez disposer du kit 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/gérer des points de terminaison/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 certain nombre d’instances dans un déploiement, vous devez disposer d’un quota disponible 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/invites, une 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 Kit de développement logiciel (SDK), vous devez déjà disposer 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)

Dans le déploiement en ligne, vous pouvez faire référence à un modèle enregistré ou spécifier le chemin d’accès du modèle (où se trouvent les fichiers de modèle à télécharger) directement dans le texte. Il est recommandé d’inscrire 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 inscrire 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 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, vous pouvez ajouter une description et des balises à votre point de terminaison.
• Si vous le souhaitez, vous pouvez ajouter une description et des balises à votre point de terminaison.
• Si vous souhaitez déployer dans un cluster Kubernetes (cluster AKS ou activé pour Arc) qui est attaché à votre espace de travail, vous pouvez déployer le flux pour en faire un point de terminaison en ligne Kubernetes.

Voici un exemple de définition de point de terminaison qui utilise par défaut l’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 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, 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 assignée par l’utilisateur existante pour le point de terminaison.

Si vous souhaitez utiliser l’identité affectée par l’utilisateur, vous pouvez spécifier les attributs suivants dans :endpoint.yaml

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

En outre, vous devez également spécifier l'identité Client ID assignée par l'utilisateur sous environment_variables la deployment.yaml comme suit. Vous trouverez le Client ID dans le Overview de l’identité managée dans Azure portail.

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.

Voici un exemple de définition de déploiement dans lequel 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, vous devez spécifier 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

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 Endpoints>Consume> Informations de consommationbasic.

Configurations avancées

Déployer avec différentes connexions à partir du développement de flux

Vous pouvez vouloir modifier 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.

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

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

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

   • Le Dockerfile contenu est similaire au texte suivant :

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

2. remplacez la section d’environnement dans le 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 déploiement FastAPI (aperçu)

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 PROMPTFLOW_SERVING_ENGINEd’environnement.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

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

Lorsque vous déployez votre flux en ligne, il existe deux variables d’environnement que vous configurez pour la parallélisation : PROMPTFLOW_WORKER_NUM et PROMPTFLOW_WORKER_THREADS. En outre, vous devez également définir le max_concurrent_requests_per_instance paramètre.

Voici un exemple de configuration 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étermine le nombre de workers (processus) qui seront démarrés dans un conteneur. La valeur par défaut est égale au nombre de cœurs d’UC, et la valeur maximale est deux fois le nombre de cœurs d’UC.

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

  Note

  Lorsque vous définissez PROMPTFLOW_WORKER_THREADS 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. Cela peut améliorer le débit total en permettant à certaines requêtes d’être mises en 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 des paramètres ci-dessus, vous devez surveiller les métriques suivantes pour garantir des performances et une stabilité optimales :

• Utilisation du processeur et de la mémoire de l'instance dans ce déploiement
• Réponses de type non-200 : (4xx, 5xx)
  • Si vous recevez une réponse 429, cela indique généralement que vous devez soit ajuster vos paramètres de concurrence en suivant le guide ci-dessus, soit mettre à l’échelle votre déploiement.
• Azure état de limitation 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 le suivi et les métriques du déploiement de flux de commandes.

Les métriques et traces spécifiques du 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 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 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, la request_timeout_ms valeur 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é.
• 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 liés aux déploiements de flux d’invite.
• Une fois que 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é, 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.