Biblioteca de clientes do Azure Análise de Texto para Java – versão 5.4.0

O Serviço Cognitivo do Azure para Linguagem é um serviço baseado em nuvem que fornece recursos de NLP (Processamento de Linguagem Natural) para entender e analisar texto e inclui os seguintes recursos de main:

• Análise de Sentimento
• Entidades de reconhecimento de entidade (entidades nomeadas, vinculadas e pii (informações de identificação pessoal)
• Detecção de Idioma
• Extração de Frases-Chave
• Análise de várias ações por documento
• Análise de entidades de saúde
• Resumo de texto abstrativo
• Resumo de texto extrativo
• Reconhecimento de Entidade Nomeada personalizado
• Classificação de texto personalizado

Código-fonte | Pacote (Maven) | Documentação | de referência da APIDocumentação | do produtoAmostras

Introdução

Pré-requisitos

• Um Java Development Kit (JDK) versão 8 ou posterior.
• Assinatura do Azure
• Serviços Cognitivos ou conta de serviço de linguagem para usar esse pacote.

Incluir o Pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre o BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-textanalytics</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente no BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-textanalytics</artifactId>
    <version>5.4.0</version>
</dependency>

Nota: Essa versão da biblioteca de clientes usa como padrão a 2023-04-01 versão do serviço. É uma versão mais recente do que 3_0e 3_12022-05-01.

Esta tabela mostra a relação entre os serviços do SDK e as versões de API com suporte do serviço:

Versão do SDK	Versão da API do serviço com suporte
5.3.x	3.0, 3.1, 2022-05-01, 2023-04-01 (padrão)
5.2.x	3.0, 3.1, 2022-05-01
5.1.x	3.0, 3.1
5.0.x	3.0

Criar um recurso dos Serviços Cognitivos ou do Serviço de Linguagem

O serviço De linguagem dá suporte ao acesso de vários serviços e de serviço único. Crie um recurso dos Serviços Cognitivos se você planeja acessar vários serviços cognitivos em um só ponto de extremidade/chave. Somente para acesso ao serviço de linguagem, crie um recurso de serviço de linguagem.

Você pode criar o recurso usando o Portal do Azure ou a CLI do Azure seguindo as etapas neste documento.

Autenticar o cliente

Para interagir com o serviço de Linguagem, você precisará criar uma instância do cliente Análise de Texto, os clientes assíncronos e síncronos podem ser criados usando TextAnalyticsClientBuilder a invocação buildClient() cria um cliente síncrono enquanto buildAsyncClient() cria sua contraparte assíncrona.

Você precisará de um ponto de extremidade e de uma chave ou token do AADCredential para instanciar um objeto cliente.

Pesquisando o ponto de extremidade

Você pode encontrar o ponto de extremidade para o recurso de serviço de linguagem no Portal do Azure em "Chaves e Ponto de Extremidade" ou na CLI do Azure.

# Get the endpoint for the Language service resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "endpoint"

Criar um cliente Análise de Texto com credencial de chave

Depois de ter o valor da chave, forneça-o como uma cadeia de caracteres para o AzureKeyCredential. Isso pode ser encontrado no Portal do Azure na seção "Chaves e Ponto de Extremidade" no recurso de serviço de linguagem criado ou executando o seguinte comando da CLI do Azure:

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

Use a chave como o parâmetro de credencial para autenticar o cliente:

TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildClient();

A biblioteca de clientes Análise de Texto do Azure fornece uma maneira de girar a chave existente.

AzureKeyCredential credential = new AzureKeyCredential("{key}");
TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(credential)
    .endpoint("{endpoint}")
    .buildClient();

credential.update("{new_key}");

Criar um cliente Análise de Texto com a credencial do Azure Active Directory

O SDK do Azure para Java dá suporte a um pacote de Identidade do Azure, facilitando a obtenção de credenciais de plataforma de identidade da Microsoft.

A autenticação com o AAD requer alguma configuração inicial:

• Adicionar o pacote de Identidade do Azure

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.10.4</version>
</dependency>

• Registrar um novo aplicativo do Azure Active Directory
• Conceda acesso ao Serviço de Linguagem atribuindo a "Cognitive Services User" função à sua entidade de serviço.

Após a instalação, você pode escolher qual tipo de credencial do azure.identity usar. Por exemplo, DefaultAzureCredential pode ser usado para autenticar o cliente: 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.

A autorização é mais fácil usando DefaultAzureCredential. Ele encontra a melhor credencial a ser usada em seu ambiente de execução. Para obter mais informações sobre como usar a autorização do Azure Active Directory com o Serviço de Linguagem, consulte a documentação associada.

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
TextAnalyticsAsyncClient textAnalyticsAsyncClient = new TextAnalyticsClientBuilder()
    .endpoint("{endpoint}")
    .credential(defaultCredential)
    .buildAsyncClient();

Principais conceitos

cliente Análise de Texto

A biblioteca de clientes Análise de Texto fornece um TextAnalyticsClient e TextAnalyticsAsyncClient para fazer análise em lotes de documentos. Ele fornece operações síncronas e assíncronas para acessar um uso específico do serviço de Linguagem, como detecção de idioma ou extração de frases-chave.

Entrada

Uma entrada de texto, também chamada de documento, é uma única unidade do documento a ser analisada pelos modelos preditivos no serviço de linguagem. As operações em um cliente Análise de Texto podem levar um único documento ou uma coleção de documentos para serem analisados como um lote. Consulte limitações de serviço para o documento, incluindo limites de comprimento do documento, tamanho máximo do lote e codificação de texto com suporte.

Operação em vários documentos

Para cada operação com suporte, o cliente Análise de Texto fornece sobrecargas de método para levar um único documento, um lote de documentos como cadeias de caracteres ou um lote de TextDocumentInput objetos ou DetectLanguageInput . A sobrecarga que recebe o TextDocumentInput lote ou DetectLanguageInput permite que os chamadores forneçam a cada documento uma ID exclusiva, indiquem que os documentos no lote são escritos em idiomas diferentes ou fornecem uma dica de país sobre o idioma do documento.

Retornar valor

Um resultado da operação, como AnalyzeSentimentResult, é o resultado de uma operação de serviço de linguagem, contendo uma previsão ou previsões sobre um único documento e uma lista de avisos dentro dele. 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. Um resultado da operação contém uma isError propriedade que permite identificar se uma operação executada foi bem-sucedida ou não para o documento especificado. Quando a operação resulta em um erro, você pode simplesmente chamar getError() para obter TextAnalyticsError , que contém o motivo pelo qual ela não foi bem-sucedida. Se você estiver interessado em quantos caracteres estão em seu documento ou no número de transações de operação que passaram, basta chamar getStatistics() para obter o TextDocumentStatistics que contém ambas as informações.

Retornar coleção de valores

Uma coleção de resultados de operação, como AnalyzeSentimentResultCollection, que é a coleção do resultado da análise da operação de sentimento. Ele também inclui a versão do modelo da operação e as estatísticas dos documentos do lote.

Observação: é recomendável usar os métodos de lote ao trabalhar em ambientes de produção, pois eles permitem que você envie uma solicitação com vários documentos. Isso é mais eficaz do que enviar uma solicitação por cada documento.

Exemplos

As seções a seguir fornecem vários snippets de código que abrangem algumas das tarefas mais comuns do Serviço de Linguagem, incluindo:

• Analisar Sentimento
• Detectar Idioma
• Extrair frases-chave
• Reconhecer entidades nomeadas
• Reconhecer entidades de informações de identificação pessoal
• Reconhecer entidades vinculadas
• Analisar entidades de saúde
• Analisar várias ações
• Reconhecimento de Entidades Personalizadas
• Classificação de texto personalizado
• Resumo de texto abstrativo
• Resumo de texto extrativo

Cliente Análise de Texto

O serviço de linguagem dá suporte à criação de cliente síncrona e assíncrona usando TextAnalyticsClientBuilder,

TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildClient();

ou

TextAnalyticsAsyncClient textAnalyticsAsyncClient = new TextAnalyticsClientBuilder()
    .credential(new AzureKeyCredential("{key}"))
    .endpoint("{endpoint}")
    .buildAsyncClient();

Analisar sentimento

Execute um modelo preditivo para identificar o sentimento positivo, negativo, neutro ou misto contido no documento ou lote de documentos fornecidos.

String document = "The hotel was dark and unclean. I like microsoft.";
DocumentSentiment documentSentiment = textAnalyticsClient.analyzeSentiment(document);
System.out.printf("Analyzed document sentiment: %s.%n", documentSentiment.getSentiment());
documentSentiment.getSentences().forEach(sentenceSentiment ->
    System.out.printf("Analyzed sentence sentiment: %s.%n", sentenceSentiment.getSentiment()));

Para obter exemplos sobre como usar a opção AnalyzeSentimentBatch recomendada de produção, consulte aqui.

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

Consulte a documentação do serviço para obter uma discussão conceitual sobre análise de sentimento.

Detectar o idioma

Execute um modelo preditivo para determinar o idioma no qual o documento ou lote de documentos fornecidos está escrito.

String document = "Bonjour tout le monde";
DetectedLanguage detectedLanguage = textAnalyticsClient.detectLanguage(document);
System.out.printf("Detected language name: %s, ISO 6391 name: %s, confidence score: %f.%n",
    detectedLanguage.getName(), detectedLanguage.getIso6391Name(), detectedLanguage.getConfidenceScore());

Para obter exemplos sobre como usar a opção DetectLanguageBatch recomendada de produção, consulte aqui. Consulte a documentação do serviço para obter uma discussão conceitual sobre a detecção de idiomas.

Extrair frases-chave

Execute um modelo para identificar uma coleção de frases significativas encontradas no documento ou lote de documentos fornecidos.

String document = "My cat might need to see a veterinarian.";
System.out.println("Extracted phrases:");
textAnalyticsClient.extractKeyPhrases(document).forEach(keyPhrase -> System.out.printf("%s.%n", keyPhrase));

Para obter exemplos sobre como usar a opção ExtractKeyPhrasesBatch recomendada de produção, consulte aqui. Consulte a documentação do serviço para obter uma discussão conceitual sobre a extração de frases-chave.

Reconhecer entidades nomeadas

Execute um modelo preditivo para identificar uma coleção de entidades nomeadas no documento ou lote de documentos fornecidos e categorizar essas entidades em categorias como pessoa, localização ou organização. Para obter mais informações sobre categorias disponíveis, consulte Categorias de entidade nomeadas.

String document = "Satya Nadella is the CEO of Microsoft";
textAnalyticsClient.recognizeEntities(document).forEach(entity ->
    System.out.printf("Recognized entity: %s, category: %s, subcategory: %s, confidence score: %f.%n",
        entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getConfidenceScore()));

Para obter exemplos sobre como usar a opção RecognizeEntitiesBatch recomendada de produção, consulte aqui. Consulte a documentação do serviço para obter uma discussão conceitual sobre o reconhecimento de entidade nomeada.

Reconhecer entidades de informações de identificação pessoal

Execute um modelo preditivo para identificar uma coleção de entidades pii (informações de identificação pessoal) no documento fornecido. Ele reconhece e categoriza entidades PII em seu texto de entrada, como Números da Previdência Social, informações de conta bancária, crédito cartão números e muito mais. Esse ponto de extremidade só tem suporte para versões de API v3.1-preview.1 e superiores.

String document = "My SSN is 859-98-0987";
PiiEntityCollection piiEntityCollection = textAnalyticsClient.recognizePiiEntities(document);
System.out.printf("Redacted Text: %s%n", piiEntityCollection.getRedactedText());
piiEntityCollection.forEach(entity -> System.out.printf(
    "Recognized Personally Identifiable Information entity: %s, entity category: %s, entity subcategory: %s,"
        + " confidence score: %f.%n",
    entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getConfidenceScore()));

Para obter exemplos sobre como usar a opção RecognizePiiEntitiesBatch recomendada de produção, consulte aqui. Consulte a documentação do serviço para obter tipos de entidade PII com suporte.

Reconhecer entidades vinculadas

Execute um modelo preditivo para identificar uma coleção de entidades encontradas no documento ou lote de documentos fornecidos e inclua informações que vinculam as entidades às respectivas entradas correspondentes em um base de dados de conhecimento conhecido.

String document = "Old Faithful is a geyser at Yellowstone Park.";
textAnalyticsClient.recognizeLinkedEntities(document).forEach(linkedEntity -> {
    System.out.println("Linked Entities:");
    System.out.printf("Name: %s, entity ID in data source: %s, URL: %s, data source: %s.%n",
        linkedEntity.getName(), linkedEntity.getDataSourceEntityId(), linkedEntity.getUrl(), linkedEntity.getDataSource());
    linkedEntity.getMatches().forEach(match ->
        System.out.printf("Text: %s, confidence score: %f.%n", match.getText(), match.getConfidenceScore()));
});

Para obter exemplos sobre como usar a opção RecognizeLinkedEntitiesBatch recomendada de produção, consulte aqui. Consulte a documentação do serviço para obter uma discussão conceitual sobre vinculação de entidade.

Analisar entidades de saúde

Análise de Texto para a saúde é um serviço conteinerizado que extrai e rotula informações médicas relevantes de textos não estruturados, como anotações médicas, resumos de alta, documentos clínicos e registros eletrônicos de saúde.

• Reconhecimento de entidades de saúde

Para obter mais informações, consulte Como usar Análise de Texto para integridade.

Reconhecimento de entidades personalizadas

O NER personalizado é um dos recursos personalizados oferecidos pelo Serviço Cognitivo do Azure para Linguagem. Ele consiste em um serviço de API baseado em nuvem que aplica a inteligência do aprendizado de máquina para permitir que você crie modelos personalizados para tarefas de reconhecimento de entidade nomeada personalizado.

• Reconhecimento de entidades personalizadas

Para obter mais informações , consulte Como usar: reconhecimento de entidades personalizadas.

Classificação personalizada de textos

A classificação de textos personalizada é um dos recursos personalizados oferecidos pelo Serviço Cognitivo do Azure para Linguagem. Ela consiste em um serviço de API baseado em nuvem que aplica a inteligência do aprendizado de máquina para permitir que você crie modelos personalizados para tarefas de classificação de texto.

• Classificação de rótulo único

• Classificação de vários rótulos

Para obter mais informações , consulte Como usar: classificação de texto personalizada.

Analisar várias ações

A Analyze funcionalidade permite escolher qual dos recursos de serviço de linguagem com suporte será executado no mesmo conjunto de documentos. Atualmente, os recursos com suporte são:

• Reconhecimento de Entidades Nomeadas
• Reconhecimento de entidades PII
• Reconhecimento de Entidade Vinculada
• Extração de Frases-Chave
• Análise de Sentimento
• Análise de serviços de saúde
• Reconhecimento de Entidade Personalizada (API versão 2022-05-01 e mais recente)
• Classificação de Single-Label personalizada (API versão 2022-05-01 e mais recente)
• Classificação personalizada de vários rótulos (API versão 2022-05-01 e mais recente)
• Resumo de Texto Abstrativo (API versão 2023-04-01 e mais recente)
• Resumo de Texto Extrativo (API versão 2023-04-01 e mais recente)

Exemplo: análise de várias ações

Para obter mais exemplos, como exemplos assíncronos, consulte aqui.

Solução de problemas

Geral

Análise de Texto clientes geram exceções. Por exemplo, se você tentar detectar os idiomas de um lote de texto com as mesmas IDs de documento, 400 o erro será retornado indicando uma solicitação incorreta. No snippet de código a seguir, o erro é tratado normalmente com a captura da exceção e a exibição de informações adicionais sobre o erro.

List<DetectLanguageInput> documents = Arrays.asList(
    new DetectLanguageInput("1", "This is written in English.", "us"),
    new DetectLanguageInput("1", "Este es un documento  escrito en Español.", "es")
);

try {
    textAnalyticsClient.detectLanguageBatchWithResponse(documents, null, Context.NONE);
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
}

Habilitar o log do cliente

Você pode definir a variável de ambiente AZURE_LOG_LEVEL para exibir instruções de log feitas na biblioteca de cliente. Por exemplo, a configuração AZURE_LOG_LEVEL=2 mostraria todas as mensagens informativas, de aviso e de log de erros. Os níveis de log podem ser encontrados aqui: níveis de log.

Cliente HTTP padrão

Por padrão, todas as bibliotecas de cliente usam o cliente HTTP do Netty. Adicionar a dependência acima configurará automaticamente a biblioteca de cliente para usar o cliente HTTP do Netty. A configuração ou a alteração do cliente HTTP é detalhada no wiki de clientes HTTP.

Biblioteca SSL padrão

Todas as bibliotecas de cliente, por padrão, usam a biblioteca SSL com o uso do Tomcat nativo para habilitar o desempenho de nível nativo para operações SSL. A biblioteca SSL é um uber jar que contém bibliotecas nativas para Linux/macOS/Windows e fornece melhor desempenho em comparação com a implementação SSL padrão no JDK. Para obter mais informações, incluindo como reduzir o tamanho da dependência, consulte a seção ajuste de desempenho da wiki.

Próximas etapas

• Os exemplos são explicados em detalhes aqui.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder e de fato concede, os direitos de usar sua contribuição.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.