Biblioteca de clientes de Conversas dos Serviços de Linguagem Cognitiva do Azure para .NET – versão 1.1.0

  • Artigo

O Reconhecimento vocal de conversação - também conhecido como CLU para abreviar - é um serviço de IA de conversação baseado em nuvem que fornece muitos recursos de compreensão da linguagem, como:

  • Aplicativo de conversa: ele é usado na extração de intenções e entidades em conversas
  • Aplicativo de fluxo de trabalho: atua como um orquestrador para selecionar o melhor candidato para analisar conversas para obter a melhor resposta de aplicativos como Qna, Luis e Aplicativo de Conversa

Código-fonte | Pacote (NuGet) | Documentação | de referência da APIAmostras | Documentação do produto | Documentação | da API REST de análiseDocumentação da API REST de criação

Introdução

Instalar o pacote

Instale a biblioteca de clientes conversas dos Serviços de Linguagem Cognitiva do Azure para .NET com o NuGet:

dotnet add package Azure.AI.Language.Conversations

Pré-requisitos

Embora você possa usar esse SDK para criar e importar projetos de conversa, o Language Studio é o método preferido para criar projetos.

Autenticar o cliente

Para interagir com o serviço Conversas, você precisará criar uma instância da ConversationAnalysisClient classe . Você precisará de um ponto de extremidade e uma chave de API para instanciar um objeto cliente. Para obter mais informações sobre como autenticar com os Serviços Cognitivos, consulte Autenticar solicitações nos Serviços Cognitivos do Azure.

Obter uma chave de API

Você pode obter o ponto de extremidade e uma chave de API do recurso dos Serviços Cognitivos no Portal do Azure.

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

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

Namespaces

Comece importando o namespace para a ConversationAnalysisClient classe relacionada e :

using Azure.Core;
using Azure.AI.Language.Conversations;

Criar um ConversationAnalysisClient

Depois de determinar o ponto de extremidade e a chave de API , você poderá instanciar um ConversationAnalysisClient:

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");

ConversationAnalysisClient client = new ConversationAnalysisClient(endpoint, credential);

Criar um ConversationAuthoringClient

Para usar o ConversationAuthoringClient, use o namespace a seguir, além daqueles acima, se necessário.

using Azure.AI.Language.Conversations.Authoring;

Com o ponto de extremidade e a chave de API, você pode instanciar um ConversationAuthoringClient:

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
AzureKeyCredential credential = new AzureKeyCredential("{api-key}");

ConversationAuthoringClient client = new ConversationAuthoringClient(endpoint, credential);

Criar um cliente usando a autenticação do Azure Active Directory

Você também pode criar um ConversationAnalysisClient ou ConversationAuthoringClient usando a autenticação do AAD (Azure Active Directory). Seu usuário ou entidade de serviço deve receber a função "Leitor de Linguagem dos Serviços Cognitivos". Usando o DefaultAzureCredential , você pode autenticar um serviço usando a Identidade Gerenciada ou uma entidade de serviço, autenticar-se como um desenvolvedor trabalhando em um aplicativo e muito mais sem alterar o código.

Antes de poder usar o DefaultAzureCredentialou qualquer tipo de credencial do Azure.Identity, primeiro você precisará instalar o pacote Azure.Identity.

Para usar DefaultAzureCredential com uma ID do cliente e um segredo, você precisará definir as AZURE_TENANT_IDvariáveis de ambiente , AZURE_CLIENT_IDe AZURE_CLIENT_SECRET , como alternativa, você pode passar esses valores para o ClientSecretCredential também em Azure.Identity.

Use o namespace certo para DefaultAzureCredential na parte superior do arquivo de origem:

using Azure.Identity;

Em seguida, você pode criar uma instância de DefaultAzureCredential e passá-la para uma nova instância do seu cliente:

Uri endpoint = new Uri("https://myaccount.cognitiveservices.azure.com");
DefaultAzureCredential credential = new DefaultAzureCredential();

ConversationAnalysisClient client = new ConversationAnalysisClient(endpoint, credential);

Observe que os pontos de extremidade regionais não dão suporte à autenticação do AAD. Em vez disso, crie um nome de domínio personalizado para seu recurso usar a autenticação do AAD.

Principais conceitos

ConversationAnalysisClient

O ConversationAnalysisClient é a interface principal para fazer previsões usando seus modelos de Conversas implantados. Ele fornece APIs síncronas e assíncronas para enviar consultas.

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 | Operações de execução prolongada | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

A biblioteca de clientes Azure.AI.Language.Conversations fornece APIs síncronas e assíncronas.

Os exemplos a seguir mostram cenários comuns usando o clientcriado acima.

Analisar uma conversa

Para analisar uma conversa, você pode chamar o AnalyzeConversation() método :

string projectName = "Menu";
string deploymentName = "production";

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = "Send an email to Carol about tomorrow's demo",
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,

        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};

Response response = client.AnalyzeConversation(RequestContent.Create(data));

using JsonDocument result = JsonDocument.Parse(response.ContentStream);
JsonElement conversationalTaskResult = result.RootElement;
JsonElement conversationPrediction = conversationalTaskResult.GetProperty("result").GetProperty("prediction");

Console.WriteLine($"Top intent: {conversationPrediction.GetProperty("topIntent").GetString()}");

Console.WriteLine("Intents:");
foreach (JsonElement intent in conversationPrediction.GetProperty("intents").EnumerateArray())
{
    Console.WriteLine($"Category: {intent.GetProperty("category").GetString()}");
    Console.WriteLine($"Confidence: {intent.GetProperty("confidenceScore").GetSingle()}");
    Console.WriteLine();
}

Console.WriteLine("Entities:");
foreach (JsonElement entity in conversationPrediction.GetProperty("entities").EnumerateArray())
{
    Console.WriteLine($"Category: {entity.GetProperty("category").GetString()}");
    Console.WriteLine($"Text: {entity.GetProperty("text").GetString()}");
    Console.WriteLine($"Offset: {entity.GetProperty("offset").GetInt32()}");
    Console.WriteLine($"Length: {entity.GetProperty("length").GetInt32()}");
    Console.WriteLine($"Confidence: {entity.GetProperty("confidenceScore").GetSingle()}");
    Console.WriteLine();

    if (entity.TryGetProperty("resolutions", out JsonElement resolutions))
    {
        foreach (JsonElement resolution in resolutions.EnumerateArray())
        {
            if (resolution.GetProperty("resolutionKind").GetString() == "DateTimeResolution")
            {
                Console.WriteLine($"Datetime Sub Kind: {resolution.GetProperty("dateTimeSubKind").GetString()}");
                Console.WriteLine($"Timex: {resolution.GetProperty("timex").GetString()}");
                Console.WriteLine($"Value: {resolution.GetProperty("value").GetString()}");
                Console.WriteLine();
            }
        }
    }
}

Opções adicionais podem ser passadas para AnalyzeConversation como habilitar uma saída mais detalhada:

string projectName = "Menu";
string deploymentName = "production";

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = "Send an email to Carol about tomorrow's demo",
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,
        verbose = true,

        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};

Response response = client.AnalyzeConversation(RequestContent.Create(data));

Analisar uma conversa em um idioma diferente

A language propriedade pode ser definida para especificar o idioma da conversa:

string projectName = "Menu";
string deploymentName = "production";

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = "Enviar un email a Carol acerca de la presentación de mañana",
            language = "es",
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,
        verbose = true,

        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};

Response response = client.AnalyzeConversation(RequestContent.Create(data));

Analisar uma conversa usando um projeto de orquestração

Para analisar uma conversa usando um projeto de orquestração, você pode chamar o AnalyzeConversation() método assim como o projeto de conversa.

string projectName = "DomainOrchestrator";
string deploymentName = "production";

var data = new
{
    analysisInput = new
    {
        conversationItem = new
        {
            text = "How are you?",
            id = "1",
            participantId = "1",
        }
    },
    parameters = new
    {
        projectName,
        deploymentName,

        // Use Utf16CodeUnit for strings in .NET.
        stringIndexType = "Utf16CodeUnit",
    },
    kind = "Conversation",
};

Response response = client.AnalyzeConversation(RequestContent.Create(data));

using JsonDocument result = JsonDocument.Parse(response.ContentStream);
JsonElement conversationalTaskResult = result.RootElement;
JsonElement orchestrationPrediction = conversationalTaskResult.GetProperty("result").GetProperty("prediction");

Previsão de respostas a perguntas

Se sua conversa foi analisada pelas Respostas às Perguntas, ela incluirá uma intenção - talvez até mesmo a principal intenção - da qual você pode recuperar respostas:

string respondingProjectName = orchestrationPrediction.GetProperty("topIntent").GetString();
JsonElement targetIntentResult = orchestrationPrediction.GetProperty("intents").GetProperty(respondingProjectName);

