內容分類教學課程

目標對象

本教學課程的設計在於讓您透過 Cloud Natural Language API 快速開始探索並開發應用程式。本教學課程的設計對象為熟悉基本程式設計的人員，但即便您對程式設計只有粗淺的認識，也應能跟得上課程。完成本教學課程後，您應能使用參考資料說明文件建立自己的基本應用程式。

本教學課程採用 Python 程式碼逐步操作自然語言應用程式。本文目的並非提供 Python 用戶端程式庫的相關說明，而是解釋如何呼叫 Natural Language API。以 Java 和 Node.js 撰寫應用程式的方法大致類似。請參閱 Natural Language API 範例以取得其他語言的範例 (包括本教學課程的範例)。

必備條件

本教學課程有幾項必備條件：

• 您已在 Google Cloud 控制台設定 Cloud Natural Language 專案。
• 您已在 Google Cloud 主控台使用應用程式預設憑證設定環境。
• 您熟悉如何使用 Python 在 Google Cloud 控制台上進行程式設計。
• 您已設定好 Python 開發環境。建議先在系統上安裝最新版本的 Python、pip 和 virtualenv。如需操作說明，請參閱 Google Cloud Platform 的 Python 開發環境設定指南。
• 您已安裝 適用於 Python 的 Google Cloud 用戶端程式庫

總覽

本教學課程會透過 classifyText 要求逐步引導您操作基本的自然語言應用程式，該應用程式會將內容分類並附上置信度分數，例如：

category: "/Internet & Telecom/Mobile & Wireless/Mobile Apps & Add-Ons"
confidence: 0.6499999761581421

如要查看所有可用類別標籤的清單，請參閱類別。

在這個教學課程中，您將建立應用程式來執行下列工作：

• 分類多個文字檔案並將結果寫入索引檔案。
• 處理輸入查詢文字以尋找類似的文字檔案。
• 處理輸入查詢類別標籤以尋找類似的文字檔案。

本教學課程使用來自維基百科的內容。您可以建立類似的應用程式來處理新聞或線上評論等內容。

來源檔案

您可以在 GitHub 的 Python 用戶端程式庫範例中找到教學課程原始碼。

本教學課程使用來自維基百科的範例原文。您可以在 GitHub 專案的 resources/texts 資料夾中找到範例文字檔案。

匯入程式庫

如要使用 Cloud Natural Language API，您必須從 google-cloud-language 程式庫匯入 language 模組。language.types 模組包含建立要求所需的類別。language.enums 模組用於指定輸入文字的類型。本教學課程是將純文字內容分類 (language.enums.Document.Type.PLAIN_TEXT)。

為了根據內容分類結果計算文字的相似度，本教學課程會使用 numpy 進行向量計算。

Python

如要瞭解如何安裝及使用 Natural Language 的用戶端程式庫，請參閱 Natural Language 用戶端程式庫。詳情請參閱 Natural Language Python API 參考資料說明文件。

如要向 Natural Language 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

import argparse
import json
import os

from google.cloud import language_v1
import numpy

步驟 1：將內容分類

您可以使用 Python 用戶端程式庫建立要求來呼叫 Natural Language API 以分類內容。Python 用戶端程式庫會封裝傳送至 Natural Language API 的要求詳細資料及其回應。

教學課程中的 classify 函式會先建立 LanguageServiceClient 類別的例項，然後呼叫 LanguageServiceClient 例項的 classify_text 方法，以呼叫 Natural Language API classifyText 方法。

教學課程的 classify 函式只會為本範例分類文字內容。如要分類網頁內容，請將網頁的來源 HTML 做為 text 進行傳遞，並將 type 參數設為 language.enums.Document.Type.HTML。

詳情請參閱「分類內容」。如要進一步瞭解 Natural Language API 要求的結構，請參閱 Natural Language 參考資料。

Python

如要瞭解如何安裝及使用 Natural Language 的用戶端程式庫，請參閱 Natural Language 用戶端程式庫。詳情請參閱 Natural Language Python API 參考資料說明文件。

如要向 Natural Language 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

