Installer et exécuter des conteneurs Docker pour LUIS

Les conteneurs vous permettent d’utiliser LUIS dans votre propre environnement. Les conteneurs conviennent particulièrement bien à certaines exigences de sécurité et de gouvernance des données. Cet article explique comment télécharger, installer et exécuter un conteneur LUIS.

Le conteneur Language Understanding (LUIS) charge votre modèle Language Understanding qui a été entraîné ou publié. En tant qu’application LUIS, le conteneur Docker fournit l’accès aux prédictions de requêtes à partir des points de terminaison d’API du conteneur. Vous pouvez collecter les journaux de requête du conteneur et les charger à nouveau dans l’application Language Understanding pour améliorer la précision de prédiction de l’application.

La vidéo suivante illustre l’utilisation de ce conteneur.

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

Prérequis

Voici les prérequis à l’exécution du conteneur LUIS :

• Docker installé sur un ordinateur hôte. Vous devez configurer Docker pour permettre aux conteneurs de se connecter à Azure et de lui envoyer des données de facturation.
  • Sous Windows, vous devez également configurer Docker pour prendre en charge les conteneurs Linux.
  • Vous devez disposer d’une connaissance élémentaire des concepts liés à Docker.
• Une ressource LUIS avec le niveau tarifaire gratuit (F0) ou standard (S).
• Une application entraînée ou publiée empaquetée en tant qu’entrée montée dans le conteneur avec son ID d’application associé. Vous pouvez obtenir le fichier empaqueté à partir du portail LUIS ou des API de création. Si vous obtenez des applications empaquetées LUIS à partir des API de création, vous aurez également besoin de votre clé de création.

Collecter les paramètres obligatoires

Trois paramètres principaux sont obligatoires pour tous les conteneurs Azure AI. Les termes du contrat de licence logiciel Microsoft doivent être présents avec la valeur Accepter. Un URI de point de terminaison et une clé API sont également nécessaires.

URI de point de terminaison

La valeur {ENDPOINT_URI} est disponible sur la page Vue d’ensemble du portail Azure de la ressource Azure AI Services correspondante. Accédez à la page Vue d’ensemble, puis pointez sur le point de terminaison pour afficher une icône Copier dans le Presse-papiers . Copiez et utilisez le point de terminaison si nécessaire.

Touches

La valeur {API_KEY} est utilisée pour démarrer le conteneur et est disponible sur la page Clés de la ressource Azure AI Services correspondante sur le portail Azure. Accédez à la page Clés, puis sélectionnez l’icône Copier dans le Presse-papiers .

ID d’application {APP_ID}

Cet ID sert à sélectionner l’application. Vous pouvez trouver l'ID de l'application dans le portail LUIS en cliquant sur Gérer en haut de l'écran de votre application, puis sur Paramètres.

Clé de création {AUTHORING_KEY}

cette clé sert à obtenir l’application empaquetée à partir du service LUIS dans le cloud et à charger les journaux d’activité de requêtes vers le cloud. Vous aurez besoin de votre clé de création si vous exportez votre application à l'aide de l'API REST, décrite plus loin dans l'article.

Vous pouvez obtenir votre clé de création dans le portail LUIS en cliquant sur Gérer en haut de l'écran de votre application, puis sur Ressources Azure.

API de création de fichier de package

API de création d’applications empaquetées :

• API de package publiée
• API de package non publiée et uniquement entraînée

L’ordinateur hôte

L’hôte est un ordinateur x64 qui exécute le conteneur Docker. Il peut s’agir d’un ordinateur local ou d’un service d’hébergement Docker dans Azure, comme :

• Azure Kubernetes Service.
• Azure Container Instances.
• Un cluster Kubernetes déployé sur Azure Stack. Pour plus d’informations, consultez Déployer Kubernetes sur Azure Stack.

Exigences et suggestions relatives au conteneur

Le tableau ci-dessous répertorie les valeurs minimales et recommandées pour l’hôte de conteneur. Vos besoins peuvent varier en fonction du volume du trafic.

• Chaque cœur doit être cadencé à au moins 2,6 gigahertz (GHz).
• TPS - transactions par seconde

Le nombre de cœurs et la quantité de mémoire correspondent aux paramètres --cpus et --memory qui sont utilisés dans le cadre de la commande docker run.

Obtenir l’image conteneur avec docker pull

L’image conteneur LUIS se trouve dans le syndicat du registre de conteneurs mcr.microsoft.com. Elle réside dans le référentiel azure-cognitive-services/language et se nomme luis. Le nom complet de l’image conteneur est mcr.microsoft.com/azure-cognitive-services/language/luis.

