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": "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 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": "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 angepasst. 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 enthält die Sprache des Dokuments, die in der ersten Anfrage übergeben oder, falls nicht angegeben, automatisch erkannt 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 und magnitude (siehe Beschreibung oben).

Ein Antwortwert auf die Gettysburg-Rede mit einem Score von 0.2 gibt an, dass das Dokument emotional leicht positiv ist. Ein Wert von 3.6 hingegen steht für ein relativ emotionales Dokument, wenn man bedenkt, wie kurz das Dokument ist (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 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 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:

Stimmung Beispielwerte
Eindeutig positiv* "score": 0,8, "magnitude": 3,0
Eindeutig negativ* "score": -0,6, "magnitude": 4,0
Neutral "score": 0,1, "magnitude": 0,0
Gemischt "score": 0,0, "magnitude": 4,0

* Die Stimmungen "Eindeutig positiv" und "Eindeutig negativ" variieren für verschiedene Anwendungsfälle und Kunden. Sie sehen möglicherweise unterschiedliche Suchergebnisse für Ihr spezifisches Szenario. Wir empfehlen Ihnen, einen Schwellenwert zu definieren, der Ihrem Zweck entspricht, und dann den Schwellenwert nach dem Testen anzupassen und die Ergebnisse zu überprüfen. Zum Beispiel können Sie einen Schwellenwert mit einem Score über 0,25 als eindeutig positiv definieren und dann den Score-Schwellenwert in 0,15 ändern, nachdem Sie Ihre Daten und Ergebnisse überprüft haben und feststellen, dass die Scores von 0,15–0,25 ebenfalls als positiv angesehen werden sollten.

Entitätsanalyse

Die Entitätsanalyse stellt Informationen über Entitäten im Text bereit, die sich im Allgemeinen auf benannte "Dinge" beziehen, wie zum Beispiel berühmte Personen, Sehenswürdigkeiten, allgemeine Objekte usw.

Entitäten fallen im weitesten Sinn in zwei Kategorien: Eigennamen, die eindeutigen Entitäten zugeordnet werden (bestimmte Personen, Orte usw.), oder Gattungsnamen (bei der Verarbeitung von Natural Language auch "Substantive" genannt). Hier kann eine allgemeine Regel gut befolgt werden: Wenn es sich um ein Substantiv handelt, kann es als "Entität" bezeichnet werden. Entitäten werden im Originaltext als indexierte Offsets zurückgegeben.

Eine Anfrage für eine Entitätsanalyse muss ein encodingType-Argument übergeben, damit die zurückgegebenen Offsets entsprechend interpretiert werden können.

Antwortfelder der Entitätsanalyse

Die Entitätsanalyse gibt eine Gruppe der erkannten Entitäten und der mit diesen Entitäten verknüpften Parameter zurück, wie zum Beispiel Entitätstyp, Relevanz der Entität für den Gesamttext und Textstellen, die sich auf dieselbe Entität beziehen. Entitäten werden in der Reihenfolge ihrer salience-Scores (vom höchsten bis zum niedrigsten) zurückgegeben, die ihre Relevanz für den Gesamttext wiedergeben.

Hier ist eine Antwort für analyzeEntities auf die Entitätsanfrage:

{
  "entities": [
    {
      "name": "Lawrence of Arabia",
      "type": "WORK_OF_ART",
      "metadata": {
        "mid": "/m/0bx0l",
        "wikipedia_url": "http://en.wikipedia.org/wiki/Lawrence_ofArabia(film)"
      },
      "salience": 0.75222147,
      "mentions": [
        {
          "text": {
            "content": "Lawrence of Arabia",
            "beginOffset": 1
          },
          "type": "PROPER"
        },
        {
          "text": {
            "content": "film biography",
            "beginOffset": 39
          },
          "type": "COMMON"
        }
      ]
    },
    {
      "name": "T.E. Lawrence",
      "type": "PERSON",
      "metadata": {
        "mid": "/m/0bx5v",
        "wikipedia_url": "http://en.wikipedia.org/wiki/T._E._Lawrence"
      },
      "salience": 0.12430617,
      "mentions": [
        {
          "text": {
            "content": "T. E. Lawrence",
            "beginOffset": 94
          },
          "type": "PROPER"
        },
        {
          "text": {
            "content": "Lieutenant",
            "beginOffset": 83
          },
          "type": "COMMON"
        },
        {
          "text": {
            "content": "Lawrence",
            "beginOffset": 145
          },
          "type": "PROPER"
        }
      ]
    },
    {
      "name": "British",
      "type": "LOCATION",
      "metadata": {
        "mid": "/m/07ssc",
        "wikipedia_url": "http://en.wikipedia.org/wiki/United_Kingdom"
      },
      "salience": 0.078094982,
      "mentions": [
        {
          "text": {
            "content": "British",
            "beginOffset": 75
          },
          "type": "PROPER"
        }
      ]
    },
    {
      "name": "film",
      "type": "WORK_OF_ART",
      "metadata": {},
      "salience": 0.033808723,
      "mentions": [
        {
          "text": {
            "content": "film",
            "beginOffset": 161
          },
          "type": "COMMON"
        }
      ]
    },
    {
      "name": "Peter O'Toole",
      "type": "PERSON",
      "metadata": {
        "mid": "/m/0h0jz",
        "wikipedia_url": "http://en.wikipedia.org/wiki/Peter_O'Toole"
      },
      "salience": 0.011568651,
      "mentions": [
        {
          "text": {
            "content": "Peter O'Toole",
            "beginOffset": 110
          },
          "type": "PROPER"
        }
      ]
    }
  ],
  "language": "en"
}

Beachten Sie, dass die Natural Language API Entitäten für "Lawrence of Arabia" (den Film) und "T. E. Lawrence" (die Person) zurückgibt. Mit der Entitätsanalyse können ähnliche Entitäten wie zum Beispiel "Lawrence" in diesem Fall eindeutig gemacht werden.

Die Entitätsparameter werden in den folgenden Feldern gespeichert:

  • type gibt den Typ dieser Entität an, zum Beispiel, ob die Entität eine Person, ein Ort, ein Gebrauchsgut usw. ist. Mit diesen Angaben können Entitäten unterschieden und/oder eindeutig beschrieben sowie für das Schreiben von Mustern oder das Extrahieren von Informationen verwendet werden. Zum Beispiel können mit einem type-Wert ähnlich lautende Entitäten wie "Lawrence of Arabia" mit der Tag-Kennzeichnung WORK_OF_ART (Film) von "T. E. Lawrence" mit der Tag-Kennzeichnung PERSON unterschieden werden. (Weitere Informationen finden Sie unter Entitätstypen.)

  • metadata enthält Quellinformationen über das Knowledge-Repository der Entität. Zusätzliche Repositories werden möglicherweise in Zukunft bereitgestellt. Dieses Feld kann die folgenden Unterfelder enthalten:

    • wikipedia_url enthält, sofern vorhanden, die Wikipedia-URL für diese Entität.
    • mid enthält, sofern vorhanden, die maschinengenerierte Kennzeichnung (Machine-Generated Identifier, MID), die dem Google Knowledge Graph-Eintrag der Entität entspricht. Die mid-Werte kommen in verschiedenen Sprachen nur einmal vor, sodass Sie mit solchen Werten Entitäten aus verschiedenen Sprachen verknüpfen können. Weitere Informationen zum Untersuchen dieser MID-Werte finden Sie in der Dokumentation zur Google Knowledge Graph Search API.

      Nicht alle für mid zurückgegebenen Werte können mit der Google Knowledge Graph API überprüft werden. Sie können mid als eindeutige Kennung für eine Entität verwenden. Sie sollten es jedoch nicht dazu verwenden, zusätzliche Informationen über die Entität abzurufen.

  • salience gibt den Stellenwert bzw. die Relevanz dieser Entität für den gesamten Dokumenttext an. Dieser Wert kann beim Abrufen von Informationen und bei der Zusammenfassung nützlich sein, indem auffällige Entitäten priorisiert werden. Werte, die näher bei 0.0 liegen, haben eine niedrige Relevanz. Werte, die näher bei 1.0 liegen, haben eine hohe Relevanz.

  • mentions geben die Offset-Stellen im Text an, an denen eine Entität erwähnt wird. Diese Informationen sind nützlich, wenn Sie alle Erwähnungen der Person "Lawrence" im Text finden möchten, aber nicht den Filmtitel. Sie können mit Erwähnungen auch die Liste der Entitätsaliasse wie "Lawrence" erfassen, die sich auf dieselbe Entität "T. E. Lawrence" beziehen. Eine Entitätserwähnung ist vom Typ PROPER oder COMMON. Zum Beispiel kann eine Entität, die ein Eigenname ist, für "Lawrence of Arabia" direkt als der Filmtitel oder als ein allgemeines Substantiv ("Filmbiografie" über T. E. Lawrence) erwähnt werden.

Sentimentanalyse pro Entität

Bei der Sentimentanalyse pro Entität wird die Entitätsanalyse mit der Sentimentanalyse kombiniert und es wird versucht, die (positive oder negative) Einstellung zu erkennen, die in den Entitäten des Texts zum Ausdruck kommt. Jede Entitätsstimmung wird durch numerische Score- und Magnitude-Werte dargestellt und für jede Erwähnung einer Entität bestimmt. Diese Punktzahlen werden dann in eine allgemeine Sentimentpunktzahl (Score und Magnitude) für eine Entität zusammengefasst.

Anfragen für eine Sentimentanalyse pro Entität

So werden Anfragen für eine Sentimentanalyse pro Entität über die Methode analyzeEntitySentiment an die Natural Language gesendet:

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"I love R&B music. Marvin Gaye is the best.
               'What's Going On' is one of my favorite songs.
               It was so sad when Marvin Gaye died."
  },
  "encodingType":"UTF8"
}

