Partager via


Bibliothèque cliente Azure Analyse de texte pour JavaScript - version 5.1.0

Azure TextAnalytics est un service basé sur le cloud qui fournit un traitement avancé en langage naturel sur du texte brut et comprend six fonctions principales :

Note: Ce KIT de développement logiciel (SDK) cible l’API de service Azure Analyse de texte version 3.1.0.

  • Détection de la langue
  • Analyse des sentiments
  • Extraction d’expressions clés
  • Reconnaissance d’entité nommée
  • Reconnaissance des informations d’identification personnelle
  • Reconnaissance d’entités liées
  • Analyse des soins de santé
  • Prendre en charge plusieurs actions par document

Utilisez la bibliothèque cliente pour :

  • Détectez le texte d’entrée de langue dans lequel il est écrit.
  • Déterminez ce que les clients pensent de votre marque ou de votre sujet en analysant le texte brut à la recherche d’indices sur les sentiments positifs ou négatifs.
  • Extrayez automatiquement des phrases clés pour identifier rapidement les points principaux.
  • Identifiez et catégorisez les entités dans votre texte en tant que personnes, lieux, organisations, date/heure, quantités, pourcentages, devises, spécifiques aux soins de santé, etc.
  • Effectuez plusieurs des tâches ci-dessus à la fois.

Liens clés :

Prise en main

Environnements actuellement pris en charge

Pour plus d’informations, consultez notre politique de support .

Prérequis

Si vous utilisez Azure CLI, remplacez <your-resource-group-name> et <your-resource-name> par vos propres noms uniques :

az cognitiveservices account create --kind TextAnalytics --resource-group <your-resource-group-name> --name <your-resource-name> --sku <your-sku-name> --location <your-location>

Installez le package @azure/ai-text-analytics

Installez la bibliothèque cliente Azure Analyse de texte pour JavaScript avec npm:

npm install @azure/ai-text-analytics

Créez et authentifiez unTextAnalyticsClient

Pour créer un objet client afin d’accéder à l’API Analyse de texte, vous aurez besoin de la endpoint ressource de votre Analyse de texte et d’un credential. Le client Analyse de texte peut utiliser des informations d’identification Azure Active Directory ou des informations d’identification de clé API pour s’authentifier.

Vous trouverez le point de terminaison de votre ressource d’analyse de texte dans le portail Azure ou à l’aide de l’extrait de code Azure CLI ci-dessous :

az cognitiveservices account show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

Utilisation d’une clé API

Utilisez le portail Azure pour accéder à votre ressource Analyse de texte et récupérer une clé API, ou utilisez l’extrait de code Azure CLI ci-dessous :

Note: Parfois, la clé API est appelée « clé d’abonnement » ou « clé API d’abonnement ».

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

Une fois que vous avez une clé API et un point de terminaison, vous pouvez utiliser la AzureKeyCredential classe pour authentifier le client comme suit :

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

Utilisation d’informations d’identification Azure Active Directory

L’authentification par clé API cliente est utilisée dans la plupart des exemples, mais vous pouvez également vous authentifier auprès d’Azure Active Directory à l’aide de la bibliothèque Azure Identity. Pour utiliser le fournisseur DefaultAzureCredential indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, installez le @azure/identity package :

npm install @azure/identity

Vous devrez également inscrire une nouvelle application AAD et accorder l’accès à Analyse de texte en attribuant le "Cognitive Services User" rôle à votre principal de service (remarque : d’autres rôles tels que n’accorderont "Owner" pas les autorisations nécessaires, suffiront "Cognitive Services User" uniquement pour exécuter les exemples et l’exemple de code).

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.

const { TextAnalyticsClient } = require("@azure/ai-text-analytics");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new TextAnalyticsClient("<endpoint>", new DefaultAzureCredential());

Concepts clés

TextAnalyticsClient

TextAnalyticsClientest l’interface principale pour les développeurs qui utilisent la bibliothèque cliente Analyse de texte. Explorez les méthodes de cet objet client pour comprendre les différentes fonctionnalités du service Analyse de texte auquel vous pouvez accéder.

