Princípios básicos da Natural Language API

Este documento é um guia sobre os princípios básicos do uso da API Cloud Natural Language. Neste guia conceitual, abordamos os tipos de solicitações que podem ser feitas à API Natural Language, como construir essas solicitações e como lidar com as respostas. Recomenda-se que todos os usuários da Natural Language API leiam esse guia e um dos tutoriais associados antes de trabalhar com a API.

Recursos da linguagem natural

Na Natural Language API, há vários métodos para executar análises e anotação do texto. Cada nível de análise apresenta informações valiosas para entendimento da linguagem. Os métodos estão listados a seguir:

• Análise de sentimentos: inspeciona o texto fornecido e identifica a opinião emocional dominante nele, principalmente para determinar a atitude do escritor como positiva, negativa ou neutra. A análise de sentimento é realizada por meio do método analyzeSentiment.

• Análise de entidade: inspeciona o texto fornecido em busca de entidades conhecidas (substantivos próprios como país, cidade etc. e substantivos comuns como animais, objetos etc.). Depois, retorna informações sobre essas entidades. A análise de entidades é realizada com o método analyzeEntities.

• Análise do sentimento da entidade: inspeciona o texto fornecido em busca de entidades conhecidas (substantivos próprios e comuns), retorna informações sobre essas entidades e identifica a opinião emocional predominante dentro do texto. Isso ocorre especialmente para determinar a atitude do escritor em relação à entidade como positiva, negativa ou neutra. A análise de entidades é realizada com o método analyzeEntitySentiment.

• Análise sintática: extrai informações linguísticas ao dividir o texto fornecido em uma série de frases e tokens (geralmente, limites de palavra) e apresentar uma análise mais detalhada desses tokens. A análise sintática é realizada com o método analyzeSyntax.

• Classificação de conteúdo: analisa o conteúdo do texto e retorna uma categoria. A classificação de conteúdo é realizada usando o método classifyText.

Cada chamada de API também detecta e retorna o idioma se o autor da chamada não o tiver especificado na solicitação inicial.

Além disso, se você quiser executar várias operações de linguagem natural em determinado texto usando apenas uma chamada de API, a solicitação annotateText também poderá ser usada para realizar a análise de sentimento e de entidade.

Solicitações básicas do Natural Language

A Natural Language API é uma REST API e consiste em solicitações e resposta JSON. Veja uma solicitação simples de análise de entidade JSON de linguagem natural:

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

Estes campos são explicados abaixo:

• document contém os dados dessa solicitação, que consistem nos seguintes subcampos:
  • type: tipo de documento (HTML ou PLAIN_TEXT)
  • language: (opcional) o idioma do texto na solicitação. Se não for especificado, o idioma será detectado automaticamente. Para informações sobre quais idiomas são compatíveis com a API Natural Language, consulte Idiomas compatíveis. Os idiomas incompatíveis retornam um erro na resposta JSON.
    
  • content ou gcsContentUri que contêm o texto a ser avaliado. Se passar content, esse texto será incluído diretamente na solicitação JSON, como mostrado acima. Se passar gcsContentUri, o campo precisa conter um URI que direcione para o conteúdo de texto no Google Cloud Storage.
• encodingType (obrigatório): o esquema de codificação em que os deslocamentos de caracteres retornados no texto precisam ser calculados e corresponder à codificação do texto transmitido. Se esse parâmetro não for definido, não ocorrerá erro na solicitação, mas todos os deslocamentos serão definidos como -1.

Como especificar o conteúdo do texto

Para transmitir uma solicitação da Natural Language API, especifique o texto a ser processado de uma das duas maneiras:

• Transmitindo o texto diretamente em um campo content.
• Transmitindo um URI do Google Cloud Storage em um campo gcsContentUri.

Em qualquer caso, não transmita mais do que o permitido pelos Limites de conteúdo. Observe que esses limites de conteúdo são por byte, não por caractere. Portanto, o tamanho de caracteres depende da codificação do texto.

A solicitação abaixo se refere a um arquivo do Google Cloud Storage que contém o Discurso de Gettysburg:

{
  "document":{
    "type":"PLAIN_TEXT",
    "language": "EN",
    "gcsContentUri":"gs://cloud-samples-tests/natural-language/gettysburg.txt"
  },
}

Análise de sentimentos

A análise de sentimentos determina a atitude de modo geral, positiva ou negativa, expressa no texto. O sentimento é representado pelos valores numéricos score e magnitude.

Campos de resposta da análise de sentimentos

Uma resposta analyzeSentiment de amostra ao Discurso de Gettysburg é mostrada abaixo:

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

