Démarrage rapide : compréhension du langage courant

  • Article

Utilisez cet article pour commencer à comprendre le langage courant à l’aide de Language Studio et de l’API REST. Pour essayer un exemple, procédez comme suit.

Prérequis

Connexion à Language Studio

  1. Accédez à Language Studio et connectez-vous avec votre compte Azure.

  2. Dans la fenêtre Choose a language resource (Choisir une ressource de langue) qui s’affiche, recherchez votre abonnement Azure, puis choisissez votre ressource de langue. Si vous n’avez pas de ressource, vous pouvez en créer une nouvelle.

    Détails de l’instance Valeur requise
    Abonnement Azure Votre abonnement Azure.
    Groupe de ressources Azure Nom de votre groupe de ressources Azure.
    Nom de la ressource Azure Nom de votre ressource Azure.
    Emplacement Une des régions prises en charge pour votre ressource Language. Par exemple, « USA Ouest 2 ».
    Niveau tarifaire Un des niveaux tarifaires valides pour votre ressource Language. Vous pouvez utiliser le niveau tarifaire gratuit (F0) pour tester le service.

    A screenshot showing the resource selection screen in Language Studio.

Créer un projet de compréhension du langage courant

Une fois que vous avez sélectionné une ressource Language, créez un projet de compréhension du langage courant. 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. Seuls les utilisateurs qui disposent d’un accès à la ressource de langue utilisée peuvent accéder à votre projet.

Pour ce guide de démarrage rapide, vous pouvez télécharger cet exemple de fichier projet et l’importer. Ce projet peut prédire les commandes prévues à partir de l’entrée utilisateur, par exemple : lecture d’e-mails, suppression d’e-mails et ajout d’une pièce jointe à un e-mail.

  1. Sous Comprendre les questions et le langage courant, dans Language Studio, sélectionnez Compréhension du langage courant.

    A screenshot showing the location of Custom Language Understanding in the Language Studio landing page.

  2. Cela vous amène à la page Projets de compréhension du langage courant. En regard du bouton Création d’un projet, sélectionnez Importer.

    A screenshot showing the conversation project page in Language Studio.

  3. Dans la fenêtre qui s’affiche, chargez le fichier JSON que vous souhaitez importer. Assurez-vous que votre fichier suit le format JSON pris en charge.

Une fois le chargement terminé, vous accédez à la page Définition du schéma. Pour ce guide de démarrage rapide, le schéma est déjà généré et les énoncés sont déjà étiquetés avec des intentions et des entités.

Entraîner votre modèle

En règle générale, après avoir créé un projet, vous devez générer un schéma et étiqueter des énoncés. Pour ce guide de démarrage rapide, nous avons déjà importé un projet prêt avec un schéma généré et des énoncés étiquetés.

Pour entraîner un modèle, vous devez démarrer un travail d’entraînement. La sortie d’un travail d’entraînement réussi est votre modèle formé.

Pour commencer à effectuer l’apprentissage de votre modèle à partir de Language Studio :

  1. Dans le menu de gauche, sélectionnez Effectuer l’apprentissage du modèle.

  2. Sélectionnez Démarrer un travail de formation dans le menu supérieur.

  3. Sélectionnez Entraîner un nouveau modèle, puis entrez le nom d’un nouveau modèle dans la zone de texte. Sinon, pour remplacer un modèle existant par un modèle entraîné sur les nouvelles données, sélectionnez Remplacer un modèle existant, puis sélectionnez un modèle existant. La remplacement d’un modèle entraîné est irréversible. Toutefois, cela n’affecte pas vos modèles déployés tant que vous ne déployez pas le nouveau modèle.

  4. Sélectionnez le mode d’entraînement. Vous pouvez choisir l’Entraînement standard pour un entraînement plus rapide, mais il n’est disponible que pour l’anglais. Vous pouvez aussi opter pour l’Entraînement avancé, qui est pris en charge pour d’autres langues et les projets multilingues, mais les temps d’entraînement sont plus longs. Apprenez-en davantage sur les modes d’apprentissage.

  5. Sélectionnez une méthode de fractionnement des données. Vous pouvez choisir l’option Fractionnement automatique du jeu de test à partir des données d’entraînement. Dans ce cas, le système fractionne vos énoncés en jeux d’apprentissage et de test, selon les pourcentages spécifiés. Vous pouvez aussi Utiliser un fractionnement manuel des données d’entraînement et de test. Cette option est activée uniquement si vous avez ajouté des énoncés à votre jeu de test pendant l’étiquetage de vos énoncés.

  6. Sélectionner le bouton Train (Entraîner).

    A screenshot showing the training page in Language Studio.

  7. Sélectionnez l’ID du travail d’entraînement dans la liste. Un volet latéral s’affichera, dans lequel vous pourrez consulter la progression de l’entraînement, l’état du travail et d’autres détails concernant ce travail.

    Notes

    • Seuls les emplois de formation achevés avec succès génèrent des modèles.
    • L’entraînement peut prendre entre quelques minutes et quelques heures, selon le nombre d’énoncés.
    • Vous ne pouvez avoir qu’un seul travail d’entraînement en cours d’exécution à la fois. Vous ne pouvez pas lancer d’autres travaux d’entraînement dans le même projet tant que le travail en cours d’exécution n’est pas terminé.
    • Le machine learning utilisé pour entraîner les modèles est régulièrement mis à jour. Pour effectuer l’apprentissage sur une version de configuration précédente, sélectionnez Cliquez ici pour modifier à partir de la page Démarrer un travail d’apprentissage, puis choisissez une version précédente.

