Aspectos básicos de la API Natural Language

En este documento se explican los conceptos básicos para usar la API Cloud Natural Language. En esta guía conceptual se describen los tipos de solicitudes que puedes enviar a la API Natural Language, cómo crear esas solicitudes y cómo gestionar sus respuestas. Recomendamos que todos los usuarios de la API Natural Language lean esta guía y uno de los tutoriales asociados antes de empezar a usar la API.

Funciones de Natural Language

La API Natural Language tiene varios métodos para realizar análisis y anotaciones en el texto. Cada nivel de análisis proporciona información valiosa para comprender el lenguaje. Estos métodos son los siguientes:

• El análisis de sentimiento inspecciona el texto proporcionado e identifica la opinión emocional predominante en él, sobre todo para determinar si la actitud del autor es positiva, negativa o neutra. El análisis de sentimiento se realiza mediante el método analyzeSentiment.

• Análisis de entidades: inspecciona el texto proporcionado para buscar entidades conocidas (nombres propios, como personajes públicos, monumentos, etc.). Nombres comunes, como restaurante, estadio, etc.) y devuelve información sobre esas entidades. El análisis de entidades se realiza con el método analyzeEntities.

• El análisis de sentimiento de entidades inspecciona el texto proporcionado para buscar entidades conocidas (nombres propios y nombres comunes), devuelve información sobre esas entidades e identifica la opinión emocional predominante de la entidad en el texto, especialmente para determinar si la actitud del autor hacia la entidad es positiva, negativa o neutra. El análisis de entidades se realiza con el método analyzeEntitySentiment.

• El análisis sintáctico extrae información lingüística, dividiendo el texto proporcionado en una serie de frases y tokens (generalmente, límites de palabras), y proporciona un análisis más detallado de esos tokens. El análisis sintáctico se realiza con el método analyzeSyntax.

• Clasificación de contenido: analiza el contenido de texto y devuelve una categoría de contenido para el contenido. La clasificación del contenido se realiza mediante el método classifyText.

Cada llamada a la API también detecta y devuelve el idioma, si el llamante no lo especifica en la solicitud inicial.

Además, si quieres realizar varias operaciones de lenguaje natural en un texto determinado con una sola llamada a la API, también puedes usar la solicitud annotateText para realizar análisis de sentimiento y de entidades.

Solicitudes básicas de lenguaje natural

La API Natural Language es una API REST que consta de solicitudes y respuestas JSON. A continuación, se muestra una solicitud JSON sencilla de análisis de entidades de lenguaje 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"
}

A continuación se explican estos campos:

• document contiene los datos de esta solicitud, que consta de los siguientes subcampos:
  • type: tipo de documento (HTML o PLAIN_TEXT)
  • language: (opcional) el idioma del texto de la solicitud. Si no se especifica, el idioma se detectará automáticamente. Para obtener información sobre los idiomas admitidos por la API Natural Language, consulta Idiomas admitidos. Si se usan idiomas no admitidos, se devolverá un error en la respuesta JSON.
    
  • content o gcsContentUri, que contienen el texto que se va a evaluar. Si se envía content, este texto se incluye directamente en la solicitud JSON (como se muestra arriba). Si se pasa gcsContentUri, el campo debe contener un URI que apunte a contenido de texto en Google Cloud Storage.
• encodingType: (obligatorio) el esquema de codificación en el que se deben calcular los desplazamientos de caracteres devueltos en el texto, que debe coincidir con la codificación del texto proporcionado. Si no se define este parámetro, la solicitud no generará ningún error, pero todos los desplazamientos se definirán en -1.

Especificar el contenido de texto

Cuando envías una solicitud a la API Natural Language, especificas el texto que quieres procesar de una de estas dos formas:

• Pasando el texto directamente en un campo content.
• Se pasa un URI de Google Cloud Storage en un campo gcsContentUri.

En cualquier caso, debes asegurarte de no superar los límites de contenido. Tenga en cuenta que estos límites de contenido se miden en bytes, no en caracteres, por lo que la longitud de los caracteres depende de la codificación del texto.

La solicitud que se muestra a continuación hace referencia a un archivo de Google Cloud Storage que contiene el discurso de Gettysburg:

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

Análisis de sentimiento

El análisis de sentimiento intenta determinar la actitud general (positiva o negativa) que se expresa en el texto. El sentimiento se representa con valores numéricos score y magnitude.

Campos de respuesta del análisis de sentimiento

A continuación, se muestra un ejemplo de respuesta analyzeSentiment a la alocución 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
      }
    },
   ...
}

Estos valores de campo se describen a continuación:

• documentSentiment contiene el sentimiento general del documento, que consta de los siguientes campos:
  • score del sentimiento oscila entre -1.0 (negativo) y 1.0 (positivo), y corresponde a la inclinación emocional general del texto.
  • magnitude indica la intensidad general de la emoción (tanto positiva como negativa) en el texto proporcionado, entre 0.0 y +inf. A diferencia de score, magnitude no se normaliza para documentSentiment; cada expresión de emoción en el texto (tanto positiva como negativa) contribuye a la magnitude del texto (por lo que los bloques de texto más largos pueden tener magnitudes mayores).
• language_code contiene el idioma del documento, que se ha indicado en la solicitud inicial o se ha detectado automáticamente si no se ha especificado.
• language_supported contiene un valor booleano para identificar si el idioma se admite oficialmente.
• sentences contiene una lista de las frases extraídas del documento original, que incluye lo siguiente:
  • sentiment contiene los valores de sentimiento a nivel de frase asociados a cada frase, que contienen score entre -1.0 (negativo) y 1.0 (positivo), así como valores de magnitude entre 0.0 y 1.0. Ten en cuenta que magnitude de sentences se normaliza.

Un valor de sentimiento de 0.2 en el discurso de Gettysburg indica que es ligeramente positivo, mientras que el valor de magnitud de 3.6 indica que es un documento relativamente emotivo, teniendo en cuenta su pequeño tamaño (aproximadamente un párrafo). Ten en cuenta que la primera frase del discurso de Gettysburg contiene una score positiva muy alta de 0.8.

Interpretar los valores del análisis de sentimiento

La puntuación del sentimiento de un documento indica la emoción general del documento. La magnitud del sentimiento de un documento indica la cantidad de contenido emocional que hay en él. Este valor suele ser proporcional a la longitud del documento.

Es importante tener en cuenta que la API Natural Language indica las diferencias entre las emociones positivas y negativas de un documento, pero no identifica emociones positivas y negativas específicas. Por ejemplo, "enfado" y "tristeza" se consideran emociones negativas. Sin embargo, cuando la API Natural Language analiza texto que se considera "enfadado" o "triste", la respuesta solo indica que el sentimiento del texto es negativo, no "triste" o "enfadado".

Un documento con una puntuación neutra (alrededor de 0.0) puede indicar que el documento no genera muchas emociones o que genera emociones mixtas, con valores positivos y negativos altos que se anulan entre sí. Por lo general, puede usar magnitudevaloresmagnitude para distinguir estos casos, ya que los documentos verdaderamente neutrales tendrán un valor magnitudebajomagnitude, mientras que los documentos mixtos tendrán valores de mayor magnitud.

Cuando compares documentos entre sí (especialmente si tienen longitudes diferentes), asegúrate de usar los valores de magnitude para calibrar las puntuaciones, ya que pueden ayudarte a medir la cantidad pertinente de contenido emocional.

En el siguiente gráfico se muestran algunos valores de ejemplo y cómo interpretarlos:

* El sentimiento "claramente positivo" y "claramente negativo" varía en función de los casos prácticos y los clientes. Es posible que obtengas resultados diferentes en tu caso concreto. Te recomendamos que definas un umbral que te resulte útil y que lo ajustes después de probar y verificar los resultados. Por ejemplo, puedes definir un umbral de cualquier puntuación superior a 0,25 como claramente positiva y, a continuación, modificar el umbral de puntuación a 0,15 después de revisar tus datos y resultados y determinar que las puntuaciones de 0,15 a 0,25 también deben considerarse positivas.

Análisis de entidades

Análisis de entidades proporciona información sobre las entidades del texto, que generalmente hacen referencia a "cosas" con nombre, como personajes famosos, monumentos, objetos comunes, etc.

Las entidades se dividen en dos categorías: nombres propios que se asignan a entidades únicas (personas, lugares, etc. específicos) o nombres comunes (también llamados "nominales" en el procesamiento del lenguaje natural). Una buena práctica general es que, si algo es un sustantivo, se considera una "entidad". Las entidades se devuelven como desplazamientos indexados en el texto original.

Una solicitud de análisis de entidades debe incluir un argumento encodingType para que los desplazamientos devueltos se puedan interpretar correctamente.

Campos de respuesta del análisis de entidades

El análisis de entidades devuelve un conjunto de entidades detectadas y los parámetros asociados a esas entidades, como el tipo de entidad, la relevancia de la entidad en el texto general y las ubicaciones del texto que hacen referencia a la misma entidad.

A continuación se muestra una respuesta analyzeEntities a la solicitud de entidad:

{
  "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",
          "probability": 0.805
        }
      ]
    },
    {
      "name": "film biography",
      "type": "WORK_OF_ART",
      "metadata": {},
      "mentions": [
        {
          "text": {
            "content": "film biography",
            "beginOffset": 37
          },
          "type": "COMMON",
          "probability": 0.876
        }
      ]
    }
  ],
  "languageCode"