Installer, puis exécuter des conteneurs de reconnaissance d’entités nommées personnalisées

Les conteneurs vous permettent d’héberger l’API de reconnaissance d’entités nommées personnalisées sur votre propre infrastructure à l’aide de votre propre modèle formé. Si vous avez des exigences de sécurité ou de gouvernance des données qui ne peuvent pas être satisfaites par un appel à distance de la fonction de reconnaissance d’entités nommées personnalisées, les conteneurs peuvent être une bonne option.

Remarque

  • Le compte gratuit est limité à 5 000 enregistrements texte par mois et seuls les niveaux tarifairesGratuit et Standard sont valides pour les conteneurs. Pour plus d’informations sur les taux de requête de transaction, consultez Données et limites de service.

Prérequis

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 {ENDPOINT_URI} valeur est disponible dans la page Vue d’ensemble du portail Azure de la ressource Foundry Tools correspondante. Accédez à la page Aperçu survolez le point de terminaison, et une icône Copier dans le presse-papiers apparaît. Copiez et utilisez le point de terminaison si nécessaire.

Capture d’écran montrant la collecte de l’URI du point de terminaison en vue d’une utilisation ultérieure.

Touches

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

Capture d’écran montrant l’obtention de l’une des deux clés en vue d’une utilisation ultérieure.

Important

Ces clés d’abonnement sont utilisées pour accéder à votre API Foundry Tools. Ne partagez pas vos clés. Stockez-les en toute sécurité. Par exemple, utilisez Azure Key Vault. Nous vous recommandons également de regénérer ces clés régulièrement. Une seule clé est nécessaire pour effectuer un appel d’API. Lors de la regénération de la première clé, vous pouvez utiliser la deuxième clé pour un accès continu au service.

Spécifications et recommandations relatives à 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 :

Le tableau suivant décrit les spécifications minimales et recommandées pour le conteneur de reconnaissance d’entités nommées personnalisées. Chaque cœur de processeur doit être cadencé à au moins 2,6 gigahertz (GHz) ou plus. Les transactions par seconde (TPS) autorisées sont également indiquées.

Configuration minimale pour l’hôte Configuration recommandée pour l’hôte TPS minimales TPS maximales
Reconnaissance d’entité nommée personnalisée 1 cœur, 2 Go de mémoire 1 cœur, 4 Go de mémoire 15 30

Le cœur d’UC 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.

Exporter votre modèle de reconnaissance d’entités nommées personnalisées

Avant de continuer à exécuter l’image Docker, vous devez exporter votre propre modèle entraîné pour l’exposer à votre conteneur. Utilisez la commande suivante pour extraire votre modèle et remplacer les espaces réservés par vos propres valeurs :

Texte de remplacement Valeur Format ou exemple
{API_KEY} Clé de votre ressource de reconnaissance d’entités nommées personnalisées. Cette information est disponible dans le portail Azure, sur la page Key and endpoint (Clé et point de terminaison) de votre ressource. xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI} Point de terminaison d’accès à l’API de reconnaissance d’entités nommées personnalisées. Cette information est disponible dans le portail Azure, sur la page Key and endpoint (Clé et point de terminaison) de votre ressource. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT_NAME} Nom du projet contenant le modèle que vous souhaitez exporter. Vous pouvez le trouver sous l’onglet de vos projets dans le portail Microsoft Foundry. myProject
{TRAINED_MODEL_NAME} Nom du modèle formé que vous souhaitez exporter. Vous trouverez vos modèles entraînés sous l’onglet Évaluation de votre modèle sous votre projet dans le portail Microsoft Foundry. myTrainedModel 
curl --location --request PUT '{ENDPOINT_URI}/language/authoring/analyze-text/projects/{PROJECT_NAME}/exported-models/{TRAINED_MODEL_NAME}?api-version=2023-04-15-preview' \
--header 'Ocp-Apim-Subscription-Key: {API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "TrainedmodelLabel": "{TRAINED_MODEL_NAME}"
}'

Obtenir l’image conteneur avec docker pull

L’image du conteneur de reconnaissance d’entités nommées personnalisées est disponible sur le syndicat de registres de conteneurs mcr.microsoft.com. Elle réside dans le référentiel azure-cognitive-services/textanalytics/ et se nomme customner. Le nom entièrement qualifié de l’image de conteneur est mcr.microsoft.com/azure-cognitive-services/textanalytics/customner.

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 de Microsoft Container Registry.

docker pull mcr.microsoft.com/azure-cognitive-services/textanalytics/customner:latest

Conseil

Vous pouvez utiliser la commande docker images pour lister vos images conteneurs téléchargées. Par exemple, la commande suivante liste l’ID, le référentiel et la balise de chaque image conteneur téléchargée dans un tableau :

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

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

Exécuter le conteneur avec docker run

Une fois le conteneur sur l’ordinateur hôte, utilisez la commande docker run pour exécuter les conteneurs. Chaque conteneur continuera à s’exécuter jusqu’à ce que vous l’arrêtiez.

Important

  • les commandes docker dans les sections suivantes utilisent la barre oblique inverse, \, comme caractère de continuation de ligne. Remplacez-la ou supprimez-la en fonction des exigences de votre système d’exploitation hôte.
  • Vous devez spécifier les options Eula, Billing et ApiKey pour exécuter le conteneur, sinon il ne démarrera pas. Pour plus d'informations, consultez Facturation.

Pour exécuter le conteneur Reconnaissance d’entités nommées personnalisées, exécutez la commande docker run suivante. Remplacez les espaces réservés par vos propres valeurs :

Texte de remplacement Valeur Format ou exemple
{API_KEY} Clé de votre ressource de reconnaissance d’entités nommées personnalisées. Cette information est disponible dans le portail Azure, sur la page Key and endpoint (Clé et point de terminaison) de votre ressource. xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
{ENDPOINT_URI} Point de terminaison d’accès à l’API de reconnaissance d’entités nommées personnalisées. Cette information est disponible dans le portail Azure, sur la page Key and endpoint (Clé et point de terminaison) de votre ressource. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT_NAME} Nom du projet contenant le modèle que vous souhaitez exporter. Vous pouvez le trouver sous l’onglet de vos projets dans le portail Microsoft Foundry. myProject
{LOCAL_PATH} Chemin d’accès dans lequel le modèle exporté à l’étape précédente sera téléchargé. Vous pouvez choisir le chemin d’accès que vous voulez. C:/custom-ner-model
{TRAINED_MODEL_NAME} Nom du modèle formé que vous souhaitez exporter. Vous trouverez vos modèles entraînés sous l’onglet Évaluation de votre modèle sous votre projet dans le portail Microsoft Foundry. myTrainedModel 
docker run --rm -it -p5000:5000  --memory 4g --cpus 1 \
-v {LOCAL_PATH}:/modelPath \
mcr.microsoft.com/azure-cognitive-services/textanalytics/customner:latest \
EULA=accept \
BILLING={ENDPOINT_URI} \
APIKEY={API_KEY} \
projectName={PROJECT_NAME}
exportedModelName={TRAINED_MODEL_NAME}

Cette commande :

  • Exécute un conteneur de reconnaissance d’entités nommées personnalisées, puis télécharge votre modèle exporté sur le chemin d’accès local spécifié.
  • Alloue un cœur de processeur et 4 gigaoctets (Go) de mémoire.
  • Expose le port TCP 5000 et alloue un pseudo-TTY pour le conteneur
  • Supprime automatiquement le conteneur après sa fermeture. L’image conteneur est toujours disponible sur l’ordinateur hôte.

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 Foundry Tools en cours d’exécution sur l’hôte ensemble. Vous pouvez également avoir plusieurs conteneurs du même conteneur Foundry Tools en cours d’exécution.

Interroger le point de terminaison de prédiction du conteneur

Le conteneur fournit des API REST de point de terminaison pour la prédiction de requêtes.

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

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

URL de la demande Objectif
http://localhost:5000/ Le conteneur fournit une page d’accueil.
http://localhost:5000/ready Appelée avec la méthode GET, cette URL permet de vérifier que le conteneur est prêt à accepter une requête adressée au modèle. Cette requête peut être utilisée pour les sondes de vivacité et de disponibilité de Kubernetes.
http://localhost:5000/status Également accessible via GET, cette URL permet de vérifier si la clé API utilisée pour démarrer le conteneur est valide sans provoquer de requête vers un point de terminaison. Cette requête peut être utilisée pour les sondes de vivacité et de disponibilité de Kubernetes.
http://localhost:5000/swagger Le conteneur fournit un ensemble complet de documentation pour les points de terminaison et une fonctionnalité Essayer. Avec cette fonctionnalité, vous pouvez entrer vos paramètres dans un formulaire HTML basé sur le web, et constituer la requête sans avoir à écrire du code. Une fois la requête retournée, un exemple de commande CURL est fourni pour illustrer les en-têtes HTTP, et le format du corps qui est nécessaire.

Page d’accueil du conteneur

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, sélectionnez 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.

Conseil

Pour plus d’informations et de conseils sur la résolution des problèmes, consultez les questions fréquentes (FAQ) sur les conteneurs Azure AI.

Facturation

Les conteneurs de reconnaissance d’entités nommées personnalisées envoient des informations de facturation à Azure, à l’aide d’une ressource de reconnaissance d’entités nommées personnalisées 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.

Les conteneurs Foundry Tools ne sont pas autorisés à s’exécuter sans être connectés au point de terminaison de contrôle ou de 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 Foundry Tools n’envoient pas de données client, telles que l’image ou le texte en cours d’analyse, à Microsoft.

Connexion à Azure

Le conteneur requiert les valeurs de l’argument billing 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. Consultez le FAQ sur le conteneur Foundry Tools pour obtenir un exemple des informations envoyées à Microsoft pour la facturation.

Arguments de facturation

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

Option Description
ApiKey Clé API de la ressource Foundry Tools utilisée pour suivre les informations de facturation.
La valeur de cette option doit être définie sur une clé API pour la ressource provisionnée spécifiée dans Billing.
Billing Point de terminaison de la ressource Foundry Tools utilisée pour suivre les informations de facturation.
La valeur de cette option doit être définie sur l’URI de point de terminaison d’une ressource Azure provisionnée.
Eula Indique que vous avez accepté la licence pour le conteneur.
La valeur de cette option doit être définie sur accepter.

Résumé

Dans cet article, vous avez découvert les concepts et le workflow du téléchargement, de l’installation, puis de l’exécution des conteneurs de reconnaissance d’entités nommées personnalisées. En résumé :

  • La reconnaissance d’entités nommées personnalisées fournit des conteneurs Linux pour Docker.
  • 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 ou le Kit de développement logiciel (SDK) pour appeler des opérations dans des conteneurs de reconnaissance d’entités nommées personnalisées en spécifiant l’URI hôte du conteneur.
  • Vous devez spécifier les informations de facturation lors de l’instanciation d’un conteneur.

Important

Les conteneurs Azure AI ne sont pas autorisés à fonctionner sans être connectés à Azure à des fins de mesure. Les clients doivent configurer les conteneurs de manière à ce qu’ils communiquent les informations de facturation au service de contrôle à tout moment. Les conteneurs Azure AI ne transmettent aucune donnée client (p. ex., le texte analysé) à Microsoft.

Étapes suivantes

  • Last updated on