Azure.AI.Language.QuestionAnswering 1.0.0

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package Azure.AI.Language.QuestionAnswering --version 1.0.0
NuGet\Install-Package Azure.AI.Language.QuestionAnswering -Version 1.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Azure.AI.Language.QuestionAnswering" Version="1.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Azure.AI.Language.QuestionAnswering --version 1.0.0
#r "nuget: Azure.AI.Language.QuestionAnswering, 1.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Azure.AI.Language.QuestionAnswering as a Cake Addin
#addin nuget:?package=Azure.AI.Language.QuestionAnswering&version=1.0.0

// Install Azure.AI.Language.QuestionAnswering as a Cake Tool
#tool nuget:?package=Azure.AI.Language.QuestionAnswering&version=1.0.0

Azure Cognitive Language Services Question Answering client library for .NET

The Question Answering service is a cloud-based API service that lets you create a conversational question-and-answer layer over your existing data. Use it to build a knowledge base by extracting questions and answers from your semi-structured content, including FAQ, manuals, and documents. Answer users’ questions with the best answers from the QnAs in your knowledge base—automatically. Your knowledge base gets smarter, too, as it continually learns from user behavior.

Source code | Package (NuGet) | API reference documentation | Product documentation | Samples | Migration guide

Getting started

Install the package

Install the Azure Cognitive Language Services Question Answering client library for .NET with NuGet:

dotnet add package Azure.AI.Language.QuestionAnswering --prerelease

Prerequisites

Note: the new unified Cognitive Language Services are not currently available for deployment.

Authenticate the client

In order to interact with the Question Answering service, you'll need to create an instance of the QuestionAnsweringClient class. You will need an endpoint, and an API key to instantiate a client object. For more information regarding authenticating with Cognitive Services, see Authenticate requests to Azure Cognitive Services.

Get an API key

You can get the endpoint and an API key from the Cognitive Services resource or Question Answering resource in the Azure Portal.

Alternatively, use the Azure CLI command shown below to get the API key from the Question Answering resource.

az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>
Create a QuestionAnsweringClient

Once you've determined your endpoint and API key you can instantiate a QuestionAnsweringClient:

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

QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential);

Key concepts

QuestionAnsweringClient

The QuestionAnsweringClient is the primary interface for asking questions using a knowledge base with your own information, or text input using pre-trained models. It provides both synchronous and asynchronous APIs to ask questions.

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

The Azure.AI.Language.QuestionAnswering client library provides both synchronous and asynchronous APIs.

The following examples show common scenarios using the client created above.

Ask a question

The only input required to a ask a question using an existing knowledge base is just the question itself:

string projectName = "FAQ";
string deploymentName = "prod";
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();
}

You can set additional properties on QuestionAnsweringClientOptions to limit the number of answers, specify a minimum confidence score, and more.

Ask a follow-up question

If your knowledge base is configured for chit-chat, you can ask a follow-up question provided the previous question-answering ID and, optionally, the exact question the user asked:

string projectName = "FAQ";
string deploymentName = "prod";
// 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();
}

Troubleshooting

General

When you interact with the Cognitive Language Services Question Answering client library using the .NET SDK, errors returned by the service correspond to the same HTTP status codes returned for REST API requests.

For example, if you submit a question to a non-existant knowledge base, a 400 error is returned indicating "Bad Request".

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());
}

You will notice that additional information is logged, like the client request ID of the operation.

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

Setting up console logging

The simplest way to see the logs is to enable console logging. To create an Azure SDK log listener that outputs messages to the console use the AzureEventSourceListener.CreateConsoleLogger method.

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

To learn more about other logging mechanisms see here.

Next steps

  • View our samples.
  • Read about the different features of the Question Answering service.
  • Try our service demos.

Contributing

See the CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on Azure.AI.Language.QuestionAnswering:

Package Downloads
Encamina.Enmarcha.AI.QuestionsAnswering.Azure

Package Description

Kopylowi.Utility.Cognitive

Package Description

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Azure.AI.Language.QuestionAnswering:

Repository Stars
OfficeDev/microsoft-teams-apps-faqplus
FAQ Plus is a friendly Q&A bot that brings a human in the loop when it is unable to help with an answer from the knowledge base.
Version Downloads Last updated
1.1.0 120,593 10/14/2022
1.1.0-beta.2 22,911 7/19/2022
1.1.0-beta.1 4,136 2/8/2022
1.0.0 37,821 11/3/2021
1.0.0-beta.2 489 10/5/2021
1.0.0-beta.1 311 7/27/2021