Déployer votre modèle

En général, après avoir formé un modèle, vous examinez les détails de son évaluation. Dans ce guide de démarrage rapide, vous allez simplement déployer votre modèle et le rendre disponible pour pouvoir l’essayer dans Language Studio. Vous pouvez également appeler l’API de prévision.

Pour déployer votre modèle à partir de Language Studio :

  1. Dans le menu de gauche, sélectionnez Déploiement d’un modèle.

  2. Sélectionnez Ajouter un déploiement pour démarrer l’Assistant Ajouter un déploiement.

    A screenshot showing the model deployment button in Language Studio.

  3. Sélectionnez Créer un nom de déploiement pour créer un nouveau déploiement et attribuer un modèle entraîné dans la liste déroulante ci-dessous. Sinon, vous pouvez sélectionner Remplacer un nom de déploiement existant pour remplacer efficacement le modèle utilisé par un déploiement existant.

    Notes

    Le remplacement d’un déploiement existant ne nécessite pas de modifier votre appel de l’API de prédiction. Toutefois, les résultats obtenus sont basés sur le modèle qui vient d’être attribué.

    A screenshot showing the screen for adding a new deployment in Language Studio.

  4. Sélectionnez un modèle entraîné dans la liste déroulante Modèle.

  5. Sélectionnez Déployer pour démarrer le travail de déploiement.

  6. Une fois le déploiement réussi, une date d’expiration s’affiche à côté de celui-ci. L’expiration du déploiement correspond au moment où votre modèle déployé n’est plus disponible pour la prédiction. Cela se produit généralement douze mois après l’expiration d’une configuration de l’apprentissage.

Tester un modèle déployé

Pour tester vos modèles déployés à partir de Language Studio :

  1. Sélectionnez Test des déploiements dans le menu de gauche.

  2. Pour les projets multilingues, sélectionnez la langue de l’énoncé que vous testez dans la liste déroulante Sélectionnez la langue du texte.

  3. Dans la liste déroulante Nom du déploiement, sélectionnez le nom de déploiement correspondant au modèle que vous souhaitez tester. Vous pouvez uniquement tester les modèles qui sont attribués aux déploiements.

  4. Dans la zone de texte, entrez un énoncé à tester. Par exemple, si vous avez créé une application pour les énoncés liés aux e-mails, vous pouvez entrez Supprimer cet e-mail.

  5. En haut de la page, sélectionnez Exécuter le test.

  6. Après avoir exécuté le test, vous devriez voir la réponse du modèle dans le résultat. Vous pouvez afficher les résultats en mode Cartes d’entités ou au format JSON.

Nettoyer les ressources

Une fois que vous n’avez plus besoin de votre projet, vous pouvez le supprimer à l’aide de Language Studio. Sélectionnez Projets dans le menu de navigation de gauche, sélectionnez le projet que vous voulez supprimer, puis cliquez sur Supprimer dans le menu du haut.

Prérequis

Créer une ressource à partir du portail Azure

  1. Connectez-vous au Portail Azure pour créer une ressource Azure AI Language.

  2. Sélectionnez Créer une ressource

  3. Dans la fenêtre qui s’affiche, recherchez Service de langage

  4. Sélectionnez Créer

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

    Détails de l’instance Valeur requise
    Région Une des régions prises en charge pour votre ressource Language.
    Nom Nom obligatoire pour votre ressource Language
    Niveau tarifaire Un des niveaux tarifaires pris en charge pour votre ressource de langue.

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

  1. Accédez à la page de présentation de votre ressource sur le Portail Azure.

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

    A screenshot showing the key and endpoint page in the Azure portal

Importer un nouvel exemple de projet CLU

Une fois que vous avez créé une ressource de langue, créez un projet de compréhension du langage courant. 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. Seuls les utilisateurs qui disposent d’un accès à la ressource de langue utilisée peuvent accéder à votre projet.

Pour ce guide de démarrage rapide, vous pouvez télécharger cet exemple de projet et l’importer. Ce projet peut prédire les commandes prévues à partir de l’entrée utilisateur, par exemple : lecture d’e-mails, suppression d’e-mails et ajout d’une pièce jointe à un e-mail.

Déclencher le travail d’importation de projet

Envoyez une requête POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour importer votre projet.

URL de la demande

Utilisez l’URL suivante quand vous créez votre demande d’API. Remplacez les valeurs d’espace réservé par vos propres valeurs.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/: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 et doit correspondre au nom du projet dans le fichier JSON que vous importez. EmailAppDemo
{API-VERSION} Version de l’API que vous appelez. 2023-04-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

Le corps JSON que vous envoyez est similaire à l’exemple suivant. Pour plus d’informations sur l’objet JSON, consultez la documentation de référence .

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Conversation",
    "settings": {
      "confidenceThreshold": 0.7
    },
    "projectName": "{PROJECT-NAME}",
    "multilingual": true,
    "description": "Trying out CLU",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Conversation",
    "intents": [
      {
        "category": "intent1"
      },
      {
        "category": "intent2"
      }
    ],
    "entities": [
      {
        "category": "entity1"
      }
    ],
    "utterances": [
      {
        "text": "text1",
        "dataset": "{DATASET}",
        "intent": "intent1",
        "entities": [
          {
            "category": "entity1",
            "offset": 5,
            "length": 5
          }
        ]
      },
      {
        "text": "text2",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "intent": "intent2",
        "entities": []
      }
    ]
  }
}
Clé Espace réservé Valeur Exemple
{API-VERSION} Version de l’API que vous appelez. 2023-04-01
projectName {PROJECT-NAME} Nom de votre projet. Cette valeur respecte la casse. EmailAppDemo
language {LANGUAGE-CODE} Chaîne spécifiant le code de langue des énoncés utilisés dans votre projet. Si votre projet est multilingue, choisissez le code de langue de la majorité des énoncés. en-us
multilingual true Valeur booléenne qui vous permet d’utiliser des documents en plusieurs langues dans votre jeu de données. Lorsque votre modèle est déployé, vous pouvez interroger le modèle dans n’importe quelle langage prise en charge incluant les langages qui ne sont pas inclus dans vos documents d’apprentissage. true
dataset {DATASET} Consultez Comment entraîner un modèle pour plus d’informations sur le fractionnement de vos données en un jeu de test et un jeu d’entraînement. Les valeurs possibles pour cette propriété sont Train et Test. Train

En cas de requête réussie, la réponse de l’API contient un operation-location en-tête avec une URL que vous pouvez utiliser pour vérifier l’état du travail d’importation. Il est au format suivant :

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

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

Lorsque vous envoyez une requête d’importation de projet réussie, l’URL de demande complète permettant de vérifier l’état du travail d’importation (y compris votre point de terminaison, le nom du projet et l’ID de travail) est contenue dans l’en-tête de operation-location la réponse.

Utilisez la requête GET suivante pour interroger l’état de la tâche d’importation. 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-conversations/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 de votre travail d’importation. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} Version de l’API que vous appelez. 2023-04-01

headers

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

Clé Description Valeur
Ocp-Apim-Subscription-Key Clé de votre ressource. Utilisée pour authentifier vos demandes d’API. {YOUR-PRIMARY-RESOURCE-KEY}

Response body

Une fois que vous avez envoyé la requête, vous recevrez la réponse suivante. Continuez à interroger ce point de terminaison jusqu’à ce que le paramètre status passe à « réussi ».

{
  "jobId": "xxxxx-xxxxx-xxxx-xxxxx",
  "createdDateTime": "2022-04-18T15:17:20Z",
  "lastUpdatedDateTime": "2022-04-18T15:17:22Z",
  "expirationDateTime": "2022-04-25T15:17:20Z",
  "status": "succeeded"
}

Commencer l’entraînement de votre modèle

En règle générale, après avoir créé un projet, vous devez générer un schéma et étiqueter des énoncés. Pour ce guide de démarrage rapide, nous avons déjà importé un projet prêt avec un schéma généré et des énoncés étiquetés.

Créez une requête POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour envoyer un travail d’apprentissage.

URL de la demande

