Tutorial de classificação de conteúdo

Público-alvo

Este tutorial foi criado para permitir que você comece a explorar e desenvolver aplicativos com a API Cloud Natural Language. Ele se destina a pessoas familiarizadas com a programação básica, ou seja, é possível acompanhá-lo mesmo se não tiver muito conhecimento. Após concluir este tutorial, você estará apto a usar a Documentação de referência para criar seus aplicativos básicos.

Neste tutorial, vamos trabalhar com um aplicativo da Natural Language usando o código Python. O objetivo aqui não é explicar as bibliotecas de cliente Python, mas explicar como fazer chamadas para a API Natural Language. Aplicativos em Java e Node.js são basicamente similares. Para outras linguagens, consulte as Amostras da API Natural Language, inclusive a deste tutorial.

Pré-requisitos

Os pré-requisitos para este tutorial são:

• configurar um projeto do Cloud Natural Language no Console do Google Cloud;
• ter configurado seu ambiente usando o Application Default Credentials no Console do Google Cloud;
• estar familiarizado com Python na programação do Console do Google Cloud;
• Configurar o ambiente de desenvolvimento do Python. É recomendável ter a versão mais recente do Python, pip e virtualenv instalados no seu sistema. Para ver instruções, consulte o Guia de configuração do ambiente para desenvolvedores do Python no Google Cloud Platform.
• a biblioteca de cliente do Google Cloud para Python instalada.

Visão geral

Neste tutorial, você encontra a descrição de um aplicativo básico da Natural Language usando solicitações classifyText, que classificam o conteúdo em categorias junto com uma pontuação de confiança como:

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

Para ver a lista de todos os rótulos de categoria disponíveis, consulte Categorias.

Neste tutorial, você criará um aplicativo para realizar as seguintes tarefas:

• Classificar vários arquivos de texto e gravar o resultado em um arquivo de índice.
• Processar o texto da consulta de entrada para encontrar arquivos de texto semelhantes.
• Processar os rótulos de categoria da consulta de entrada para encontrar arquivos de texto semelhantes.

O tutorial usa conteúdo da Wikipédia. Você pode criar um aplicativo semelhante para processar artigos de notícias, comentários on-line e assim por diante.

Arquivos de origem

Você pode encontrar o código-fonte do tutorial nas amostras da biblioteca de cliente do Python no GitHub.

Este tutorial usa exemplos de texto de origem da Wikipédia. Você pode encontrar os arquivos de texto de exemplo na pasta recursos/textos do projeto do GitHub.

Como importar bibliotecas

Para usar a API Cloud Natural Language, é necessário importar o módulo language da biblioteca google-cloud-language. O módulo language.types contém classes que são necessárias para criar solicitações. O módulo language.enums é usado para especificar o tipo do texto de entrada. Neste tutorial, classificamos o conteúdo de texto simples (language.enums.Document.Type.PLAIN_TEXT).

Para calcular a semelhança entre o texto com base na classificação de conteúdo resultante, este tutorial usa numpy para cálculos vetoriais.

Python

Para saber como instalar e usar a biblioteca de cliente para a Natural Language, consulte Bibliotecas de cliente da Natural Language. Para mais informações, consulte a documentação de referência da API Natural Language Python.

Para se autenticar no Natural Language, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import argparse
import json
import os

from google.cloud import language_v1
import numpy

Etapa 1: classificar o conteúdo

Com a biblioteca de cliente do Python, você pode fazer uma solicitação para que a API Natural Language classifique conteúdo. A biblioteca de cliente do Python inclui os detalhes das solicitações e respostas da API Natural Language.

A função classify no tutorial chama o método classifyText da API Natural Language criando primeiro uma instância da classe LanguageServiceClient e depois chamando o método classify_text da instância LanguageServiceClient.

A função classify do tutorial classifica somente o conteúdo de texto para este exemplo. Você também pode classificar o conteúdo de uma página da Web transmitindo o HTML de origem da página da Web como o text e definindo o parâmetro type como language.enums.Document.Type.HTML.

Para mais informações, consulte Como classificar conteúdo. Para mais detalhes sobre a estrutura das solicitações para a Natural Language, consulte a Referência da Natural Language.

Python

Para saber como instalar e usar a biblioteca de cliente para a Natural Language, consulte Bibliotecas de cliente da Natural Language. Para mais informações, consulte a documentação de referência da API Natural Language Python.

