Noções básicas da API Natural Language

Este documento fornece um guia sobre os princípios básicos da utilização da Cloud Natural Language API. Este guia conceptual aborda os tipos de pedidos que pode fazer à API Natural Language, como criar esses pedidos e como processar as respetivas respostas. Recomendamos que todos os utilizadores da API Natural Language leiam este guia e um dos tutoriais associados antes de começarem a usar a API propriamente dita.

Funcionalidades de linguagem natural

A API Natural Language tem vários métodos para realizar a análise e a anotação no seu texto. Cada nível de análise fornece informações valiosas para a compreensão da linguagem. Estes métodos são apresentados abaixo:

• A análise de sentimentos inspeciona o texto fornecido e identifica a opinião emocional predominante no texto, especialmente para determinar a atitude de um escritor como positiva, negativa ou neutra. A análise de sentimentos é realizada através do método analyzeSentiment.

• A análise de entidades inspeciona o texto fornecido para encontrar entidades conhecidas (nomes próprios, como figuras públicas, pontos de referência, etc.). Substantivos comuns, como restaurante, estádio, etc.) e devolve informações sobre essas entidades. A análise de entidades é realizada com o método analyzeEntities.

• A análise de sentimentos de entidades inspeciona o texto fornecido para entidades conhecidas (nomes próprios e substantivos comuns), devolve informações sobre essas entidades e identifica a opinião emocional predominante da entidade no texto, especialmente para determinar a atitude de um escritor em relação à entidade como positiva, negativa ou neutra. A análise de entidades é realizada com o método analyzeEntitySentiment.

• A análise sintática extrai informações linguísticas, dividindo o texto fornecido numa série de frases e tokens (geralmente, limites de palavras), fornecendo uma análise mais detalhada desses tokens. A análise sintática é realizada com o método analyzeSyntax.

• A classificação de conteúdo analisa o conteúdo de texto e devolve uma categoria de conteúdo para o conteúdo. A classificação de conteúdo é realizada através do método classifyText.

Cada chamada API também deteta e devolve o idioma, se o autor da chamada não o tiver especificado no pedido inicial.

Além disso, se quiser realizar várias operações de linguagem natural num determinado texto usando apenas uma chamada API, também pode usar o pedido annotateText para realizar a análise de sentimentos e a análise de entidades.

Pedidos básicos de linguagem natural

A API Natural Language é uma API REST e consiste em pedidos JSON e respostas. Segue-se um pedido de análise de entidades JSON de linguagem natural simples:

