Natural Language API 基本資訊

本文提供 Cloud Natural Language API 的基本使用指南。這份概念指南涵蓋了您可以向 Natural Language API 提出的要求類型、如何建構這些要求，以及如何處理其回應等資訊。我們建議 Natural Language API 的所有使用者，先閱讀這份指南並完成一個相關聯的教學課程後，再去深入瞭解 API 本身。

Natural Language 功能

Natural Language API 提供多種可讓您執行文字分析與註解的方法。各個分析步驟都為理解語言提供了寶貴的資訊。以下列出這些方法：

• 情緒分析會檢查指定的文字內容，進而識別文字內容的主要情緒主張，特別是判斷撰寫者的態度為正面、負面或中立。情緒分析是透過 analyzeSentiment 方法執行。

• 實體分析會檢查指定文字中的已知實體 (公眾人物、等專有名詞；餐廳或體育館等普通名詞) 並傳回有關這些實體的資訊。實體分析是透過 analyzeEntities 方法執行。

• 實體情緒分析會檢查指定文字中的已知實體 (專有名詞和普通名詞)，傳回這些實體的相關資訊，並識別文字中實體的主要情緒主張，特別是判斷撰寫者對實體的態度為正面、負面或中立。實體分析是透過 analyzeEntitySentiment 方法執行。

• 語法分析會擷取語言資訊，將指定的文字內容拆解為各段語句與符記 (通稱斷詞) 並提供有關這些符記的進一步分析。語法分析是透過 analyzeSyntax 方法執行。

• 內容分類會分析文字內容並傳回其內容類別。內容分類是透過 classifyText 方法執行。

若進行 API 呼叫者未在初始要求中指定語言，所有 API 呼叫會偵測並傳回該語言的資訊。

此外，如果您想使用單一 API 呼叫，對指定文字執行多項自然語言作業，也可以使用 annotateText 要求執行情緒分析和實體分析。

基本的 Natural Language 要求

Natural Language API 屬於 REST API，由 JSON 要求與回應組成。以下所示為簡易的 Natural Language 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，欄位必須包含 URI，且此 URI 須指向 Google Cloud Storage 中的文字內容。
• encodingType - (必填) 計算傳回的字元在文字內容中的位移值時採用的編碼配置，該編碼配置必須符合傳遞文字的編碼。如未設定此參數，要求雖不會發生錯誤，但會將這些位移值都設為 -1。

指定文字內容

傳遞 Natural Language API 要求時，有兩種方式可指定要處理的文字：

• 直接在 content 欄位中傳遞文字。
• 在 gcsContentUri 欄位中傳遞 Google Cloud Storage URI。

無論哪一種情況，您都應該確保傳遞文字符合內容限制。請注意，這些內容限制是以位元組為單位，而非字元；因此，字元長度取決於文字的編碼。

下方的要求是內含蓋茨堡宣言的 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 並無正規化；文字內容中的每種情緒表達 (無論正負面) 都會提高文字的 magnitude 值 (因此文字篇幅較長，幅度值可能也會較大)。documentSentiment
• language_code 提供文件的語言資訊，可在初始要求中傳遞，亦可由系統自動偵測 (如果沒有的話)。
• language_supported 包含布林值，用於識別語言是否為官方支援的語言
• sentences 提供從原始文件中擷取的語句清單，其中包含：
  • sentiment 提供各個語句的「語句整體情緒」值，包含介於 -1.0 (負面) 和 1.0 (正面) 之間的 score，以及介於 0.0 和 1.0 之間的 magnitude 值。請注意，magnitude 會針對 sentences 正規化。

蓋茨堡宣言的情緒值為 0.2，代表情緒偏向正面，magnitude 值為 3.6，代表在文件篇幅不長 (約一個段落) 的前提下，文件情緒相對強烈。請注意，蓋茨堡演說的第一句含有非常高的正面 score，即 0.8。

情緒分析值說明

文件的情緒分數 (score) 代表文件的整體情緒。文件情緒的 magnitude 值表示文件中情緒內容的程度，通常與文件長度成正比。

值得注意的是，Natural Language API 可區分文件中的正面與負面情緒，但無法辨識確切的正面與負面情緒。舉例來說，「生氣」和「難過」都是負面情緒。然而，當 Natural Language API 分析視為「生氣」或「難過」的文字時，僅會在回應中表示文字為負面情緒，而非「生氣」或「難過」。

如果文件的情緒分數接近 0.0，可能代表文件情緒較為平淡，也可能代表文件同時含有強烈的正面和負面情緒，兩者相互抵銷。一般而言，您可以透過 magnitude 值來消除這些情況的歧義，因為真正中立的文件會有較低的 magnitude 值，而混合文件則會有較高的量值。

比較文件時 (尤其是長度不同的文件)，請務必使用 magnitude 值校正分數，因為這有助於評估相關的情緒內容量。

下方圖表顯示部分範例值並說明如何解讀：

* 「明顯正面」和「明顯負面」的情緒會因為用途和客戶而有所不同。您可能會在自己的情境中得到不同的結果。建議您定義適合自身情況的臨界值，並在測試與驗證結果後調整這個臨界值。舉例來說，您可能會將任何超過 0.25 分數臨界值的分數定義為明顯正面，然後在檢閱您的資料與結果後，發現分數 0.15 至 0.25 也應視為正面，因而將分數臨界值修改為 0.15。

實體分析

實體分析提供文字中有關實體的資訊，通常是指具有名稱的「事物」，例如名人、地標或一般物體等。

實體大致可分為兩種類別：對應至唯一實體 (特定人名或地名等) 的專有名詞或是普通名詞 (在自然語言處理中亦稱為「一般名詞」)。常用的認定標準是，只要是名詞就可視為「實體」。實體會依照原文傳回索引位移值。

實體分析要求應傳遞 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