Para se autenticar no Natural Language, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

O resultado retornado é um dicionário com os rótulos de categoria como chaves e as pontuações de confiança como valores, como:

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

O script de Python do tutorial está organizado para que possa ser executado a partir da linha de comando para experiências rápidas. Por exemplo, é possível executar:

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

Observação :o conteúdo a ser classificado precisa ter pelo menos 20 tokens (palavras) para que a API Natural Language retorne uma resposta.

Etapa 2: indexar vários arquivos de texto

A função index no script do tutorial usa, como entrada, um diretório contendo vários arquivos de texto e o caminho para um arquivo onde ela armazena a saída indexada (o nome de arquivo padrão é index.json). A função index lê o conteúdo de cada arquivo de texto no diretório de entrada e transmite os arquivos de texto para a API Cloud Natural Language para classificação em categorias de conteúdo.

Python

Para saber como instalar e usar a biblioteca de cliente para a Natural Language, consulte Bibliotecas de cliente da Natural Language. Para mais informações, consulte a documentação de referência da API Natural Language Python.

Para se autenticar no Natural Language, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Os resultados da API Cloud Natural Language para cada arquivo são organizados em um único dicionário, serializados como uma string JSON e depois gravados em um arquivo. Exemplo:

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

Para indexar arquivos de texto a partir da linha de comando com o nome de arquivo de saída padrão index.json, execute o seguinte comando:

python classify_text_tutorial.py index resources/texts

Etapa 3: consultar o índice

Consultar com rótulos de categoria

Depois que o arquivo de índice (nome de arquivo padrão = index.json) for criado, poderemos fazer consultas ao índice para recuperar alguns dos nomes de arquivos e suas pontuações de confiança.

Uma maneira de fazer isso é usar um rótulo de categoria como a consulta, que o tutorial realiza com a função query_category. A implementação das funções auxiliares, como similarity, pode ser encontrada no arquivo classify_text_tutorial.py. Nos seus aplicativos, a pontuação e a classificação de similaridade precisam ser cuidadosamente projetadas em torno de casos de uso específicos.

Python

Para saber como instalar e usar a biblioteca de cliente para a Natural Language, consulte Bibliotecas de cliente da Natural Language. Para mais informações, consulte a documentação de referência da API Natural Language Python.

Para se autenticar no Natural Language, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Para ver uma lista de todas as categorias disponíveis, consulte Categorias.

Como antes, é possível chamar a função query_category a partir da linha de comando:

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

A saída será semelhante a esta:

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

Consultar com texto

Como alternativa, você pode fazer consultas com um texto que pode não fazer parte do texto indexado. A função query do tutorial é semelhante à função query_category, com a adição da etapa para criar uma solicitação classifyText para a entrada de texto e usar os resultados para consultar o arquivo de índice.

Python

Para saber como instalar e usar a biblioteca de cliente para a Natural Language, consulte Bibliotecas de cliente da Natural Language. Para mais informações, consulte a documentação de referência da API Natural Language Python.

Para se autenticar no Natural Language, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Para fazer isso na linha de comando, execute:

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

Isso mostra algo semelhante ao exemplo a seguir:

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

A seguir

Com a API de classificação de conteúdo, você pode criar outros aplicativos. Exemplo:

• Classificar cada parágrafo de um artigo para ver a transição entre os tópicos.

• Classificar o conteúdo do carimbo de data/hora e analisar a tendência dos tópicos ao longo do tempo.

• Comparar as categorias de conteúdo com o sentimento do conteúdo usando o método analyzeSentiment.

• Comparar as categorias de conteúdo com as entidades mencionadas no texto.

Além disso, outros produtos do Google Cloud Platform podem ser usados para simplificar o fluxo de trabalho:

• No aplicativo de exemplo deste tutorial, processamos arquivos de texto locais, mas é possível modificar o código para processar arquivos de texto armazenados em um bucket do Google Cloud Storage transmitindo um URI do Google Cloud Storage para o método classify_text.

• No aplicativo de amostra deste tutorial, armazenamos o arquivo de índice localmente, e cada consulta é processada por meio da leitura de todo o arquivo de índice. Isso gerará alta latência se você tiver uma grande quantidade de dados indexados ou se precisar processar várias consultas. O Datastore é uma escolha excelente e prática para armazenar os dados do índice.