{
  "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 deste pedido, que consistem nos seguintes subcampos:
  • type: tipo de documento (HTML ou PLAIN_TEXT)
  • language - (opcional) o idioma do texto no pedido. Se não for especificado, o idioma é detetado automaticamente. Para obter informações sobre os idiomas suportados pela API Natural Language, consulte o artigo Suporte de idiomas. Os idiomas não suportados devolvem um erro na resposta JSON.
    
  • content ou gcsContentUri, que contêm o texto a avaliar. Se passar content, este texto é incluído diretamente no pedido JSON (conforme mostrado acima). Se passar gcsContentUri, o campo tem de conter um URI que aponte para conteúdo de texto no Google Cloud Storage.
• encodingType - (obrigatório) o esquema de codificação no qual os desvios de carateres devolvidos no texto devem ser calculados, que tem de corresponder à codificação do texto transmitido. Se este parâmetro não estiver definido, o pedido não vai gerar um erro, mas todos os desvios vão ser definidos como -1.

Especificar conteúdo de texto

Quando transmite um pedido da API Natural Language, especifica o texto a processar de uma das seguintes formas:

• Transmitir o texto diretamente num campo content.
• Transmitir um URI do Google Cloud Storage num campo gcsContentUri.

Em qualquer dos casos, deve certificar-se de que não excede os limites de conteúdo permitidos. Tenha em atenção que estes limites de conteúdo são por byte e não por carater. Por conseguinte, o comprimento dos carateres depende da codificação do texto.

O pedido abaixo refere-se a um ficheiro 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 sensação geral

A análise de sentimentos tenta determinar a atitude geral (positiva ou negativa) expressa no texto. O sentimento é representado por valores numéricos score e magnitude.

Campos de resposta da análise de sensação geral

Abaixo, é apresentado um exemplo de analyzeSentiment resposta à Discurso de Gettysburg:

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

Estes valores dos campos 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 à tendência emocional geral do texto.
  • magnitude indica a intensidade 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 no texto (positiva e negativa) contribui para a magnitude do texto (por isso, os blocos de texto mais longos podem ter magnitudes maiores).
• language_code contém o idioma do documento, transmitido no pedido inicial ou detetado automaticamente se estiver ausente.
• language_supported contém um valor booleano para identificar se o idioma é oficialmente suportado
• sentences contém uma lista das frases extraídas do documento original, que contém:
  • sentiment contém os valores de sentimento ao nível da frase anexados a cada frase, que contêm score entre -1.0 (negativo) e 1.0 (positivo), bem como valores de magnitude entre 0.0 e 1.0. Tenha em atenção que magnitude para sentences é normalizado.

Um valor de sentimento de 0.2 para o discurso de Gettysburg indica que é ligeiramente positivo em termos de emoção, enquanto o valor de magnitude de 3.6 indica um documento relativamente emocional, dado o seu pequeno tamanho (cerca de um parágrafo). Tenha em atenção que a primeira frase do discurso de Gettysburg contém uma positividade muito elevada score de 0.8.

Interpretar os valores da análise de sensação geral

A pontuação do sentimento de um documento indica a emoção geral de um documento. A magnitude do sentimento de um documento indica a quantidade de conteúdo emocional presente no documento, e este valor é frequentemente proporcional ao comprimento do documento.

É importante ter em atenção que a API Natural Language indica diferenças entre emoções positivas e negativas num documento, mas não identifica emoções positivas e negativas específicas. Por exemplo, "zangado" e "triste" são considerados emoções negativas. No entanto, quando a API Natural Language analisa texto considerado "zangado" ou texto considerado "triste", a resposta indica apenas que o sentimento no texto é negativo e não "triste" ou "zangado".

Um documento com uma pontuação neutra (cerca de 0.0) pode indicar um documento com poucas emoções ou emoções mistas, com valores positivos e negativos elevados que se anulam mutuamente. Geralmente, pode usar valores magnitude para desambiguar estes casos, uma vez que os documentos verdadeiramente neutros têm um valor magnitude baixo, enquanto os documentos mistos têm valores de magnitude mais elevados.

Quando comparar documentos entre si (especialmente documentos de comprimentos diferentes), certifique-se de que usa os valores magnitude para calibrar as suas classificações, uma vez que podem ajudar a avaliar a quantidade relevante de conteúdo emocional.

O gráfico abaixo mostra alguns valores de exemplo e como os interpretar:

* O sentimento "claramente positivo" e "claramente negativo" varia consoante os diferentes exemplos de utilização e clientes. Pode encontrar resultados diferentes para o seu cenário específico. Recomendamos que defina um limite que funcione para si e, em seguida, ajuste o limite após testar e validar os resultados. Por exemplo, pode definir um limite de qualquer pontuação superior a 0,25 como claramente positiva e, em seguida, modificar o limite de pontuação para 0,15 depois de rever os dados e os resultados e verificar que as pontuações entre 0,15 e 0,25 também devem ser consideradas positivas.

Análise de entidades

A análise de entidades fornece informações sobre entidades no texto, que geralmente se referem a "coisas" com nome, como indivíduos famosos, marcos, objetos comuns, etc.

As entidades dividem-se em duas categorias: nomes próprios que são mapeados para entidades únicas (pessoas, locais, etc. específicos) ou nomes comuns (também denominados "nominais" no processamento de linguagem natural). Uma boa prática geral a seguir é que, se algo for um substantivo, qualifica-se como uma "entidade". As entidades são devolvidas como deslocamentos indexados no texto original.

Um pedido de análise de entidades deve transmitir um argumento encodingType para que os desvios devolvidos possam ser interpretados corretamente.

Campos de resposta da análise de entidades

A análise de entidades devolve um conjunto de entidades detetadas e parâmetros associados a essas entidades, como o tipo da entidade, a relevância da entidade para o texto geral e as localizações no texto que se referem à mesma entidade.

A analyzeEntities resposta ao pedido de entidade é apresentada abaixo:

{
  "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
          },
          "type": "PROPER",
          "probability": 0.914
        }
      ]
    },
    {
      "name": "Lawrence of Arabia",
      "type": "WORK_OF_ART",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Lawrence of Arabia",
            "beginOffset": 0
          },
          "type": "PROPER",
          "probability": 0.761
        }
      ]
    },
    {
      "name": "Lieutenant",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Lieutenant",
            "beginOffset": 66
          },
          "type": "COMMON",
          "probability": 0.927
        }
      ]
    },
    {
      "name": "Peter O Toole",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "Peter O Toole",
            "beginOffset": 93
          },
          "type": "PROPER",
          "probability": 0.907
        }
      ]
    },
    {
      "name": "T. E. Lawrence",
      "type": "PERSON",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "T. E. Lawrence",
            "beginOffset": 77
          },
          "type": "PROPER",
          "probability": 0.853
        }
      ]
    },
    {
      "name": "film",
      "type": "WORK_OF_ART",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "film",
            "beginOffset": 129
          },
          "type": "COMMON"