Biblioteca cliente de Azure Text Analytics para JavaScript: versión 5.1.0

Artículo
04/05/2023

Azure TextAnalytics es un servicio basado en la nube que proporciona procesamiento avanzado de lenguaje natural sobre texto sin formato e incluye seis funciones principales:

Nota: Este SDK tiene como destino azure Text Analytics service API, versión 3.1.0.

Detección de idiomas
Análisis de sentimiento
Extracción de frases clave
Reconocimiento de entidades con nombre
Reconocimiento de información de identificación personal
Reconocimiento de entidades vinculadas
Análisis de atención sanitaria
Compatibilidad con varias acciones por documento

Use la biblioteca cliente para:

Detecte en qué idioma se escribe el texto de entrada.
Determine qué clientes piensan de su marca o tema mediante el análisis de texto sin formato para obtener pistas sobre opiniones positivas o negativas.
Extracción de las frases clave para identificar rápidamente los puntos principales.
Identifique y clasifique las entidades del texto como personas, lugares, organizaciones, fecha y hora, cantidades, porcentajes, monedas, específicas de la atención sanitaria, etc.
Realice varias de las tareas anteriores a la vez.

Vínculos principales:

Introducción

Entornos admitidos actualmente

Versiones de LTS de Node.js
Versiones más recientes de Safari, Chrome, Edge y Firefox.

Para más información, consulte la directiva de compatibilidad.

Requisitos previos

Una suscripción de Azure.
Un recurso de Cognitive Services o Text Analytics existente. Si necesita crear el recurso, puede usar Azure Portal o la CLI de Azure.

Si usa la CLI de Azure, reemplace <your-resource-group-name> y <your-resource-name> por sus propios nombres únicos:

az cognitiveservices account create --kind TextAnalytics --resource-group <your-resource-group-name> --name <your-resource-name> --sku <your-sku-name> --location <your-location>

Instalar el paquete `@azure/ai-text-analytics`

Instale la biblioteca cliente de Azure Text Analytics para JavaScript con npm:

npm install @azure/ai-text-analytics

Crear y autenticar una `TextAnalyticsClient`

Para crear un objeto de cliente para acceder a la API de Text Analytics, necesitará el endpoint del recurso de Text Analytics y un credential. El cliente de Text Analytics puede usar credenciales de Azure Active Directory o una credencial de clave de API para autenticarse.

Puede encontrar el punto de conexión del recurso de Text Analytics en Azure Portal o mediante el fragmento de código de la CLI de Azure siguiente:

az cognitiveservices account show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

Uso de una clave de API

Use Azure Portal para ir al recurso de Text Analytics y recuperar una clave de API, o bien use el fragmento de código de la CLI de Azure siguiente:

Nota: A veces, la clave de API se conoce como "clave de suscripción" o "clave de API de suscripción".

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Una vez que tenga una clave de API y un punto de conexión, puede usar la AzureKeyCredential clase para autenticar el cliente de la siguiente manera:

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

Uso de una credencial de Azure Active Directory

La autenticación de clave de API de cliente se usa en la mayoría de los ejemplos, pero también puede autenticarse con Azure Active Directory mediante la biblioteca de identidades de Azure. Para usar el proveedor DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, instale el @azure/identity paquete:

npm install @azure/identity

También deberá registrar una nueva aplicación de AAD y conceder acceso a Text Analytics mediante la asignación del "Cognitive Services User" rol a la entidad de servicio (nota: otros roles como "Owner" no concederán los permisos necesarios, solo "Cognitive Services User" serán suficientes para ejecutar los ejemplos y el código de ejemplo).

Establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

const { TextAnalyticsClient } = require("@azure/ai-text-analytics");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new TextAnalyticsClient("<endpoint>", new DefaultAzureCredential());

Conceptos clave

TextAnalyticsClient

TextAnalyticsClientes la interfaz principal para los desarrolladores que usan la biblioteca cliente de Text Analytics. Explore los métodos de este objeto de cliente para comprender las diferentes características del servicio Text Analytics al que puede acceder.

Entrada

Un documento representa una sola unidad de entrada que analizarán los modelos predictivos del servicio Text Analytics. Las operaciones en TextAnalyticsClient toman una colección de entradas que se van a analizar como un lote. Los métodos de operación tienen sobrecargas que permiten representar las entradas como cadenas o como objetos con metadatos adjuntos.

Por ejemplo, cada documento se puede pasar como una cadena en una matriz, por ejemplo,

const documents = [
  "I hated the movie. It was so slow!",
  "The movie made it into my top ten favorites.",
  "What a great movie!"
];

o bien, si desea pasar un documento id por elemento o languagecountryHint/, se pueden proporcionar como una lista de o DetectLanguageInput dependiendo de TextDocumentInput la operación;

const textDocumentInputs = [
  { id: "1", language: "en", text: "I hated the movie. It was so slow!" },
  { id: "2", language: "en", text: "The movie made it into my top ten favorites." },
  { id: "3", language: "en", text: "What a great movie!" }
];

Consulte las limitaciones del servicio para la entrada, incluidos los límites de longitud del documento, el tamaño máximo del lote y las codificaciones de texto admitidas.

Valor devuelto

El valor devuelto correspondiente a un único documento es un resultado correcto o un objeto de error. Cada TextAnalyticsClient método devuelve una matriz heterogénea de resultados y errores que corresponden a las entradas por índice. Una entrada de texto y su resultado tendrán el mismo índice en las colecciones de entrada y resultados. Opcionalmente, la colección también puede incluir información sobre el lote de entrada y cómo se procesó en el statistics campo.

Un resultado, como AnalyzeSentimentResult, es el resultado de una operación de Text Analytics, que contiene una predicción o predicciones sobre una sola entrada de texto. El tipo de resultado de una operación también puede incluir información sobre el documento de entrada y cómo se procesó.

El objeto de error , TextAnalyticsErrorResult, indica que el servicio encontró un error al procesar el documento y contiene información sobre el error.

Control de errores de documentos

En la colección devuelta por una operación, los errores se distinguen de las respuestas correctas por la presencia de la error propiedad , que contiene el objeto interno TextAnalyticsError si se encontró un error. Para los objetos de resultado correctos, esta propiedad siempreundefined es .

Por ejemplo, para filtrar todos los errores, puede usar lo siguiente filter:

const results = await client.analyzeSentiment(documents);
const onlySuccessful = results.filter((result) => result.error === undefined);

Nota: Los usuarios de TypeScript pueden beneficiarse de una mejor comprobación de tipos de objetos de error y resultados si compilerOptions.strictNullChecks está establecido true en en la tsconfig.json configuración. Por ejemplo:

const [result] = await client.analyzeSentiment(["Hello world!"]);

if (result.error !== undefined) {
  // In this if block, TypeScript will be sure that the type of `result` is
  // `TextAnalyticsError` if compilerOptions.strictNullChecks is enabled in
  // the tsconfig.json

  console.log(result.error);
}

Esta funcionalidad se introdujo en TypeScript 3.2, por lo que los usuarios de TypeScript 3.1 deben convertir los valores de resultado a su variante correcta correspondiente de la siguiente manera:

const [result] = await client.detectLanguage(["Hello world!"]);

if (result.error === undefined) {
  const { primaryLanguage } = result as DetectLanguageSuccessResult;
}

Ejemplos

Análisis de opiniones

Analice la opinión del texto para determinar si es positivo, negativo, neutro o mixto, incluido el análisis de opiniones por oración y las puntuaciones de confianza.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "I did not like the restaurant. The food was too spicy.",
  "The restaurant was decorated beautifully. The atmosphere was unlike any other restaurant I've been to.",
  "The food was yummy. :)"
];

