Biblioteca de clientes de Respostas às Perguntas dos Serviços de Linguagem Cognitiva do Azure para .NET – versão 1.1.0

  • Artigo

O serviço de Respostas a Perguntas é um serviço de API baseado em nuvem que permite criar uma camada de perguntas e respostas conversacionais sobre os dados existentes. Use-o para criar uma base de dados de conhecimento extraindo perguntas e respostas de seu conteúdo semiestruturado, incluindo perguntas frequentes, manuais e documentos. Responda às perguntas dos usuários com as melhores respostas dos QnAs em seu base de dados de conhecimento automaticamente. Sua base de dados de conhecimento também fica mais inteligente, pois aprende continuamente com o comportamento do usuário.

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

Introdução

Instalar o pacote

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

dotnet add package Azure.AI.Language.QuestionAnswering

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 de Respostas a Perguntas, você precisará criar uma instância da QuestionAnsweringClient classe para consultar projetos existentes ou uma instância do QuestionAnsweringAuthoringClient para gerenciar projetos em seu recurso. 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 ou do recurso de Resposta a Perguntas no Portal do Azure.

Como alternativa, use o comando da CLI do Azure mostrado abaixo para obter a chave de API do recurso Respostas às Perguntas.

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

Criar um QuestionAnsweringClient

Para usar o QuestionAnsweringClient, use os namespaces corretos:

using Azure.Core;
using Azure.AI.Language.QuestionAnswering;

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

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

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

Criar um QuestionAnsweringAuthoringClient

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

using Azure.AI.Language.QuestionAnswering.Authoring;

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

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

QuestionAnsweringAuthoringClient client = new QuestionAnsweringAuthoringClient(endpoint, credential);

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

Você também pode criar um QuestionAnsweringClient ou QuestionAnsweringAuthoringClient 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();

QuestionAnsweringClient client = new QuestionAnsweringClient(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

QuestionAnsweringClient

A QuestionAnsweringClient é a interface principal para fazer perguntas usando um base de dados de conhecimento com suas próprias informações ou entrada de texto usando modelos pré-treinados. Ele fornece APIs síncronas e assíncronas para fazer perguntas.

QuestionAnsweringAuthoringClient

O QuestionAnsweringAuthoringClient fornece uma interface para gerenciar projetos de Resposta a Perguntas. Exemplos das operações disponíveis incluem criar e implantar projetos, atualizar suas fontes de conhecimento e atualizar pares de perguntas e respostas. Ele fornece APIs síncronas e assíncronas.

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

Exemplos

QuestionAnsweringClient

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

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

Faça uma pergunta

A única entrada necessária para fazer uma pergunta usando um base de dados de conhecimento existente é apenas a própria pergunta:

string projectName = "{ProjectName}";
string deploymentName = "{DeploymentName}";
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);
Response<AnswersResult> response = client.GetAnswers("How long should my Surface battery last?", project);

foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
{
    Console.WriteLine($"({answer.Confidence:P2}) {answer.Answer}");
    Console.WriteLine($"Source: {answer.Source}");
    Console.WriteLine();
}

Você pode definir propriedades adicionais em QuestionAnsweringClientOptions para limitar o número de respostas, especificar uma pontuação de confiança mínima e muito mais.

Fazer uma pergunta de acompanhamento

Se o base de dados de conhecimento estiver configurado para bate-papo, você poderá fazer uma pergunta de acompanhamento desde a ID anterior de resposta às perguntas e, opcionalmente, a pergunta exata feita pelo usuário:

string projectName = "{ProjectName}";
string deploymentName = "{DeploymentName}";
// Answers are ordered by their ConfidenceScore so assume the user choose the first answer below:
KnowledgeBaseAnswer previousAnswer = answers.Answers.First();
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);
AnswersOptions options = new AnswersOptions
{
    AnswerContext = new KnowledgeBaseAnswerContext(previousAnswer.QnaId.Value)
};

Response<AnswersResult> response = client.GetAnswers("How long should charging take?", project, options);

foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
{
    Console.WriteLine($"({answer.Confidence:P2}) {answer.Answer}");
    Console.WriteLine($"Source: {answer.Source}");
    Console.WriteLine();
}

QuestionAnsweringAuthoringClient

Os exemplos a seguir mostram cenários comuns usando a QuestionAnsweringAuthoringClient instância criada nesta seção.

Criar um novo projeto

Para criar um novo projeto, você deve especificar o nome do projeto e criar uma RequestContent instância com os parâmetros necessários para configurar o projeto.

// Set project name and request content parameters
string newProjectName = "{ProjectName}";
RequestContent creationRequestContent = RequestContent.Create(
    new {
        description = "This is the description for a test project",
        language = "en",
        multilingualResource = false,
        settings = new {
            defaultAnswer = "No answer found for your question."
            }
        }
    );

Response creationResponse = client.CreateProject(newProjectName, creationRequestContent);

// Projects can be retrieved as follows
Pageable<BinaryData> projects = client.GetProjects();

Console.WriteLine("Projects: ");
foreach (BinaryData project in projects)
{
    Console.WriteLine(project);
}

Implantar o projeto

Seus projetos podem ser implantados usando o DeployProjectAsync ou o síncrono DeployProject. Tudo o que você precisa especificar é o nome do projeto e o nome da implantação que você deseja usar. Observe que o serviço não permitirá que você implante projetos vazios.

// Set deployment name and start operation
string newDeploymentName = "{DeploymentName}";

Operation<BinaryData> deploymentOperation = client.DeployProject(WaitUntil.Completed, newProjectName, newDeploymentName);

// Deployments can be retrieved as follows
Pageable<BinaryData> deployments = client.GetDeployments(newProjectName);
Console.WriteLine("Deployments: ");
foreach (BinaryData deployment in deployments)
{
    Console.WriteLine(deployment);
}

Adicionar uma fonte de conhecimento

Uma maneira de adicionar conteúdo ao seu projeto é adicionar uma fonte de conhecimento. O exemplo a seguir mostra como você pode configurar uma RequestContent instância para adicionar uma nova fonte de conhecimento do tipo "url".

// Set request content parameters for updating our new project's sources
string sourceUri = "{KnowledgeSourceUri}";
RequestContent updateSourcesRequestContent = RequestContent.Create(
    new[] {
        new {
                op = "add",
                value = new
                {
                    displayName = "MicrosoftFAQ",
                    source = sourceUri,
                    sourceUri = sourceUri,
                    sourceKind = "url",
                    contentStructureKind = "unstructured",
                    refresh = false
                }
            }
    });

Operation<Pageable<BinaryData>> updateSourcesOperation = client.UpdateSources(WaitUntil.Completed, newProjectName, updateSourcesRequestContent);

// Knowledge Sources can be retrieved as follows
Pageable<BinaryData> sources = updateSourcesOperation.Value;

Console.WriteLine("Sources: ");
foreach (BinaryData source in sources)
{
    Console.WriteLine(source);
}

Solução de problemas

Geral

Quando você interage com a biblioteca de clientes de Resposta a Perguntas 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 uma pergunta a um base de dados de conhecimento não existente, um 400 erro será retornado indicando "Solicitação Incorreta".

try
{
    QuestionAnsweringProject project = new QuestionAnsweringProject("invalid-knowledgebase", "test");
    Response<AnswersResult> response = client.GetAnswers("Does this knowledge base exist?", project);
}
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: Please verify azure search service is up, restart the WebApp and try again
Status: 400 (Bad Request)
ErrorCode: BadArgument

Content:
{
    "error": {
    "code": "BadArgument",
    "message": "Please verify azure search service is up, restart the WebApp and try again"
    }
}

Headers:
x-envoy-upstream-service-time: 23
apim-request-id: 76a83876-22d1-4977-a0b1-559a674f3605
Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
X-Content-Type-Options: nosniff
Date: Wed, 30 Jun 2021 00:32:07 GMT
Content-Length: 139
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 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.

Impressões