Démarrage rapide : reconnaissance d’entités nommées personnalisées

Prérequis

• Un abonnement Azure. Si vous n’en avez pas, vous pouvez en créer un gratuitement.

• Autorisations requises. Assurez-vous que la personne qui établit le compte et le projet est affectée au rôle de Propriétaire du compte Azure AI au niveau de l’abonnement. Vous pouvez également disposer du rôle Contributeur ou Contributeur Cognitive Services au niveau de l’étendue de l’abonnement. Pour plus d’informations, consultezContrôle d’accès en fonction du rôle (RBAC).

• Ressource de langue avec un compte de stockage. Dans la page Sélectionner des fonctionnalités supplémentaires, sélectionnez la case classification de texte personnalisée, reconnaissance d’entité nommée personnalisée, analyse des sentiments personnalisée et analyse de texte personnalisée pour la santé afin de lier un compte de stockage requis à cette ressource :

  

• Projet Foundry créé dans Foundry. Pour plus d’informations, consultezCréer un projet Foundry.

• Jeu de données NER personnalisé chargé dans votre conteneur de stockage. Un jeu de données de reconnaissance d’entité nommée personnalisé (NER) est la collection de documents texte étiquetés utilisés pour entraîner votre modèle NER personnalisé. Vous pouvez télécharger notre exemple de jeu de données pour ce guide de démarrage rapide. La langue source est l’anglais.

Étape 1 : Configurer les rôles, autorisations et paramètres requis

Commençons par configurer vos ressources.

Activer la fonctionnalité de reconnaissance d’entité nommée personnalisée

Vérifiez que la fonctionnalité De classification de texte personnalisée /Reconnaissance d’entité nommée personnalisée est activée dans le portail Azure.

1. Accédez à votre ressource de langue dans le portail Azure.
2. Dans le menu de gauche, sous La section Gestion des ressources , sélectionnez Fonctionnalités.
3. Vérifiez que la fonctionnalité de classification de texte personnalisée /Reconnaissance d’entité nommée personnalisée est activée.
4. Si votre compte de stockage n’est pas affecté, sélectionnez et connectez votre compte de stockage.
5. Sélectionnez Appliquer.

Ajouter des rôles requis pour votre ressource de langue

1. Dans la page de ressources de langue du portail Azure, sélectionnez Contrôle d’accès (IAM) dans le volet gauche.
2. Sélectionnez Ajouter pour Ajouter des Attributions de Rôles, puis ajoutez le rôle Propriétaire du Langage pour Cognitive Services ou le rôle Contributeur pour Cognitive Services pour votre ressource de langue.
3. Dans le champ Attribuer l’accès à, sélectionnez Utilisateur, groupe ou principal du service.
4. Sélectionnez Sélectionner des membres.
5. Sélectionnez votre nom d’utilisateur. Vous pouvez rechercher des noms d’utilisateur dans le champ Sélectionner. Répétez cette étape pour tous les rôles.
6. Répétez ces étapes pour tous les comptes d’utilisateur qui ont besoin d’accéder à cette ressource.

Ajouter des rôles requis pour votre compte de stockage

1. Accédez à la page de votre compte de stockage dans le portail Azure.
2. Sélectionnez Contrôle d’accès (IAM) dans le volet gauche.
3. Sélectionnez Ajouter pour ajouter des attributions de rôles, puis choisissez le rôle contributeur aux données blob de stockage sur le compte de stockage.
4. Dans Attribuer l’accès, sélectionnez Identité managée.
5. Sélectionnez Sélectionner des membres.
6. Sélectionnez votre abonnement et langue comme identité managée. Vous pouvez rechercher votre ressource de langue dans le champ Sélectionner .

Ajouter des rôles d’utilisateur requis

1. Accédez à la page de votre compte de stockage dans le portail Azure.
2. Sélectionnez Contrôle d’accès (IAM) dans le volet gauche.
3. Sélectionnez Ajouter pour ajouter des attributions de rôles, puis choisissez le rôle contributeur aux données blob de stockage sur le compte de stockage.
4. Dans le champ Attribuer l’accès à, sélectionnez Utilisateur, groupe ou principal du service.
5. Sélectionnez Sélectionner des membres.
6. Sélectionnez votre flux utilisateur. Vous pouvez rechercher des noms d’utilisateur dans le champ Sélectionner.

Étape 2 : Charger votre jeu de données dans votre conteneur de stockage

