Bibliothèque cliente Azure Analyse de texte pour Java - version 5.4.0

  • Article

Azure Cognitive Service for Language est un service cloud qui fournit des fonctionnalités de traitement en langage naturel (NLP) pour comprendre et analyser le texte, et comprend les fonctionnalités main suivantes :

  • Analyse des sentiments
  • Reconnaissance d’entité (entités nommées, liées et informations d’identification personnelle))
  • Détection de la langue
  • Extraction d’expressions clés
  • Analyse de plusieurs actions par document
  • Analyse des entités de soins de santé
  • Résumé de texte abstrait
  • Résumé de texte extractif
  • Reconnaissance d’entité nommée personnalisée
  • Classification de texte personnalisée

| Code sourcePackage (Maven) | Documentation de référence sur les | APIDocumentation | produitÉchantillons

Prise en main

Prérequis

Inclure le package

Inclure le fichier de nomenclature

Incluez le kit azure-sdk-bom à votre projet pour prendre la dépendance sur la version de disponibilité générale de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez LE FICHIER README DE NOMENCLATURE DU KIT DE DÉVELOPPEMENT LOGICIEL AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Incluez ensuite la dépendance directe dans la section des dépendances sans la balise de version.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-textanalytics</artifactId>
  </dependency>
</dependencies>

Inclure une dépendance directe

Si vous souhaitez prendre la dépendance sur une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-textanalytics</artifactId>
    <version>5.4.0</version>
</dependency>

Note: Cette version de la bibliothèque cliente utilise par défaut la 2023-04-01 version du service. Il s’agit d’une version plus récente que 3_0, 3_1 et 2022-05-01.

Ce tableau montre la relation entre les services sdk et les versions d’API prises en charge du service :

Version du SDK Version d’API prise en charge du service
5.3.x 3.0, 3.1, 2022-05-01, 2023-04-01 (par défaut)
5.2.x 3.0, 3.1, 2022-05-01
5.1.x 3.0, 3.1
5.0.x 3.0

Créer une ressource Cognitive Services ou Language Service

Le service Language prend en charge l’accès multiservices et à service unique. Créez une ressource Cognitive Services si vous envisagez d’accéder à plusieurs services Cognitive Services sous un seul point de terminaison/clé. Pour l’accès au service Language uniquement, créez une ressource de service Language.

Vous pouvez créer la ressource à l’aide du portail Azure ou d’Azure CLI en suivant les étapes décrites dans ce document.

Authentifier le client

Pour interagir avec le service Language, vous devez créer une instance du client Analyse de texte. Les clients asynchrones et synchrones peuvent être créés à l’aide TextAnalyticsClientBuilder de l’appel de buildClient() crée un client synchrone tout en buildAsyncClient() créant son équivalent asynchrone.

Vous aurez besoin d’un point de terminaison et d’une clé ou d’une clé AAD TokenCredential pour instancier un objet client.

Recherche du point de terminaison

Vous trouverez le point de terminaison de votre ressource de service Language dans le portail Azure sous « Clés et point de terminaison » ou Azure CLI.

# Get the endpoint for the Language service resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "endpoint"

Créer un client Analyse de texte avec des informations d’identification de clé

Une fois que vous avez la valeur de la clé, fournissez-la sous forme de chaîne à AzureKeyCredential. Vous pouvez le trouver dans le portail Azure sous la section « Clés et point de terminaison » de votre ressource de service Language créée ou en exécutant la commande Azure CLI suivante :

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Utilisez la clé comme paramètre d’informations d’identification pour authentifier le client :

TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildClient();

La bibliothèque cliente Azure Analyse de texte permet de faire pivoter la clé existante.

AzureKeyCredential credential = new AzureKeyCredential("{key}");
TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(credential)
    .endpoint("{endpoint}")
    .buildClient();

credential.update("{new_key}");

Créer un client Analyse de texte avec les informations d’identification Azure Active Directory

Le Kit de développement logiciel (SDK) Azure pour Java prend en charge un package Azure Identity, ce qui facilite l’obtention des informations d’identification à partir de Plateforme d'identités Microsoft.

L’authentification avec AAD nécessite une configuration initiale :

  • Ajouter le package Azure Identity
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.4</version>
</dependency>

Après l’installation, vous pouvez choisir le type d’informations d’identification d’azure.identity à utiliser. Par exemple, DefaultAzureCredential peut être utilisé pour authentifier le client : définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

L’autorisation est la plus simple à l’aide de DefaultAzureCredential. Il trouve les meilleures informations d’identification à utiliser dans son environnement en cours d’exécution. Pour plus d’informations sur l’utilisation de l’autorisation Azure Active Directory avec le service Language, reportez-vous à la documentation associée.

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
TextAnalyticsAsyncClient textAnalyticsAsyncClient = new TextAnalyticsClientBuilder()
    .endpoint("{endpoint}")
    .credential(defaultCredential)
    .buildAsyncClient();

Concepts clés

client Analyse de texte

La bibliothèque cliente Analyse de texte fournit un TextAnalyticsClient et un TextAnalyticsAsyncClient pour effectuer des analyses sur des lots de documents. Il fournit des opérations synchrones et asynchrones pour accéder à une utilisation spécifique du service Language, comme la détection de langue ou l’extraction d’expressions clés.

Entrée

Une entrée de texte, également appelée document, est une unité de document unique à analyser par les modèles prédictifs dans le service Language. Les opérations sur un client Analyse de texte peuvent nécessiter l’analyse d’un seul document ou d’une collection de documents en tant que lot. Consultez Limitations du service pour le document, notamment les limites de longueur du document, la taille maximale des lots et l’encodage de texte pris en charge.

Opération sur plusieurs documents

Pour chaque opération prise en charge, le client Analyse de texte fournit des surcharges de méthode pour prendre un seul document, un lot de documents sous forme de chaînes ou un lot d’objets TextDocumentInput ou DetectLanguageInput . La surcharge du TextDocumentInput lot ou DetectLanguageInput permet aux appelants de donner à chaque document un ID unique, d’indiquer que les documents du lot sont écrits dans différentes langues ou de fournir un indicateur de pays sur la langue du document.

Valeur retournée

Un résultat d’opération, tel que AnalyzeSentimentResult, est le résultat d’une opération de service Language, qui contient une ou des prédictions relatives à un document unique et une liste d’avertissements à l’intérieur de celui-ci. Le type de résultat d’une opération peut également inclure éventuellement des informations sur le document d’entrée et la façon dont il a été traité. Un résultat d’opération contient une isError propriété qui permet d’identifier si une opération exécutée a réussi ou échoué pour le document donné. Lorsque l’opération génère une erreur, vous pouvez simplement appeler getError() pour obtenir TextAnalyticsError ce qui contient la raison de son échec. Si vous souhaitez connaître le nombre de caractères dans votre document ou le nombre de transactions d’opération effectuées, il vous suffit d’appeler getStatistics() pour obtenir le TextDocumentStatistics qui contient les deux informations.

Collection de valeurs de retour

Collection de résultats d’opération, telle que AnalyzeSentimentResultCollection, qui est la collection du résultat de l’analyse de l’opération de sentiment. Il inclut également la version du modèle de l’opération et les statistiques des documents batch.

Remarque : Il est recommandé d’utiliser les méthodes de traitement par lots lorsque vous travaillez sur des environnements de production, car elles vous permettent d’envoyer une requête avec plusieurs documents. C’est plus performant que l’envoi d’une requête pour chaque document.

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches les plus courantes du service Language, notamment :

client Analyse de texte

Le service de langage prend en charge la création de client synchrone et asynchrone à l’aide de TextAnalyticsClientBuilder,

TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildClient();

ou

TextAnalyticsAsyncClient textAnalyticsAsyncClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildAsyncClient();

Analyser les sentiments

Exécutez un modèle prédictif pour identifier le sentiment positif, négatif, neutre ou mixte contenu dans le document ou le lot de documents fourni.

String document = "The hotel was dark and unclean. I like microsoft.";
DocumentSentiment documentSentiment = textAnalyticsClient.analyzeSentiment(document);
System.out.printf("Analyzed document sentiment: %s.%n", documentSentiment.getSentiment());
documentSentiment.getSentences().forEach(sentenceSentiment ->
    System.out.printf("Analyzed sentence sentiment: %s.%n", sentenceSentiment.getSentiment()));

Pour obtenir des exemples sur l’utilisation de l’option AnalyzeSentimentBatch recommandée en production, consultez ici.

Pour obtenir des informations plus précises sur les opinions relatives aux aspects d’un produit/service, également connu sous le nom Analyse des sentiments basée sur les aspects dans le traitement en langage naturel (NLP), consultez l’exemple d’analyse des sentiments avec exploration d’opinions, voir ici.