Entrée

Un document représente une seule unité d’entrée à analyser par les modèles prédictifs dans le service Analyse de texte. Les opérations sur TextAnalyticsClient prennent une collection d’entrées à analyser en tant que lot. Les méthodes d’opération ont des surcharges qui permettent aux entrées d’être représentées sous forme de chaînes ou d’objets avec des métadonnées attachées.

Par exemple, chaque document peut être passé sous forme de chaîne dans un tableau, par exemple.

const documents = [
  "I hated the movie. It was so slow!",
  "The movie made it into my top ten favorites.",
  "What a great movie!"
];

ou, si vous souhaitez passer un document id par élément ou languagecountryHint/, ils peuvent être donnés sous forme de liste de ou DetectLanguageInput en fonction de TextDocumentInput l’opération ;

const textDocumentInputs = [
  { id: "1", language: "en", text: "I hated the movie. It was so slow!" },
  { id: "2", language: "en", text: "The movie made it into my top ten favorites." },
  { id: "3", language: "en", text: "What a great movie!" }
];

Consultez Limitations du service pour l’entrée, notamment les limites de longueur du document, la taille maximale des lots et les encodages de texte pris en charge.

Valeur renvoyée

La valeur de retour correspondant à un document unique est un résultat réussi ou un objet d’erreur. Chaque TextAnalyticsClient méthode retourne un tableau hétérogène de résultats et d’erreurs qui correspondent aux entrées par index. Une entrée de texte et son résultat auront le même index dans les collections d’entrée et de résultat. La collection peut également inclure éventuellement des informations sur le lot d’entrée et la façon dont il a été traité dans le statistics champ.

Un résultat, tel que AnalyzeSentimentResult, est le résultat d’une opération de Analyse de texte, contenant une prédiction ou des prédictions relatives à une entrée de texte unique. 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é.

L’objet error, TextAnalyticsErrorResult, indique que le service a rencontré une erreur lors du traitement du document et contient des informations sur l’erreur.

Gestion des erreurs de document

Dans la collection retournée par une opération, les erreurs sont distinguées des réponses réussies par la présence de la error propriété, qui contient l’objet interne TextAnalyticsError si une erreur a été rencontrée. Pour les objets de résultat réussis, cette propriété est toujoursundefined.

Par exemple, pour filtrer toutes les erreurs, vous pouvez utiliser les éléments suivants filter:

const results = await client.analyzeSentiment(documents);
const onlySuccessful = results.filter((result) => result.error === undefined);

Remarque : les utilisateurs de TypeScript peuvent bénéficier d’une meilleure vérification de type des objets de résultat et d’erreur si compilerOptions.strictNullChecks est défini sur true dans la tsconfig.json configuration. Par exemple :

const [result] = await client.analyzeSentiment(["Hello world!"]);

if (result.error !== undefined) {
  // In this if block, TypeScript will be sure that the type of `result` is
  // `TextAnalyticsError` if compilerOptions.strictNullChecks is enabled in
  // the tsconfig.json

  console.log(result.error);
}

Cette fonctionnalité a été introduite dans TypeScript 3.2, de sorte que les utilisateurs de TypeScript 3.1 doivent caster les valeurs de résultats en leur variante de réussite correspondante comme suit :

const [result] = await client.detectLanguage(["Hello world!"]);

if (result.error === undefined) {
  const { primaryLanguage } = result as DetectLanguageSuccessResult;
}

Exemples

Analyser les sentiments

Analysez le sentiment de texte pour déterminer s’il est positif, négatif, neutre ou mixte, y compris l’analyse des sentiments par phrase et les scores de confiance.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "I did not like the restaurant. The food was too spicy.",
  "The restaurant was decorated beautifully. The atmosphere was unlike any other restaurant I've been to.",
  "The food was yummy. :)"
];

async function main() {
  const results = await client.analyzeSentiment(documents);

  for (const result of results) {
    if (result.error === undefined) {
      console.log("Overall sentiment:", result.sentiment);
      console.log("Scores:", result.confidenceScores);
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}

main();

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

Reconnaître les entités

Reconnaître et classer des entités dans le texte en tant que personnes, lieux, organisations, dates/heures, quantités, devises, etc.

Le paramètre language est facultatif. S’il n’est pas spécifié, le modèle anglais par défaut est utilisé.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "Microsoft was founded by Bill Gates and Paul Allen.",
  "Redmond is a city in King County, Washington, United States, located 15 miles east of Seattle.",
  "Jeff bought three dozen eggs because there was a 50% discount."
];

async function main() {
  const results = await client.recognizeEntities(documents, "en");

  for (const result of results) {
    if (result.error === undefined) {
      console.log(" -- Recognized entities for input", result.id, "--");
      for (const entity of result.entities) {
        console.log(entity.text, ":", entity.category, "(Score:", entity.confidenceScore, ")");
      }
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}

main();

Reconnaître les entités PII

Il existe un point de terminaison et une opération distincts pour reconnaître les informations d’identification personnelle (PII) dans le texte, tels que les numéros de sécurité sociale, les informations de compte bancaire, les numéros de carte de crédit, etc. Son utilisation est très similaire à la reconnaissance d’entité standard ci-dessus :

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));
const documents = [
  "The employee's SSN is 555-55-5555.",
  "The employee's phone number is (555) 555-5555."
];
async function main() {
  const results = await client.recognizePiiEntities(documents, "en");
  for (const result of results) {
    if (result.error === undefined) {
      console.log(" -- Recognized PII entities for input", result.id, "--");
      for (const entity of result.entities) {
        console.log(entity.text, ":", entity.category, "(Score:", entity.confidenceScore, ")");
      }
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}
main();

Reconnaître les entités liées

Une entité « liée » est une entité qui existe dans un base de connaissances (par exemple, Wikipédia). L’opération recognizeLinkedEntities peut lever l’ambiguïté des entités en déterminant à quelle entrée dans un base de connaissances elles font probablement référence (par exemple, dans un morceau de texte, le mot « Mars » fait-il référence à la planète, ou au dieu romain de la guerre). Les entités liées contiennent des URL associées à l’base de connaissances qui fournit la définition de l’entité.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "Microsoft was founded by Bill Gates and Paul Allen.",
  "Easter Island, a Chilean territory, is a remote volcanic island in Polynesia.",
  "I use Azure Functions to develop my product."
];

async function main() {
  const results = await client.recognizeLinkedEntities(documents, "en");

  for (const result of results) {
    if (result.error === undefined) {
      console.log(" -- Recognized linked entities for input", result.id, "--");
      for (const entity of result.entities) {
        console.log(entity.name, "(URL:", entity.url, ", Source:", entity.dataSource, ")");
        for (const match of entity.matches) {
          console.log(
            "  Occurrence:",
            '"' + match.text + '"',
            "(Score:",
            match.confidenceScore,
            ")"
          );
        }
      }
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}

main();

Extraire des expressions clés

L’extraction d’expressions clés identifie les principaux points de discussion d’un document. Par exemple, si nous considérons le texte d’entrée « la nourriture était délicieuse et le personnel était merveilleux », le service retourne « nourriture » et « personnel merveilleux ».

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "Redmond is a city in King County, Washington, United States, located 15 miles east of Seattle.",
  "I need to take my cat to the veterinarian.",
  "I will travel to South America in the summer."
];

async function main() {
  const results = await client.extractKeyPhrases(documents, "en");

  for (const result of results) {
    if (result.error === undefined) {
      console.log(" -- Extracted key phrases for input", result.id, "--");
      console.log(result.keyPhrases);
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}

main();

Détecter la langue

Déterminez la langue d’un morceau de texte.

Le countryHint paramètre est facultatif, mais peut aider le service à fournir une sortie correcte si le pays d’origine est connu. S’il est fourni, il doit être défini sur un code de pays ISO-3166 Alpha-2 à deux lettres (tel que « nous » pour le États-Unis ou « jp » pour le Japon) ou sur la valeur "none". Si le paramètre n’est pas fourni, le modèle par défaut "us" (États-Unis) sera utilisé. Si vous ne connaissez pas le pays d’origine du document, le paramètre "none" doit être utilisé et le service Analyse de texte applique un modèle qui est paramétré pour un pays d’origine inconnu.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "This is written in English.",
  "Il documento scritto in italiano.",
  "Dies ist in deutscher Sprache verfasst."
];

async function main() {
  const results = await client.detectLanguage(documents, "none");

  for (const result of results) {
    if (result.error === undefined) {
      const { primaryLanguage } = result;
      console.log(
        "Input #",
        result.id,
        "identified as",
        primaryLanguage.name,
        "( ISO6391:",
        primaryLanguage.iso6391Name,
        ", Score:",
        primaryLanguage.confidenceScore,
        ")"
      );
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}

main();

Analyser les entités de soins de santé

L’analyse des soins de santé identifie les entités de soins de santé. Par exemple, en fonction du texte d’entrée « Ibuprofène prescrit de 100 mg, pris deux fois par jour », le service retourne « 100 mg » classé comme Dosage, « ibuprofène » comme MedicationName et « deux fois par jour » comme Fréquence.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "Prescribed 100mg ibuprofen, taken twice daily.",
  "Patient does not suffer from high blood pressure."
];

async function main() {
  const poller = await client.beginAnalyzeHealthcareEntities(documents);
  const results = await poller.pollUntilDone();

  for await (const result of results) {
    console.log(`- Document ${result.id}`);
    if (!result.error) {
      console.log("\tRecognized Entities:");
      for (const entity of result.entities) {
        console.log(`\t- Entity ${entity.text} of type ${entity.category}`);
      }
    } else console.error("\tError:", result.error);
  }
}

main();

Analyser les actions

Analyser les actions permet l’application de plusieurs analyses (actions nommées) à la fois.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "Microsoft was founded by Bill Gates and Paul Allen.",
  "The employee's SSN is 555-55-5555.",
  "Easter Island, a Chilean territory, is a remote volcanic island in Polynesia.",
  "I use Azure Functions to develop my product."
];

async function main() {
  const actions = {
    recognizeEntitiesActions: [{ modelVersion: "latest" }],
    recognizePiiEntitiesActions: [{ modelVersion: "latest" }],
    extractKeyPhrasesActions: [{ modelVersion: "latest" }]
  };
  const poller = await client.beginAnalyzeActions(documents, actions);
  const resultPages = await poller.pollUntilDone();
  for await (const page of resultPages) {
    const keyPhrasesAction = page.extractKeyPhrasesResults[0];
    if (!keyPhrasesAction.error) {
      for (const doc of keyPhrasesAction.results) {
        console.log(`- Document ${doc.id}`);
        if (!doc.error) {
          console.log("\tKey phrases:");
          for (const phrase of doc.keyPhrases) {
            console.log(`\t- ${phrase}`);
          }
        } else {
          console.error("\tError:", doc.error);
        }
      }
    }

    const entitiesAction = page.recognizeEntitiesResults[0];
    if (!entitiesAction.error) {
      for (const doc of entitiesAction.results) {
        console.log(`- Document ${doc.id}`);
        if (!doc.error) {
          console.log("\tEntities:");
          for (const entity of doc.entities) {
            console.log(`\t- Entity ${entity.text} of type ${entity.category}`);
          }
        } else {
          console.error("\tError:", doc.error);
        }
      }
    }

    const piiEntitiesAction = page.recognizePiiEntitiesResults[0];
    if (!piiEntitiesAction.error) {
      for (const doc of piiEntitiesAction.results) {
        console.log(`- Document ${doc.id}`);
        if (!doc.error) {
          console.log("\tPii Entities:");
          for (const entity of doc.entities) {
            console.log(`\t- Entity ${entity.text} of type ${entity.category}`);
          }
        } else {
          console.error("\tError:", doc.error);
        }
      }
    }
  }
}

main();

Résolution des problèmes

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans @azure/logger :

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Étapes suivantes

Consultez le répertoire d’exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.

Contribution

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la génération et le test du code.

Impressions