Ensuite, nous allons ajouter un conteneur et charger vos fichiers de jeu de données directement dans le répertoire racine de votre conteneur de stockage. Ces documents sont utilisés pour entraîner votre modèle.

1. Ajoutez un conteneur au compte de stockage associé à votre ressource de langue. Pour plus d’informations, consultezcréer un conteneur.

2. Téléchargez l’exemple de jeu de données à partir de GitHub. L’exemple de jeu de données fourni contient 20 contrats de prêt :

   • Chaque accord comprend deux parties : un prêteur et un emprunteur.
   • Vous extrayez des informations pertinentes pour : les deux parties, la date d’accord, le montant du prêt et le taux d’intérêt.

3. Ouvrez le fichier .zip et extrayez le dossier contenant les fichiers texte.

4. Accédez à Foundry.

5. Si vous n’êtes pas encore connecté, le portail vous invite à le faire avec vos informations d’identification Azure.

6. Une fois connecté, accédez à votre projet Foundry existant pour ce guide de démarrage rapide.

7. Sélectionnez Centre d’administration dans le menu de navigation de gauche.

8. Sélectionnez Ressources connectées dans la section Hub du menu Centre d’administration .

9. Ensuite, choisissez l'espace de stockage blob qui a été défini pour vous en tant que ressource connectée.

10. Dans le stockage blob de l’espace de travail, sélectionnez Afficher dans le portail Azure.

11. Sur la page Azure Portal de votre stockage d’objets blob, sélectionnez Téléverser dans le menu en haut de la page. Ensuite, choisissez les fichiers .txt et .json que vous avez téléchargés précédemment. Enfin, sélectionnez le bouton Charger pour ajouter le fichier à votre conteneur.

    

Maintenant que les ressources Azure requises sont approvisionnées et configurées dans le portail Azure, nous allons utiliser ces ressources dans Foundry pour créer un modèle personnalisé de Reconnaissance d'entités nommées (NER) affiné.

Étape 3 : Connecter votre ressource de langue

Ensuite, nous créons une connexion à votre ressource language afin que Foundry puisse y accéder en toute sécurité. Cette connexion fournit une gestion et une authentification sécurisées des identités, ainsi que l’accès contrôlé et isolé aux données.

1. Revenez à la fonderie.

2. Accédez à votre projet Foundry existant pour ce guide de démarrage rapide.

3. Sélectionnez Centre d’administration dans le menu de navigation de gauche.

4. Sélectionnez Ressources connectées dans la section Hub du menu Centre d’administration .

5. Dans la fenêtre principale, sélectionnez le bouton + Nouvelle connexion .

6. Sélectionnez Langue dans la fenêtre Ajouter une connexion à des ressources externes .

7. Sélectionnez Ajouter une connexion, puis fermez.

   

Étape 4 : Ajuster votre modèle NER personnalisé

À présent, nous sommes prêts à créer un modèle NER personnalisé.

1. Dans la section Projet du menu Centre de gestion , sélectionnez Accéder au projet.

2. Dans le menu Vue d’ensemble , sélectionnez Réglage précis.

3. Dans la fenêtre principale, sélectionnez l’onglet Réglage précis du service IA , puis le bouton + Ajuster.

4. Dans la fenêtre Créer un réglage précis du service, choisissez l’onglet Reconnaissance d’entité nommée personnalisée , puis sélectionnez Suivant.

   

5. Dans la fenêtre Créer une tâche de réglage fin du service, remplissez les champs comme suit :

   • Service connecté. Le nom de votre ressource de langue doit déjà apparaître dans ce champ par défaut. si ce n’est pas le cas, ajoutez-le à partir du menu déroulant.

   • Nom. Donnez un nom à votre projet d'optimisation.

   • Langue. L’anglais est défini comme valeur par défaut et apparaît déjà dans le champ.

   • Description. Vous pouvez éventuellement fournir une description ou laisser ce champ vide.

   • Conteneur de magasin d’objets blob. Sélectionnez le conteneur de stockage d’objets blob de l’espace de travail à partir de l’étape 2 et cliquez sur le bouton Se connecter.

6. Enfin, sélectionnez le bouton Créer. L’exécution de l’opération de création peut prendre quelques minutes.

Étape 5 : Entraîner votre modèle

1. Dans le menu Bien démarrer , choisissez Gérer les données. Dans la fenêtre Ajouter des données pour l’apprentissage et le test , vous voyez les exemples de données que vous avez précédemment chargés dans votre conteneur Stockage Blob Azure.
2. Ensuite, dans le menu Commencer, sélectionnez Entraîner le modèle.
3. Sélectionnez le bouton + Modèle de train. Lorsque la fenêtre Entraîner un nouveau modèle s’affiche, entrez un nom pour votre nouveau modèle et conservez les valeurs par défaut. Sélectionnez le bouton Suivant.
4. Dans la fenêtre Entraîner un nouveau modèle, conservez l'option séparer automatiquement le jeu de test des données d’apprentissage activée par défaut avec le pourcentage recommandé défini à 80 % pour les données d’apprentissage et 20 % pour les données de test.
5. Passez en revue la configuration de votre modèle, puis sélectionnez le bouton Créer .
6. Après l’apprentissage d’un modèle, vous pouvez sélectionner Évaluer le modèle dans le menu Bien démarrer . Vous pouvez sélectionner votre modèle dans la fenêtre Évaluer votre modèle et apporter des améliorations si nécessaire.

Étape 6 : Déployer votre modèle

En règle générale, après l’entraînement d’un modèle, vous passez en revue ses détails d’évaluation. Pour ce guide de démarrage rapide, vous pouvez simplement déployer votre modèle et le mettre à la disposition des tests dans le terrain de jeu Azure Language ou en appelant l’API de prédiction. Toutefois, si vous le souhaitez, vous pouvez prendre un moment pour sélectionner Évaluer votre modèle dans le menu de gauche et explorer les données de télémétrie détaillées pour votre modèle. Effectuez les étapes suivantes pour déployer votre modèle dans Foundry.

1. Sélectionnez Déployer le modèle dans le menu de gauche.

2. Ensuite, sélectionnez ➕Déployer un modèle entraîné à partir de la fenêtre Déployer votre modèle.

   

3. Vérifiez que le bouton Créer un nouveau déploiement est sélectionné.

4. Complétez les champs de fenêtre Déployer un modèle entraînée :

   • Nom du déploiement. Nommez votre modèle.
   • Attribuez un modèle. Sélectionnez votre modèle entraîné dans le menu déroulant.
   • Région. Sélectionnez une région dans le menu déroulant.

5. Enfin, sélectionnez le bouton Créer. Le déploiement de votre modèle peut prendre quelques minutes.

6. Une fois le déploiement réussi, vous pouvez afficher l’état du déploiement de votre modèle sur la page Déployer votre modèle. La date d’expiration qui apparaît marque la date à laquelle votre modèle déployé devient indisponible pour les tâches de prédiction. Cette date est généralement de 18 mois après le déploiement d’une configuration d’entraînement.

   

Étape 7 : Essayer azure Language Playground

Le jeu de langage fournit un bac à sable pour tester et configurer votre modèle affiné avant de le déployer en production, sans écrire de code.

1. Dans la barre de menus supérieure, sélectionnez Essayer dans le terrain de jeu.
2. Dans la fenêtre Azure Language Playground, sélectionnez la vignette Reconnaissance d’entité nommée personnalisée.
3. Dans la section Configuration , sélectionnez le nom de votre projet et le nom du déploiement dans les menus déroulants.
4. Entrez une entité et sélectionnez Exécuter.
5. Vous pouvez évaluer les résultats dans la fenêtre Détails .

Voilà, félicitations !

Dans ce guide de démarrage rapide, vous avez créé un modèle NER personnalisé affiné, l’avez déployé dans Foundry et testé votre modèle dans Azure Language Playground.

Nettoyer les ressources

Si vous n’avez plus besoin de votre projet, vous pouvez le supprimer de La foundry.

1. Accédez à la page d’accueil Foundry . Lancez le processus d’authentification en vous connectant, sauf si vous avez déjà terminé cette étape et que votre session est active.
2. Sélectionnez le projet que vous souhaitez supprimer de l’objet Keep building with Foundry.
3. Sélectionner le Centre de gestion.
4. Sélectionnez Supprimer le projet.

Pour supprimer le hub avec tous ses projets :

1. Accédez à l’onglet Vue d’ensemble de la section Hub .

2. Sur la droite, sélectionnez Supprimer le hub.

3. Le lien ouvre le portail Azure pour vous permettre de supprimer le hub.

Prérequis

• Abonnement Azure - En créer un gratuitement

Créer une nouvelle langue Azure dans la ressource Foundry Tools et le compte de stockage Azure

Avant de pouvoir utiliser la reconnaissance d’entité nommée personnalisée (NER), vous devez créer une ressource language, ce qui vous donne les informations d’identification dont vous avez besoin pour créer un projet et commencer à entraîner un modèle. Vous avez également besoin d’un compte de stockage Azure, où vous pouvez charger votre jeu de données utilisé pour créer votre modèle.

Créer une ressource à partir du portail Azure

1. Connectez-vous au portail Azure pour créer une ressource Azure Language in Foundry Tools.

2. Dans la fenêtre qui s’affiche, sélectionnez Classification de texte personnalisée et reconnaissance d’entités nommées personnalisées dans les fonctionnalités personnalisées. Sélectionnez Continuer pour créer votre ressource en bas de l’écran.

   

3. Créez une ressource de langue avec les détails suivants.

   Nom	Description
   Abonnement	Votre abonnement Azure.
   groupe de ressources	Groupe de ressources qui contient votre ressource. Vous pouvez utiliser un groupe de resources existant ou en créer un.
   Région	Région de votre ressource de langue. Par exemple, « USA Ouest 2 ».
   Nom	Nom de votre ressource.
   Niveau tarifaire	Niveau tarifaire de votre ressource de langue. Vous pouvez utiliser le niveau tarifaire gratuit (F0) pour tester le service.

   Remarque

   Si vous recevez un message indiquant que « votre compte de connexion n’est pas propriétaire du groupe de ressources du compte de stockage sélectionné », votre compte doit avoir un rôle de propriétaire attribué sur le groupe de ressources avant de pouvoir créer une ressource de langue. Pour obtenir de l’aide, contactez le propriétaire de votre abonnement Azure.

4. Dans la section Classification de texte personnalisée et reconnaissance d’entités nommées personnalisées, sélectionnez un compte de stockage existant ou Nouveau compte de stockage. Ces valeurs sont destinées à vous aider à commencer, et pas nécessairement aux valeurs de compte de stockage que vous souhaitez utiliser dans les environnements de production. Pour éviter la latence lors de la création de votre projet, connectez-vous aux comptes de stockage dans la même région que votre ressource de langue.

   Valeur du compte de stockage	Valeur recommandée
   Nom du compte de stockage	Nom quelconque
   Type de compte de stockage	Stockage localement redondant standard (LRS)

5. Vérifiez que l’Avis d’IA responsable est coché. Au bas de la page, sélectionnez Vérifier + créer, puis Créer.

Charger les exemples de données dans un conteneur d’objets blob

Après avoir créé un compte de stockage Azure et l’avoir connecté à votre ressource de langue, vous devez charger les documents à partir de l’exemple de jeu de données dans le répertoire racine de votre conteneur. Ces documents sont utilisés pour entraîner votre modèle.

1. Téléchargez l’exemple de jeu de données à partir de GitHub.

2. Ouvrez le fichier .zip et extrayez le dossier contenant les fichiers texte.

3. Dans le Portail Azure, accédez au compte de stockage que vous avez créé et sélectionnez-le.

4. Dans votre compte de stockage, sélectionnez Conteneurs dans le menu de gauche, situé sous Stockage de données. Dans l’écran qui s’affiche, sélectionnez + Conteneur. Donnez au conteneur le nom exemple de données et laissez le Niveau d’accès public par défaut.

   

5. Une fois votre conteneur créé, sélectionnez-le. Sélectionnez ensuite le bouton Charger pour sélectionner les fichiers .txt et .json que vous avez téléchargés précédemment.

   

L'exemple de jeu de données fourni contient 20 accords de prêt. Chaque accord comprend deux parties : un prêteur et un emprunteur. Vous pouvez utiliser l’exemple de fichier fourni pour extraire les informations pertinentes relatives aux deux parties, la date du contrat, le montant du prêt et le taux d’intérêt.

Récupération des clés et du point de terminaison de la ressource

1. Accédez à la page de vue d’ensemble de votre ressource dans le portail Azure

2. Dans le menu de gauche, sélectionnez Clés et point de terminaison. Le point de terminaison et la clé sont utilisés pour les demandes d’API.

   

Créer un projet NER personnalisé

Une fois votre ressource et votre compte de stockage configurés, créez un projet NER personnalisé. Un projet est une zone de travail qui vous permet de créer des modèles ML personnalisés en fonction de vos données. Votre projet est accessible à vous et à d’autres personnes qui ont accès à la ressource de langue Azure utilisée.

Utilisez le fichier d’étiquettes que vous avez téléchargé à partir des exemples de données à l’étape précédente et ajoutez-le au corps de la requête suivante.

Déclencher un travail d’importation de projet

Soumettez une demande POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour importer votre fichier d’étiquettes. Vérifiez que votre fichier d’étiquettes respecte le format accepté.

Si un projet portant le même nom existe déjà, les données de ce projet sont remplacées.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}

Espace réservé	Valeur	Exemple
{ENDPOINT}	Point de terminaison pour l’authentification de votre demande d’API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nom de votre projet. Cette valeur respecte la casse.	myProject
{API-VERSION}	Version de l’API que vous appelez. La valeur référencée ici est pour la dernière version publiée. Pour plus d’informations, consultezCycle de vie du modèle.	2022-05-01

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Clé	Valeur
Ocp-Apim-Subscription-Key	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

body

Utilisez le code JSON suivant dans votre demande. Remplacez les valeurs d’espace réservé par vos propres valeurs.

{
    "projectFileVersion": "{API-VERSION}",
    "stringIndexType": "Utf16CodeUnit",
    "metadata": {
        "projectName": "{PROJECT-NAME}",
        "projectKind": "CustomEntityRecognition",
        "description": "Trying out custom NER",
        "language": "{LANGUAGE-CODE}",
        "multilingual": true,
        "storageInputContainerName": "{CONTAINER-NAME}",
        "settings": {}
    },
    "assets": {
    "projectKind": "CustomEntityRecognition",
        "entities": [
            {
                "category": "Entity1"
            },
            {
                "category": "Entity2"
            }
        ],
        "documents": [
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "entities": [
                    {
                        "regionOffset": 0,
                        "regionLength": 500,
                        "labels": [
                            {
                                "category": "Entity1",
                                "offset": 25,
                                "length": 10
                            },
                            {
                                "category": "Entity2",
                                "offset": 120,
                                "length": 8
                            }
                        ]
                    }
                ]
            },
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "entities": [
                    {
                        "regionOffset": 0,
                        "regionLength": 100,
                        "labels": [
                            {
                                "category": "Entity2",
                                "offset": 20,
                                "length": 5
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Clé	Espace réservé	Valeur	Exemple
api-version	{API-VERSION}	Version de l’API que vous appelez. La version utilisée ici doit être la même version d’API dans l’URL. En savoir plus sur les autres versions d’API disponibles	2022-03-01-preview
projectName	{PROJECT-NAME}	Nom de votre projet. Cette valeur respecte la casse.	myProject
projectKind	CustomEntityRecognition	Type de projet.	CustomEntityRecognition
language	{LANGUAGE-CODE}	Chaîne spécifiant le code de langue des documents utilisés dans votre projet. Si votre projet est un projet multilingue, choisissez le code de langue de la plupart des documents.	en-us
multilingual	true	Valeur booléenne permettant à l’ensemble de données de contenir des documents dans plusieurs langues. Quand votre modèle est déployé, vous pouvez interroger le modèle dans n’importe quelle langue prise en charge (pas nécessairement incluse dans vos documents d’apprentissage). Consultez Prise en charge de la langue pour plus d’informations sur la prise en charge multilingue.	true
storageInputContainerName	{CONTAINER-NAME}	Nom de votre conteneur de stockage Azure contenant vos documents chargés.	myContainer
entities		Tableau contenant tous les types d’entités que vous avez dans le projet et extraits de vos documents.
documents		Tableau contenant tous les documents de votre projet et la liste des entités étiquetées dans chaque document.	[]
location	{DOCUMENT-NAME}	Emplacement des documents dans le conteneur de stockage.	doc1.txt
dataset	{DATASET}	Jeu de test dans lequel ce fichier est placé lors du fractionnement avant l’entraînement. Pour plus d’informations, consultezComment entraîner un modèle. Les valeurs possibles pour ce champ sont Train et Test.	Train

Une fois que vous avez envoyé votre demande d’API, vous recevez une 202 réponse indiquant que le travail a été envoyé correctement. Dans les en-têtes de réponse, extrayez la valeur operation-location. Voici un exemple de format :

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} sert à identifier votre demande, car cette opération est asynchrone. Vous utilisez cette URL pour obtenir l’état de la tâche d’importation.

Scénarios d’erreur possibles pour cette requête :

• La ressource sélectionnée n’a pas les autorisations appropriées pour le compte de stockage.
• Le storageInputContainerName spécifié n’existe pas.
• Le code de langue utilisé est non valide ou si le type de code de langue n’est pas une chaîne.
• La valeur multilingual est une chaîne et non pas une valeur booléenne.

Obtenir l’état de la tâche d’importation

Utilisez la requête GET suivante pour obtenir l’état de l’importation de votre projet. Remplacez les valeurs d’espace réservé par vos propres valeurs.

URL de la demande

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

Espace réservé	Valeur	Exemple
{ENDPOINT}	Point de terminaison pour l’authentification de votre demande d’API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nom de votre projet. Cette valeur respecte la casse.	myProject
{JOB-ID}	ID permettant de localiser l’état d’apprentissage de votre modèle. Il s’agit de la valeur d’en-tête location que vous avez reçue à l’étape précédente.	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION}	Version de l’API que vous appelez. La valeur référencée correspond à la dernière version publiée. Pour plus d’informations, consultezCycle de vie du modèle.	2022-05-01

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Clé	Valeur
Ocp-Apim-Subscription-Key	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

Entraîner votre modèle

En règle générale, après avoir créé un projet, vous commencez à ajouter des étiquettes aux documents qui se trouvent dans le conteneur connecté à votre projet. Pour ce guide de démarrage rapide, vous avez importé un exemple de jeu de données étiqueté et initialisé votre projet avec l’exemple de fichier de balises JSON.

Démarrer un travail d’apprentissage

Une fois votre projet importé, vous pouvez commencer à entraîner votre modèle.

Envoyez une requête POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour envoyer un travail d’apprentissage. Remplacez les valeurs d’espace réservé par vos propres valeurs.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}

Espace réservé	Valeur	Exemple
{ENDPOINT}	Point de terminaison pour l’authentification de votre demande d’API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nom de votre projet. Cette valeur respecte la casse.	myProject
{API-VERSION}	Version de l’API que vous appelez. La valeur référencée correspond à la dernière version publiée. Pour plus d’informations, consultezCycle de vie du modèle.	2022-05-01

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Clé	Valeur
Ocp-Apim-Subscription-Key	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

Corps de la demande

Utilisez le code JSON suivant dans le corps de la demande. Le modèle est reçu comme {MODEL-NAME} une fois l’entraînement terminé. Seuls les travaux de formation réussis produisent des modèles.

{
    "modelLabel": "{MODEL-NAME}",
    "trainingConfigVersion": "{CONFIG-VERSION}",
    "evaluationOptions": {
        "kind": "percentage",
        "trainingSplitPercentage": 80,
        "testingSplitPercentage": 20
    }
}

Clé	Espace réservé	Valeur	Exemple
modelLabel	{MODEL-NAME}	Nom du modèle attribué à votre modèle une fois qu'il a été entraîné avec succès.	myModel
trainingConfigVersion	{CONFIG-VERSION}	Il s’agit de la version du modèle utilisée pour entraîner le modèle.	2022-05-01
evaluationOptions		Option permettant de fractionner vos données entre des jeux d’entraînement et de test.	{}
kind	percentage	Méthodes de fractionnement. Les valeurs possibles sont percentage ou manual. Pour plus d’informations, consultezComment entraîner un modèle.	percentage
trainingSplitPercentage	80	Pourcentage de vos données étiquetées à inclure dans le jeu d’entraînement. La valeur recommandée est 80.	80
testingSplitPercentage	20	Pourcentage de vos données étiquetées à inclure dans le jeu de test. La valeur recommandée est 20.	20

Une fois que vous avez envoyé votre demande d’API, vous recevez une 202 réponse indiquant que le travail a été envoyé correctement. Dans les en-têtes de réponse, extrayez la valeur location formatée comme suit :

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} sert à identifier votre demande, car cette opération est asynchrone. Vous pouvez utiliser cette URL pour obtenir l’état de l’apprentissage.

Obtenir l’état des travaux d’apprentissage

L’apprentissage peut prendre entre 10 et 30 minutes pour cet exemple de jeu de données. Vous pouvez utiliser la requête suivante pour continuer à vérifier l’état du travail de formation jusqu’à ce qu’il soit terminé avec succès.

Utilisez la requête GET suivante pour obtenir l’état de progression du processus d’apprentissage de votre modèle. Remplacez les valeurs d’espace réservé par vos propres valeurs.

URL de la demande

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

Espace réservé	Valeur	Exemple
{ENDPOINT}	Point de terminaison pour l’authentification de votre demande d’API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nom de votre projet. Cette valeur respecte la casse.	myProject
{JOB-ID}	ID permettant de localiser l’état d’apprentissage de votre modèle. Il s’agit de la valeur d’en-tête location que vous avez reçue à l’étape précédente.	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION}	Version de l’API que vous appelez. La valeur référencée correspond à la dernière version publiée. Pour plus d’informations, consultezCycle de vie du modèle.	2022-05-01

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Clé	Valeur
Ocp-Apim-Subscription-Key	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

Corps de la réponse

Une fois la requête envoyée, vous recevez la réponse suivante.

{
  "result": {
    "modelLabel": "{MODEL-NAME}",
    "trainingConfigVersion": "{CONFIG-VERSION}",
    "estimatedEndDateTime": "2022-04-18T15:47:58.8190649Z",
    "trainingStatus": {
      "percentComplete": 3,
      "startDateTime": "2022-04-18T15:45:06.8190649Z",
      "status": "running"
    },
    "evaluationStatus": {
      "percentComplete": 0,
      "status": "notStarted"
    }
  },
  "jobId": "{JOB-ID}",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

Déployer votre modèle

En règle générale, après l’entraînement d’un modèle, vous passez en revue les détails de l’évaluation et vous apportez des améliorations si nécessaire. Dans ce guide de démarrage rapide, vous venez de déployer votre modèle et de le rendre disponible pour essayer dans Language Studio, ou vous pouvez appeler l’API de prédiction.

Démarrer le travail de déploiement

Envoyez une requête PUT en utilisant l’URL, les en-têtes et le corps JSON suivants pour envoyer un travail de déploiement. Remplacez les valeurs d’espace réservé par vos propres valeurs.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}

Espace réservé	Valeur	Exemple
{ENDPOINT}	Point de terminaison pour l’authentification de votre demande d’API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nom de votre projet. Cette valeur respecte la casse.	myProject
{DEPLOYMENT-NAME}	Nom de votre déploiement. Cette valeur respecte la casse.	staging
{API-VERSION}	Version de l’API que vous appelez. La valeur référencée correspond à la dernière version publiée. Pour plus d’informations, consultezCycle de vie du modèle.	2022-05-01

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Clé	Valeur
Ocp-Apim-Subscription-Key	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

Corps de la demande

Utilisez le code JSON suivant dans le corps de la demande. Utilisez le nom du modèle que vous attribuez au déploiement.

{
  "trainedModelLabel": "{MODEL-NAME}"
}

Clé	Espace réservé	Valeur	Exemple
trainedModelLabel	{MODEL-NAME}	Nom du modèle affecté à votre déploiement. Vous pouvez uniquement attribuer des modèles entraînés avec succès. Cette valeur respecte la casse.	myModel

Une fois que vous avez envoyé votre demande d’API, vous recevez une 202 réponse indiquant que le travail a été envoyé correctement. Dans les en-têtes de réponse, extrayez la valeur operation-location formatée comme suit :

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} sert à identifier votre demande, car cette opération est asynchrone. Vous pouvez utiliser cette URL pour obtenir l’état du déploiement.

Obtenir l’état du travail de déploiement

Utilisez la requête GET suivante pour interroger l’état du travail de déploiement. Vous pouvez vous servir de l’URL reçue à l’étape précédente ou remplacer les valeurs d’espace réservé par les vôtres.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

Espace réservé	Valeur	Exemple
{ENDPOINT}	Point de terminaison pour l’authentification de votre demande d’API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nom de votre projet. Cette valeur respecte la casse.	myProject
{DEPLOYMENT-NAME}	Nom de votre déploiement. Cette valeur respecte la casse.	staging
{JOB-ID}	ID permettant de localiser l’état d’apprentissage de votre modèle. Elle se trouve dans la location valeur d’en-tête que vous avez reçue à l’étape précédente.	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION}	Version de l’API que vous appelez. La valeur référencée correspond à la dernière version publiée. Pour plus d’informations, consultezCycle de vie du modèle.	2022-05-01

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Clé	Valeur
Ocp-Apim-Subscription-Key	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

Corps de la réponse

Une fois la requête envoyée, vous recevez la réponse suivante. Continuez à interroger ce point de terminaison jusqu’à ce que le paramètre status passe à « réussi ». Vous devez normalement obtenir un code 200 pour indiquer la réussite de la demande.

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Extraire des entités personnalisées

Une fois votre modèle déployé, vous pouvez commencer à l’utiliser pour extraire des entités de votre texte à l’aide de l’API de prédiction. Dans l’exemple de jeu de données, téléchargé précédemment, vous trouverez des documents de test que vous pouvez utiliser à cette étape.

Envoyer une tâche de NER personnalisée

Utilisez cette requête POST pour démarrer une tâche de classification de texte.

{ENDPOINT}/language/analyze-text/jobs?api-version={API-VERSION}

Espace réservé	Valeur	Exemple
{ENDPOINT}	Point de terminaison pour l’authentification de votre demande d’API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION}	Version de l’API que vous appelez. La valeur référencée correspond à la dernière version publiée. Pour plus d’informations, consultezCycle de vie du modèle.	2022-05-01

headers

Clé	Valeur
Ocp-Apim-Subscription-Key	Clé qui fournit l’accès à cette API.

body

{
  "displayName": "Extracting entities",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomEntityRecognition",
      "taskName": "Entity Recognition",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

Clé	Espace réservé	Valeur	Exemple
displayName	{JOB-NAME}	Nom de votre travail.	MyJobName
documents	[{},{}]	Liste des documents sur lesquels exécuter des tâches.	[{},{}]
id	{DOC-ID}	Nom ou ID du document.	doc1
language	{LANGUAGE-CODE}	Chaîne spécifiant le code de langue du document. Si cette clé n’est pas spécifiée, le service suppose la langue par défaut du projet sélectionné lors de la création du projet. Pour obtenir la liste des codes de langue pris en charge, consultez Prise en charge linguistique.	en-us
text	{DOC-TEXT}	Tâche de document sur laquelle exécuter les tâches.	Lorem ipsum dolor sit amet
tasks		Liste des tâches à effectuer.	[]
taskName	CustomEntityRecognition	Nom de la tâche	CustomEntityRecognition
parameters		Liste de paramètres à passer à la tâche.
project-name	{PROJECT-NAME}	Nom de votre projet. Cette valeur respecte la casse.	myProject
deployment-name	{DEPLOYMENT-NAME}	Nom de votre déploiement. Cette valeur respecte la casse.	prod

response

Vous recevez une réponse 202 indiquant que votre tâche a été envoyée avec succès. Dans les en-têtes de réponse, extrayez operation-location. operation-location est au format suivant :

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

Vous pouvez utiliser cette URL pour interroger l’état d’achèvement de la tâche et obtenir les résultats une fois la tâche terminée.

Obtenir les résultats de la tâche

Utilisez la demande GET suivante pour interroger l’état/les résultats de la tâche de reconnaissance d’entité personnalisée.

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

Espace réservé	Valeur	Exemple
{ENDPOINT}	Point de terminaison pour l’authentification de votre demande d’API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION}	Version de l’API que vous appelez. La valeur référencée correspond à la dernière version publiée. Pour plus d’informations, consultezCycle de vie du modèle.	2022-05-01