Sie können in Ihrer Anfrage einen optionalen language-Parameter angeben, der den Sprachcode für den Text im content-Parameter identifiziert. Wenn Sie keinen language-Parameter angeben, erkennt die Natural Language die Sprache für Ihren Anfrageinhalt automatisch. Informationen dazu, welche Sprachen von der Natural Language unterstützt werden, finden Sie unter Sprachunterstützung.

Antworten auf eine Sentimentanalyse pro Entität

Die Natural Language API verarbeitet den gegebenen Text, um die Entitäten zu extrahieren und die Stimmung zu bestimmen. Eine Anfrage für eine Sentimentanalyse pro Entität gibt eine Antwort zurück, die folgende Informationen enthält: die in den Dokumentinhalten gefundenen entities, den Eintrag mentions für jede Erwähnung der Entität und die numerischen Werte von score und magnitude für jede Erwähnung, wie unter Werte der Sentimentanalyse interpretieren beschrieben. Die score- und magnitude-Werte für eine Entität sind eine Zusammenfassung der spezifischen score- und magnitude-Werte für jede Erwähnung der Entität. Die score- und magnitude-Werte für eine Entität können 0 sein, wenn die Stimmung im Text einen niedrigen Wert ergibt, was zu einer magnitude von 0 führt, oder wenn die Stimmung gemischt ist, was zu einem score von 0 führt.

