Biblioteca de clientes do Azure Análise de Texto para JavaScript – versão 5.1.0

  • Artigo

O Azure TextAnalytics é um serviço baseado em nuvem que fornece processamento avançado de linguagem natural em texto bruto e inclui seis funções principais:

Nota: Esse SDK tem como destino a API do serviço Análise de Texto do Azure versão 3.1.0.

  • Detecção de Idioma
  • Análise de Sentimento
  • Extração de Frases-Chave
  • Reconhecimento de Entidade Nomeada
  • Reconhecimento de informações de identificação pessoal
  • Reconhecimento de Entidade Vinculada
  • Análise de serviços de saúde
  • Suporte a várias ações por documento

Use a biblioteca de clientes para:

  • Detecte em qual idioma o texto de entrada está escrito.
  • Determine o que os clientes pensam de sua marca ou tópico analisando texto bruto para obter pistas sobre sentimentos positivos ou negativos.
  • Extrai automaticamente frases-chave para identificar rapidamente os principais pontos.
  • Identifique e categorize entidades em seu texto como pessoas, locais, organizações, data/hora, quantidades, porcentagens, moedas, específicos de saúde e muito mais.
  • Execute várias das tarefas acima ao mesmo tempo.

Links principais:

Introdução

Ambientes com suporte no momento

Confira nossa política de suporte para mais detalhes.

Pré-requisitos

Se você usar a CLI do Azure, substitua <your-resource-group-name> e <your-resource-name> por seus próprios nomes exclusivos:

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

Instalar o pacote @azure/ai-text-analytics

Instale a biblioteca de clientes do Azure Análise de Texto para JavaScript com npm:

npm install @azure/ai-text-analytics

Criar e autenticar um TextAnalyticsClient

Para criar um objeto cliente para acessar a API Análise de Texto, você precisará do endpoint do recurso Análise de Texto e de um credential. O cliente Análise de Texto pode usar credenciais do Azure Active Directory ou uma credencial de chave de API para autenticar.

Você pode encontrar o ponto de extremidade do recurso de análise de texto no Portal do Azure ou usando o snippet da CLI do Azure abaixo:

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

Usando uma chave de API

Use o Portal do Azure para navegar até o recurso Análise de Texto e recuperar uma chave de API ou usar o snippet da CLI do Azure abaixo:

Nota: Às vezes, a chave de API é chamada de "chave de assinatura" ou "chave de API de assinatura".

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

Depois de ter uma chave de API e um ponto de extremidade, você poderá usar a AzureKeyCredential classe para autenticar o cliente da seguinte maneira:

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

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

Usando uma credencial do Azure Active Directory

A autenticação de chave de API do cliente é usada na maioria dos exemplos, mas você também pode autenticar com o Azure Active Directory usando a biblioteca de identidade do Azure. Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, instale o @azure/identity pacote:

npm install @azure/identity

Você também precisará registrar um novo aplicativo do AAD e conceder acesso a Análise de Texto atribuindo a "Cognitive Services User" função à entidade de serviço (observação: outras funções como "Owner" não concederão as permissões necessárias, apenas "Cognitive Services User" serão suficientes para executar os exemplos e o código de exemplo).

Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: 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());

Principais conceitos

TextAnalyticsClient

TextAnalyticsClienté a interface principal para desenvolvedores que usam a biblioteca de clientes do Análise de Texto. Explore os métodos neste objeto cliente para entender os diferentes recursos do serviço Análise de Texto que você pode acessar.

Entrada

Um documento representa uma única unidade de entrada a ser analisada pelos modelos preditivos no serviço Análise de Texto. As operações em TextAnalyticsClient levam uma coleção de entradas a serem analisadas como um lote. Os métodos de operação têm sobrecargas que permitem que as entradas sejam representadas como cadeias de caracteres ou como objetos com metadados anexados.

Por exemplo, cada documento pode ser passado como uma cadeia de caracteres em uma matriz, por exemplo,

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

ou, se você quiser passar um documento id por item ou languagecountryHint/, eles poderão ser dados como uma lista de TextDocumentInput ou DetectLanguageInput dependendo da operação;

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!" }
];

Confira limitações de serviço para a entrada, incluindo limites de comprimento do documento, tamanho máximo do lote e codificações de texto com suporte.

Valor Retornado

O valor retornado correspondente a um único documento é um resultado bem-sucedido ou um objeto de erro. Cada TextAnalyticsClient método retorna uma matriz heterogênea de resultados e erros que correspondem às entradas por índice. Uma entrada de texto e seu resultado terão o mesmo índice nas coleções de entrada e resultado. Opcionalmente, a coleção também pode incluir informações sobre o lote de entrada e como ele foi processado no statistics campo.

Um resultado, como AnalyzeSentimentResult, é o resultado de uma operação de Análise de Texto, contendo uma previsão ou previsões sobre uma única entrada de texto. O tipo de resultado de uma operação também pode incluir, opcionalmente, informações sobre o documento de entrada e como ele foi processado.

O objeto de erro , TextAnalyticsErrorResult, indica que o serviço encontrou um erro ao processar o documento e contém informações sobre o erro.

Tratamento de erros de documento

Na coleção retornada por uma operação, os erros são diferenciados das respostas bem-sucedidas pela presença da error propriedade , que contém o objeto interno TextAnalyticsError se um erro foi encontrado. Para objetos de resultado bem-sucedidos, essa propriedade é sempreundefined.

Por exemplo, para filtrar todos os erros, você pode usar o seguinte filter:

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

Observação: os usuários do TypeScript poderão se beneficiar de uma melhor verificação de tipo de objetos de resultado e erro se compilerOptions.strictNullChecks estiver definido como true na tsconfig.json configuração. Por exemplo:

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);
}

Essa funcionalidade foi introduzida no TypeScript 3.2, portanto, os usuários do TypeScript 3.1 devem converter valores de resultado em sua variante de sucesso correspondente da seguinte maneira:

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

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

Exemplos

Analisar Sentimento

Analise o sentimento do texto para determinar se ele é positivo, negativo, neutro ou misto, incluindo análise de sentimento por frase e pontuações de confiança.

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 obter informações mais granulares sobre as opiniões relacionadas a aspectos de um produto/serviço, também conhecido como Análise de Sentimento Baseada em Aspectos no NLP (Processamento de Linguagem Natural), consulte um exemplo de análise de sentimento com mineração de opiniões aqui.

Reconhecer entidades

Reconhecer e categorizar entidades no texto como pessoas, locais, organizações, datas/horas, quantidades, moedas etc.

O language é opcional. Se não for especificado, o modelo padrão em inglês será usado.

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();

Reconhecer entidades PII

Há um ponto de extremidade e uma operação separados para reconhecer PII (Informações de Identificação Pessoal) em texto, como Números da Previdência Social, informações de conta bancária, números de cartão de crédito etc. Seu uso é muito semelhante ao reconhecimento de entidade padrão acima:

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();

Reconhecer entidades vinculadas

Uma entidade "Vinculada" é aquela que existe em um base de dados de conhecimento (como a Wikipédia). A recognizeLinkedEntities operação pode desambiguar entidades determinando a qual entrada em um base de dados de conhecimento elas provavelmente se referem (por exemplo, em um pedaço de texto, a palavra "Marte" se refere ao planeta ou ao deus romano da guerra). As entidades vinculadas contêm URLs associadas ao base de dados de conhecimento que fornece a definição da entidade.

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();

Extrair frases-chave

A extração de frases-chave identifica os principais pontos de discussão em um documento. Por exemplo, texto de entrada especificado “A comida estava deliciosa e a equipe foi maravilhosa”, o serviço retorna “comida” e “equipe maravilhosa”.

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();

Detectar o idioma

Determine o idioma de um trecho de texto.

O countryHint parâmetro é opcional, mas pode ajudar o serviço a fornecer a saída correta se o país de origem for conhecido. Se fornecido, ele deve ser definido como um código de país de duas letras ISO-3166 Alfa-2 (como "nós" para o Estados Unidos ou "jp" para o Japão) ou para o valor "none". Se o parâmetro não for fornecido, o modelo padrão "us" (Estados Unidos) será usado. Se você não souber o país de origem do documento, o parâmetro "none" deverá ser usado e o serviço Análise de Texto aplicará um modelo ajustado para um país de origem desconhecido.

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();

Analisar entidades de saúde

A análise de serviços de saúde identifica entidades de saúde. Por exemplo, dado o texto de entrada "Prescrito 100mg ibuprofeno, tomado duas vezes por dia", o serviço retorna "100mg" categorizado como Dosagem, "ibuprofeno" como MedicationName e "duas vezes por dia" como Frequência.

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();

Analisar ações

As ações de análise permitem a aplicação de várias análises (ações nomeadas) ao mesmo tempo.

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();

Solução de problemas

Log

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, veja os documentos do pacote @azure/logger.

Próximas etapas

Dê uma olhada no diretório de exemplos para obter exemplos detalhados sobre como usar essa biblioteca.

Contribuição

Se você quiser contribuir com essa biblioteca, leia o guia de contribuição para saber como criar e testar o código.

Impressões