コンテンツ分類チュートリアル

対象

このチュートリアルは、Cloud Natural Language API を使用するアプリケーションの調査と開発をすぐに開始できるように作られています。基本的なプログラミングについて理解されている方を対象としていますが、プログラミングの深い知識がなくても、チュートリアルに沿って学習できるようになっています。このチュートリアルを終了すると、リファレンスドキュメントを使用して独自の基本的なアプリケーションを作成できるようになります。

このチュートリアルでは、Python コードを使用して Natural Language のアプリケーションを体験します。ここでの目的は、Python クライアントライブラリについて説明することではなく、Natural Language API を呼び出す方法を説明することです。Java や Node.js のアプリケーションも基本的にはこれと同様です。その他の言語のサンプル（チュートリアル内で使用するこのサンプルを含む）については、Natural Language API のサンプルをご覧ください。

前提条件

このチュートリアルでは次の事前準備が必要です。

Google Cloud Console で Cloud Natural Language プロジェクトが設定されている。
Google Cloud Console でアプリケーションのデフォルト認証情報を使用する環境が設定されている。
Google Cloud Console での Python によるプログラミングを十分に理解している。
Python 開発環境が設定されている。ご使用のシステムに最新バージョンの Python、pip、virtualenv をインストールしておくことをおすすめします。手順については、Google Cloud Platform 向け Python 開発環境のセットアップガイドをご覧ください。
Python 用 Google Cloud クライアントライブラリがインストールされている。

概要

このチュートリアルでは、classifyText リクエストを使用して、基本的な Natural Language アプリケーションについて説明します。このアプリケーションでは、次のようにコンテンツをカテゴリに分類するとともに、信頼スコアを割り当てます。

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

使用可能なすべてのカテゴリラベルのリストについては、カテゴリをご覧ください。

このチュートリアルでは、次のタスクを実行するアプリケーションを作成します。

複数のテキストファイルを分類し、その結果をインデックスファイルに書き込みます。
入力クエリのテキストを処理して同様のテキストファイルを見つけます。
入力クエリのカテゴリラベルを処理して同様のテキストファイルを見つけます。

このチュートリアルでは、Wikipedia のコンテンツを使用します。同様のアプリケーションを作成して、ニュース記事やオンラインコメントなどを処理することもできます。

ソースファイル

チュートリアルのソースコードは GitHub 上の Python クライアントライブラリサンプルに含まれています。

このチュートリアルでは、Wikipedia から引用したサンプルソーステキストを使用します。サンプルテキストファイルは、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. コンテンツを分類する

Natural Language API に対してコンテンツの分類をリクエストするには、Python クライアントライブラリを使用できます。Natural Language API へのリクエストとそのレスポンスの詳細は、Python クライアントライブラリによりカプセル化されています。

このチュートリアルで使用する classify 関数は Natural Language API の classifyText メソッドを呼び出すために、まず、LanguageServiceClient クラスのインスタンスを作成します。その後、LanguageServiceClient インスタンスの classify_text メソッドを呼び出します。

チュートリアルの classify 関数で分類するのは、このサンプルのテキストコンテンツだけです。ウェブページのコンテンツを分類する場合は、ウェブページのソース HTML を text として渡し、type パラメータを language.enums.Document.Type.HTML に設定します。

詳しくは、コンテンツの分類をご覧ください。Natural Language に対するリクエストの構造についての詳細は、Natural Language API リファレンスをご覧ください。

Python

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. "

ステップ 2. 複数のテキストファイルにインデックスを付ける

チュートリアルのスクリプトにある index 関数は、複数のテキストファイルを含むディレクトリと、インデックスが付けられた出力を保存するファイルへのパス（デフォルトのファイル名は index.json）を、入力に取ります。index 関数は、入力ディレクトリ内にある各テキストファイルの内容を読み取ってから、それらのテキストファイルをコンテンツカテゴリの分類対象として Google Cloud Natural Language API に渡します。

Python

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 によるファイルごとの結果は 1 つの辞書に編成され、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）が作成されたら、インデックスに対するクエリを実行して、ファイル名とその信頼スコアの一部を取得できます。

これを行う 1 つの方法は、クエリとしてカテゴリラベルを使用することです。このチュートリアルではそのために query_category 関数を使用します。similarity などのヘルパー関数の実装は、classify_text_tutorial.py ファイルの中で確認できます。実際のアプリケーションでは、類似度のスコア付けとランク付けを実際のユースケースに基づいて注意深く設計する必要があります。

Python

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

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 バケットに保存されているテキストファイルを処理することもできます。それには、classify_text メソッドに Google Cloud Storage URI を渡すようにコードを変更します。
このチュートリアルのサンプルアプリケーションでは、インデックスファイルをローカルに保存し、インデックスファイル全体を読み取ることによって各クエリを処理しています。この方法では、大量のインデックス付きデータがある場合や多数のクエリを処理しなければならない場合に、レイテンシが高くなります。したがって、インデックスデータの保存には Datastore を利用するのが実用的で便利です。

コンテンツ分類チュートリアル

対象

前提条件

概要

ソースファイル

ライブラリのインポート

Python

ステップ 1. コンテンツを分類する

Python

ステップ 2. 複数のテキスト ファイルにインデックスを付ける

Python

ステップ 3. インデックスを照会する

カテゴリラベルを使用したクエリ

Python

テキストを使用したクエリ

Python

次のステップ

ステップ 2. 複数のテキストファイルにインデックスを付ける