Comprendre les ressources pour créer un modèle de compréhension du langage courant

9 minutes

Pour utiliser le service Language Understanding afin de développer une solution NLP, vous devez créer une ressource de langue dans Azure. Cette ressource est utilisée pour créer votre modèle et traiter les demandes de prédiction des applications clientes.

Conseil

Le labo de ce module couvre la création d’un modèle pour la compréhension du langage courant. Pour voir des modules plus ciblés sur la classification de texte personnalisée et la reconnaissance d’entités nommées personnalisées, consultez les modules de solution personnalisés Développer des solutions en langage naturel dans le parcours d’apprentissage.

Créer votre modèle

Pour les fonctionnalités qui nécessitent un modèle pour la prédiction, vous devez créer, entraîner et déployer ce modèle avant de l’utiliser pour faire une prédiction. Cette création et cet entraînement apprennent au service Azure AI Language ce qu’il faut rechercher.

Tout d’abord, vous devez créer votre ressource Azure AI Language dans le portail Azure. Ensuite :

Recherchez Azure AI services.
Recherchez et sélectionnez Service de langage.
Sélectionnez Créer sous leService de langage.
Renseignez les détails nécessaires, en choisissant la région la plus proche de vous géographiquement (pour de meilleures performances) et en lui donnant un nom unique.

Une fois cette ressource créée, vous avez besoin d’une clé et du point de terminaison. Ils se trouvent à gauche sous Clés et point de terminaison dans la page Vue d’ensemble de la ressource.

Utiliser Language Studio

Pour une méthode plus visuelle de création, d’entraînement et de déploiement de votre modèle, utilisez Language Studio pour effectuer chacune de ces étapes. Dans la page principale, vous pouvez choisir de créer un projet de compréhension du langage courant. Une fois le projet créé, appliquez le même processus que ci-dessus pour créer, entraîner et déployer votre modèle.

Le labo de ce module vous guide dans l’utilisation de Language Studio pour créer votre modèle. Pour en savoir plus, consultez le guide de démarrage rapide de Language Studio

Utiliser l’API REST

Une des méthodes pour créer votre modèle est d’utiliser l’API REST. Le modèle consiste à créer votre projet, importer des données, et entraîner, déployer, puis utiliser votre modèle.

Ces tâches sont effectuées de manière asynchrone. Vous devez envoyer une demande à l’URI approprié pour chaque étape, puis envoyer une autre demande pour obtenir l’état de ce travail.

Par exemple, si vous voulez déployer un modèle pour un projet de compréhension du langage courant, vous envoyez le travail de déploiement, puis vérifiez son état.

Authentification

Pour chaque appel à votre ressource Azure AI Language, vous authentifiez la demande en fournissant l’en-tête suivant.

Clé	Valeur
`Ocp-Apim-Subscription-Key`	Clé de votre ressource

Demander le déploiement

Envoyez une demande POST au point de terminaison suivant.

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

Espace réservé	Valeur	Exemple
`{ENDPOINT}`	Le point de terminaison de votre ressource Azure AI Language	`https://<your-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	`2022-05-01`

Ajoutez le body suivant à votre demande.

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

Espace réservé	Valeur
`{MODEL-NAME}`	Nom du modèle qui est attribué à votre déploiement. Cette valeur respecte la casse.

Quand votre demande est envoyée, vous recevez une réponse 202 avec l’en-tête de réponse operation-location. Cet en-tête a une URL qui permet de demander l’état, dont le format est :

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

Obtenir l’état de déploiement

Envoyez une demande GET à l’URL à partir de l’en-tête de réponse ci-dessus. Les valeurs sont déjà remplies à partir de la demande de déploiement initiale.

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

Espace réservé	Valeur
`{ENDPOINT}`	Point de terminaison pour l’authentification de votre demande d’API
`{PROJECT-NAME}`	Nom de votre projet (sensible à la casse)
`{DEPLOYMENT-NAME}`	Nom de votre déploiement (sensible à la casse)
`{JOB-ID}`	ID pour localiser l’état d’entraînement de votre modèle, il se trouve dans la valeur d’en-tête détaillée ci-dessus, dans la demande de déploiement
`{API-VERSION}`	Version de l’API que vous appelez

Le corps de la réponse donne les détails de l’état du déploiement. Le champ status a la valeur réussite une fois le déploiement terminé.

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"String",
    "lastUpdatedDateTime":"String",
    "expirationDateTime":"String",
    "status":"running"
}

Pour voir la procédure pas à pas complète de chaque étape avec des exemples de demandes, consultez le guide de démarrage rapide de la compréhension du langage courant.

Interroger votre modèle

Pour interroger votre modèle pour une prédiction, vous pouvez utiliser des kits de développement logiciel (SDK) en C# ou Python, ou utiliser l’API REST.

Interroger à l’aide de kits de développement logiciel (SDK)

Pour interroger votre modèle à l’aide d’un kit de développement logiciel (SDK), vous devez d’abord créer votre client. Une fois que vous avez votre client, vous l’utilisez pour appeler le point de terminaison approprié.

var languageClient = new TextAnalyticsClient(endpoint, credentials);
var response = languageClient.ExtractKeyPhrases(document);

language_client = TextAnalyticsClient(
            endpoint=endpoint, 
            credential=credentials)
response = language_client.extract_key_phrases(documents = documents)[0]

D’autres fonctionnalités de langage, telles que la compréhension du langage conversationnel, exigent que la requête soit formulée et envoyée différemment.

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = userText,
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,
        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};
Response response = await client.AnalyzeConversationAsync(RequestContent.Create(data));

result = client.analyze_conversation(
    task={
        "kind": "Conversation",
        "analysisInput": {
            "conversationItem": {
                "participantId": "1",
                "id": "1",
                "modality": "text",
                "language": "en",
                "text": query
            },
            "isLoggingEnabled": False
        },
        "parameters": {
            "projectName": cls_project,
            "deploymentName": deployment_slot,
            "verbose": True
        }
    }
)

Interroger à l’aide de l’API REST

Pour interroger votre modèle à l’aide de REST, créez une requête POST sur l’URL appropriée en spécifiant le corps approprié. Pour les fonctionnalités intégrées comme la détection de langue ou l’analyse des sentiments, vous interrogez le point de terminaison analyze-text.

Conseil

Rappelez-vous que chaque demande doit être authentifiée avec la clé de votre ressource Azure AI Language dans l’en-tête Ocp-Apim-Subscription-Key

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

Paramètre substituable	Valeur
`{ENDPOINT}`	Point de terminaison pour l’authentification de votre demande d’API
`{API-VERSION}`	Version de l’API que vous appelez

Dans le corps de cette demande, vous devez spécifier le paramètre kind, qui indique au service le type de compréhension du langage que vous demandez.

Si vous voulez détecter la langue, par exemple, le corps JSON ressemble à ce qui suit.

{
    "kind": "LanguageDetection",
    "parameters": {
        "modelVersion": "latest"
    },
    "analysisInput":{
        "documents":[
            {
                "id":"1",
                "text": "This is a document written in English."
            }
        ]
    }
}

D’autres fonctionnalités linguistiques, comme la compréhension du langage courant, nécessitent de router la requête vers un autre point de terminaison. Par exemple, la demande de compréhension du langage courant est envoyée au point suivant.

{ENDPOINT}/language/:analyze-conversations?api-version={API-VERSION}

Espace réservé	Valeur
`{ENDPOINT}`	Point de terminaison pour l’authentification de votre demande d’API
`{API-VERSION}`	Version de l’API que vous appelez

Cette demande comprend un corps JSON similaire à ce qui suit.

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "id": "1",
      "participantId": "1",
      "text": "Sample text"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "stringIndexType": "TextElement_V8"
  }
}

Espace réservé	Valeur
`{PROJECT-NAME}`	Nom du projet dans lequel vous avez créé votre modèle
`{DEPLOYMENT-NAME}`	Nom de votre déploiement

Exemple de réponse

La réponse de requête d’un kit de développement logiciel (SDK) est l’objet retourné, qui varie en fonction de la fonctionnalité (par exemple, dans response.key_phrases ou response.Value). L’API REST retourne JSON similaire à ce qui suit.

{
    "kind": "KeyPhraseExtractionResults",
    "results": {
        "documents": [{
            "id": "1",
            "keyPhrases": ["modern medical office", "Dr. Smith", "great staff"],
            "warnings": []
        }],
        "errors": [],
        "modelVersion": "{VERSION}"
    }
}

Pour d’autres modèles comme la compréhension du langage conversationnel, un exemple de réponse à votre requête serait similaire à ce qui suit.

{
  "kind": "ConversationResult",
  "result": {
    "query": "String",
    "prediction": {
      "topIntent": "intent1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text",
          "offset": 7,
          "length": 4,
          "confidenceScore": 1
        }
      ]
    }
  }
}

Les kits de développement logiciel (SDK) pour Python et C# retournent JSON qui est très similaire à la réponse REST.

Pour voir la documentation complète des fonctionnalités, notamment des exemples et des guides pratiques, consultez les pages de la documentation Azure AI Language.