Azure Textanalyse Clientbibliothek für Java – Version 5.4.0

Azure Cognitive Service for Language ist ein cloudbasierter Dienst, der NLP-Features (Natural Language Processing) zum Verstehen und Analysieren von Text bereitstellt und die folgenden Standard Features enthält:

• Standpunktanalyse
• Entitätserkennung (Benannte, verknüpfte und personenbezogene Informationen( PII) Entitäten)
• Spracherkennung
• Schlüsselwortextraktion
• Analyse mehrerer Aktionen pro Dokument
• Analyse von Entitäten im Gesundheitswesen
• Zusammenfassung abstraktioniver Text
• Extraktive Textzusammenfassung
• Benutzerdefinierte Erkennung benannter Entitäten (Custom Named Entity Recognition)
• Benutzerdefinierte Textklassifizierung

Quellcode | Paket (Maven) | API-Referenzdokumentation | Produktdokumentation | Proben

Erste Schritte

Voraussetzungen

• Java Development Kit (JDK), Version 8 oder höher.
• Azure-Abonnement
• Cognitive Services- oder Language-Dienstkonto , um dieses Paket zu verwenden.

Schließen Sie das Paket ein

BOM-Datei einfügen

Fügen Sie das azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit von der GA-Version der Bibliothek zu übernehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur Stückliste finden Sie in der AZURE SDK-BOM-INFODATEI.

<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>

und fügen Sie dann die direkte Abhängigkeit ohne Versions-Tag in den Abschnitt „Abhängigkeit“ ein.

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

Direkte Abhängigkeiten einfügen

Wenn Sie abhängigkeiten von einer bestimmten Version der Bibliothek übernehmen möchten, die in der Stückliste nicht vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

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

Hinweis: Diese Version der Clientbibliothek verwendet standardmäßig die 2023-04-01 Version des Diensts. Es handelt sich um eine neuere Version als 3_0, 3_1 und 2022-05-01.

Diese Tabelle zeigt die Beziehung zwischen SDK-Diensten und unterstützten API-Versionen des Diensts:

SDK-Version	Unterstützte API-Version des Diensts
5.3.x	3.0, 3.1, 2022-05-01, 2023-04-01 (Standard)
5.2.x	3.0, 3.1, 2022-05-01
5.1.x	3.0, 3.1
5.0.x	3.0

Erstellen einer Cognitive Services- oder Language Service-Ressource

Der Sprachdienst unterstützt sowohl den Zugriff mit mehreren Diensten als auch den Einzeldienst. Erstellen Sie eine Cognitive Services-Ressource, wenn Sie planen, über einen einzelnen Endpunkt bzw. Schlüssel auf mehrere Cognitive Services-Instanzen zuzugreifen. Erstellen Sie nur für den Sprachdienstzugriff eine Sprachdienstressource.

Sie können die Ressource mithilfe des Azure-Portals oder der Azure CLI erstellen, indem Sie die Schritte in diesem Dokument ausführen.

Authentifizieren des Clients

Um mit dem Sprachdienst zu interagieren, müssen Sie eine instance des Textanalyse-Clients erstellen. Sowohl der asynchrone als auch der synchrone Client kann mithilfe des TextAnalyticsClientBuilder Aufrufens buildClient() erstellt werden, erstellt einen synchronen Client, während buildAsyncClient() sein asynchrones Pendant erstellt wird.

Sie benötigen einen Endpunkt und entweder einen Schlüssel oder AAD TokenCredential , um ein Clientobjekt zu instanziieren.

Nachschlagen des Endpunkts

Sie finden den Endpunkt für Ihre Sprachdienstressource im Azure-Portal unter "Schlüssel und Endpunkt" oder unter der Azure CLI.

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

Erstellen eines Textanalyse-Clients mit Schlüsselanmeldeinformationen

Sobald Sie über den Wert für den Schlüssel verfügen, geben Sie ihn als Zeichenfolge für AzureKeyCredential an. Dies finden Sie im Azure-Portal im Abschnitt "Schlüssel und Endpunkt" in Ihrer erstellten Sprachdienstressource oder indem Sie den folgenden Azure CLI-Befehl ausführen:

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

Verwenden Sie den Schlüssel als Anmeldeinformationsparameter, um den Client zu authentifizieren:

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

Die Azure Textanalyse-Clientbibliothek bietet eine Möglichkeit, den vorhandenen Schlüssel zu rotieren.

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

credential.update("{new_key}");

Erstellen eines Textanalyse-Clients mit Azure Active Directory-Anmeldeinformationen

Das Azure SDK für Java unterstützt ein Azure Identity-Paket, das das Abrufen von Anmeldeinformationen von Microsoft Identity Platform vereinfacht.

Die Authentifizierung mit AAD erfordert eine anfängliche Einrichtung:

• Hinzufügen des Azure Identity-Pakets

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.4</version>
</dependency>

• Registrieren einer neuen Azure Active Directory-Anwendung
• Gewähren Sie den Zugriff auf den Sprachdienst, indem Sie die "Cognitive Services User" Rolle Ihrem Dienstprinzipal zuweisen.

Nach dem Setup können Sie auswählen, welcher Typ von Anmeldeinformationen aus azure.identity verwendet werden soll. Als Beispiel kann DefaultAzureCredential verwendet werden, um den Client zu authentifizieren: Legen Sie die Werte der Client-ID, der Mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Die Autorisierung ist am einfachsten mit DefaultAzureCredential. Es findet die besten Anmeldeinformationen, die in seiner ausgeführten Umgebung verwendet werden können. Weitere Informationen zur Verwendung der Azure Active Directory-Autorisierung mit dem Sprachdienst finden Sie in der zugehörigen Dokumentation.

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

Wichtige Begriffe

Textanalyse Client

Die Textanalyse-Clientbibliothek stellt einen TextAnalyticsClient und TextAnalyticsAsyncClient bereit, um Analysen von Dokumentenbatches durchzuführen. Sie bietet sowohl synchrone als auch asynchrone Vorgänge für den Zugriff auf eine bestimmte Verwendung des Sprachdiensts, z. B. Spracherkennung oder Schlüsselbegriffsextraktion.

Eingabe

Eine Texteingabe, auch als Dokument bezeichnet, ist eine einzelne Dokumenteinheit, die von den Vorhersagemodellen im Sprachdienst analysiert werden soll. Vorgänge auf einem Textanalyse-Client können ein einzelnes Dokument oder eine Sammlung von Dokumenten als Batch analysieren. Weitere Informationen finden Sie unter Dienstbeschränkungen für das Dokument, einschließlich Einschränkungen für die Dokumentlänge, maximale Batchgröße und unterstützte Textcodierung.

Vorgang für mehrere Dokumente

Für jeden unterstützten Vorgang stellt der Textanalyse-Client Methodenüberladungen bereit, um ein einzelnes Dokument, einen Batch von Dokumenten als Zeichenfolgen oder einen Batch mit entwederTextDocumentInput- oder DetectLanguageInput -Objekten zu nehmen. Durch die Überladung, die den TextDocumentInput - oder DetectLanguageInput -Batch nimmt , können Aufrufer jedem Dokument eine eindeutige ID zukommen lassen, angeben, dass die Dokumente im Batch in verschiedenen Sprachen geschrieben sind, oder einen Länderhinweis zur Sprache des Dokuments bereitstellen.

Rückgabewert

Ein Vorgangsergebnis, z AnalyzeSentimentResult. B. , ist das Ergebnis eines Sprachdienstvorgangs, der eine Vorhersage oder Vorhersagen zu einem einzelnen Dokument und eine Liste der darin enthaltenen Warnungen enthält. Der Ergebnistyp eines Vorgangs kann optional auch Informationen zum Eingabedokument und seiner Verarbeitung enthalten. Ein Vorgangsergebnis enthält eine isError Eigenschaft, mit der ermittelt werden kann, ob ein ausgeführter Vorgang für das angegebene Dokument erfolgreich war oder nicht erfolgreich war. Wenn der Vorgang zu einem Fehler führt, können Sie einfach abrufen TextAnalyticsError aufrufengetError(), der den Grund enthält, warum er nicht erfolgreich ist. Wenn Sie daran interessiert sind, wie viele Zeichen sich in Ihrem Dokument befinden oder wie viele Vorgangstransaktionen durchgeführt wurden, rufen Sie getStatistics() einfach auf, um die zu erhalten, die TextDocumentStatistics beide Informationen enthält.

Rückgabewertauflistung

Eine Vorgangsergebnissammlung, z AnalyzeSentimentResultCollection. B. , bei der es sich um die Sammlung des Ergebnisses des Analysevorgangs handelt. Sie enthält auch die Modellversion des Vorgangs und statistiken der Batchdokumente.

Hinweis: Es wird empfohlen, die Batchmethoden zu verwenden, wenn Sie in Produktionsumgebungen arbeiten, da sie es Ihnen ermöglichen, eine Anforderung mit mehreren Dokumenten zu senden. Dies ist effizienter als das Senden einer Anforderung pro Dokument.

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der häufigsten Sprachdienstaufgaben behandeln, einschließlich:

