Grundlagen der Natural Language API

In diesem Dokument wird die grundlegende Verwendung der Cloud Natural Language API erläutert. Sie erfahren, welche Arten von Anfragen Sie an die Natural Language API senden können, wie Sie diese Anfragen erstellen und die Antworten verarbeiten. Wir empfehlen allen Nutzern, diese Anleitung für die Natural Language API zu lesen und eines der damit verknüpften Lernprogramme durchzugehen, bevor sie sich näher mit der API befassen.

Funktionen der Natural Language API

Die Natural Language API verfügt über mehrere Methoden zur Durchführung von Analysen und Erstellung von Anmerkungen zu Ihrem Text. Die einzelnen Ebenen einer Analyse liefern wertvolle Informationen für das Sprachverständnis. Zu diesen Methoden zählen:

• Die Sentimentanalyse untersucht den gegebenen Text auf die darin vorherrschende emotionale Stimmung, insbesondere um zu erkennen, ob der Autor eine positive, negative oder neutrale Einstellung hat. Die Sentimentanalyse wird mit der Methode analyzeSentiment durchgeführt.

• Die Entitätsanalyse untersucht den gegebenen Text auf bekannte Entitäten (Eigennamen wie zum Beispiel Personen des öffentlichen Lebens, Sehenswürdigkeiten usw.) und gibt Informationen über diese Entitäten zurück. Sie untersucht häufige Gattungsnamen (z. B. Restaurant, Stadion usw.) und gibt Informationen über diese Entitäten zurück. Die Entitätsanalyse erfolgt mit der Methode analyzeEntities.

• Die Sentimentanalyse pro Entität untersucht den gegebenen Text auf bekannte Entitäten (Eigennamen und Gattungsnamen), gibt Informationen über diese Entitäten zurück und erkennt die in der Entität vorherrschende emotionale Stimmung, insbesondere um zu erkennen, ob der Autor eine positive, negative oder neutrale Einstellung hat. Die Entitätsanalyse erfolgt mit der Methode analyzeEntitySentiment.

• Die Syntaxanalyse extrahiert linguistische Informationen und unterteilt den gegebenen Text in eine Reihe von Sätzen und Tokens (im Allgemeinen Wortgrenzen) für eine weitere Analyse dieser Tokens. Die Syntaxanalyse erfolgt mit der Methode analyzeSyntax.

• Die Inhaltsklassifizierung analysiert Textinhalt und gibt eine Inhaltskategorie für den Inhalt zurück. Die Inhaltsklassifizierung wird mithilfe der Methode classifyText durchgeführt.

Bei jedem API-Aufruf wird die Sprache erkannt und zurückgegeben, falls bei der ersten Anfrage keine Sprache angegeben wurde.

Außerdem können Sie, wenn Sie bei einem bestimmten Text mehrere Analysevorgänge natürlicher Sprache mit nur einem API-Aufruf durchführen möchten, mit der annotateText-Anfrage auch eine Sentimentanalyse und eine Entitätsanalyse durchführen.

Grundlegende Natural Language-Anfragen

Die Natural Language API ist eine REST API und besteht aus JSON-Anfragen und -Antworten. Hier ist eine einfache Anfrage für eine Natural Language JSON-Entitätsanalyse:

{
  "document":{
    "type":"PLAIN_TEXT",
    "language_code": "EN",
    "content":"'Lawrence of Arabia' is a highly rated film biography about
                British Lieutenant T. E. Lawrence. Peter O'Toole plays
                Lawrence in the film."
  },
  "encodingType":"UTF8"
}

Diese Felder werden im Folgenden beschrieben:

• document enthält die Daten für diese Anfrage, die aus folgenden Unterfeldern besteht:
  • type: Dokumenttyp (HTML oder PLAIN_TEXT).
  • language: (optional) die Sprache des Textes in der Anfrage. Falls nicht angegeben, wird die Sprache automatisch erkannt. Informationen dazu, welche Sprachen von der Natural Language API unterstützt werden, finden Sie unter Sprachunterstützung. Nicht unterstützte Sprachen geben in der JSON-Antwort einen Fehler zurück.
    
  • Entweder content oder gcsContentUri, die den auszuwertenden Text enthalten. Bei der Übergabe von content wird dieser Text direkt in der JSON-Anfrage angegeben (wie oben dargestellt). Bei der Übergabe von gcsContentUri muss das Feld einen URI enthalten, der auf Textinhalte in Google Cloud Storage verweist.
• encodingType – (erforderlich) das Codierungsschema, bei dem die zurückgegebenen Zeichen-Offsets im Text, die mit der Codierung des übergebenen Texts übereinstimmen müssen, zu berechnen sind. Wenn dieser Parameter nicht festgelegt ist, gibt die Anfrage keinen Fehler zurück, doch alle Offsets werden auf -1 gesetzt.

Textinhalt festlegen

Bei der Übergabe einer Natural Language API-Anfrage haben Sie zwei Möglichkeiten, den zu verarbeitenden Text anzugeben:

• Übergabe des Texts direkt in einem content-Feld
• Übergabe eines Google Cloud Storage-URIs in einem gcsContentUri-Feld

