Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Natural Language API の基本

このドキュメントでは、Cloud Natural Language API の基本的な使用方法について説明します。取り上げる内容は、Natural Language API に対するリクエストの種類、リクエストの作成方法、リクエストに対するレスポンスの処理方法です。Natural Language API を使用するすべてのユーザーに、実際に API を使用する前にこのガイドと関連チュートリアルを 1 つ読むことをおすすめします。

Natural Language の特長

Natural Language API には、テキストを分析したりアノテーションを付けたりするためのメソッドがいくつか用意されています。各レベルの分析から、言語理解のための貴重な情報が得られます。使用できるメソッドは次のとおりです。

感情分析: 指定されたテキストを調べて、そのテキストの背景にある感情的な考え方を分析します。具体的には、執筆者の考え方がポジティブか、ネガティブか、ニュートラルかを判断します。感情分析を実行するには analyzeSentiment メソッドを使用します。
エンティティ分析: 指定されたテキストに既知のエンティティ（著名人、ランドマークなどの固有名詞、レストラン、競技場などの普通名詞）が含まれているかどうかを調べて、そのエンティティに関する情報を返します。エンティティ分析を行うには、analyzeEntities メソッドを使用します。
エンティティ感情分析: 指定されたテキストに既知のエンティティ（固有名詞や普通名詞）が含まれているかどうかを調べて、そのエンティティに関する情報を返し、そのテキスト内でのそのエンティティの感情的な考え方を分析します。具体的には、そのエンティティに対する執筆者の考え方がポジティブか、ネガティブか、ニュートラルかを判断します。エンティティ分析を行うには、analyzeEntitySentiment メソッドを使用します。
構文解析: 言語情報を抽出し、指定されたテキストを一連の文とトークン（通常は単語の境界）に分解して、それらのトークンをさらに分析できるようにします。構文解析を行うには、analyzeSyntax メソッドを使用します。
コンテンツ分類: テキストコンテンツを分析し、そのコンテンツのコンテンツカテゴリを返します。コンテンツ分類を行うには、classifyText メソッドを使用します。

各 API 呼び出しでは、言語も検出されて返されます（最初のリクエストで呼び出し元によって指定されていない場合）。

さらに、指定したテキストに対して 1 回の API 呼び出しで複数の自然言語オペレーションを実行することもできます。annotateText リクエストを使用すると、感情分析とエンティティ分析を実行できます。

使ってみる

Google Cloud を初めて使用される方は、アカウントを作成して、実際のシナリオでの Natural Language のパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。

Natural Language の無料トライアル

Natural Language の基本的なリクエスト

Natural Language API は REST API であり、JSON のリクエストとレスポンスで構成されます。Natural Language API の単純なエンティティ分析の JSON リクエストの例を以下に示します。

{
  "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"
}

各フィールドの内容は次のとおりです。

document には、このリクエストのデータが格納されます。これは、次のサブフィールドで構成されます。
- type - ドキュメントの種類（HTML または PLAIN_TEXT）
- language - （省略可）リクエストに含まれているテキストの言語。指定しない場合、言語が自動的に検出されます。Natural Language API でサポートされる言語については、言語のサポートをご覧ください。サポートされていない言語を指定すると、JSON レスポンスでエラーが返されます。
- content または gcsContentUri: 評価するテキストが含まれています。content を渡すと、そのテキストが直接 JSON リクエストに含まれます（上の例を参照）。gcsContentUri を渡す場合は、そのフィールドに Google Cloud Storage 内のテキストコンテンツを表す URI が含まれている必要があります。
encodingType: （必須）返されるテキスト内の文字オフセットの計算に使用するエンコードスキーム。リクエストで渡すテキストのエンコードと一致している必要があります。このパラメータを設定しないと、リクエスト自体はエラーになりませんが、それらのオフセットがすべて -1 に設定されます。

テキストコンテンツの指定

Natural Language API のリクエストを渡す際には、処理するテキストを次のいずれかの方法で指定します。

テキストを直接 content フィールドに含めて渡します。
Google Cloud Storage URI を gcsContentUri フィールドに含めて渡します。

いずれの場合も、コンテンツの制限を超えないようにする必要があります。コンテンツの制限は、文字単位ではなくバイト単位であるので注意してください。テキストのエンコードによって文字数が異なります。

以下のリクエストは、ゲティスバーグの演説が含まれている Google Cloud Storage ファイルを参照しています。

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

感情分析

感情分析は、テキスト内で表現されている全体的な態度（ポジティブかネガティブか）を特定します。感情は、score と magnitude の数値によって表されます。

感情分析のレスポンスフィールド

ゲティスバーグの演説に対する analyzeSentiment レスポンスの例を以下に示します。

{
  "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
      }
    },
   ...
}

各フィールドの値は次のとおりです。

documentSentiment には、次のフィールドで構成されるドキュメントの全体的な感情が含まれます。
- score: -1.0（ネガティブ）～1.0（ポジティブ）のスコアで感情が表されます。これは、テキストの全体的な感情の傾向に相当します。
- magnitude: 指定したテキストの全体的な感情の強度（ポジティブとネガティブの両方）が 0.0～+inf の値で示されます。score と違って、magnitude は documentSentiment に対して正規化されていないため、テキスト内で感情（ポジティブとネガティブの両方）が表現されるたびにテキストの magnitude の値が増加します。そのため、テキストブロックが長いほど、値が高くなる傾向があります。
language_code にはドキュメントの言語が含まれています。最初のリクエストで言語を渡した場合はその言語が含まれ、渡さなかった場合は自動的に検出された言語が含まれます。
language_supported には、言語が正式にサポートされているかどうかを示すブール値が含まれています。
sentences には、元のドキュメントから抽出された文のリストが含まれています。リストには次のものが含まれます。
- sentimentには、各文に関連付けられた文レベルの感情の値が格納されています。これには、-1.0（ネガティブ）と 1.0（ポジティブ）の間の score 値と、0.0 と 1.0 の間の magnitude 値が含まれます。sentences の magnitude は正規化されていることにご注意ください。

ゲティスバーグの演説に対する感情値が 0.2 であることは、感情的にややポジティブであることを示しています。一方、強度の値が 3.6 であることは、このドキュメントの短さ（1 段落ほど）を考えると、かなり感情的な値であるといえます。ゲティスバーグの演説の最初の文に、非常にポジティブな score（0.8）が含まれていることに注目してください。

感情分析の値の解釈

ドキュメントの感情分析の score は、ドキュメントの全体的な感情を示します。ドキュメントの感情分析の magnitude は、そのドキュメントに感情的な内容がどのくらい含まれているかを示します。この値は、ドキュメントの長さに比例する傾向があります。

Natural Language API は、ドキュメント内のポジティブな感情とネガティブな感情の違いを示しますが、具体的なポジティブな感情とネガティブな感情を特定するものではありません。たとえば、「怒っている（angry）」と「悲しい（sad）」は両方ともネガティブな感情とみなされます。ただし、Natural Language API が「怒っている」とみなされるテキストまたは「悲しい」とみなされるテキストを分析する場合、レスポンスではテキストの感情が「悲しい」または「怒り」ではなくネガティブであることだけが示されます。

score の値がニュートラル（ほぼ 0.0）なドキュメントは、感情的でない場合もあれば、ポジティブとネガティブの両方の値が高いために互いに相殺されている混合的なドキュメントである場合もあります。通常、これらの場合に曖昧さを取り除くために、magnitude の値が使用できます。本当にニュートラルなドキュメントの magnitude の値は低くなりますが、混在的なドキュメントの magnitude の値は大きくなります。

ドキュメントを互いに比較する場合（特にドキュメントの長さが違う場合）は、magnitude の値を使用してスコアを調整する必要があります。この値は、感情的なコンテンツに関連する数量を測定する際に役立ちます。

次の表は、いくつかのサンプル値とその解釈の例を示しています。

センチメント	サンプル値
明らかにポジティブ*	`"score"`: 0.8, `"magnitude"`: 3.0
明らかにネガティブ*	`"score"`: -0.6, `"magnitude"`: 4.0
ニュートラル	`"score"`: 0.1, `"magnitude"`: 0.0
混合	`"score"`: 0.0, `"magnitude"`: 4.0

* 「明らかにポジティブ」と「明らかにネガティブ」という感情は、ユースケースと顧客ごとに異なります。実際に使用するときは、上記のものとは異なる結果となることもあります。実際の例に適したしきい値を定義し、テストと結果の検証の後でそのしきい値を調整することをおすすめします。たとえば、スコアが 0.25 を超えたら「明らかにポジティブ」というようにしきい値を定義してから、データと結果を確認します。0.15～0.25 のスコアもポジティブと見なせることがわかった場合は、それに基づいてスコアしきい値を 0.15 に変更します。

エンティティ分析

エンティティ分析は、テキスト内のエンティティ（著名人、ランドマーク、日常的な物など、名前が付けられている「モノ」）に関する情報を提供します。

エンティティは、大きく 2 つに分類されます。固有のエンティティ（特定の人、場所など）に対応する固有名詞と、自然言語処理では「名詞類」とも呼ばれる普通名詞です。通常は、名詞が「エンティティ」になると考えて構いません。エンティティは、元のテキストに対するインデックスオフセットとして返されます。

エンティティ分析のリクエストでは、返されたオフセットを正しく解釈できるように、encodingType 引数を渡す必要があります。

エンティティ分析のレスポンスフィールド

エンティティ分析では、検出された一連のエンティティと、それらのエンティティに関連付けられたパラメータ（エンティティのタイプ、エンティティとテキスト全体の関連性、同じエンティティを参照するテキスト内の位置など）が返されます。

エンティティリクエストに対する analyzeEntities レスポンスを以下に示します。

{
  "entities": [
    {
      "name": "British",
      "type": "LOCATION",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "British",
            "beginOffset": 58
          },
          "type": "PROPER",
          "probability": 0.941
        }
      ]
    },
    {
      "name": "Lawrence",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Lawrence",
            "beginOffset": 113
          },
          "type": "PROPER",
          "probability": 0.914
        }
      ]
    },
    {
      "name": "Lawrence of Arabia",
      "type": "WORK_OF_ART",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Lawrence of Arabia",
            "beginOffset": 0
          },
          "type": "PROPER",
          "probability": 0.761
        }
      ]
    },
    {
      "name": "Lieutenant",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Lieutenant",
            "beginOffset": 66
          },
          "type": "COMMON",
          "probability": 0.927
        }
      ]
    },
    {
      "name": "Peter O Toole",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Peter O Toole",
            "beginOffset": 93
          },
          "type": "PROPER",
          "probability": 0.907
        }
      ]
    },
    {
      "name": "T. E. Lawrence",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {

Natural Language API の基本 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。