{
  "entities": [
    {
      "name": "R&B music",
      "type": "WORK_OF_ART",
      "metadata": {},
      "salience": 0.5306305,
      "mentions": [
        {
          "text": {
            "content": "R&B music",
            "beginOffset": 7
          },
          "type": "COMMON",
          "sentiment": {
            "magnitude": 0.9,
            "score": 0.9
          }
        }
      ],
      "sentiment": {
        "magnitude": 0.9,
        "score": 0.9
      }
    },
    {
      "name": "Marvin Gaye",
      "type": "PERSON",
      "metadata": {
        "mid": "/m/012z8_",
        "wikipedia_url": "http://en.wikipedia.org/wiki/Marvin_Gaye"
      },
      "salience": 0.21584158,
      "mentions": [
        {
          "text": {
            "content": "Marvin Gaye",
            "beginOffset": 18
          },
          "type": "PROPER",
          "sentiment": {
            "magnitude": 0.4,
            "score": 0.4
          }
        },
        {
          "text": {
            "content": "Marvin Gaye",
            "beginOffset": 138
          },
          "type": "PROPER",
          "sentiment": {
            "magnitude": 0.2,
            "score": -0.2
          }
        }
      ],
      "sentiment": {
        "magnitude": 0.6,
        "score": 0.1
      }
    },
    ...
  ],
  "language": "en"
}

Ein Beispiel finden Sie unter Entitätsstimmung analysieren.

Syntaxanalyse

Die Natural Language API stellt leistungsstarke Tools für die Analyse und das Parsen von Text durch die Syntaxanalyse bereit. Verwenden Sie für die Durchführung der Syntaxanalyse die analyzeSyntax-Methode.

Die Syntaxanalyse besteht aus den folgenden Vorgängen:

  • Bei der Satzextraktion wird der Textfluss in eine Reihe von Sätzen unterteilt.
  • Bei der Vergabe von Tokens wird der Textfluss in eine Reihe von Tokens unterteilt, wobei jedes Token in der Regel einem einzelnen Wort entspricht.
  • Die Natural Language API verarbeitet dann die Tokens und fügt unter Verwendung ihrer Stellungen innerhalb der Sätze Syntaxinformationen zu den Tokens hinzu.

Eine vollständige Dokumentation für die Gruppe von Syntaxtokens finden Sie in der Anleitung zu Morphologie & Abhängigkeitsstrukturen.

Syntaxanalyseanfragen

So werden Anfragen für eine Syntaxanalyse über die Methode analyzeSyntax an die Natural Language API gesendet:

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Ask not what your country can do for you,
               ask what you can do for your country."
  },
  "encodingType":"UTF8"
}

Syntaxanalyseantworten

Die Natural Language API verarbeitet den gegebenen Text und extrahiert Sätze und Tokens. Eine Syntaxanalyseanfrage gibt eine Antwort zurück, die diese sentences und tokens in der folgenden Form enthält:

{
  "sentences": [
    ... Array of sentences with sentence information
  ],
  "tokens": [
    ... Array of tokens with token information
  ]
}

Satzextraktion

Bei der Durchführung einer Syntaxanalyse gibt die Natural Language API ein Array von Sätzen zurück, die aus dem bereitgestellten Text extrahiert wurden, wobei jeder Satz die folgenden Felder in einem übergeordneten text-Element enthält:

  • beginOffset gibt das (nullbasierte) Zeichen-Offset im gegebenen Text zurück, bei dem der Satz beginnt. Beachten Sie, dass dieses Offset mit dem übergebenen encodingType berechnet wird.
  • content enthält den vollständigen Text des extrahierten Satzes.

Das folgende Element vom Typ sentences wird z. B. als Antwort auf eine Syntaxanalyseanfrage für die Gettysburg-Rede zurückgegeben:

{
  "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
      }
    },
    {
      "text": {
        "content": "Now we are engaged in a great civil war, testing whether
                    that nation or any nation so conceived and so dedicated can
                    long endure.",
        "beginOffset": 175
      }
    },
...
...
    {
      "text": {
        "content": "It is rather for us to be here dedicated to the great task
                    remaining before us--that from these honored dead we take
                    increased devotion to that cause for which they gave the
                    last full measure of devotion--that we here highly resolve
                    that these dead shall not have died in vain, that this
                    nation under God shall have a new birth of freedom, and that
                    government of the people, by the people, for the people
                    shall not perish from the earth.",
        "beginOffset": 1002
      }
    }
  ],
  "language": "en"
}

Eine Syntaxanalyse-Anfrage an die Natural Language API enthält außerdem eine Reihe von Tokens. Sie können die mit den einzelnen Tokens verknüpften Informationen verwenden, um eine weitere Analyse der zurückgegebenen Sätze durchzuführen. Weitere Informationen zu diesen Tokens finden Sie in der Anleitung zu Morphologie & Abhängigkeitsstrukturen.

Tokenisierung

Bei der analyzeSyntax-Methode wird außerdem Text in eine Reihe von Tokens umgewandelt, die den verschiedenen Textelementen (Wortgrenzen) der übergebenen Inhalte entsprechen. Der Vorgang, bei dem die Natural Language API diese Reihe von Tokens entwickelt, wird Tokenisierung genannt.

Nachdem diese Tokens extrahiert sind, werden sie von der Natural Language API verarbeitet, um die jeweilige Wortart (einschließlich morphologischer Informationen) und das Lemma der Tokens zu ermitteln. Außerdem werden Tokens evaluiert und in eine Abhängigkeitsstruktur eingeordnet. Damit erkennen Sie die syntaktische Bedeutung der Tokens und können die Beziehung der Tokens zueinander und zu den Sätzen veranschaulichen, in denen sie enthalten sind. Die mit diesen Tokens verknüpften syntaktischen und morphologischen Informationen sind nützlich für das Verständnis der syntaktischen Struktur von Sätzen in der Natural Language API.

Hier ist die Reihe von Tokenfeldern, die in einer JSON-Antwort auf eine Syntaxanalyse zurückgegeben wird:

  • text enthält die mit diesem Token verknüpften Textdaten mit den folgenden untergeordneten Feldern:

    • beginOffset enthält das (nullbasierte) Zeichen-Offset im gegebenen Text. Obwohl die (unten beschriebenen) Abhängigkeiten nur in Sätzen vorhanden sind, befinden sich Token-Offsets im gesamten Text. Beachten Sie, dass dieses Offset mit dem übergebenen encodingType berechnet wird.
    • content enthält die eigentlichen Textinhalte aus dem Originaltext.
  • partOfSpeech liefert grammatische Informationen. Dazu gehören morphologische Informationen über das Token, z. B. Zeitform, Person, Numerus und Genus. Detaillierte Informationen zu diesen Feldern finden Sie in der Anleitung zu Morphologie & Abhängigkeitsstrukturen.

  • lemma enthält den "Stamm", auf dem dieses Wort basiert, was Ihnen die Kanonisierung der Wortverwendung in Ihrem Text ermöglicht. Zum Beispiel basieren die Wörter "write", "writing", "wrote" und "written" alle auf demselben Lemma ("write"). Plural- und Singularformen basieren ebenfalls auf Lemmata: "Haus" und "Häuser" beziehen sich beide auf dieselbe Form. (Siehe Lemma (Morphologie).)

  • dependencyEdge-Felder erkennen den Zusammenhang zwischen Wörtern in einem Satz mit einem Token über die Ränder in einer gezielten Struktur. Diese Informationen können bei der Übersetzung, der Extraktion von Informationen und der Zusammenfassung nützlich sein. (Die Anleitung zu Morphologie & Abhängigkeitsstrukturen enthält alle Einzelheiten zum Parsen von Abhängigkeiten.) Jedes dependencyEdge-Feld enthält die folgenden untergeordneten Felder:

    • headTokenIndex stellt den (nullbasierten) Indexwert des "übergeordneten Tokens" dieses Tokens im einschließenden Satz des Tokens bereit. Ein Token ohne ein übergeordnetes Token indexiert sich selbst.
    • label stellt den Typ der Abhängigkeit dieses Tokens für sein Haupttoken bereit.

Das folgende Zitat aus der Antrittsrede von Franklin D. Roosevelt erzeugt die folgenden Tokens:

HINWEIS: Alle partOfSpeech-Tags, die *_UNKNOWN-Werte enthalten, wurden zwecks Übersichtlichkeit entfernt.

 "tokens": [
    {
      "text": {
        "content": "The",
        "beginOffset": 4
      },
      "partOfSpeech": {
        "tag": "DET",
      },
      "dependencyEdge": {
        "headTokenIndex": 2,
        "label": "DET"
      },
      "lemma": "The"
    },
    {
      "text": {
        "content": "only",
        "beginOffset": 8
      },
      "partOfSpeech": {
        "tag": "ADJ",
      },
      "dependencyEdge": {
        "headTokenIndex": 2,
        "label": "AMOD"
      },
      "lemma": "only"
    },
    {
      "text": {
        "content": "thing",
        "beginOffset": 13
      },
      "partOfSpeech": {
        "tag": "NOUN",
        "number": "SINGULAR",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "NSUBJ"
      },
      "lemma": "thing"
    },
    {
      "text": {
        "content": "we",
        "beginOffset": 19
      },
      "partOfSpeech": {
        "tag": "PRON",
        "case": "NOMINATIVE",
        "number": "PLURAL",
        "person": "FIRST",
      },
      "dependencyEdge": {
        "headTokenIndex": 4,
        "label": "NSUBJ"
      },
      "lemma": "we"
    },
    {
      "text": {
        "content": "have",
        "beginOffset": 22
      },
      "partOfSpeech": {
        "tag": "VERB",
        "mood": "INDICATIVE",
        "tense": "PRESENT",
      },
      "dependencyEdge": {
        "headTokenIndex": 2,
        "label": "RCMOD"
      },
      "lemma": "have"
    },
    {
      "text": {
        "content": "to",
        "beginOffset": 27
      },
      "partOfSpeech": {
        "tag": "PRT",
      },
      "dependencyEdge": {
        "headTokenIndex": 6,
        "label": "AUX"
      },
      "lemma": "to"
    },
    {
      "text": {
        "content": "fear",
        "beginOffset": 30
      },
      "partOfSpeech": {
        "tag": "VERB",
      },
      "dependencyEdge": {
        "headTokenIndex": 4,
        "label": "XCOMP"
      },
      "lemma": "fear"
    },
    {
      "text": {
        "content": "is",
        "beginOffset": 35
      },
      "partOfSpeech": {
        "tag": "VERB",
        "mood": "INDICATIVE",
        "number": "SINGULAR",
        "person": "THIRD",
        "tense": "PRESENT",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "ROOT"
      },
      "lemma": "be"
    },
    {
      "text": {
        "content": "fear",
        "beginOffset": 38
      },
      "partOfSpeech": {
        "tag": "NOUN",
        "number": "SINGULAR",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "ATTR"
      },
      "lemma": "fear"
    },
    {
      "text": {
        "content": "itself",
        "beginOffset": 43
      },
      "partOfSpeech": {
        "tag": "PRON",
        "case": "ACCUSATIVE",
        "gender": "NEUTER",
        "number": "SINGULAR",
        "person": "THIRD",
      },
      "dependencyEdge": {
        "headTokenIndex": 8,
        "label": "NN"
      },
      "lemma": "itself"
    },
    {
      "text": {
        "content": ".",
        "beginOffset": 49
      },
      "partOfSpeech": {
        "tag": "PRON",
        "case": "ACCUSATIVE",
        "gender": "NEUTER",
        "number": "SINGULAR",
        "person": "THIRD",
      },
      "dependencyEdge": {
        "headTokenIndex": 8,
        "label": "NN"
      },
      "lemma": "itself"
    },
    {
      "text": {
        "content": ".",
        "beginOffset": 49
      },
      "partOfSpeech": {
        "tag": "PUNCT",
      },
      "dependencyEdge": {
        "headTokenIndex": 7,
        "label": "P"
      },
      "lemma": "."
    }
  ],

Inhaltsklassifizierung

Sie können ein Dokument von der Natural Language analysieren lassen und eine Liste der Inhaltskategorien zurückgeben, die für den im Dokument enthaltenen Text gelten. Rufen Sie zum Klassifizieren der Inhalte in einem Dokument die Methode classifyText auf.

Eine vollständige Liste der für die Methode classifyText zurückgegebenen Inhaltskategorien finden Sie hier.

Die Natural Language filtert die von der Methode classifyText zurückgegebenen Kategorien, sodass nur die relevantesten Kategorien für eine Anfrage enthalten sind. Wenn zum Beispiel sowohl /Science als auch /Science/Astronomy auf ein Dokument zutreffen, wird nur die Kategorie /Science/Astronomy zurückgegeben, da sie das konkretere Ergebnis liefert.

Ein Beispiel für die Klassifizierung von Inhalten mit der Natural Language finden Sie unter Inhaltsklassifizierung.

Mehrere Vorgänge in einer einzelnen Anfrage durchführen

Wenn Sie eine Reihe von Analysevorgängen natürlicher Sprache innerhalb eines einzelnen Methodenaufrufs ausführen möchten, können Sie annotateText als allgemeine Natural Language API-Anfrage verwenden. Eine Textanmerkungs-JSON-Anfrage ähnelt einer standardmäßigen Entitätsanalyse-Anfrage. Sie erfordert aber die Übergabe verschiedener Elemente, mit denen die für den Text auszuführenden Vorgänge angegeben werden. Diese Elemente sind:

  • extractDocumentSentiment führt eine Sentimentanalyse durch, wie im Abschnitt Sentimentanalyse beschrieben.
  • extractEntities führt eine Entitätsanalyse durch, wie im Abschnitt Entitätsanalyse beschrieben.
  • extractSyntax gibt an, dass der gegebene Text zur Durchführung der Syntaxanalyse verarbeitet werden soll, wie im Abschnitt Syntaxanalyse beschrieben.

Die folgende Anfrage ruft die API auf, um in einem kurzen Satz features mit einer Anmerkung zu versehen.

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"The windy, cold weather was unbearable this winter."
  },
  "features":{
    "extractSyntax":true,
    "extractEntities":true,
    "extractDocumentSentiment":true
  },
  "encodingType":"UTF8"
}