Esses valores de campo estão descritos abaixo:

• documentSentiment contém o sentimento geral do documento, que consiste nos seguintes campos:
  • score do sentimento varia entre -1.0 (negativo) e 1.0 (positivo) e corresponde à inclinação emocional geral do texto.
  • magnitude indica a força geral da emoção (positiva e negativa) no texto fornecido, entre 0.0 e +inf. Ao contrário de score, magnitude não é normalizado para documentSentiment. Cada expressão de emoção dentro do texto (tanto positiva quanto negativa) contribui para a magnitude do texto. Ou seja, blocos de texto mais longos podem ter magnitudes maiores.
• language_code contém o idioma do documento, transmitido na solicitação inicial ou detectado automaticamente, se ausente.
• language_supported contém um valor booleano para identificar se o idioma é oficialmente compatível
• sentences contém uma lista das sentenças extraídas do documento original, que contém:
  • sentiment contém os valores de sentimento no nível de frase anexados a cada frase, que contêm score entre -1.0 (negativo) e 1.0 (positivo). como e magnitude entre 0.0 e 1.0. magnitude para sentences é normalizado.

Um valor de sentimento de 0.2 no Discurso de Gettysburg indica que a emoção é um pouco positiva, enquanto o valor de magnitude de 3.6 indica um documento relativamente emotivo, devido ao tamanho pequeno (de cerca de um parágrafo). A primeira sentença do Discurso de Gettysburg contém um score positivo muito alto de 0.8.

Como interpretar valores da análise de sentimento

A pontuação de sentimento de um documento indica a emoção de modo geral. A magnitude de sentimento de um documento indica o conteúdo emocional presente nele, e esse valor é geralmente proporcional ao tamanho do documento.

É importante observar que a Natural Language API identifica diferenças entre emoções positivas e negativas em um documento, mas não especifica quais são essas emoções positivas e negativas. Por exemplo, "irritado" e "triste" são consideradas emoções negativas. No entanto, quando a Natural Language API analisa o texto que é considerado "irritado", ou texto classificado como "triste", a resposta apenas indica que o sentimento no texto é negativo, não "triste" ou "irritado".

Um documento com uma pontuação neutra de aproximadamente 0.0 pode indicar baixa emoção, ou indicar emoções mistas, com valores altamente positivos e também negativos que se anulam. Geralmente, você usa valores de magnitude para diferenciar esses casos, porque os documentos verdadeiramente neutros terão um valor de magnitude baixo, enquanto documentos mistos terão valores de magnitude maiores.

Ao comparar documentos entre si, especialmente documentos de diferentes tamanhos, certifique-se de usar os valores de magnitude para calibrar suas pontuações, porque elas podem ajudar a medir a quantidade relevante de conteúdo emocional.

A tabela abaixo exibe algumas amostras de valores e sua respectiva interpretação:

* O sentimento "claramente positivo" e "claramente negativo" varia de acordo com os diferentes casos de uso e clientes. É possível encontrar resultados diferentes para seu cenário específico. Recomendamos que você defina um limite que funcione para seu caso e depois ajuste o limite após testar e verificar os resultados. Por exemplo, defina um limite de qualquer pontuação acima de 0,25 como claramente positivo e, em seguida, modificar o limite de pontuação para 0,15 depois de revisar seus dados e resultados e descobrir que as pontuações de 0,15 a 0,25 também devem ser consideradas positivas.

Análise de entidade

A análise de entidade fornece informações sobre entidades do texto, que geralmente se referem a elementos nomeados, por exemplo, celebridades, pontos de referência, objetos comuns etc.

As entidades se dividem em duas categorias: substantivos próprios que se associam a entidades exclusivas, ou seja, pessoas, locais etc. específicos, ou substantivos comuns, também chamados de "nominais" no processamento da linguagem natural. Segundo uma boa prática geral, se o elemento é um substantivo, ele é qualificado como uma "entidade". As entidades são retornadas como deslocamentos indexados no texto original.

Uma solicitação de análise de entidade deve transmitir um argumento encodingType, para que os deslocamentos retornados possam ser interpretados corretamente.

Campos da resposta da análise de entidade

A análise de entidade retorna um conjunto das entidades detectadas e os parâmetros associados a elas, por exemplo, tipo de entidade, relevância da entidade para o texto de modo geral e locais no texto que se referem à mesma entidade.

Uma resposta analyzeEntities para a solicitação de entidade é mostrada abaixo:

{
  "entities": [
    {
      "name": "British",
      "type": "LOCATION",
      "metadata": {},
      "mentions"