Azure Textanalyse-Clientbibliothek für JavaScript – Version 5.1.0

  • Artikel

Azure TextAnalytics ist ein cloudbasierter Dienst, der eine erweiterte Verarbeitung natürlicher Sprache über Rohtext ermöglicht und sechs Hauptfunktionen umfasst:

Hinweis: Dieses SDK ist für Azure Textanalyse-Dienst-API Version 3.1.0 ausgerichtet.

  • Spracherkennung
  • Standpunktanalyse
  • Schlüsselwortextraktion
  • Erkennung benannter Entitäten
  • Erkennung personenbezogener Informationen
  • Erkennung verknüpfter Entitäten
  • Analyse des Gesundheitswesens
  • Unterstützung mehrerer Aktionen pro Dokument

Verwenden Sie die Clientbibliothek für folgende Aktionen:

  • Ermitteln Sie, in welcher Sprache Eingabetext geschrieben ist.
  • Bestimmen Sie, was Kunden über Ihre Marke oder Ihr Thema denken, indem Sie Rohtext analysieren, um Hinweise auf eine positive oder negative Stimmung zu finden.
  • Extrahieren Sie automatisch Schlüsselwörter, um die wichtigsten Inhalte zu ermitteln.
  • Identifizieren und kategorisieren Sie Entitäten in Ihrem Text als Personen, Orte, Organisationen, Datum/Uhrzeit, Mengen, Prozentsätze, Währungen, Gesundheitswesen und vieles mehr.
  • Führen Sie mehrere der oben genannten Aufgaben gleichzeitig aus.

Wichtige Links:

Erste Schritte

Die derzeitig unterstützten Umgebungen

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

Wenn Sie die Azure CLI verwenden, ersetzen <your-resource-group-name> Sie und <your-resource-name> durch Ihre eigenen eindeutigen Namen:

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

Installieren Sie das Paket @azure/ai-text-analytics.

Installieren Sie die Azure Textanalyse-Clientbibliothek für JavaScript mit npm:

npm install @azure/ai-text-analytics

Erstellen und Authentifizieren eines TextAnalyticsClient

Um ein Clientobjekt für den Zugriff auf die Textanalyse-API zu erstellen, benötigen Sie die endpoint ihrer Textanalyse Ressource und eine credential. Der Textanalyse-Client kann entweder Azure Active Directory-Anmeldeinformationen oder API-Schlüsselanmeldeinformationen für die Authentifizierung verwenden.

Sie finden den Endpunkt für Ihre Textanalyseressource entweder im Azure-Portal oder mithilfe des folgenden Azure CLI-Ausschnitts :

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

Verwenden eines API-Schlüssels

Verwenden Sie das Azure-Portal, um zu Ihrer Textanalyse-Ressource zu navigieren und einen API-Schlüssel abzurufen, oder verwenden Sie den folgenden Azure CLI-Codeausschnitt:

Hinweis: Manchmal wird der API-Schlüssel als "Abonnementschlüssel" oder "Abonnement-API-Schlüssel" bezeichnet.

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

Sobald Sie über einen API-Schlüssel und -Endpunkt verfügen, können Sie die AzureKeyCredential -Klasse verwenden, um den Client wie folgt zu authentifizieren:

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

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

Verwenden von Azure Active Directory-Anmeldeinformationen

Die Client-API-Schlüsselauthentifizierung wird in den meisten Beispielen verwendet, Sie können sich jedoch auch mit Azure Active Directory mithilfe der Azure Identity-Bibliothek authentifizieren. Um den unten gezeigten Anbieter DefaultAzureCredential oder andere anbieter von Anmeldeinformationen zu verwenden, die mit dem Azure SDK bereitgestellt werden, installieren Sie das @azure/identity Paket:

npm install @azure/identity

Sie müssen auch eine neue AAD-Anwendung registrieren und zugriff auf Textanalyse gewähren, indem Sie die "Cognitive Services User" Rolle Ihrem Dienstprinzipal zuweisen (Hinweis: Andere Rollen, z"Owner". B. erteilen die erforderlichen Berechtigungen nicht, reichen nur "Cognitive Services User" aus, um die Beispiele und den Beispielcode auszuführen).

