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

  • Artigo

O Serviço Cognitivo do Azure para Linguagem é um serviço baseado em nuvem que fornece processamento avançado de linguagem natural por texto bruto e inclui os seguintes recursos de main:

Nota: Esse SDK tem como destino o Serviço Cognitivo do Azure para API de Linguagem versão 2023-04-01.

  • 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
  • Vinculação de Identidade
  • Análise de serviços de saúde
  • Resumo extrativo
  • Resumo Abstrativo
  • Reconhecimento de Entidade Personalizada
  • Classificação personalizada de documentos
  • Suporte a várias ações por documento

Use a biblioteca de clientes para:

  • Detecte em qual texto de entrada de idioma está escrito.
  • Determine o que os clientes pensam de sua marca ou tópico analisando texto bruto para obter pistas sobre sentimento positivo ou negativo.
  • 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, percentuais, moedas, específicos à saúde e muito mais.
  • Execute várias das tarefas acima ao mesmo tempo.

Links principais:

Migrando da @azure/ai-text-analytics consultoria⚠️

Consulte o Guia de Migração para obter instruções detalhadas sobre como atualizar o código do aplicativo da versão 5.x da biblioteca de clientes do Análise de Texto de IA para a nova biblioteca de clientes de Texto da Linguagem de IA.

What's New

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-language-text

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

npm install @azure/ai-language-text

Criar e autenticar um TextAnalysisClient

Para criar um objeto cliente para acessar a API de Linguagem, você precisará do endpoint recurso de Linguagem e de um credential. O cliente de 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 para o recurso idioma 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 "properties.endpoint"

Usando uma chave de API

Use o Portal do Azure para navegar até o recurso Idioma 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 { TextAnalysisClient, AzureKeyCredential } = require("@azure/ai-language-text");

const client = new TextAnalysisClient("<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 ao Language 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, bastará apenas "Cognitive Services User" 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 { TextAnalysisClient } = require("@azure/ai-language-text");
const { DefaultAzureCredential } = require("@azure/identity");

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

Principais conceitos

TextAnalysisClient

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

Entrada

Um documento representa uma única unidade de entrada a ser analisada pelos modelos preditivos no serviço de linguagem. As operações em TextAnalysisClient 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/, ele poderá ser dado 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!" },
];

Consulte 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 TextAnalysisClient 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.

Um resultado, como SentimentAnalysisResult, é o resultado de uma operação language, 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 , TextAnalysisErrorResult, 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 TextAnalysisError 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.analyze("SentimentAnalysis", documents);
const onlySuccessful = results.filter((result) => result.error === undefined);

Observação: os usuários do TypeScript podem 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.analyze("SentimentAnalysis", ["Hello world!"]);

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

  console.log(result.error);
}

Exemplos

Uso do cliente

Tarefas predefinidas

Tarefas personalizadas

Solução de problemas

Registro em 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:

const { setLogLevel } = require("@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