async function main() {
  const results = await client.analyzeSentiment(documents);

  for (const result of results) {
    if (result.error === undefined) {
      console.log("Overall sentiment:", result.sentiment);
      console.log("Scores:", result.confidenceScores);
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}

main();

Para obtener información más detallada sobre las opiniones relacionadas con aspectos de un producto o servicio, también conocido como Análisis de sentimiento basado en aspectos en procesamiento de lenguaje natural (NLP), consulte aquí un ejemplo sobre el análisis de sentimiento con minería de opiniones.

Reconocimiento de entidades

Reconocer y clasificar entidades en texto como personas, lugares, organizaciones, fechas y horas, cantidades, monedas, etc.

El language es opcional. Si no se especifica, se usará el modelo en inglés predeterminado.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "Microsoft was founded by Bill Gates and Paul Allen.",
  "Redmond is a city in King County, Washington, United States, located 15 miles east of Seattle.",
  "Jeff bought three dozen eggs because there was a 50% discount."
];

async function main() {
  const results = await client.recognizeEntities(documents, "en");

  for (const result of results) {
    if (result.error === undefined) {
      console.log(" -- Recognized entities for input", result.id, "--");
      for (const entity of result.entities) {
        console.log(entity.text, ":", entity.category, "(Score:", entity.confidenceScore, ")");
      }
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}

main();

Reconocimiento de entidades DE PII

Hay un punto de conexión y una operación independientes para reconocer información de identificación personal (PII) en texto como números de seguridad social, información de cuenta bancaria, números de tarjeta de crédito, etc. Su uso es muy similar al reconocimiento de entidades estándar anterior:

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");
const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));
const documents = [
  "The employee's SSN is 555-55-5555.",
  "The employee's phone number is (555) 555-5555."
];
async function main() {
  const results = await client.recognizePiiEntities(documents, "en");
  for (const result of results) {
    if (result.error === undefined) {
      console.log(" -- Recognized PII entities for input", result.id, "--");
      for (const entity of result.entities) {
        console.log(entity.text, ":", entity.category, "(Score:", entity.confidenceScore, ")");
      }
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}
main();

Reconocimiento de entidades vinculadas

Una entidad "Vinculada" es aquella que existe en un knowledge base (como Wikipedia). La recognizeLinkedEntities operación puede eliminar la ambigüedad de las entidades mediante la determinación de qué entrada en un knowledge base probablemente hacen referencia (por ejemplo, en un fragmento de texto, hace referencia a la palabra "Marte" al planeta o al dios romano de la guerra). Las entidades vinculadas contienen direcciones URL asociadas a la knowledge base que proporciona la definición de la entidad.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "Microsoft was founded by Bill Gates and Paul Allen.",
  "Easter Island, a Chilean territory, is a remote volcanic island in Polynesia.",
  "I use Azure Functions to develop my product."
];

async function main() {
  const results = await client.recognizeLinkedEntities(documents, "en");

  for (const result of results) {
    if (result.error === undefined) {
      console.log(" -- Recognized linked entities for input", result.id, "--");
      for (const entity of result.entities) {
        console.log(entity.name, "(URL:", entity.url, ", Source:", entity.dataSource, ")");
        for (const match of entity.matches) {
          console.log(
            "  Occurrence:",
            '"' + match.text + '"',
            "(Score:",
            match.confidenceScore,
            ")"
          );
        }
      }
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}

main();

Extracción de frases clave

La extracción de frases clave identifica los principales puntos de conversación de un documento. Por ejemplo, dado el texto de entrada "La comida estaba deliciosa y el personal era maravilloso", el servicio devuelve "comida" y "personal maravilloso".

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "Redmond is a city in King County, Washington, United States, located 15 miles east of Seattle.",
  "I need to take my cat to the veterinarian.",
  "I will travel to South America in the summer."
];

async function main() {
  const results = await client.extractKeyPhrases(documents, "en");

  for (const result of results) {
    if (result.error === undefined) {
      console.log(" -- Extracted key phrases for input", result.id, "--");
      console.log(result.keyPhrases);
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}

main();

Detección de idioma

Determine el idioma de un fragmento de texto.

El countryHint parámetro es opcional, pero puede ayudar al servicio a proporcionar una salida correcta si se conoce el país de origen. Si se proporciona, debe establecerse en un código de país de dos letras ISO-3166 Alpha-2 (como "nosotros" para el Estados Unidos o "jp" para Japón) o en el valor "none". Si no se proporciona el parámetro , se usará el modelo predeterminado "us" (Estados Unidos). Si no conoce el país de origen del documento, se debe usar el parámetro "none" y el servicio Text Analytics aplicará un modelo optimizado para un país de origen desconocido.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "This is written in English.",
  "Il documento scritto in italiano.",
  "Dies ist in deutscher Sprache verfasst."
];

async function main() {
  const results = await client.detectLanguage(documents, "none");

  for (const result of results) {
    if (result.error === undefined) {
      const { primaryLanguage } = result;
      console.log(
        "Input #",
        result.id,
        "identified as",
        primaryLanguage.name,
        "( ISO6391:",
        primaryLanguage.iso6391Name,
        ", Score:",
        primaryLanguage.confidenceScore,
        ")"
      );
    } else {
      console.error("Encountered an error:", result.error);
    }
  }
}

main();

Análisis de entidades sanitarias

El análisis sanitario identifica las entidades sanitarias. Por ejemplo, dado el texto de entrada "Prescribe 100 mg de ibuprofeno, tomado dos veces al día", el servicio devuelve "100mg" categorizado como Dosis, "ibuprofeno" como MedicationName, y "dos veces al día" como Frecuencia.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "Prescribed 100mg ibuprofen, taken twice daily.",
  "Patient does not suffer from high blood pressure."
];

async function main() {
  const poller = await client.beginAnalyzeHealthcareEntities(documents);
  const results = await poller.pollUntilDone();

  for await (const result of results) {
    console.log(`- Document ${result.id}`);
    if (!result.error) {
      console.log("\tRecognized Entities:");
      for (const entity of result.entities) {
        console.log(`\t- Entity ${entity.text} of type ${entity.category}`);
      }
    } else console.error("\tError:", result.error);
  }
}

main();

Analizar acciones

Las acciones de análisis permiten la aplicación de varios análisis (acciones con nombre) a la vez.

const { TextAnalyticsClient, AzureKeyCredential } = require("@azure/ai-text-analytics");

const client = new TextAnalyticsClient("<endpoint>", new AzureKeyCredential("<API key>"));

const documents = [
  "Microsoft was founded by Bill Gates and Paul Allen.",
  "The employee's SSN is 555-55-5555.",
  "Easter Island, a Chilean territory, is a remote volcanic island in Polynesia.",
  "I use Azure Functions to develop my product."
];

async function main() {
  const actions = {
    recognizeEntitiesActions: [{ modelVersion: "latest" }],
    recognizePiiEntitiesActions: [{ modelVersion: "latest" }],
    extractKeyPhrasesActions: [{ modelVersion: "latest" }]
  };
  const poller = await client.beginAnalyzeActions(documents, actions);
  const resultPages = await poller.pollUntilDone();
  for await (const page of resultPages) {
    const keyPhrasesAction = page.extractKeyPhrasesResults[0];
    if (!keyPhrasesAction.error) {
      for (const doc of keyPhrasesAction.results) {
        console.log(`- Document ${doc.id}`);
        if (!doc.error) {
          console.log("\tKey phrases:");
          for (const phrase of doc.keyPhrases) {
            console.log(`\t- ${phrase}`);
          }
        } else {
          console.error("\tError:", doc.error);
        }
      }
    }

    const entitiesAction = page.recognizeEntitiesResults[0];
    if (!entitiesAction.error) {
      for (const doc of entitiesAction.results) {
        console.log(`- Document ${doc.id}`);
        if (!doc.error) {
          console.log("\tEntities:");
          for (const entity of doc.entities) {
            console.log(`\t- Entity ${entity.text} of type ${entity.category}`);
          }
        } else {
          console.error("\tError:", doc.error);
        }
      }
    }

    const piiEntitiesAction = page.recognizePiiEntitiesResults[0];
    if (!piiEntitiesAction.error) {
      for (const doc of piiEntitiesAction.results) {
        console.log(`- Document ${doc.id}`);
        if (!doc.error) {
          console.log("\tPii Entities:");
          for (const entity of doc.entities) {
            console.log(`\t- Entity ${entity.text} of type ${entity.category}`);
          }
        } else {
          console.error("\tError:", doc.error);
        }
      }
    }
  }
}

main();

Solución de problemas

Registro

La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

Pasos siguientes

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados sobre cómo usar esta biblioteca.

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar el código.

SDK de Microsoft Azure para JavaScript

Impresiones

Compartir a través de

Biblioteca cliente de Azure Text Analytics para JavaScript: versión 5.1.0

Introducción

Entornos admitidos actualmente

Requisitos previos

Instalar el paquete `@azure/ai-text-analytics`

Crear y autenticar una `TextAnalyticsClient`

Uso de una clave de API

Uso de una credencial de Azure Active Directory

Conceptos clave

TextAnalyticsClient

Entrada

Valor devuelto

Control de errores de documentos

Ejemplos

Análisis de opiniones

Reconocimiento de entidades

Reconocimiento de entidades DE PII

Reconocimiento de entidades vinculadas

Extracción de frases clave

Detección de idioma

Análisis de entidades sanitarias

Analizar acciones

Solución de problemas

Registro

Pasos siguientes

Contribuciones

Recursos adicionales

Compartir a través de

Biblioteca cliente de Azure Text Analytics para JavaScript: versión 5.1.0

Introducción

Entornos admitidos actualmente

Requisitos previos

Instalar el paquete @azure/ai-text-analytics

Crear y autenticar una TextAnalyticsClient

Uso de una clave de API

Uso de una credencial de Azure Active Directory

Conceptos clave

TextAnalyticsClient

Entrada

Valor devuelto

Control de errores de documentos

Ejemplos

Análisis de opiniones

Reconocimiento de entidades

Reconocimiento de entidades DE PII

Reconocimiento de entidades vinculadas

Extracción de frases clave

Detección de idioma

Análisis de entidades sanitarias

Analizar acciones

Solución de problemas

Registro

Pasos siguientes

Contribuciones

Proyectos relacionados

Recursos adicionales

Instalar el paquete `@azure/ai-text-analytics`

Crear y autenticar una `TextAnalyticsClient`