Reportez-vous à la documentation du service pour une présentation conceptuelle de l’analyse des sentiments.

Détecter la langue

Exécutez un modèle prédictif pour déterminer la langue dans laquelle le document ou le lot de documents fournis sont écrits.

String document = "Bonjour tout le monde";
DetectedLanguage detectedLanguage = textAnalyticsClient.detectLanguage(document);
System.out.printf("Detected language name: %s, ISO 6391 name: %s, confidence score: %f.%n",
    detectedLanguage.getName(), detectedLanguage.getIso6391Name(), detectedLanguage.getConfidenceScore());

Pour obtenir des exemples sur l’utilisation de l’option DetectLanguageBatch recommandée en production, consultez ici. Reportez-vous à la documentation du service pour une présentation conceptuelle de la détection de langue.

Extraire les phrases clés

Exécutez un modèle pour identifier une collection d’expressions significatives trouvées dans le document ou le lot de documents fourni.

String document = "My cat might need to see a veterinarian.";
System.out.println("Extracted phrases:");
textAnalyticsClient.extractKeyPhrases(document).forEach(keyPhrase -> System.out.printf("%s.%n", keyPhrase));

Pour obtenir des exemples sur l’utilisation de l’option ExtractKeyPhrasesBatch recommandée en production, consultez ici. Reportez-vous à la documentation du service pour une présentation conceptuelle de l’extraction de phrases clés.

Reconnaître les entités nommées

Exécutez un modèle prédictif pour identifier une collection d’entités nommées dans le document ou le lot de documents fourni et classer ces entités en catégories telles que personne, emplacement ou organization. Pour plus d’informations sur les catégories disponibles, consultez Catégories d’entités nommées.

String document = "Satya Nadella is the CEO of Microsoft";
textAnalyticsClient.recognizeEntities(document).forEach(entity ->
    System.out.printf("Recognized entity: %s, category: %s, subcategory: %s, confidence score: %f.%n",
        entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getConfidenceScore()));

Pour obtenir des exemples sur l’utilisation de l’option RecognizeEntitiesBatch recommandée en production, consultez ici. Reportez-vous à la documentation du service pour une présentation conceptuelle de la reconnaissance d’entité nommée.

Reconnaître les entités d’informations d’identification personnelle

Exécutez un modèle prédictif pour identifier une collection d’entités d’informations d’identification personnelle (PII) dans le document fourni. Il reconnaît et classe les entités d’identification personnelle dans son texte d’entrée, comme les numéros de sécurité sociale, les informations de compte bancaire, les numéros de crédit carte, etc. Ce point de terminaison est uniquement pris en charge pour les versions d’API v3.1-preview.1 et ultérieures.

String document = "My SSN is 859-98-0987";
PiiEntityCollection piiEntityCollection = textAnalyticsClient.recognizePiiEntities(document);
System.out.printf("Redacted Text: %s%n", piiEntityCollection.getRedactedText());
piiEntityCollection.forEach(entity -> System.out.printf(
    "Recognized Personally Identifiable Information entity: %s, entity category: %s, entity subcategory: %s,"
        + " confidence score: %f.%n",
    entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getConfidenceScore()));

Pour obtenir des exemples sur l’utilisation de l’option RecognizePiiEntitiesBatch recommandée en production, consultez ici. Reportez-vous à la documentation du service pour connaître les types d’entités PII pris en charge.

Reconnaître des entités liées

Exécutez un modèle prédictif pour identifier une collection d’entités trouvées dans le document ou le lot de documents fourni, et incluez des informations liant les entités à leurs entrées correspondantes dans un base de connaissances bien connu.

String document = "Old Faithful is a geyser at Yellowstone Park.";
textAnalyticsClient.recognizeLinkedEntities(document).forEach(linkedEntity -> {
    System.out.println("Linked Entities:");
    System.out.printf("Name: %s, entity ID in data source: %s, URL: %s, data source: %s.%n",
        linkedEntity.getName(), linkedEntity.getDataSourceEntityId(), linkedEntity.getUrl(), linkedEntity.getDataSource());
    linkedEntity.getMatches().forEach(match ->
        System.out.printf("Text: %s, confidence score: %f.%n", match.getText(), match.getConfidenceScore()));
});

Pour obtenir des exemples sur l’utilisation de l’option RecognizeLinkedEntitiesBatch recommandée en production, consultez ici. Reportez-vous à la documentation du service pour une présentation conceptuelle de la liaison d’entités.