def classify(text, verbose=True):
    """Classify the input text into categories."""

    language_client = language_v1.LanguageServiceClient()

    document = language_v1.Document(
        content=text, type_=language_v1.Document.Type.PLAIN_TEXT
    )
    response = language_client.classify_text(request={"document": document})
    categories = response.categories

    result = {}

    for category in categories:
        # Turn the categories into a dictionary of the form:
        # {category.name: category.confidence}, so that they can
        # be treated as a sparse vector.
        result[category.name] = category.confidence

    if verbose:
        print(text)
        for category in categories:
            print("=" * 20)
            print("{:<16}: {}".format("category", category.name))
            print("{:<16}: {}".format("confidence", category.confidence))

    return result

傳回的結果是使用類別標籤做為索引鍵並以信心分數做為值的字典，例如：

{
    "/Computers & Electronics": 0.800000011920929,
    "/Internet & Telecom/Mobile & Wireless/Mobile Apps & Add-Ons": 0.6499999761581421
}

教學課程中的 Python 指令碼經過編排，可從指令列執行以進行快速實驗。舉例來說，您可以執行：

python classify_text_tutorial.py classify "Google Home enables users to speak voice commands to interact with services through the Home's intelligent personal assistant called Google Assistant. A large number of services, both in-house and third-party, are integrated, allowing users to listen to music, look at videos or photos, or receive news updates entirely by voice. "

注意： 待分類內容至少要有 20 個符記 (字詞)，Natural Language API 才會傳回回應。

步驟 2：建立多個文字檔案的索引

教學課程指令碼中的 index 函式會將包含多個文字檔的目錄，以及儲存已編入索引的輸出內容的檔案路徑 (預設檔案名稱為 index.json) 做為輸入內容。index 函式會讀取輸入目錄中每個文字檔的內容，然後將文字檔傳遞至 Cloud Natural Language API，以便分類為內容類別。

Python

如要瞭解如何安裝及使用 Natural Language 的用戶端程式庫，請參閱 Natural Language 用戶端程式庫。詳情請參閱 Natural Language Python API 參考資料說明文件。

如要向 Natural Language 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

def index(path, index_file):
    """Classify each text file in a directory and write
    the results to the index_file.
    """

    result = {}
    for filename in os.listdir(path):
        file_path = os.path.join(path, filename)

        if not os.path.isfile(file_path):
            continue

        try:
            with open(file_path) as f:
                text = f.read()
                categories = classify(text, verbose=False)

                result[filename] = categories
        except Exception:
            print(f"Failed to process {file_path}")

    with open(index_file, "w", encoding="utf-8") as f:
        f.write(json.dumps(result, ensure_ascii=False))

    print(f"Texts indexed in file: {index_file}")
    return result

Cloud Natural Language API 針對各個檔案傳回的結果會整理為單一字典，接著序列化為 JSON 字串並寫入檔案。例如：

{
    "android.txt": {
        "/Computers & Electronics": 0.800000011920929,
        "/Internet & Telecom/Mobile & Wireless/Mobile Apps & Add-Ons": 0.6499999761581421
    },
    "google.txt": {
        "/Internet & Telecom": 0.5799999833106995,
        "/Business & Industrial": 0.5400000214576721
    }
}

如要使用預設輸出檔案名稱 index.json 從指令列為文字檔建立索引，請執行下列指令：

python classify_text_tutorial.py index resources/texts

步驟 3：查詢索引

透過類別標籤查詢

建立索引檔案 (預設檔案名稱 = index.json) 後，我們可以對索引進行查詢，擷取部分檔案名稱及其置信度分數。

其中一種方法是使用類別標籤做為查詢，本教學課程會透過 query_category 函式完成這項操作。輔助函式 (例如 similarity) 的實作項目可在 classify_text_tutorial.py 檔案中找到。您的應用程式應根據特定用途審慎設計相似度分數與評等。

Python

如要瞭解如何安裝及使用 Natural Language 的用戶端程式庫，請參閱 Natural Language 用戶端程式庫。詳情請參閱 Natural Language Python API 參考資料說明文件。

如要向 Natural Language 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

def query_category(index_file, category_string, n_top=3):
    """Find the indexed files that are the most similar to
    the query label.

    The list of all available labels:
    https://cloud.google.com/natural-language/docs/categories
    """

    with open(index_file) as f:
        index = json.load(f)

    # Make the category_string into a dictionary so that it is
    # of the same format as what we get by calling classify.
    query_categories = {category_string: 1.0}

    similarities = []
    for filename, categories in index.items():
        similarities.append((filename, similarity(query_categories, categories)))

    similarities = sorted(similarities, key=lambda p: p[1], reverse=True)

    print("=" * 20)
    print(f"Query: {category_string}\n")
    print(f"\nMost similar {n_top} indexed texts:")
    for filename, sim in similarities[:n_top]:
        print(f"\tFilename: {filename}")
        print(f"\tSimilarity: {sim}")
        print("\n")

    return similarities

如需所有可用類別的清單，請參閱類別。

一如往常，您可以透過指令列呼叫 query_category 函式：

python classify_text_tutorial.py query-category index.json "/Internet & Telecom/Mobile & Wireless"

畫面會顯示類似以下的輸出：

Query: /Internet & Telecom/Mobile & Wireless


Most similar 3 indexed texts:
  Filename: android.txt
  Similarity: 0.665573579045


  Filename: google.txt
  Similarity: 0.517527175966


  Filename: gcp.txt
  Similarity: 0.5

透過文字查詢

您還可以使用不屬於索引的文字進行查詢。教學課程的 query 函式與 query_category 函式類似，但多了一個步驟，即針對文字輸入內容提出 classifyText 要求，並使用結果查詢索引檔案。

Python

如要瞭解如何安裝及使用 Natural Language 的用戶端程式庫，請參閱 Natural Language 用戶端程式庫。詳情請參閱 Natural Language Python API 參考資料說明文件。

如要向 Natural Language 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

def query(index_file, text, n_top=3):
    """Find the indexed files that are the most similar to
    the query text.
    """

    with open(index_file) as f:
        index = json.load(f)

    # Get the categories of the query text.
    query_categories = classify(text, verbose=False)

    similarities = []
    for filename, categories in index.items():
        similarities.append((filename, similarity(query_categories, categories)))

    similarities = sorted(similarities, key=lambda p: p[1], reverse=True)

    print("=" * 20)
    print(f"Query: {text}\n")
    for category, confidence in query_categories.items():
        print(f"\tCategory: {category}, confidence: {confidence}")
    print(f"\nMost similar {n_top} indexed texts:")
    for filename, sim in similarities[:n_top]:
        print(f"\tFilename: {filename}")
        print(f"\tSimilarity: {sim}")
        print("\n")

    return similarities

如要執行此操作，請透過指令列執行：

python classify_text_tutorial.py query index.json "Google Home enables users to speak voice commands to interact with services through the Home's intelligent personal assistant called Google Assistant. A large number of services, both in-house and third-party, are integrated, allowing users to listen to music, look at videos or photos, or receive news updates entirely by voice. "

這會顯示類似下面的內容：

Query: Google Home enables users to speak voice commands to interact with services through the Home's intelligent personal assistant called Google Assistant. A large number of services, both in-house and third-party, are integrated, allowing users to listen to music, look at videos or photos, or receive news updates entirely by voice.

  Category: /Internet & Telecom, confidence: 0.509999990463
  Category: /Computers & Electronics/Software, confidence: 0.550000011921

Most similar 3 indexed texts:
  Filename: android.txt
  Similarity: 0.600579500049


  Filename: google.txt
  Similarity: 0.401314790229


  Filename: gcp.txt
  Similarity: 0.38772339779

相關資源

透過內容分類 API，您可以建立其他應用程式。例如：

• 將文章的各個段落分類，藉此查看主題之間的轉換。

• 將具有時間戳記的內容分類並分析各段時間的趨勢主題。

• 使用 analyzeSentiment 方法比較內容類別與內容情緒。

• 比較內容類別分類以及文字提及實體的分析。

不僅如此，您還可以使用其他 Google Cloud Platform 產品來簡化您的工作流程：

• 在這個教學課程的應用程式範例中，我們處理的是本機文字檔，但您可以修改程式碼，將 Google Cloud Storage URI 傳遞至 classify_text 方法，以便處理儲存在 Google Cloud Storage 值區的文字檔。

• 在這個教學課程的應用程式範例中，我們是將索引檔案儲存在本機，且每次查詢都會讀取整個索引檔案。也就是說，如果索引資料龐大或需要處理多個查詢，就會出現高度延遲狀況。儲存索引資料時，Datastore 是理所當然的便利選擇。