Legen Sie die Werte der Client-ID, Mandanten-ID und geheimen Clientschlüssel der AAD-Anwendung als Umgebungsvariablen fest: 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());

Wichtige Begriffe

TextAnalyticsClient

TextAnalyticsClientist die primäre Schnittstelle für Entwickler, die die Textanalyse Clientbibliothek verwenden. Erkunden Sie die Methoden für dieses Clientobjekt, um die verschiedenen Features des Textanalyse-Diensts zu verstehen, auf den Sie zugreifen können.

Eingabe

Ein Dokument stellt eine einzelne Eingabeeinheit dar, die von den Vorhersagemodellen im Textanalyse-Dienst analysiert werden soll. Vorgänge für TextAnalyticsClient nehmen eine Sammlung von Eingaben an, die als Batch analysiert werden sollen. Die Vorgangsmethoden verfügen über Überladungen, mit denen die Eingaben als Zeichenfolgen oder als Objekte mit angefügten Metadaten dargestellt werden können.

Beispielsweise kann jedes Dokument als Zeichenfolge in einem Array übergeben werden, z. B.

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

oder, wenn Sie ein Dokument id pro Element oder languagecountryHint/übergeben möchten, können sie als Liste von TextDocumentInput oder DetectLanguageInput je nach Vorgang angegeben werden;

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!" }
];

Weitere Informationen finden Sie unter Diensteinschränkungen für die Eingabe, einschließlich Einschränkungen für die Dokumentlänge, maximale Batchgröße und unterstützte Textcodierungen.

Rückgabewert

Der Rückgabewert, der einem einzelnen Dokument entspricht, ist entweder ein erfolgreiches Ergebnis oder ein Fehlerobjekt. Jede TextAnalyticsClient Methode gibt ein heterogenes Array von Ergebnissen und Fehlern zurück, die den Eingaben nach Index entsprechen. Eine Texteingabe und ihr Ergebnis weisen denselben Index in den Eingabe- und Ergebnisauflistungen auf. Die Sammlung kann optional auch Informationen zum Eingabebatch und zur Verarbeitung im statistics Feld enthalten.

Ein Ergebnis, zAnalyzeSentimentResult. B. , ist das Ergebnis eines Textanalyse Vorgangs, der eine Vorhersage oder Vorhersagen zu einer einzelnen Texteingabe enthält. Der Ergebnistyp eines Vorgangs kann optional auch Informationen zum Eingabedokument und seiner Verarbeitung enthalten.

Das Fehlerobjekt , gibt an, TextAnalyticsErrorResultdass beim Dienst bei der Verarbeitung des Dokuments ein Fehler aufgetreten ist, und enthält Informationen zum Fehler.

Dokumentfehlerbehandlung

In der Auflistung, die von einem Vorgang zurückgegeben wird, werden Fehler von erfolgreichen Antworten durch das Vorhandensein der error -Eigenschaft unterschieden, die das innere TextAnalyticsError Objekt enthält, wenn ein Fehler aufgetreten ist. Für erfolgreiche Ergebnisobjekte ist diese Eigenschaft immerundefined.

Um beispielsweise alle Fehler herauszufiltern, können Sie Folgendes filterverwenden:

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

Hinweis: TypeScript-Benutzer können von einer besseren Typüberprüfung von Ergebnis- und Fehlerobjekten profitieren, wenn compilerOptions.strictNullChecks in der tsconfig.json Konfiguration auf true festgelegt ist. Beispiel:

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);
}

Diese Funktion wurde in TypeScript 3.2 eingeführt, sodass Benutzer von TypeScript 3.1 Ergebniswerte wie folgt in ihre entsprechende Erfolgsvariante umwandeln müssen:

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

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

Beispiele

Analysieren der Stimmung