• Analysieren der Stimmung
• Sprache erkennen
• Extrahieren von Schlüsselbegriffen
• Erkennen benannter Entitäten
• Erkennen persönlich identifizierbarer Informationsentitäten
• Erkennen verknüpfter Entitäten
• Analysieren von Entitäten im Gesundheitswesen
• Analysieren mehrerer Aktionen
• Erkennung benutzerdefinierter Entitäten
• Benutzerdefinierte Textklassifizierung
• Zusammenfassung abstraktioniver Text
• Extraktive Textzusammenfassung

Textanalyse Client

Der Sprachdienst unterstützt sowohl die synchrone als auch die asynchrone Clienterstellung mithilfe TextAnalyticsClientBuildervon ,

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

oder

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

Analysieren von Stimmungen

Führen Sie ein Vorhersagemodell aus, um die positive, negative, neutrale oder gemischte Stimmung im bereitgestellten Dokument oder Batch von Dokumenten zu identifizieren.

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

Beispiele zur Verwendung der empfohlenen Produktionsoption AnalyzeSentimentBatch finden Sie hier.

Ausführlichere Informationen zu den Meinungen im Zusammenhang mit Aspekten eines Produkts/einer Dienstleistung finden Sie unter Aspect-based Sentiment Analysis in Natural Language Processing (NLP), siehe Beispiel zur Stimmungsanalyse mit Opinion Mining.

Eine konzeptionelle Diskussion zur Stimmungsanalyse finden Sie in der Servicedokumentation.

Sprache erkennen

Führen Sie ein Vorhersagemodell aus, um die Sprache zu bestimmen, in der das bereitgestellte Dokument oder der bereitgestellte Dokumentbatch geschrieben ist.

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

Beispiele zur Verwendung der empfohlenen Produktionsoption DetectLanguageBatch finden Sie hier. Eine konzeptionelle Diskussion zur Spracherkennung finden Sie in der Dienstdokumentation.

Schlüsselbegriffe extrahieren

Führen Sie ein Modell aus, um eine Sammlung von wichtigen Ausdrücken zu identifizieren, die im bereitgestellten Dokument oder Batch von Dokumenten gefunden werden.

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

Beispiele zur Verwendung der empfohlenen Produktionsoption ExtractKeyPhrasesBatch finden Sie hier. Eine konzeptionelle Diskussion zur Schlüsselbegriffsextraktion finden Sie in der Dienstdokumentation.

Erkennen benannter Entitäten

Führen Sie ein Vorhersagemodell aus, um eine Sammlung benannter Entitäten im bereitgestellten Dokument oder Dokumentbatch zu identifizieren und diese Entitäten in Kategorien wie Person, Standort oder organization zu kategorisieren. Weitere Informationen zu verfügbaren Kategorien finden Sie unter Benannte Entitätskategorien.

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

Beispiele zur Verwendung der empfohlenen Produktionsoption RecognizeEntitiesBatch finden Sie hier. Eine konzeptionelle Diskussion zur Erkennung benannter Entitäten finden Sie in der Dienstdokumentation.

Identifizierbare Entitäten von Informationen erkennen

Führen Sie ein Vorhersagemodell aus, um eine Sammlung von Personally Identifiable Information(PII)-Entitäten im bereitgestellten Dokument zu identifizieren. Es erkennt und kategorisiert PII-Entitäten in seinem Eingabetext, z. B. Sozialversicherungsnummern, Bankkontoinformationen, Kredit- Karte-Nummern und vieles mehr. Dieser Endpunkt wird nur für API-Versionen v3.1-preview.1 und höher unterstützt.

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

Beispiele zur Verwendung der empfohlenen Produktionsoption RecognizePiiEntitiesBatch finden Sie hier. Informationen zu unterstützten PII-Entitätstypen finden Sie in der Dienstdokumentation.

Erkennen von verknüpften Entitäten

Führen Sie ein Vorhersagemodell aus, um eine Sammlung von Entitäten zu identifizieren, die im bereitgestellten Dokument oder Im bereitgestellten Dokumentbatch gefunden werden, und fügen Sie Informationen ein, die die Entitäten mit ihren entsprechenden Einträgen in einer bekannten Wissensdatenbank verknüpfen.

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

Beispiele zur Verwendung der empfohlenen Produktionsoption RecognizeLinkedEntitiesBatch finden Sie hier. Eine konzeptionelle Diskussion zur Entitätsverknüpfung finden Sie in der Dienstdokumentation.

Analysieren von Gesundheitseinrichtungen

Text Analytics for Health ist ein Containerdienst, der relevante medizinische Informationen aus unstrukturierten Texten wie Arztbriefen, Entlassungsberichten, klinischen Dokumenten und elektronischen Gesundheitsakten extrahiert und bezeichnet.

• Anerkennung von Entitäten im Gesundheitswesen

Weitere Informationen finden Sie unter Vorgehensweise: Verwenden von Textanalyse für die Integrität.

Erkennung benutzerdefinierter Entitäten