In beiden Fällen dürfen die zulässigen Inhaltsbeschränkungen nicht überschritten werden. Beachten Sie, dass für die Angabe dieser Inhaltsbeschränkungen Bytes und nicht Zeichen verwendet werden. Die Zeichenlänge hängt daher von der Codierung Ihres Texts ab.

Die Anfrage unten bezieht sich auf eine Datei in Google Cloud Storage mit der Gettysburg-Rede:

{
  "document":{
    "type":"PLAIN_TEXT",
    "language": "EN",
    "gcsContentUri":"gs://cloud-samples-tests/natural-language/gettysburg.txt"
  },
}

Sentimentanalyse

Bei der Sentimentanalyse wird versucht, die allgemeine (positive oder negative) Einstellung zu erkennen, die im Text zum Ausdruck kommt. Die Stimmung wird durch numerische score- und magnitude-Werte dargestellt.

Antwortfelder der Sentimentanalyse

Hier sehen Sie eine Beispielantwort für analyzeSentiment auf die Gettysburg-Rede:

{
  "documentSentiment": {
    "score": 0.2,
    "magnitude": 3.6
  },
  "language_code": "en",
   "sentences": [
    {
      "text": {
        "content": "Four score and seven years ago our fathers brought forth
        on this continent a new nation, conceived in liberty and dedicated to
        the proposition that all men are created equal.",
        "beginOffset": 0
      },
      "sentiment": {
        "magnitude": 0.8,
        "score": 0.8
      }
    },
   ...
}

Hier werden die Feldwerte beschrieben:

• documentSentiment enthält die allgemeine Stimmung des Dokuments, die aus den folgenden Feldern besteht:
  • Der score-Wert der Stimmung liegt zwischen -1.0 (negativ) und 1.0 (positiv) und entspricht der allgemeinen emotionalen Tendenz des Textes.
  • Der magnitude-Wert gibt die allgemeine Stärke der (sowohl positiven als auch negativen) Stimmung im jeweiligen Text zwischen 0.0 und +inf an. Anders als der score-Wert ist der magnitude-Wert nicht für documentSentiment normalisiert. Jeder Ausdruck von Stimmung im Text, ob positiv oder negativ, trägt zum magnitude-Wert bei, deshalb kann der Wert bei längeren Textblöcken höher sein.
• language_code enthält die Sprache des Dokuments, die in der ersten Anfrage übergeben oder, falls nicht angegeben, automatisch erkannt wird.
• language_supported enthält einen booleschen Wert, der angibt, ob die Sprache offiziell unterstützt wird.
• sentences enthält eine Liste der aus dem Originaldokument extrahierten Sätze, die Folgendes enthält:
  • sentiment enthält die mit den Sätzen verknüpften Sentimentwerte auf Satzebene. Sie umfassen Werte für score zwischen -1.0 (negativ) und 1.0 (positiv) sowie magnitude-Werte zwischen 0.0 und 1.0. magnitude für sentences wird normalisiert.

Ein Sentimentwert von 0.2 für die Gettysburg-Rede gibt an, dass die Stimmung leicht positiv ist. Der Magnitude-Wert von 3.6 hingegen steht für ein relativ emotionales Dokument, wenn man bedenkt, wie kurz es ist (nur etwa ein Absatz). Beachten Sie, dass der erste Satz der Gettysburg-Rede einen sehr hohen positiven score von 0.8 enthält.

Werte der Sentimentanalyse interpretieren

Der Wert score der Stimmung eines Dokuments gibt die allgemeine Emotion eines Dokuments an. Der Wert magnitude der Stimmung eines Dokuments gibt an, wie viele emotionale Inhalte im Dokument vorhanden sind, und dieser Wert ist häufig proportional zur Länge des Dokuments.

Die Natural Language API gibt Unterschiede zwischen positiven und negativen Emotionen in einem Dokument an, identifiziert aber keine konkreten positiven und negativen Emotionen. Zum Beispiel gelten "wütend" und "traurig" beide als negative Emotionen. Wenn die Natural Language API jedoch Text analysiert, der als "wütend" oder "traurig" gilt, gibt die Antwort nur an, dass die Stimmung im Text negativ ist, nicht dass sie "traurig" oder "wütend" ist.

Ein Dokument mit einem neutralen Score (etwa 0.0) verweist möglicherweise auf ein Dokument mit wenig Emotion oder ein Dokument mit gemischten Emotionen, in dem sowohl positive als auch negative Werte zu finden sind, die sich gegenseitig aufheben. Im Allgemeinen können Sie diese Fälle mit magnitude-Werten eindeutig machen, da neutrale Dokumente einen niedrigen magnitude-Wert haben, während gemischte Dokumente höhere magnitude-Werte haben.

Stellen Sie beim Vergleich von Dokumenten, vor allem von Dokumenten verschiedener Länge, sicher, dass Sie die magnitude-Werte verwenden, um Ihre Scores zu kalibrieren, da Sie mit ihnen die maßgebliche Menge an emotionalen Inhalten einschätzen können.

Die folgende Tabelle enthält einige Beispielwerte und ihre Interpretation: