Serviços Cognitivos do Azure Análise de Texto biblioteca de clientes para .NET – versão 5.3.0

  • Artigo

Análise de Texto faz parte do 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. Esta biblioteca de clientes oferece os seguintes recursos:

  • Detecção de idioma
  • Análise de sentimento
  • Extração de frases-chave
  • NER (reconhecimento de entidade nomeada)
  • Reconhecimento de entidade de PII (informações de identificação pessoal)
  • Vinculação de entidade
  • Análise de Texto para integridade
  • Reconhecimento de entidade nomeada personalizado (NER personalizado)
  • Classificação personalizada de textos
  • Resumo de texto extrativo
  • Resumo de texto abstrativo

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

Introdução

Instalar o pacote

Instale a biblioteca de clientes do Azure Análise de Texto para .NET com o NuGet:

dotnet add package Azure.AI.TextAnalytics

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

Observe que 5.2.0 é a primeira versão estável da biblioteca de clientes que tem como destino as APIs do Serviço Cognitivo do Azure para Linguagem, que inclui a análise de texto existente e os recursos de processamento de idioma natural encontrados na biblioteca de clientes do Análise de Texto. Além disso, a API de serviço foi alterada de controle de versão semântico para baseado em data.

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 (padrão)
5.1.X 3.0, 3.1 (padrão)
5.0.X 3.0
1.0.X 3.0

Pré-requisitos

  • Uma assinatura do Azure.
  • Um recurso existente dos Serviços Cognitivos ou do Serviço de Linguagem.

Criar um recurso dos Serviços Cognitivos ou um recurso de serviço de linguagem

O Serviço Cognitivo do Azure para 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 único ponto de extremidade e chave de API. Para acessar apenas os recursos do serviço de Linguagem, crie um recurso de serviço de linguagem.

Você pode criar um recurso por meio do portal do Azure ou, como alternativa, pode seguir as etapas neste documento para criá-lo usando a CLI do Azure.

Autenticar o cliente

A interação com o serviço usando a biblioteca de clientes começa com a criação de uma instância da classe TextAnalyticsClient . Você precisará de um ponto de extremidade e de uma chave de API ou TokenCredential de instanciar um objeto cliente. Para obter mais informações sobre como autenticar com serviços cognitivos, consulte Autenticar solicitações para os Serviços Cognitivos do Azure.

Obter uma chave de API

Você pode obter o e API key do endpoint recurso dos Serviços Cognitivos ou informações de recurso do serviço de linguagem no Portal do Azure.

Como alternativa, use o snippet da CLI do Azure abaixo para obter a chave de API do recurso serviço de linguagem.

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

Criar um TextAnalyticsClient usando uma credencial de chave de API

Depois de ter o valor da chave de API, crie um AzureKeyCredential. Isso permitirá que você atualize a chave de API sem criar um novo cliente.

Com o valor do ponto de extremidade e um AzureKeyCredential, você pode criar o TextAnalyticsClient:

Uri endpoint = new("<endpoint>");
AzureKeyCredential credential = new("<apiKey>");
TextAnalyticsClient client = new(endpoint, credential);

Criar um TextAnalyticsClient com uma credencial do Azure Active Directory

A autenticação de chave de API do cliente é usada na maioria dos exemplos neste guia de introdução, mas você também pode autenticar com o Azure Active Directory usando a biblioteca de Identidade do Azure. Observe que os pontos de extremidade regionais não dão suporte à autenticação do AAD. Crie um subdomínio personalizado para o recurso para usar esse tipo de autenticação.

Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, instale o pacote Azure.Identity:

dotnet add package Azure.Identity

Você também precisará registrar um novo aplicativo do AAD e conceder acesso ao serviço de Linguagem atribuindo a "Cognitive Services User" função à entidade de serviço.

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.

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

Principais conceitos

TextAnalyticsClient

Um TextAnalyticsClient é a interface principal para desenvolvedores que usam a biblioteca de clientes Análise de Texto. Ele fornece operações síncronas e assíncronas para acessar um uso específico da análise de texto, como detecção de idioma ou extração de frases-chave.

Entrada

Um documento é uma única unidade de entrada a ser analisada pelos modelos preditivos no serviço de Linguagem. As operações em TextAnalyticsClient podem levar um único documento ou uma coleção de documentos para serem analisados como um lote. Para limites de comprimento do documento, tamanho máximo do lote e codificação de texto com suporte, consulte aqui.

Operação em vários documentos

Para cada operação com suporte, TextAnalyticsClient fornece um método que aceita um lote de documentos como cadeias de caracteres ou um lote de TextDocumentInput objetos ou DetectLanguageInput . Esses métodos permitem 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.

Nota: É 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.

Retornar valor

Valores retornados, como AnalyzeSentimentResult, são o resultado de uma operação de Análise de Texto, contendo uma previsão ou previsões sobre um único documento. O valor retornado de uma operação também pode incluir, opcionalmente, informações sobre o documento e como ele foi processado.

Coleção de valores retornados

Uma coleção de valores return, como AnalyzeSentimentResultCollection, é uma coleção de resultados da operação, em que cada um corresponde a um dos documentos fornecidos no lote de entrada. Um documento e seu resultado terão o mesmo índice nas coleções de entrada e resultado. O valor retornado também contém uma HasError propriedade que permite identificar se uma operação executada foi bem-sucedida ou não foi bem-sucedida para o documento fornecido. Opcionalmente, ele pode incluir informações sobre o lote de documentos e como ele foi processado.

Operações do Long-Running

Para documentos grandes que levam muito tempo para serem executados, essas operações são implementadas como operações de execução prolongada. As operações de execução prolongada consistem em uma solicitação inicial enviada ao serviço para iniciar uma operação, seguida pela sondagem do serviço em intervalos para determinar se a operação foi concluída ou falhou e, se foi bem-sucedida, para obter o resultado.

Para operações de execução prolongada no SDK do Azure, o cliente expõe um Start<operation-name> método que retorna um Operation<T> ou um PageableOperation<T>. Você pode usar o método WaitForCompletionAsync() de extensão para aguardar a conclusão da operação e obter seu resultado. Um snippet de código de exemplo é fornecido para ilustrar o uso de operações de execução longa abaixo.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções do | clienteAcessando a resposta | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

A seção a seguir fornece vários snippets de código usando o clientcriado acima e aborda os main recursos presentes nesta biblioteca de clientes. Embora a maioria dos snippets abaixo use chamadas de serviço síncronas, tenha em mente que o Azure.AI.TextAnalytics pacote dá suporte a APIs síncronas e assíncronas.

Exemplos de sincronização

Exemplos assíncronos

Detectar o idioma

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

string document =
    "Este documento está escrito en un lenguaje diferente al inglés. Su objectivo es demostrar cómo"
    + " invocar el método de Detección de Lenguaje del servicio de Text Analytics en Microsoft Azure."
    + " También muestra cómo acceder a la información retornada por el servicio. Esta funcionalidad es"
    + " útil para los sistemas de contenido que recopilan texto arbitrario, donde el lenguaje no se conoce"
    + " de antemano. Puede usarse para detectar una amplia gama de lenguajes, variantes, dialectos y"
    + " algunos idiomas regionales o culturales.";

try
{
    Response<DetectedLanguage> response = client.DetectLanguage(document);
    DetectedLanguage language = response.Value;

    Console.WriteLine($"Detected language is {language.Name} with a confidence score of {language.ConfidenceScore}.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

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

Consulte a documentação do serviço para obter uma discussão conceitual sobre a detecção de idioma.

Analisar Sentimento

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

string document =
    "I had the best day of my life. I decided to go sky-diving and it made me appreciate my whole life so"
    + "much more. I developed a deep-connection with my instructor as well, and I feel as if I've made a"
    + "life-long friend in her.";

try
{
    Response<DocumentSentiment> response = client.AnalyzeSentiment(document);
    DocumentSentiment docSentiment = response.Value;

    Console.WriteLine($"Document sentiment is {docSentiment.Sentiment} with: ");
    Console.WriteLine($"  Positive confidence score: {docSentiment.ConfidenceScores.Positive}");
    Console.WriteLine($"  Neutral confidence score: {docSentiment.ConfidenceScores.Neutral}");
    Console.WriteLine($"  Negative confidence score: {docSentiment.ConfidenceScores.Negative}");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

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

Para obter informações mais granulares sobre as opiniões relacionadas aos destinos de um produto/serviço, também conhecida 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.

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

Extrair frases-chave

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

string document =
    "My cat might need to see a veterinarian. It has been sneezing more than normal, and although my"
    + " little sister thinks it is funny, I am worried it has the cold that I got last week. We are going"
    + " to call tomorrow and try to schedule an appointment for this week. Hopefully it will be covered by"
    + " the cat's insurance. It might be good to not let it sleep in my room for a while.";

try
{
    Response<KeyPhraseCollection> response = client.ExtractKeyPhrases(document);
    KeyPhraseCollection keyPhrases = response.Value;

    Console.WriteLine($"Extracted {keyPhrases.Count} key phrases:");
    foreach (string keyPhrase in keyPhrases)
    {
        Console.WriteLine($"  {keyPhrase}");
    }
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

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

Consulte a documentação do serviço para obter uma discussão conceitual sobre 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 passados e categorizar essas entidades em categorias como pessoa, localização ou organização. Para obter mais informações sobre categorias disponíveis, consulte Análise de Texto Categorias de Entidade Nomeada.

string document =
    "We love this trail and make the trip every year. The views are breathtaking and well worth the hike!"
    + " Yesterday was foggy though, so we missed the spectacular views. We tried again today and it was"
    + " amazing. Everyone in my family liked the trail although it was too challenging for the less"
    + " athletic among us. Not necessarily recommended for small children. A hotel close to the trail"
    + " offers services for childcare in case you want that.";

try
{
    Response<CategorizedEntityCollection> response = client.RecognizeEntities(document);
    CategorizedEntityCollection entitiesInDocument = response.Value;

    Console.WriteLine($"Recognized {entitiesInDocument.Count} entities:");
    foreach (CategorizedEntity entity in entitiesInDocument)
    {
        Console.WriteLine($"  Text: {entity.Text}");
        Console.WriteLine($"  Offset: {entity.Offset}");
        Console.WriteLine($"  Length: {entity.Length}");
        Console.WriteLine($"  Category: {entity.Category}");
        if (!string.IsNullOrEmpty(entity.SubCategory))
            Console.WriteLine($"  SubCategory: {entity.SubCategory}");
        Console.WriteLine($"  Confidence score: {entity.ConfidenceScore}");
        Console.WriteLine();
    }
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

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

Consulte a documentação do serviço para obter uma discussão conceitual sobre o reconhecimento de entidade nomeada.

Reconhecer entidades PII

Execute um modelo preditivo para identificar uma coleção de entidades que contêm Informações de Identificação Pessoal encontradas no documento ou lote de documentos passados e categorize essas entidades em categorias como número do seguro social dos EUA, número da carteira de motorista ou número de cartão de crédito.

string document =
    "Parker Doe has repaid all of their loans as of 2020-04-25. Their SSN is 859-98-0987. To contact them,"
    + " use their phone number 800-102-1100. They are originally from Brazil and have document ID number"
    + " 998.214.865-68.";

try
{
    Response<PiiEntityCollection> response = client.RecognizePiiEntities(document);
    PiiEntityCollection entities = response.Value;

    Console.WriteLine($"Redacted Text: {entities.RedactedText}");
    Console.WriteLine();
    Console.WriteLine($"Recognized {entities.Count} PII entities:");
    foreach (PiiEntity entity in entities)
    {
        Console.WriteLine($"  Text: {entity.Text}");
        Console.WriteLine($"  Category: {entity.Category}");
        if (!string.IsNullOrEmpty(entity.SubCategory))
            Console.WriteLine($"  SubCategory: {entity.SubCategory}");
        Console.WriteLine($"  Confidence score: {entity.ConfidenceScore}");
        Console.WriteLine();
    }
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Para obter exemplos sobre como usar a opção de produção recomendada, RecognizePiiEntitiesBatch 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 passados e inclua informações vinculando as entidades às suas entradas correspondentes em um base de dados de conhecimento conhecido.

string document =
    "Microsoft was founded by Bill Gates with some friends he met at Harvard. One of his friends, Steve"
    + " Ballmer, eventually became CEO after Bill Gates as well. Steve Ballmer eventually stepped down as"
    + " CEO of Microsoft, and was succeeded by Satya Nadella. Microsoft originally moved its headquarters"
    + " to Bellevue, Washington in Januaray 1979, but is now headquartered in Redmond.";

try
{
    Response<LinkedEntityCollection> response = client.RecognizeLinkedEntities(document);
    LinkedEntityCollection linkedEntities = response.Value;

    Console.WriteLine($"Recognized {linkedEntities.Count} entities:");
    foreach (LinkedEntity linkedEntity in linkedEntities)
    {
        Console.WriteLine($"  Name: {linkedEntity.Name}");
        Console.WriteLine($"  Language: {linkedEntity.Language}");
        Console.WriteLine($"  Data Source: {linkedEntity.DataSource}");
        Console.WriteLine($"  URL: {linkedEntity.Url}");
        Console.WriteLine($"  Entity Id in Data Source: {linkedEntity.DataSourceEntityId}");
        foreach (LinkedEntityMatch match in linkedEntity.Matches)
        {
            Console.WriteLine($"    Match Text: {match.Text}");
            Console.WriteLine($"    Offset: {match.Offset}");
            Console.WriteLine($"    Length: {match.Length}");
            Console.WriteLine($"    Confidence score: {match.ConfidenceScore}");
        }
        Console.WriteLine();
    }
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

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

Consulte a documentação do serviço para obter uma discussão conceitual sobre vinculação de entidade.

Detectar idioma de forma assíncrona

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

string document =
    "Este documento está escrito en un lenguaje diferente al inglés. Su objectivo es demostrar cómo"
    + " invocar el método de Detección de Lenguaje del servicio de Text Analytics en Microsoft Azure."
    + " También muestra cómo acceder a la información retornada por el servicio. Esta funcionalidad es"
    + " útil para los sistemas de contenido que recopilan texto arbitrario, donde el lenguaje no se conoce"
    + " de antemano. Puede usarse para detectar una amplia gama de lenguajes, variantes, dialectos y"
    + " algunos idiomas regionales o culturales.";

try
{
    Response<DetectedLanguage> response = await client.DetectLanguageAsync(document);
    DetectedLanguage language = response.Value;

    Console.WriteLine($"Detected language is {language.Name} with a confidence score of {language.ConfidenceScore}.");
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Reconhecer entidades nomeadas de forma assíncrona

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

string document =
    "We love this trail and make the trip every year. The views are breathtaking and well worth the hike!"
    + " Yesterday was foggy though, so we missed the spectacular views. We tried again today and it was"
    + " amazing. Everyone in my family liked the trail although it was too challenging for the less"
    + " athletic among us. Not necessarily recommended for small children. A hotel close to the trail"
    + " offers services for childcare in case you want that.";

try
{
    Response<CategorizedEntityCollection> response = await client.RecognizeEntitiesAsync(document);
    CategorizedEntityCollection entitiesInDocument = response.Value;

    Console.WriteLine($"Recognized {entitiesInDocument.Count} entities:");
    foreach (CategorizedEntity entity in entitiesInDocument)
    {
        Console.WriteLine($"  Text: {entity.Text}");
        Console.WriteLine($"  Offset: {entity.Offset}");
        Console.WriteLine($"  Length: {entity.Length}");
        Console.WriteLine($"  Category: {entity.Category}");
        if (!string.IsNullOrEmpty(entity.SubCategory))
            Console.WriteLine($"  SubCategory: {entity.SubCategory}");
        Console.WriteLine($"  Confidence score: {entity.ConfidenceScore}");
        Console.WriteLine();
    }
}
catch (RequestFailedException exception)
{
    Console.WriteLine($"Error Code: {exception.ErrorCode}");
    Console.WriteLine($"Message: {exception.Message}");
}

Analisar entidades de saúde de forma assíncrona

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. Para obter mais informações, consulte Como usar Análise de Texto para integridade.

string documentA =
    "RECORD #333582770390100 | MH | 85986313 | | 054351 | 2/14/2001 12:00:00 AM |"
    + " CORONARY ARTERY DISEASE | Signed | DIS |"
    + Environment.NewLine
    + " Admission Date: 5/22/2001 Report Status: Signed Discharge Date: 4/24/2001"
    + " ADMISSION DIAGNOSIS: CORONARY ARTERY DISEASE."
    + Environment.NewLine
    + " HISTORY OF PRESENT ILLNESS: The patient is a 54-year-old gentleman with a history of progressive"
    + " angina over the past several months. The patient had a cardiac catheterization in July of this"
    + " year revealing total occlusion of the RCA and 50% left main disease, with a strong family history"
    + " of coronary artery disease with a brother dying at the age of 52 from a myocardial infarction and"
    + " another brother who is status post coronary artery bypass grafting. The patient had a stress"
    + " echocardiogram done on July, 2001, which showed no wall motion abnormalities, but this was a"
    + " difficult study due to body habitus. The patient went for six minutes with minimal ST depressions"
    + " in the anterior lateral leads, thought due to fatigue and wrist pain, his anginal equivalent. Due"
    + " to the patient'sincreased symptoms and family history and history left main disease with total"
    + " occasional of his RCA was referred for revascularization with open heart surgery.";

string documentB = "Prescribed 100mg ibuprofen, taken twice daily.";

// Prepare the input of the text analysis operation. You can add multiple documents to this list and
// perform the same operation on all of them simultaneously.
List<string> batchedDocuments = new()
{
    documentA,
    documentB
};

// Perform the text analysis operation.
AnalyzeHealthcareEntitiesOperation operation = await client.AnalyzeHealthcareEntitiesAsync(WaitUntil.Completed, batchedDocuments);

Console.WriteLine($"The operation has completed.");
Console.WriteLine();

// View the operation status.
Console.WriteLine($"Created On   : {operation.CreatedOn}");
Console.WriteLine($"Expires On   : {operation.ExpiresOn}");
Console.WriteLine($"Id           : {operation.Id}");
Console.WriteLine($"Status       : {operation.Status}");
Console.WriteLine($"Last Modified: {operation.LastModified}");
Console.WriteLine();

// View the operation results.
await foreach (AnalyzeHealthcareEntitiesResultCollection documentsInPage in operation.Value)
{
    Console.WriteLine($"Analyze Healthcare Entities, model version: \"{documentsInPage.ModelVersion}\"");
    Console.WriteLine();

    foreach (AnalyzeHealthcareEntitiesResult documentResult in documentsInPage)
    {
        if (documentResult.HasError)
        {
            Console.WriteLine($"  Error!");
            Console.WriteLine($"  Document error code: {documentResult.Error.ErrorCode}");
            Console.WriteLine($"  Message: {documentResult.Error.Message}");
            continue;
        }

        Console.WriteLine($"  Recognized the following {documentResult.Entities.Count} healthcare entities:");
        Console.WriteLine();

        // View the healthcare entities that were recognized.
        foreach (HealthcareEntity entity in documentResult.Entities)
        {
            Console.WriteLine($"  Entity: {entity.Text}");
            Console.WriteLine($"  Category: {entity.Category}");
            Console.WriteLine($"  Offset: {entity.Offset}");
            Console.WriteLine($"  Length: {entity.Length}");
            Console.WriteLine($"  NormalizedText: {entity.NormalizedText}");
            Console.WriteLine($"  Links:");

            // View the entity data sources.
            foreach (EntityDataSource entityDataSource in entity.DataSources)
            {
                Console.WriteLine($"    Entity ID in Data Source: {entityDataSource.EntityId}");
                Console.WriteLine($"    DataSource: {entityDataSource.Name}");
            }

            // View the entity assertions.
            if (entity.Assertion is not null)
            {
                Console.WriteLine($"  Assertions:");

                if (entity.Assertion?.Association is not null)
                {
                    Console.WriteLine($"    Association: {entity.Assertion?.Association}");
                }

                if (entity.Assertion?.Certainty is not null)
                {
                    Console.WriteLine($"    Certainty: {entity.Assertion?.Certainty}");
                }

                if (entity.Assertion?.Conditionality is not null)
                {
                    Console.WriteLine($"    Conditionality: {entity.Assertion?.Conditionality}");
                }
            }
        }

        Console.WriteLine($"  We found {documentResult.EntityRelations.Count} relations in the current document:");
        Console.WriteLine();

        // View the healthcare entity relations that were recognized.
        foreach (HealthcareEntityRelation relation in documentResult.EntityRelations)
        {
            Console.WriteLine($"    Relation: {relation.RelationType}");
            if (relation.ConfidenceScore is not null)
            {
                Console.WriteLine($"    ConfidenceScore: {relation.ConfidenceScore}");
            }
            Console.WriteLine($"    For this relation there are {relation.Roles.Count} roles");

            // View the relation roles.
            foreach (HealthcareEntityRelationRole role in relation.Roles)
            {
                Console.WriteLine($"      Role Name: {role.Name}");

                Console.WriteLine($"      Associated Entity Text: {role.Entity.Text}");
                Console.WriteLine($"      Associated Entity Category: {role.Entity.Category}");
                Console.WriteLine();
            }

            Console.WriteLine();
        }

        Console.WriteLine();
    }
}

Executar várias ações de forma assíncrona

Essa funcionalidade permite executar várias ações em um ou mais documentos. Ações incluem:

  • Reconhecimento de Entidades Nomeadas
  • Reconhecimento de entidades PII
  • Reconhecimento de Entidade Vinculada
  • Extração de Frases-Chave
  • Análise de Sentimento
  • Reconhecimento de Entidades de Saúde (veja o exemplo aqui)
  • Reconhecimento de Entidades Nomeadas Personalizadas (veja o exemplo aqui)
  • Classificação de rótulo único personalizado (veja o exemplo aqui)
  • Classificação de vários rótulos personalizados (veja o exemplo aqui)
    string documentA =
        "We love this trail and make the trip every year. The views are breathtaking and well worth the hike!"
        + " Yesterday was foggy though, so we missed the spectacular views. We tried again today and it was"
        + " amazing. Everyone in my family liked the trail although it was too challenging for the less"
        + " athletic among us.";

    string documentB =
        "Last week we stayed at Hotel Foo to celebrate our anniversary. The staff knew about our anniversary"
        + " so they helped me organize a little surprise for my partner. The room was clean and with the"
        + " decoration I requested. It was perfect!";

    // Prepare the input of the text analysis operation. You can add multiple documents to this list and
    // perform the same operation on all of them simultaneously.
    List<string> batchedDocuments = new()
    {
        documentA,
        documentB
    };

    TextAnalyticsActions actions = new()
    {
        ExtractKeyPhrasesActions = new List<ExtractKeyPhrasesAction>() { new ExtractKeyPhrasesAction() { ActionName = "ExtractKeyPhrasesSample" } },
        RecognizeEntitiesActions = new List<RecognizeEntitiesAction>() { new RecognizeEntitiesAction() { ActionName = "RecognizeEntitiesSample" } },
        DisplayName = "AnalyzeOperationSample"
    };

    // Perform the text analysis operation.
    AnalyzeActionsOperation operation = await client.AnalyzeActionsAsync(WaitUntil.Completed, batchedDocuments, actions);

    // View the operation status.
    Console.WriteLine($"Created On   : {operation.CreatedOn}");
    Console.WriteLine($"Expires On   : {operation.ExpiresOn}");
    Console.WriteLine($"Id           : {operation.Id}");
    Console.WriteLine($"Status       : {operation.Status}");
    Console.WriteLine($"Last Modified: {operation.LastModified}");
    Console.WriteLine();

    if (!string.IsNullOrEmpty(operation.DisplayName))
    {
        Console.WriteLine($"Display name: {operation.DisplayName}");
        Console.WriteLine();
    }

    Console.WriteLine($"Total actions: {operation.ActionsTotal}");
    Console.WriteLine($"  Succeeded actions: {operation.ActionsSucceeded}");
    Console.WriteLine($"  Failed actions: {operation.ActionsFailed}");
    Console.WriteLine($"  In progress actions: {operation.ActionsInProgress}");
    Console.WriteLine();

    await foreach (AnalyzeActionsResult documentsInPage in operation.Value)
    {
        IReadOnlyCollection<ExtractKeyPhrasesActionResult> keyPhrasesResults = documentsInPage.ExtractKeyPhrasesResults;
        IReadOnlyCollection<RecognizeEntitiesActionResult> entitiesResults = documentsInPage.RecognizeEntitiesResults;

        Console.WriteLine("Recognized Entities");
        int docNumber = 1;
        foreach (RecognizeEntitiesActionResult entitiesActionResults in entitiesResults)
        {
            Console.WriteLine($" Action name: {entitiesActionResults.ActionName}");
            Console.WriteLine();
            foreach (RecognizeEntitiesResult documentResult in entitiesActionResults.DocumentsResults)
            {
                Console.WriteLine($" Document #{docNumber++}");
                Console.WriteLine($"  Recognized {documentResult.Entities.Count} entities:");

                foreach (CategorizedEntity entity in documentResult.Entities)
                {
                    Console.WriteLine();
                    Console.WriteLine($"    Entity: {entity.Text}");
                    Console.WriteLine($"    Category: {entity.Category}");
                    Console.WriteLine($"    Offset: {entity.Offset}");
                    Console.WriteLine($"    Length: {entity.Length}");
                    Console.WriteLine($"    ConfidenceScore: {entity.ConfidenceScore}");
                    Console.WriteLine($"    SubCategory: {entity.SubCategory}");
                }
                Console.WriteLine();
            }
        }

        Console.WriteLine("Extracted Key Phrases");
        docNumber = 1;
        foreach (ExtractKeyPhrasesActionResult keyPhrasesActionResult in keyPhrasesResults)
        {
            Console.WriteLine($" Action name: {keyPhrasesActionResult.ActionName}");
            Console.WriteLine();
            foreach (ExtractKeyPhrasesResult documentResults in keyPhrasesActionResult.DocumentsResults)
            {
                Console.WriteLine($" Document #{docNumber++}");
                Console.WriteLine($"  Recognized the following {documentResults.KeyPhrases.Count} Keyphrases:");

                foreach (string keyphrase in documentResults.KeyPhrases)
                {
                    Console.WriteLine($"    {keyphrase}");
                }
                Console.WriteLine();
            }
        }
    }
}

Solução de problemas

Geral

Quando você interage com os Serviços Cognitivos para Linguagem usando o SDK do .NET Análise de Texto, os erros retornados pelo serviço de Linguagem correspondem aos mesmos códigos de status HTTP retornados para solicitações da API REST.

Por exemplo, se você enviar um lote de entradas de documento de texto contendo IDs de documento duplicadas, um 400 erro será retornado, indicando "Solicitação Incorreta".

try
{
    DetectedLanguage result = client.DetectLanguage(document);
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

Você observará que informações adicionais são registradas, como a ID de solicitação do cliente da operação.

Message:
    Azure.RequestFailedException:
    Status: 400 (Bad Request)

Content:
    {"error":{"code":"InvalidRequest","innerError":{"code":"InvalidDocument","message":"Request contains duplicated Ids. Make sure each document has a unique Id."},"message":"Invalid document in request."}}

Headers:
    Transfer-Encoding: chunked
    x-aml-ta-request-id: 146ca04a-af54-43d4-9872-01a004bee5f8
    X-Content-Type-Options: nosniff
    x-envoy-upstream-service-time: 6
    apim-request-id: c650acda-2b59-4ff7-b96a-e316442ea01b
    Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
    Date: Wed, 18 Dec 2019 16:24:52 GMT
    Content-Type: application/json; charset=utf-8

Configuração do registro em log do console

A maneira mais simples de ver os logs é habilitar o log do console. Para criar um ouvinte de log do SDK do Azure que gera mensagens para o console, use o método AzureEventSourceListener.CreateConsoleLogger.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Para saber mais sobre outros mecanismos de registro em log, confira aqui.

Próximas etapas

Exemplos que mostram como usar essa biblioteca de clientes estão disponíveis neste repositório GitHub. Exemplos são fornecidos para cada main área funcional e, para cada área, são fornecidos exemplos para analisar um único documento e uma coleção de documentos no modo sincronizado e assíncrono.

Exemplos avançados

Participante

Consulte a CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

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. Para obter detalhes, visite cla.microsoft.com.

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.

Impressões