Utilisez l’URL suivante quand vous créez votre demande d’API. Remplacez les valeurs d’espace réservé par vos propres valeurs.

{ENDPOINT}/language/authoring/analyze-conversations/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. EmailApp
{API-VERSION} Version de l’API que vous appelez. 2023-04-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 l’objet suivant dans votre demande. Le modèle sera nommé d’après la valeur que vous utilisez pour le paramètre une fois la formationmodelLabel terminée.

{
  "modelLabel": "{MODEL-NAME}",
  "trainingMode": "{TRAINING-MODE}",
  "trainingConfigVersion": "{CONFIG-VERSION}",
  "evaluationOptions": {
    "kind": "percentage",
    "testingSplitPercentage": 20,
    "trainingSplitPercentage": 80
  }
}
Clé Espace réservé Valeur Exemple
modelLabel {MODEL-NAME} Nom de votre modèle. Model1
trainingConfigVersion {CONFIG-VERSION} Version du modèle de configuration de formation. Par défaut, la dernière version du modèle est utilisée. 2022-05-01
trainingMode {TRAINING-MODE} Mode d’entraînement à utiliser pour l’entraînement. Les modes pris en charge sont Entraînement standard (entraînement plus rapide, mais uniquement disponible pour l’anglais) et Entraînement avancé (pris en charge pour d’autres langues et les projets multilingues, mais supposant des temps d’entraînement plus longs). Apprenez-en davantage sur les modes d’apprentissage. standard
kind percentage Méthodes de fractionnement. Les valeurs possibles sont percentage ou manual. Pour plus d’informations, consultez Comment entraîner un modèle. percentage
trainingSplitPercentage 80 Pourcentage de vos données étiquetées à inclure dans le jeu d’apprentissage. 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

Notes

Les trainingSplitPercentage et testingSplitPercentage sont nécessaires uniquement si Kind est défini sur percentage. La somme des deux pourcentages doit être égale à 100.

Une fois que vous avez envoyé votre demande d’API, vous recevez une réponse 202 indiquant la réussite. Dans les en-têtes de réponse, extrayez la valeur operation-location. Elle est au format suivant :

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

Vous pouvez utiliser cette URL pour obtenir l’état du travail d’apprentissage.

Obtenir l’état des travaux d’apprentissage

La formation peut prendre du temps, parfois entre 10 et 30 minutes. Vous pouvez utiliser la requête suivante pour continuer à interroger l’état du travail d’apprentissage jusqu’à ce qu’il soit effectué avec succès.

Lorsque vous envoyez une requête de formation réussie, l’URL de demande complète permettant de vérifier l’état du travail (y compris votre point de terminaison, le nom du projet et l’ID de travail) est contenue dans l’en-tête de operation-location la réponse.

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é suivantes par vos valeurs :

URL de la demande

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
Espace réservé Valeur Exemple
{YOUR-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. EmailApp
{JOB-ID} ID de localisation de l’état d’entraînement de votre modèle. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} Version de l’API que vous appelez. 2023-04-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 que vous avez envoyé la demande, vous recevez la réponse suivante. Continuez à interroger ce point de terminaison jusqu’à ce que le paramètre status passe à « réussi ».

{
  "result": {
    "modelLabel": "{MODEL-LABEL}",
    "trainingConfigVersion": "{TRAINING-CONFIG-VERSION}",
    "trainingMode": "{TRAINING-MODE}",
    "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": "xxxxx-xxxxx-xxxx-xxxxx-xxxx",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}
Clé Valeur Exemple
modelLabel Le nom du modèle Model1
trainingConfigVersion Version de configuration de formation. Par défaut, la dernière version est utilisée. 2022-05-01
trainingMode Votre mode d’entraînement sélectionné. standard
startDateTime Le moment où la formation a commencé 2022-04-14T10:23:04.2598544Z
status L’état du travail de formation running
estimatedEndDateTime Durée estimée pour l’achèvement du travail de formation 2022-04-14T10:29:38.2598544Z
jobId Votre ID de travail de formation xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
createdDateTime Date et heure de création d’un travail de formation 2022-04-14T10:22:42Z
lastUpdatedDateTime Date et heure de la dernière mise à jour du travail de formation 2022-04-14T10:23:45Z
expirationDateTime Date et heure d’expiration du travail de formation 2022-04-14T10:22:42Z

Déployer votre modèle

En général, après avoir formé un modèle, vous examinez les détails de son évaluation. Dans ce guide de démarrage rapide, vous allez simplement déployer votre modèle et appeler l’API de prédiction pour interroger les résultats.

Envoyer un travail de déploiement

Créez une requête PUT en utilisant l’URL, les en-têtes et le corps JSON suivants pour commencer à déployer un modèle de compréhension du langage courant.

URL de la demande

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?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} Le nom de votre déploiement. Cette valeur respecte la casse. staging
{API-VERSION} Version de l’API que vous appelez. 2023-04-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

{
  "trainedModelLabel": "{MODEL-NAME}",
}
Clé Espace réservé Valeur Exemple
trainedModelLabel {MODEL-NAME} Nom du modèle qui est attribué à 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 réponse 202 indiquant la réussite. Dans les en-têtes de réponse, extrayez la valeur operation-location. Elle est au format suivant :

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

Vous pouvez utiliser cette URL pour obtenir l’état du travail de déploiement.

Obtenir l’état du travail de déploiement

Lorsque vous envoyez une requête de déploiement réussie, l’URL de demande complète permettant de vérifier l’état du travail (y compris votre point de terminaison, le nom du projet et l’ID de travail) est contenue dans l’en-tête de operation-location la réponse.

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

URL de la demande

{ENDPOINT}/language/authoring/analyze-conversations/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} Le nom de votre déploiement. Cette valeur respecte la casse. staging
{JOB-ID} ID de localisation de l’état d’entraînement de votre modèle. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} Version de l’API que vous appelez. 2023-04-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 que vous avez envoyé la requête, vous recevrez la réponse suivante. Continuez à interroger ce point de terminaison jusqu’à ce que le paramètre status passe à « réussi ».

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

Interrogation du modèle

Une fois votre modèle déployé, vous pouvez commencer à l’utiliser pour faire des prédictions via l’API de prédiction.

Une fois le déploiement terminé, vous pouvez commencer à interroger votre modèle déployé pour effectuer des prédictions.

Créez une demande POST en utilisant l’URL, les en-têtes et le corps JSON suivants pour commencer à tester un modèle de compréhension du langage courant.

URL de la demande

{ENDPOINT}/language/:analyze-conversations?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} La version de l’API que vous appelez. 2023-04-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

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "id": "1",
      "participantId": "1",
      "text": "Text 1"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "stringIndexType": "TextElement_V8"
  }
}
Clé Espace réservé Valeur Exemple
participantId {JOB-NAME} "MyJobName
id {JOB-NAME} "MyJobName
text {TEST-UTTERANCE} Énoncé dont vous souhaitez prédire l’intention et extraire des entités. "Read Matt's email
projectName {PROJECT-NAME} Nom de votre projet. Cette valeur respecte la casse. myProject
deploymentName {DEPLOYMENT-NAME} Nom de votre déploiement. Cette valeur respecte la casse. staging

Une fois que vous avez envoyé la demande, vous recevez la réponse suivante comme prédiction

Response body

{
  "kind": "ConversationResult",
  "result": {
    "query": "Text1",
    "prediction": {
      "topIntent": "inten1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        },
        {
          "category": "intent3",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text1",
          "offset": 29,
          "length": 12,
          "confidenceScore": 1
        }
      ]
    }
  }
}
Clé Exemple de valeur Description
query « Lire l’e-mail de Matt » le texte que vous avez envoyé pour la requête.
topIntent "Read" Intention prédite avec le score de confiance le plus élevé.
intentions [] Liste de toutes les intentions prédites pour le texte de requête, chacune avec un score de confiance.
entities [] tableau contenant la liste des entités extraites du texte de requête.

Réponse de l’API pour un projet de conversations

Dans un projet de conversations, vous obtenez des prédictions à la fois pour vos intentions et pour vos entités qui sont présentes dans votre projet.

  • Les intentions et les entités incluent un score de confiance entre 0,0 et 1,0 associé à la confiance du modèle pour la prédiction d’un certain élément dans votre projet.
  • L’intention avec le score le plus élevé est contenue dans son propre paramètre.
  • Seules les entités prédites apparaissent dans votre réponse.
  • Les entités indiquent :
    • Le texte de l’entité qui a été extraite
    • Le début de son emplacement indiqué par une valeur de décalage
    • La longueur du texte de l’entité indiquée par une valeur de longueur.

Nettoyer les ressources

Une fois que vous n’avez plus besoin de votre projet, vous pouvez le supprimer à l’aide des API.

Créez une requête DELETE en utilisant l’URL, les en-têtes et le corps JSON suivants pour supprimer un projet de compréhension du langage courant.

URL de la demande

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?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. 2023-04-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 requête API, vous recevez une réponse 202 indiquant la réussite, ce qui signifie que votre projet a été supprimé.

Étapes suivantes