Die benutzerdefinierte NER ist eines der benutzerdefinierten Features, die in Azure Cognitive Service für Language angeboten werden. Es handelt sich um einen cloudbasierten API-Dienst, der Machine Learning-Intelligenz anwendet, um Ihnen die Erstellung benutzerdefinierter Modelle für benutzerdefinierte NER-Aufgaben zu ermöglichen.

• Erkennung benutzerdefinierter Entitäten

Weitere Informationen finden Sie unter Verwenden: Erkennung benutzerdefinierter Entitäten.

Benutzerdefinierte Textklassifizierung

Die benutzerdefinierte Textklassifizierung ist eines der benutzerdefinierten Features von Azure Cognitive Service für Language. Es handelt sich um einen cloudbasierten API-Dienst, der Machine Learning-Intelligenz anwendet, um Ihnen die Erstellung benutzerdefinierter Modelle für Textklassifizierungsaufgaben zu ermöglichen.

• Klassifizierung mit einzelnen Bezeichnungen

• Klassifizierung mit mehreren Bezeichnungen

Weitere Informationen finden Sie unter Verwenden: Benutzerdefinierte Textklassifizierung.

Analysieren mehrerer Aktionen

Die Analyze Funktionalität ermöglicht die Auswahl der unterstützten Sprachdienstfeatures, die in derselben Gruppe von Dokumenten ausgeführt werden sollen. Derzeit werden folgende Features unterstützt:

• Erkennung benannter Entitäten
• Erkennung von PII-Entitäten
• Erkennung verknüpfter Entitäten
• Schlüsselwortextraktion
• Standpunktanalyse
• Analyse des Gesundheitswesens
• Benutzerdefinierte Entitätserkennung (API-Version 2022-05-01 und höher)
• Benutzerdefinierte Single-Label Klassifizierung (API-Version 2022-05-01 und höher)
• Benutzerdefinierte Klassifizierung mit mehreren Bezeichnungen (API-Version 2022-05-01 und höher)
• Zusammenfassung abstrakter Text (API-Version 2023-04-01 und höher)
• Extraktive Textzusammenfassung (API-Version 2023-04-01 und höher)

Beispiel: Analyse mehrerer Aktionen

Weitere Beispiele, z. B. asynchrone Beispiele, finden Sie hier.

Problembehandlung

Allgemein

Textanalyse Clients lösen Ausnahmen aus. Wenn Sie beispielsweise versuchen, die Sprachen eines Textbatches mit denselben Dokument-IDs zu erkennen, wird ein Fehler zurückgegeben, 400 der auf eine fehlerhafte Anforderung hinweist. Im folgenden Codeausschnitt wird der Fehler ordnungsgemäß behandelt, indem die Ausnahme abgefangen wird und zusätzliche Fehlerinformationen angezeigt werden.

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

Aktivieren der Clientprotokollierung

Sie können die Umgebungsvariable AZURE_LOG_LEVEL so festlegen, dass in der Clientbibliothek vorgenommene Protokollierungsanweisungen angezeigt werden. Durch das Festlegen von AZURE_LOG_LEVEL=2 würden beispielsweise alle Informations-, Warnungs- und Fehlerprotokollmeldungen angezeigt. Die Protokolliergrade finden Sie hier: Protokolliergrade.

HTTP-Standardclient

Alle Clientbibliotheken verwenden standardmäßig den Netty-HTTP-Client. Durch Hinzufügen der obigen Abhängigkeit wird die Clientbibliothek automatisch für die Verwendung des Netty-HTTP-Clients konfiguriert. Das Konfigurieren oder Ändern des HTTP-Clients wird detailliert im Wiki zu HTTP-Clients beschrieben.

SSL-Standardbibliothek

Alle Clientbibliotheken verwenden standardmäßig die Tomcat-native Boring-SSL-Bibliothek, um die Leistung auf nativer Ebene für SSL-Vorgänge zu ermöglichen. Die Boring-SSL-Bibliothek ist eine Uber-JAR-Datei mit nativen Bibliotheken für Linux/macOS/Windows und bietet im Vergleich zur SSL-Standardimplementierung im JDK eine bessere Leistung. Weitere Informationen, einschließlich zur Reduzierung der Abhängigkeitsgröße, finden Sie im Abschnitt Leistungsoptimierung des Wikis.

Nächste Schritte

• Die Beispiele werden hier ausführlich erläutert.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Für die meisten Beiträge ist die Zustimmung zu einer Lizenzvereinbarung für Mitwirkende (Contributor License Agreement, CLA) erforderlich, in der Sie erklären, dass Sie dazu berechtigt sind, uns die Rechte für die Nutzung Ihres Beitrags zu erteilen, und dies auch tun.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.