if (targetIntentResult.GetProperty("targetProjectKind").GetString() == "QuestionAnswering")
{
    Console.WriteLine($"Top intent: {respondingProjectName}");

    JsonElement questionAnsweringResponse = targetIntentResult.GetProperty("result");
    Console.WriteLine($"Question Answering Response:");
    foreach (JsonElement answer in questionAnsweringResponse.GetProperty("answers").EnumerateArray())
    {
        Console.WriteLine(answer.GetProperty("answer").GetString());
    }
}

Resumo de conversa

Para resumir uma conversa, você pode usar a sobrecarga de AnalyzeConversation método que retorna um Operation<BinaryData>:

var data = new
{
    analysisInput = new
    {
        conversations = new[]
        {
            new
            {
                conversationItems = new[]
                {
                    new
                    {
                        text = "Hello, how can I help you?",
                        id = "1",
                        role = "Agent",
                        participantId = "Agent_1",
                    },
                    new
                    {
                        text = "How to upgrade Office? I am getting error messages the whole day.",
                        id = "2",
                        role = "Customer",
                        participantId = "Customer_1",
                    },
                    new
                    {
                        text = "Press the upgrade button please. Then sign in and follow the instructions.",
                        id = "3",
                        role = "Agent",
                        participantId = "Agent_1",
                    },
                },
                id = "1",
                language = "en",
                modality = "text",
            },
        }
    },
    tasks = new[]
    {
        new
        {
            taskName = "Issue task",
            kind = "ConversationalSummarizationTask",
            parameters = new
            {
                summaryAspects = new[]
                {
                    "issue",
                }
            },
        },
        new
        {
            taskName = "Resolution task",
            kind = "ConversationalSummarizationTask",
            parameters = new
            {
                summaryAspects = new[]
                {
                    "resolution",
                }
            },
        },
    },
};

Operation<BinaryData> analyzeConversationOperation = client.AnalyzeConversations(WaitUntil.Completed, RequestContent.Create(data));

using JsonDocument result = JsonDocument.Parse(analyzeConversationOperation.Value.ToStream());
JsonElement jobResults = result.RootElement;
foreach (JsonElement task in jobResults.GetProperty("tasks").GetProperty("items").EnumerateArray())
{
    Console.WriteLine($"Task name: {task.GetProperty("taskName").GetString()}");
    JsonElement results = task.GetProperty("results");
    foreach (JsonElement conversation in results.GetProperty("conversations").EnumerateArray())
    {
        Console.WriteLine($"Conversation: #{conversation.GetProperty("id").GetString()}");
        Console.WriteLine("Summaries:");
        foreach (JsonElement summary in conversation.GetProperty("summaries").EnumerateArray())
        {
            Console.WriteLine($"Text: {summary.GetProperty("text").GetString()}");
            Console.WriteLine($"Aspect: {summary.GetProperty("aspect").GetString()}");
        }
        Console.WriteLine();
    }
}

Outros exemplos

Navegador nossos exemplos para obter mais exemplos de como analisar conversas.

Solução de problemas

Geral

Quando você interage com a biblioteca de clientes de Conversas dos Serviços de Linguagem Cognitiva usando o SDK do .NET, os erros retornados pelo serviço correspondem aos mesmos códigos http status retornados para solicitações de API REST.

Por exemplo, se você enviar um enunciado para um projeto não existente, um 400 erro será retornado indicando "Solicitação Incorreta".

try
{
    var data = new
    {
        analysisInput = new
        {
            conversationItem = new
            {
                text = "Send an email to Carol about tomorrow's demo",
                id = "1",
                participantId = "1",
            }
        },
        parameters = new
        {
            projectName = "invalid-project",
            deploymentName = "production",

            // Use Utf16CodeUnit for strings in .NET.
            stringIndexType = "Utf16CodeUnit",
        },
        kind = "Conversation",
    };

    Response response = client.AnalyzeConversation(RequestContent.Create(data));
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

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

Azure.RequestFailedException: The input parameter is invalid.
Status: 400 (Bad Request)
ErrorCode: InvalidArgument

Content:
{
  "error": {
    "code": "InvalidArgument",
    "message": "The input parameter is invalid.",
    "innerError": {
      "code": "InvalidArgument",
      "message": "The input parameter \"payload\" cannot be null or empty."
    }
  }
}

Headers:
Transfer-Encoding: chunked
pragma: no-cache
request-id: 0303b4d0-0954-459f-8a3d-1be6819745b5
apim-request-id: 0303b4d0-0954-459f-8a3d-1be6819745b5
x-envoy-upstream-service-time: 15
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
x-content-type-options: nosniff
Cache-Control: no-store, proxy-revalidate, no-cache, max-age=0, private
Content-Type: application/json

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 AzureEventSourceListener.CreateConsoleLogger método .

// 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

Participante

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