Biblioteca de clientes de Respostas às Perguntas dos Serviços de Linguagem Cognitiva do Azure para .NET – versão 1.1.0
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
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
- Uma assinatura do Azure
- Um recurso de Resposta a Perguntas existente
Embora você possa usar esse SDK para criar e importar projetos de conversa, o Language Studio é o método preferido para criar projetos.
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.
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>
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);
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);
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 DefaultAzureCredential
ou 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_ID
variáveis de ambiente , AZURE_CLIENT_ID
e 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.
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.
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.
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.
Opções | do cliente Acessando a resposta | Operações de execução prolongada | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente
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 client
criado acima.
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.
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();
}
Os exemplos a seguir mostram cenários comuns usando a QuestionAnsweringAuthoringClient
instância criada nesta seção.
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);
}
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);
}
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);
}
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
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.
- Exiba nossos exemplos.
- Leia sobre os diferentes recursos do serviço de Respostas a Perguntas.
- Experimente nossas demonstrações de serviço.
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.
Comentários do Azure SDK for .NET
O Azure SDK for .NET é um projeto código aberto. Selecione um link para fornecer comentários: