使用 Cloud Natural Language API 進行實體、情緒和語法分析

可讓您從文字中擷取實體、執行情緒和語法分析，並將文字分類。

在本實驗室中，我們將瞭解如何運用 Natural Language API 分析實體、情緒和語法。

課程內容

  • 建立 Natural Language API 要求並使用 curl 呼叫 API
  • 使用 Natural Language API 擷取實體並對文字執行情緒分析
  • 透過 Natural Language API 對文字執行語言分析
  • 建立不同語言的 Natural Language API 要求

事前準備

您會如何使用本教學課程？

僅閱讀 閱讀並完成練習

你對 Google Cloud Platform 的使用體驗滿意嗎？

新手 中級 熟練

自行設定環境

如果您還沒有 Google 帳戶 (Gmail 或 Google 應用程式)，請先建立帳戶。登入 Google Cloud Platform 主控台 (console.cloud.google.com)，然後建立新專案：

Screenshot from 2016-02-10 12:45:26.png

請記住專案 ID，這是所有 Google Cloud 專案中不重複的名稱 (上述名稱已遭占用，因此不適用於您，抱歉！)。本程式碼研究室稍後會將其稱為 PROJECT_ID。

接著，您必須在 Cloud 控制台中啟用帳單，才能使用 Google Cloud 資源。

完成本程式碼研究室的費用不應超過數美元，但如果您決定使用更多資源，或是將資源繼續執行 (請參閱本文件結尾的「清除」一節)，則可能會增加費用。

Google Cloud Platform 新使用者享有價值 $300 美元的免費試用期。

按一下畫面左上方的「選單」圖示。

從下拉式選單中選取「API 和服務」，然後按一下「資訊主頁」。

按一下「啟用 API 和服務」。

然後在搜尋框中搜尋「語言」。按一下「Google Cloud Natural Language API」：

按一下「啟用」，啟用 Cloud Natural Language API：

稍待片刻，等待按鈕重新啟用。啟用後，畫面會顯示以下內容：

Google Cloud Shell 是 在雲端執行的指令列環境，這種以 Debian 為基礎的虛擬機器，搭載各種您需要的開發工具 (包括 gcloud、bq、git 等等)，而且主目錄提供 5 GB 的永久儲存空間。我們會使用 Cloud Shell 建立 Natural Language API 的要求。

如要開始使用 Cloud Shell，請按一下標題列右上角的「啟用 Google Cloud Shell」圖示 Screen Shot 2015-06-08 at 5.30.32 PM.png。

系統會在控制台底部的新頁框中開啟 Cloud Shell 工作階段，並顯示指令列提示。等待 user@project:~$ 提示出現

我們會使用 curl 將要求傳送至 Natural Language API，因此需要產生 API 金鑰，才能傳入要求網址。如要建立 API 金鑰，請前往 Cloud 控制台的「API 和服務」部分，然後前往「憑證」專區：

在下拉式選單中選取「API 金鑰」：

接著，複製剛才產生的金鑰。您會在實驗室的後續步驟中使用這組金鑰。

您現在已擁有 API 金鑰，儲存為環境變數後，就不需要為每個要求插入 API 金鑰值。您可以在 Cloud Shell 中執行此操作。請務必將 <your_api_key> 替換成您剛才複製的金鑰。

export API_KEY=<YOUR_API_KEY>

我們將使用的第一個 Natural Language API 方法是 analyzeEntities。透過這個方法，API 能夠從文字中擷取實體，例如人物、地點和事件。請使用以下語句嘗試執行 API 實體分析：

Joanne Rowling, who writes under the pen names J. K. Rowling and Robert Galbraith, is a British novelist and screenwriter who wrote the Harry Potter fantasy series.

我們會在 request.json 檔案中建立要傳送至 Natural Language API 的要求。在 Cloud Shell 環境中，使用下列程式碼建立 request.json 檔案。您可以使用偏好的指令列編輯器 (nano、vim、emacs) 建立檔案，或使用 Cloud Shell 內建的 Orion 編輯器：

request.json

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Joanne Rowling, who writes under the pen names J. K. Rowling and Robert Galbraith, is a British novelist and screenwriter who wrote the Harry Potter fantasy series."
  },
  "encodingType":"UTF8"
}

透過要求，我們傳送文字資訊至 Natural Language API，支援的類型值為 PLAIN_TEXT 或 HTML。我們要在 content 中將文字傳送至 Natural Language API 進行分析。您也能將儲存在 Cloud Storage 的文字檔案傳送至 Natural Language API 進行處理。如果想傳送 Cloud Storage 中的檔案，請將 content 替換為 gcsContentUri，並將值設為文字檔案在 Cloud Storage 中的 URI。encodingType 會指示 API 在處理文字時該使用哪種類型的文字編碼。API 會使用該文字編碼計算特定實體在文字中出現的位置。

現在能使用下列 curl 指令，將要求主體和稍早儲存的 API 金鑰環境變數傳送至 Natural Language API (請在單一指令列中輸入所有指令)：

curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

回應開頭應如以下所示：

{
  "entities": [
     {
      "name": "Robert Galbraith",
      "type": "PERSON",
      "metadata": {
        "mid": "/m/042xh",
        "wikipedia_url": "https://en.wikipedia.org/wiki/J._K._Rowling"
      },
      "salience": 0.7980405,
      "mentions": [
        {
          "text": {
            "content": "Joanne Rowling",
            "beginOffset": 0
          },
          "type": "PROPER"
        },
        {
          "text": {
            "content": "Rowling",
            "beginOffset": 53
          },
          "type": "PROPER"
        },
        {
          "text": {
            "content": "novelist",
            "beginOffset": 96
          },
          "type": "COMMON"
        },
        {
          "text": {
            "content": "Robert Galbraith",
            "beginOffset": 65
          },
          "type": "PROPER"
        }
      ]
    },

    ...
  ]
}

回覆中的每個實體都包含實體 type、相關聯的 Wikipedia 網址 (如有)、salience，以及實體在文字內容中出現位置的索引。顯著性是 [0,1] 範圍內的數字，表示實體在整個文字內容中的重要性。Natural Language API 也能辨識以不同方式提及的同一實體。請查看回應中的 mentions 清單：API 能夠說明「Joanne Rowling」、「Rowling」、「novelist」及「Robert Galbriath」指的都是同一實體。

除了擷取實體外，Natural Language API 也可以讓您對一段文字執行情緒分析。此 JSON 要求必須包含與上方要求相同的參數，但這次請將這段文字改為情緒更強烈的內容。將 request.json 檔案替換為下列內容，您也可以將下方的 content 替換為自己的文字內容：

request.json

 {
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Harry Potter is the best book. I think everyone should read it."
  },
  "encodingType": "UTF8"
}

接著，我們會將要求傳送至 API 的 analyzeSentiment 端點：

curl "https://language.googleapis.com/v1/documents:analyzeSentiment?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

回應內容應如下所示：

{
  "documentSentiment": {
    "magnitude": 0.8,
    "score": 0.4
  },
  "language": "en",
  "sentences": [
    {
      "text": {
        "content": "Harry Potter is the best book.",
        "beginOffset": 0
      },
      "sentiment": {
        "magnitude": 0.7,
        "score": 0.7
      }
    },
    {
      "text": {
        "content": "I think everyone should read it.",
        "beginOffset": 31
      },
      "sentiment": {
        "magnitude": 0.1,
        "score": 0.1
      }
    }
  ]
}

請注意，我們會得到兩種情緒值：整份文件的情緒，以及按語句細分的情緒。此 sentiment 方法會傳回兩個值：score 和 magnitude。score 是介於 -1.0 和 1.0 之間的數字，表示這段陳述的情緒正面或負面程度。magnitude 是介於 0 和無限大的數字，代表這段陳述表達的情緒強度，無論是正面還是負面情緒。長度較長且含有強烈情緒陳述的文字區塊，得到的規模值也越高。第一句的分數為正面 (0.7)，第二句的分數則為中立 (0.1)。

除了提供整份文字文件的情緒詳細資料外，Natural Language API 也能按照文字內容中的實體細分情緒。我們以這句話為例：

I liked the sushi but the service was terrible.

上個工作中的做法，也就是取得整個語句的情緒分數，較不適合用於這個示例。如果這是某間餐廳眾多評論中的一則，我們可能會想明確掌握其中顧客表示喜歡與不喜歡的部分。幸好，NL API 提供 analyzeEntitySentiment 方法，可讓我們取得文字中每個實體的情緒。使用上述句子更新 request.json，即可試用：

request.json

 {
  "document":{
    "type":"PLAIN_TEXT",
    "content":"I liked the sushi but the service was terrible."
  },
  "encodingType": "UTF8"
}

接著請使用下列 curl 指令呼叫 analyzeEntitySentiment 端點：

curl "https://language.googleapis.com/v1/documents:analyzeEntitySentiment?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

我們會在回應中收到兩個實體物件，分別為「sushi」和「service」。以下是完整的 JSON 回應：

{
  "entities": [
    {
      "name": "sushi",
      "type": "CONSUMER_GOOD",
      "metadata": {},
      "salience": 0.52716845,
      "mentions": [
        {
          "text": {
            "content": "sushi",
            "beginOffset": 12
          },
          "type": "COMMON",
          "sentiment": {
            "magnitude": 0.9,
            "score": 0.9
          }
        }
      ],
      "sentiment": {
        "magnitude": 0.9,
        "score": 0.9
      }
    },
    {
      "name": "service",
      "type": "OTHER",
      "metadata": {},
      "salience": 0.47283158,
      "mentions": [
        {
          "text": {
            "content": "service",
            "beginOffset": 26
          },
          "type": "COMMON",
          "sentiment": {
            "magnitude": 0.9,
            "score": -0.9
          }
        }
      ],
      "sentiment": {
        "magnitude": 0.9,
        "score": -0.9
      }
    }
  ],
  "language": "en"
}

我們可以看到系統對「sushi」傳回的分數為 0.9，「service」的分數則為 -0.9。分析成效非常出色！您可能也會發現，系統針對每個實體傳回了兩個 sentiment 物件。如果文字內容提及其中一個字詞的次數超過一次，API 就會針對每次提及傳回不同的情緒分數與規模，以及該實體的匯總情緒。

我們將深入瞭解 Natural Language API 的第三種方法 (語法註解)，進一步分析文字的語言細節。analyzeSyntax 是一種方法，可提供文字語意和語法元素的完整詳細資料。API 會針對文字內容中的每個字詞，提供字詞的詞性 (如名詞、動詞和形容詞等) 以及與句子中其他字詞的關係 (例如是根動詞還是修飾語)。

讓我們以簡單的語句試用此方法。接下來的 JSON 要求和目前建立的要求類似，但是多了 features 鍵，這會指示 API 執行語法註解。將 request.json 換成下列內容：

request.json

{
  "document":{
    "type":"PLAIN_TEXT",
    "content": "Hermione often uses her quick wit, deft recall, and encyclopaedic knowledge to help Harry and Ron."
  },
  "encodingType": "UTF8"
}

接著呼叫 API 的 analyzeSyntax 方法：

curl "https://language.googleapis.com/v1/documents:analyzeSyntax?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

系統應會針對語句中的每個符記傳回物件，如下所示：我們將查看「uses」一詞的回應：

{
  "text": {
    "content": "uses",
    "beginOffset": 15
  },
  "partOfSpeech": {
    "tag": "VERB",
    "aspect": "ASPECT_UNKNOWN",
    "case": "CASE_UNKNOWN",
    "form": "FORM_UNKNOWN",
    "gender": "GENDER_UNKNOWN",
    "mood": "INDICATIVE",
    "number": "SINGULAR",
    "person": "THIRD",
    "proper": "PROPER_UNKNOWN",
    "reciprocity": "RECIPROCITY_UNKNOWN",
    "tense": "PRESENT",
    "voice": "VOICE_UNKNOWN"
  },
    "dependencyEdge": {
      "headTokenIndex": 2,
      "label": "ROOT"
    },
    "lemma": "use"
}

讓我們進一步瞭解回應內容。partOfSpeech 提供每個字詞的語言詳細資料 (許多字詞不適用於英文或這個特定字詞，因此為未知)。tag 則表示這個字詞的詞性，在本例中為動詞。我們也會取得時態、情態，以及單複數等詳細資料。lemma 是字詞的標準形式 (「uses」的標準形式為「use」)。舉例來說，run、runs、ran 和 running 這些字詞都以 run 這個詞條為基礎。Lemma 值適合用於持續追蹤特定字詞在一大段文字中的出現次數。

dependencyEdge 包含特定資料，可用來建立文字的相依性剖析樹狀結構。這個圖表會呈現語句中不同字詞之間的關係。上方語句的相依性剖析樹狀結構看起來可能會像這樣：

上述回應中的 headTokenIndex 是符記的索引，該符記具有指向「uses」的弧線。您可以將語句中的每個符記想像為陣列中的字詞，而「uses」的 headTokenIndex 2 則是指樹狀結構中與其相連的「often」一字。

Natural Language API 也支援英語以外的語言 (完整清單請參閱這裡)。讓我們試著對以下日文句子提出實體要求：

request.json

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"日本のグーグルのオフィスは、東京の六本木ヒルズにあります"
  },
  "encodingType": "UTF8"
}

請注意，我們沒有指明文字內容的語言種類，API 也會自動偵測。接著，我們會將要求傳送至 analyzeEntities 端點：

curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

以下是我們回應中的前兩個實體：

{
  "entities": [
    {
      "name": "日本",
      "type": "LOCATION",
      "metadata": {
        "mid": "/m/03_3d",
        "wikipedia_url": "https://en.wikipedia.org/wiki/Japan"
      },
      "salience": 0.23854347,
      "mentions": [
        {
          "text": {
            "content": "日本",
            "beginOffset": 0
          },
          "type": "PROPER"
        }
      ]
    },
    {
      "name": "グーグル",
      "type": "ORGANIZATION",
      "metadata": {
        "mid": "/m/045c7b",
        "wikipedia_url": "https://en.wikipedia.org/wiki/Google"
      },
      "salience": 0.21155767,
      "mentions": [
        {
          "text": {
            "content": "グーグル",
            "beginOffset": 9
          },
          "type": "PROPER"
        }
      ]
    },
    ...
  ]
  "language": "ja"
}

API 會擷取「日本」做為地點、「Google」做為機構，以及兩者的維基百科頁面。

您已瞭解如何使用 Cloud Natural Language API 執行文字分析工作，包括擷取實體、分析情緒及進行語法註解。

涵蓋內容

  • 建立 Natural Language API 要求並使用 curl 呼叫 API
  • 使用 Natural Language API 擷取實體並對文字執行情緒分析
  • 對文字內容執行語言分析來建立相依性剖析樹狀結構
  • 建立日文的 Natural Language API 要求

後續步驟