Analysieren Sie die Stimmung von Text, um festzustellen, ob er positiv, negativ, neutral oder gemischt ist, einschließlich der Stimmungsanalyse pro Satz und Konfidenzbewertungen.

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();

Ausführlichere Informationen zu den Meinungen im Zusammenhang mit Aspekten eines Produkts/einer Dienstleistung, die auch als Aspect-based Sentiment Analysis in Natural Language Processing (NLP) bezeichnet wird, finden Sie hier in einer Stichprobe zur Stimmungsanalyse mit Opinion Mining.

Entitäten erkennen

Erkennen und Kategorisieren von Entitäten im Text als Personen, Orte, Organisationen, Datum/Uhrzeiten, Mengen, Währungen usw.

Das language ist optional. Wenn es nicht angegeben ist, wird das englische Standardmodell verwendet.

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();

Erkennen von PII-Entitäten

Es gibt einen separaten Endpunkt und einen separaten Vorgang zum Erkennen personenbezogener Informationen (PII) in Texten wie Sozialversicherungsnummern, Bankkontoinformationen, Kreditkartennummern usw. Seine Verwendung ähnelt der oben genannten Standardentitätserkennung sehr:

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();

Erkennen verknüpfter Entitäten

Eine "verknüpfte" Entität ist eine Entität, die in einer Wissensdatenbank (z. B. Wikipedia) vorhanden ist. Die recognizeLinkedEntities Operation kann Entitäten mehrdeutig machen, indem sie bestimmen, auf welchen Eintrag in einer Wissensdatenbank sie sich wahrscheinlich beziehen (beispielsweise bezieht sich das Wort "Mars" in einem Textteil auf den Planeten oder auf den römischen Kriegsgott). Verknüpfte Entitäten enthalten zugeordnete URLs für die Wissensdatenbank, die die Definition der Entität bereitstellt.

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();

Extrahieren von Schlüsselbegriffen

Die Key Phrase-Extraktion identifiziert die wichtigsten Gesprächspunkte in einem Dokument. Zum Beispiel, wenn der eingegebene Text „Das Essen war köstlich, und es gab hervorragendes Personal“ lautet, gibt der Dienst „Essen“ und „hervorragendes Personal“ zurück.

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();

Erkennen von Sprache

Bestimmen Sie die Sprache eines Textteils.

Der countryHint Parameter ist optional, kann jedoch den Dienst bei der Bereitstellung der korrekten Ausgabe unterstützen, wenn das Ursprungsland bekannt ist. Falls angegeben, sollte sie auf einen ISO-3166 Alpha-2-Ländercode mit zwei Buchstaben (z. B. "uns" für die USA oder "jp" für Japan) oder auf den Wert "none"festgelegt werden. Wenn der Parameter nicht angegeben wird, wird das Standardmodell "us" (USA) verwendet. Wenn Sie das Ursprungsland des Dokuments nicht kennen, sollte der Parameter "none" verwendet werden, und der Textanalyse-Dienst wendet ein Modell an, das für ein unbekanntes Ursprungsland optimiert ist.

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();

Analysieren von Entitäten im Gesundheitswesen

Die Analyse des Gesundheitswesens identifiziert Entitäten im Gesundheitswesen. Wenn beispielsweise der Eingabetext "Vorgeschrieben 100mg Ibuprofen, zweimal täglich eingenommen" gegeben ist, gibt der Dienst "100mg" zurück, kategorisiert als Dosierung, "Ibuprofen" als MedicationName und "zweimal täglich" als Frequency.

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();

Analysieren von Aktionen

Analysieren von Aktionen ermöglicht die gleichzeitige Anwendung mehrerer Analysen (benannte Aktionen).

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();

Problembehandlung

Protokollierung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in der Paketdokumentation zu @azure/logger.

Nächste Schritte

Ausführliche Beispiele zur Verwendung dieser Bibliothek finden Sie im Beispielverzeichnis .

Mitwirken

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie die Anleitung für Mitwirkende, um mehr darüber zu erfahren, wie Sie den Code erstellen und testen können.

Aufrufe