Pour utiliser la dernière version du conteneur, vous pouvez utiliser l’étiquette latest. Vous trouverez aussi la liste complète des étiquettes sur MCR.

Utilisez la commande docker pull pour télécharger une image conteneur à partir du référentiel mcr.microsoft.com/azure-cognitive-services/language/luis :

docker pull mcr.microsoft.com/azure-cognitive-services/language/luis:latest

Pour obtenir une description complète des balises disponibles utilisées dans la commande précédente, telles que latest, consultez LUIS sur Docker Hub.

docker images --format "table {{.ID}}\t{{.Repository}}\t{{.Tag}}"

IMAGE ID         REPOSITORY                TAG
<image-id>       <repository-path/name>    <tag-name>

Comment utiliser le conteneur

Une fois que le conteneur est sur l’ordinateur hôte, appliquez la procédure suivante pour travailler avec le conteneur.

1. Exportez le package pour le conteneur à partir du portail LUIS ou des API LUIS.
2. Déplacez le fichier de package dans le répertoire d’entrée requis sur l’ordinateur hôte. Vous ne devez ni renommer, ni modifier, ni remplacer, ni décompresser le fichier de package LUIS.
3. Exécutez le conteneur avec le montage d’entrée et les paramètres de facturation requis. D’autres exemples de commande docker run sont disponibles.
4. Interrogation du point de terminaison de prédiction du conteneur.
5. Quand vous en avez terminé avec le conteneur, importez les journaux d’activité du point de terminaison à partir du montage de sortie dans le portail LUIS et arrêtez le conteneur.
6. Utilisez l’apprentissage actif du portail LUIS dans la page Review endpoint utterances (Passer en revue les énoncés du point de terminaison) afin d’améliorer l’application.

L’application en cours d’exécution dans le conteneur ne peut pas être modifiée. Pour changer l’application dans le conteneur, vous devez changer l’application dans le service LUIS à l’aide du portail LUIS ou utiliser les API de création LUIS. Ensuite, entraînez et/ou publiez, puis téléchargez un nouveau package et réexécutez le conteneur.

L’application LUIS à l’intérieur du conteneur ne peut pas être réexportée vers le service LUIS. Seuls les journaux d’activité de requêtes peuvent être chargés.

Exporter l’application empaquetée à partir de LUIS

Le conteneur LUIS a besoin d’une application LUIS entraînée ou publiée pour répondre aux requêtes de prédiction des énoncés d’utilisateur. Pour accéder à l’application LUIS, utilisez l’API du package entraîné ou publié.

L’emplacement par défaut est le sous-répertoire input correspondant à l’emplacement où vous exécutez la commande docker run.

Placez le fichier de package dans un répertoire et référencez ce répertoire en tant que montage d’entrée quand vous exécutez le conteneur docker.

Types de packages

Le répertoire de montage d’entrée peut contenir simultanément les modèles Production, Staging (intermédiaire) et Versioned (versionné) de l’application. Tous les packages sont montés.

Prérequis pour l’empaquetage

Avant d’empaqueter une application LUIS, vous devez disposer des éléments suivants :

Exporter le package d’application à partir du portail LUIS

Le portail Azure LUIS offre la possibilité d’exporter le package de l’application entraînée ou publiée.

Exporter le package de l’application publiée à partir du portail LUIS

Le package de l’application publiée est disponible à partir de la page de liste My Apps.

1. Connectez-vous au portail Azure LUIS.
2. Cochez la case à gauche du nom de l’application dans la liste.
3. Sélectionnez l’élément Export dans la barre d’outils contextuelle au-dessus de la liste.
4. Sélectionnez Export for container (GZIP) .
5. Sélectionnez l’environnement Production slot (Emplacement de production) ou Staging slot (Emplacement intermédiaire).
6. Le package est téléchargé à partir du navigateur.

Exporter le package de l’application versionné à partir du portail LUIS

Le package de l’application versionné est disponible à partir de la page de liste Versions.

1. Connectez-vous au portail Azure LUIS.
2. Sélectionnez l’application dans la liste.
3. Sélectionnez Manage (Gérer) dans la barre de navigation de l’application.
4. Sélectionnez Versions dans la barre de navigation gauche.
5. Cochez la case à gauche du nom de la version dans la liste.
6. Sélectionnez l’élément Export dans la barre d’outils contextuelle au-dessus de la liste.
7. Sélectionnez Export for container (GZIP) .
8. Le package est téléchargé à partir du navigateur.

Exporter le package de l’application publiée à partir de l’API

Utilisez l’API REST suivante pour empaqueter une application LUIS que vous avez déjà publiée. Remplacez les espaces réservés dans l’appel d’API par vos propres valeurs appropriées, en utilisant le tableau sous la spécification HTTP.

GET /luis/api/v2.0/package/{APP_ID}/slot/{SLOT_NAME}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}

Pour télécharger le package publié, reportez-vous à la documentation sur les API. En cas de téléchargement réussi, la réponse est un fichier de package LUIS. Enregistrez le fichier à l’emplacement de stockage spécifié pour le montage d’entrée du conteneur.

Exporter le package de l’application versionné à partir de l’API

Utilisez l’API REST suivante pour empaqueter une application LUIS que vous avez déjà entraînée. Remplacez les espaces réservés dans l’appel d’API par vos propres valeurs appropriées, en utilisant le tableau sous la spécification HTTP.

GET /luis/api/v2.0/package/{APP_ID}/versions/{APP_VERSION}/gzip HTTP/1.1
Host: {AZURE_REGION}.api.cognitive.microsoft.com
Ocp-Apim-Subscription-Key: {AUTHORING_KEY}

Pour télécharger le package versionné, reportez-vous à la documentation sur les API. En cas de téléchargement réussi, la réponse est un fichier de package LUIS. Enregistrez le fichier à l’emplacement de stockage spécifié pour le montage d’entrée du conteneur.

Exécuter le conteneur avec docker run

Utilisez la commande docker run pour exécuter le conteneur. Consultez Collecter les paramètres obligatoires pour plus d’informations sur la façon d’obtenir les valeurs {ENDPOINT_URI} et {API_KEY}.

Exemples de la commande docker run sont disponibles.

docker run --rm -it -p 5000:5000 ^
--memory 4g ^
--cpus 2 ^
--mount type=bind,src=c:\input,target=/input ^
--mount type=bind,src=c:\output\,target=/output ^
mcr.microsoft.com/azure-cognitive-services/language/luis ^
Eula=accept ^
Billing={ENDPOINT_URI} ^
ApiKey={API_KEY}

• Cet exemple utilise le répertoire du lecteur C: pour éviter tout conflit d’autorisation sur Windows. Si vous devez utiliser un répertoire spécifique en tant que répertoire d’entrée, vous devrez peut-être accorder au docker une autorisation de service.
• Ne changez pas l’ordre des arguments, sauf si vous connaissez les conteneurs Docker.
• Si vous utilisez un autre système d’exploitation, utilisez la console et/ou le terminal approprié, la syntaxe de dossier pour les montages et le caractère de continuation de ligne pour votre système. Dans ces exemples, une console Windows avec un caractère de continuation de ligne ^ est censée être utilisée. Le conteneur étant un système d’exploitation Linux, le montage cible utilise une syntaxe de dossier de type Linux.

Cette commande :

• Exécute un conteneur à partir de l’image conteneur LUIS.
• Charge l’application LUIS à partir du montage d’entrée à l’emplacement C:\input situé sur l’hôte de conteneur.
• Alloue deux cœurs de processeur et 4 gigaoctets (Go) de mémoire.
• Expose le port TCP 5000 et alloue un pseudo-TTY pour le conteneur
• Enregistre les journaux d’activité LUIS et de conteneur dans le montage de sortie à l’emplacement C:\output situé sur l’hôte de conteneur.
• Supprime automatiquement le conteneur après sa fermeture. L’image conteneur est toujours disponible sur l’ordinateur hôte.

D’autres exemples de commande docker run sont disponibles.

Exécuter plusieurs conteneurs sur le même hôte

Si vous envisagez d’exécuter plusieurs conteneurs avec les ports exposés, veillez à exécuter chaque conteneur avec un port exposé différent. Par exemple, exécutez le premier conteneur sur le port 5000 et le second conteneur sur le port 5001.

Vous pouvez avoir ce conteneur, et un autre conteneur Azure AI services qui s’exécutent ensemble sur l’hôte. Vous pouvez également disposer de plusieurs conteneurs du même conteneur Azure AI services en cours d’exécution.

API de point de terminaison prises en charge par le conteneur

Les versions V2 et V3 de l’API sont disponibles avec le conteneur.

Interroger le point de terminaison de prédiction du conteneur

Le conteneur fournit des API de point de terminaison de prédiction de requête basées sur REST. Les points de terminaison pour les applications publiées (intermédiaires ou production) ont un itinéraire différent de celui des points de terminaison pour les applications versionnées.

Utilisez l’hôte, http://localhost:5000, pour les API de conteneur.

Les paramètres de requête configurent ce qui est retourné dans la réponse de requête, et de quelle manière :

Interroger l’application LUIS

Voici un exemple de commande CURL pour interroger le conteneur d’une application publiée :

curl -G \
-d verbose=false \
-d log=true \
--data-urlencode "query=turn the lights on" \
"http://localhost:5000/luis/v3.0/apps/{APP_ID}/slots/production/predict"

curl -G \
-d verbose=false \
-d log=false \
--data-urlencode "query=turn the lights on" \
"http://localhost:5000/luis/v3.0/apps/{APP_ID}/versions/{APP_VERSION}/predict"

curl -X GET \
"http://localhost:5000/luis/v2.0/apps/{APP_ID}?q=turn%20on%20the%20lights&staging=false&timezoneOffset=0&verbose=false&log=true" \
-H "accept: application/json"

curl -X GET \
"http://localhost:5000/luis/v2.0/apps/{APP_ID}/versions/{APP_VERSION}?q=turn%20on%20the%20lights&timezoneOffset=0&verbose=false&log=true" \
-H "accept: application/json"

Importer les journaux d’activité de point de terminaison pour l’apprentissage actif

Si un montage de sortie est spécifié pour le conteneur LUIS, les fichiers journaux de requêtes d’application sont enregistrés dans le répertoire de sortie, où {INSTANCE_ID} correspond à l’ID du conteneur. Le journal des requêtes d’application contient la requête, la réponse et les horodateurs de chaque requête de prédiction soumise au conteneur LUIS.

L’emplacement suivant montre la structure de répertoires imbriqués pour les fichiers journaux du conteneur.

/output/luis/{INSTANCE_ID}/

À partir du portail LUIS, sélectionnez votre application, puis sélectionnez Import endpoint logs (Importer les journaux d’activité de point de terminaison) pour charger ces journaux d’activité.

Une fois le journal chargé, passez en revue les énoncés de point de terminaison dans le portail LUIS.

Valider l’exécution d’un conteneur

Il existe plusieurs façons de confirmer que le conteneur s’exécute. Recherchez l’adresse IP externe et le port exposé du conteneur en question, puis ouvrez le navigateur web de votre choix. Utilisez les différentes URL de requête suivantes pour vérifier que le conteneur est en cours d’exécution. Les exemples d’URL de requête listés ici sont http://localhost:5000, mais votre conteneur spécifique peut varier. Veillez à vous fier à l’adresse IP externe de votre conteneur et au port exposé.

Exécuter le conteneur déconnecté d’Internet

Pour utiliser ce conteneur déconnecté d’Internet, vous devez d’abord demander un accès en remplissant une application et en achetant un plan d’engagement. Pour plus d’informations, consultez Utiliser des conteneurs Docker dans des environnements déconnectés.

Si vous avez été autorisé à exécuter le conteneur déconnecté d’Internet, utilisez l’exemple suivant qui montre la mise en forme de la commande docker run que vous allez utiliser, avec des valeurs d’espace réservé. Remplacez ces valeurs d’espace réservé par vos propres valeurs.

Le paramètre DownloadLicense=True de votre commande docker run télécharge un fichier de licence qui permet à votre conteneur Docker de s’exécuter quand il n’est pas connecté à Internet. Il contient également une date d’expiration après laquelle le conteneur ne pourra plus être exécuté avec ce fichier de licence. Vous ne pouvez utiliser un fichier de licence qu’avec le conteneur pour lequel vous avez été approuvé. Par exemple, vous ne pouvez pas utiliser le fichier de licence d’un conteneur de reconnaissance vocale avec un conteneur Document Intelligence.

docker run --rm -it -p 5000:5000 \ 
-v {LICENSE_MOUNT} \
{IMAGE} \
eula=accept \
billing={ENDPOINT_URI} \
apikey={API_KEY} \
DownloadLicense=True \
Mounts:License={CONTAINER_LICENSE_DIRECTORY} 

Une fois le fichier de licence téléchargé, vous pourrez exécuter le conteneur dans un environnement déconnecté. L’exemple suivant illustre la mise en forme de la commande docker run que vous allez utiliser, avec des valeurs d’espace réservé. Remplacez ces valeurs d’espace réservé par vos propres valeurs.

Quel que soit l’emplacement d’exécution du conteneur, le fichier de licence doit être monté sur le conteneur et l’emplacement du dossier de licence sur le système de fichiers local du conteneur doit être spécifié avec Mounts:License=. Un montage de sortie doit également être spécifié afin que les enregistrements d’utilisation puissent être écrits pour la facturation.

docker run --rm -it -p 5000:5000 --memory {MEMORY_SIZE} --cpus {NUMBER_CPUS} \ 
-v {LICENSE_MOUNT} \ 
-v {OUTPUT_PATH} \
{IMAGE} \
eula=accept \
Mounts:License={CONTAINER_LICENSE_DIRECTORY}
Mounts:Output={CONTAINER_OUTPUT_DIRECTORY}

Arrêter le conteneur

Pour arrêter le conteneur, dans l’environnement de ligne de commande où le conteneur est en cours d’exécution, appuyez sur Ctrl+C.

Dépannage

Si vous exécutez le conteneur avec un montage de sortie et la journalisation activée, il génère des fichiers journaux qui sont utiles pour résoudre les problèmes qui se produisent lors du démarrage ou de l’exécution du conteneur.

Si vous avez des difficultés à exécuter un conteneur Azure AI services, vous pouvez essayer d’utiliser le conteneur de diagnostics Microsoft. Utilisez ce conteneur pour diagnostiquer dans votre environnement de déploiement les erreurs courantes pouvant nuire au bon fonctionnement des conteneurs Azure AI.

Pour obtenir le conteneur, utilisez la commande docker pull suivante :

docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic

Exécutez ensuite le conteneur. Remplacez {ENDPOINT_URI} par votre point de terminaison et {API_KEY} par la clé de votre ressource :

docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \
ApiKey={API_KEY}

Le conteneur teste la connectivité réseau avec le point de terminaison de facturation.

Facturation

Le conteneur LUIS envoie des informations de facturation à Azure à l’aide d’une ressource Azure AI services correspondante sur votre compte Azure.

Les requêtes sur le conteneur sont facturées au niveau tarifaire de la ressource Azure utilisée pour le paramètre ApiKey.

La licence des conteneurs Azure AI Services ne vous permet pas de les exécuter sans les connecter au point de terminaison du compteur ou de la facturation. Vous devez configurer les conteneurs de manière à ce qu’ils communiquent les informations de facturation au point de terminaison de facturation à tout moment. Les conteneurs Azure AI Services n’envoient pas de données client, telles que l’image ou le texte analysé, à Microsoft.

Connexion à Azure

Le conteneur a besoin des valeurs d’arguments de facturation pour s’exécuter. Ces valeurs permettent au conteneur de se connecter au point de terminaison de facturation. Le conteneur crée des rapports sur l’utilisation toutes les 10 à 15 minutes. Si le conteneur ne se connecte pas à Azure dans la fenêtre de temps imparti, il continue de s’exécuter, mais ne traite pas les requêtes tant que le point de terminaison de facturation n’est pas restauré. Une tentative de connexion est effectuée 10 fois, toutes les 10 à 15 minutes. S’il ne parvient pas à se connecter au point de terminaison de facturation au cours de ces 10 essais, le conteneur cesse de traiter les demandes. Pour obtenir un exemple des informations envoyées à Microsoft en lien avec la facturation, consultez le Forum aux questions sur le conteneur Azure AI Services.

Arguments de facturation

La commande docker run démarre le conteneur quand les trois options suivantes ont des valeurs valides :

Pour plus d’informations sur ces options, consultez Configurer des conteneurs.

Résumé

Dans cet article, vous avez découvert des concepts et le flux de travail pour le téléchargement, l’installation et l’exécution des conteneurs LUIS (Language Understanding). En résumé :

• LUIS (Language Understanding) fournit un conteneur Linux pour Docker offrant des prédictions de requête de point de terminaison d’énoncés.
• Les images conteneurs sont téléchargées à partir de Microsoft Container Registry (MCR).
• Les images conteneurs s’exécutent dans Docker.
• Vous pouvez utiliser l’API REST pour interroger les points de terminaison de conteneur en spécifiant l’URI hôte du conteneur.
• Vous devez spécifier les informations de facturation lors de l’instanciation d’un conteneur.

Étapes suivantes

• Pour obtenir les paramètres de configuration, passez en revue Configurer des conteneurs.
• Consultez Limitations des conteneurs LUIS pour connaître les restrictions de capacité connues.
• Reportez-vous à la section Résolution des problèmes pour résoudre les problèmes liés à la fonctionnalité LUIS.
• Utiliser plus de conteneurs Azure AI