headers

Clé	Valeur
Ocp-Apim-Subscription-Key	Clé qui fournit l’accès à cette API.

Corps de la réponse

La réponse est un document JSON avec les paramètres suivants.

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxx-xxxxx-xxxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "EntityRecognitionLROResults",
        "taskName": "Recognize Entities",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "entities": [
                {
                  "category": "Event",
                  "confidenceScore": 0.61,
                  "length": 4,
                  "offset": 18,
                  "text": "trip"
                },
                {
                  "category": "Location",
                  "confidenceScore": 0.82,
                  "length": 7,
                  "offset": 26,
                  "subcategory": "GPE",
                  "text": "Seattle"
                },
                {
                  "category": "DateTime",
                  "confidenceScore": 0.8,
                  "length": 9,
                  "offset": 34,
                  "subcategory": "DateRange",
                  "text": "last week"
                }
              ],
              "id": "1",
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

Nettoyer les ressources

Quand vous n’avez plus besoin de votre projet, vous pouvez le supprimer avec la demande DELETE suivante. Remplacez les valeurs d’espace réservé par vos propres valeurs.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}

Espace réservé	Valeur	Exemple
{ENDPOINT}	Point de terminaison pour l’authentification de votre demande d’API.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME}	Nom de votre projet. Cette valeur respecte la casse.	myProject
{API-VERSION}	Version de l’API que vous appelez. La valeur référencée correspond à la dernière version publiée. Pour plus d’informations, consultezCycle de vie du modèle.	2022-05-01

headers

Utilisez l’en-tête suivant pour authentifier votre demande.

Clé	Valeur
Ocp-Apim-Subscription-Key	Clé de votre ressource. Utilisée pour authentifier vos demandes d’API.

Une fois que vous avez envoyé votre demande d’API, vous recevez une 202 réponse indiquant la réussite, ce qui signifie que votre projet est supprimé. Un appel réussi donne un en-tête Operation-Location utilisé pour vérifier l’état du travail.