Analyser les entités de santé

L’Analyse de texte pour la santé est un service en conteneur qui extrait et étiquette les informations médicales pertinentes à partir de textes non structurés, tels que les notes du médecin, les bilans de sortie d’hospitalisation, les documents cliniques et les enregistrements d’intégrité électroniques.

Pour plus d’informations, consultez Guide pratique pour utiliser Analyse de texte pour l’intégrité.

Reconnaissance d’entités personnalisées

La Reconnaissance d’entité nommée personnalisée est l’une des fonctionnalités proposées par Azure Cognitive Service for Language. Il s’agit d’un service d’API informatique qui applique l’intelligence du Machine Learning pour vous permettre de construire des modèles personnalisés pour les tâches de reconnaissance d’entités nommées dans du texte.

Pour plus d’informations , consultez Guide pratique pour utiliser la reconnaissance d’entités personnalisées.

Classification de texte personnalisée

La classification de texte personnalisée est une des fonctionnalités personnalisées offertes par Azure Cognitive Service for Langage. Il s’agit d’un service d’API basé sur le cloud qui applique l’intelligence du machine learning à la création de modèles personnalisés pour les tâches de classification de texte.

Pour plus d’informations , consultez How to use : Custom Text Classification.

Analyser plusieurs actions

La Analyze fonctionnalité permet de choisir parmi les fonctionnalités du service language prises en charge à exécuter dans le même ensemble de documents. Actuellement, les fonctionnalités prises en charge sont les suivantes :

  • Reconnaissance des entités nommées
  • Reconnaissance des entités PII
  • Reconnaissance d’entité liée
  • Extraction d’expressions clés
  • Analyse des sentiments
  • Analyse des soins de santé
  • Reconnaissance d’entité personnalisée (API version 2022-05-01 et ultérieure)
  • Classification de Single-Label personnalisée (API version 2022-05-01 et ultérieure)
  • Classification multi-étiquette personnalisée (API version 2022-05-01 et ultérieure)
  • Résumé de texte abstrait (API version 2023-04-01 et ultérieure)
  • Synthèse de texte extractif (API version 2023-04-01 et ultérieure)

Exemple : Analyse d’actions multiples

Pour obtenir d’autres exemples, tels que des exemples asynchrones, reportez-vous ici.

Dépannage

Général

Analyse de texte clients posent des exceptions. Par exemple, si vous essayez de détecter les langues d’un lot de texte avec les mêmes ID de document, 400 l’erreur indiquant une demande incorrecte est retournée. Dans l’extrait de code suivant, l’erreur est gérée correctement via l’interception de l’exception et en affichant des informations supplémentaires sur l’erreur en question.

List<DetectLanguageInput> documents = Arrays.asList(
    new DetectLanguageInput("1", "This is written in English.", "us"),
    new DetectLanguageInput("1", "Este es un documento  escrito en Español.", "es")
);

try {
    textAnalyticsClient.detectLanguageBatchWithResponse(documents, null, Context.NONE);
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
}

Activer la journalisation du client

Vous pouvez définir la variable d’environnement AZURE_LOG_LEVEL pour afficher les instructions de journalisation figurant dans la bibliothèque de client. Par exemple, le paramètre AZURE_LOG_LEVEL=2 affiche tous les messages d’information, d’avertissement et de journal des erreurs. Les niveaux de journal se trouvent ici : niveaux de journal.

Client HTTP par défaut

Toutes les bibliothèques de client utilisent par défaut le client HTTP Netty. L’ajout de la dépendance ci-dessus configure automatiquement la bibliothèque de client pour utiliser le client HTTP Netty. La configuration ou la modification du client HTTP sont détaillées dans le wiki pour clients HTTP.

Bibliothèque SSL par défaut

Toutes les bibliothèques de client utilisent par défaut la bibliothèque BoringSSL Tomcat native pour permettre des performances de niveau natif pour les opérations SSL. La bibliothèque BoringSSL est un fichier uber jar contenant des bibliothèques natives pour Linux/macOS/Windows. Elle offre de meilleures performances que l’implémentation SSL par défaut au sein du JDK. Pour plus d’informations, notamment sur la réduction de la taille des dépendances, consultez la section du wiki consacrée à l’optimisation des performances.

Étapes suivantes

  • Les exemples sont expliqués en détail ici.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions