diff --git a/sdk/cognitivelanguage/Azure.AI.Language.Conversations/README.md b/sdk/cognitivelanguage/Azure.AI.Language.Conversations/README.md index 7ed92f4e6b8e..7fa2e5c220bd 100644 --- a/sdk/cognitivelanguage/Azure.AI.Language.Conversations/README.md +++ b/sdk/cognitivelanguage/Azure.AI.Language.Conversations/README.md @@ -1,56 +1,56 @@ # Azure Cognitive Language Services Conversations 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. +Conversations (aka LuisVNext) is a cloud-based conversational AI service that applies custom machine-learning intelligence to a user's conversational, natural language text to predict overall meaning, and pull out relevant, detailed information. The service utilizes state-of-the-art technology to create and utilize natively multilingual models, which means that users would be able to train their models in one language but predict in others. -[Source code][questionanswering_client_src] | [Package (NuGet)][questionanswering_nuget_package] | [API reference documentation][questionanswering_refdocs] | [Product documentation][questionanswering_docs] | [Samples][questionanswering_samples] +[Source code][conversationanalysis_client_src] | [Package (NuGet)][conversationanalysis_nuget_package] | [API reference documentation][conversationanalysis_refdocs] | [Product documentation][conversationanalysis_docs] | [Samples][conversationanalysis_samples] ## Getting started ### Install the package -Install the Azure Cognitive Language Services Question Answering client library for .NET with [NuGet][nuget]: +Install the Azure Cognitive Language Services Conversations client library for .NET with [NuGet][nuget]: ```powershell -dotnet add package Azure.AI.Language.QuestionAnswering --prerelease +dotnet add package Azure.AI.Language.Conversations --prerelease ``` ### Prerequisites * An [Azure subscription][azure_subscription] -* An existing Question Answering resource +* An existing Text Analytics resource > 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`][questionanswering_client_class] 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][cognitive_auth]. +In order to interact with the Conversations service, you'll need to create an instance of the [`ConversationAnalysisClient`][conversationanalysis_client_class] 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][cognitive_auth]. #### 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][azure_portal]. +You can get the **endpoint** and an **API key** from the Cognitive Services resource in the [Azure Portal][azure_portal]. -Alternatively, use the [Azure CLI][azure_cli] command shown below to get the API key from the Question Answering resource. +Alternatively, use the [Azure CLI][azure_cli] command shown below to get the API key from the Cognitive Service resource. ```powershell az cognitiveservices account keys list --resource-group --name ``` -#### Create a QuestionAnsweringClient +#### Create a ConversationAnalysisClient -Once you've determined your **endpoint** and **API key** you can instantiate a `QuestionAnsweringClient`: +Once you've determined your **endpoint** and **API key** you can instantiate a `ConversationAnalysisClient`: -```C# Snippet:QuestionAnsweringClient_Create +```C# Snippet:ConversationAnalysisClient_Create Uri endpoint = new Uri("https://myaccount.api.cognitive.microsoft.com"); AzureKeyCredential credential = new AzureKeyCredential("{api-key}"); -QuestionAnsweringClient client = new QuestionAnsweringClient(endpoint, credential); +ConversationAnalysisClient client = new ConversationAnalysisClient(endpoint, credential); ``` ## Key concepts -### QuestionAnsweringClient +### ConversationAnalysisClient -The [`QuestionAnsweringClient`][questionanswering_client_class] 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. +The [`ConversationAnalysisClient`][conversationanalysis_client_class] is the primary interface for making predictions using your deployed Conversation models. It provides both synchronous and asynchronous APIs to submit queries. ### Thread safety @@ -70,63 +70,36 @@ We guarantee that all client instance methods are thread-safe and independent of ## Examples -The Azure.AI.Language.QuestionAnswering client library provides both synchronous and asynchronous APIs. +The Azure.AI.Language.Conversations client library provides both synchronous and asynchronous APIs. -The following examples show common scenarios using the `client` [created above](#create-a-questionansweringclient). +The following examples show common scenarios using the `client` [created above](#Create a ConversationAnalysisClient). -### Ask a question +### Analyze a Conversation -The only input required to a ask a question using an existing knowledge base is just the question itself: +We will need to set up the `AnalyzeConversationOptions` with our query of choice. We can then simply call the `client.AnalyzeConversation()` method, which takes our project name as well as the options object as parameters. -```C# Snippet:QuestionAnsweringClient_QueryKnowledgeBase -QueryKnowledgeBaseOptions options = new QueryKnowledgeBaseOptions("How long should my Surface battery last?"); +```C# Snippet:ConversationAnalysis_AnalyzeConversation +AnalyzeConversationOptions options = new AnalyzeConversationOptions("We'll have 2 plates of seared salmon nigiri."); -Response response = client.QueryKnowledgeBase("FAQ", options); +Response response = client.AnalyzeConversation("Menu", options); -foreach (KnowledgeBaseAnswer answer in response.Value.Answers) -{ - Console.WriteLine($"({answer.ConfidenceScore:P2}) {answer.Answer}"); - Console.WriteLine($"Source: {answer.Source}"); - Console.WriteLine(); -} +Console.WriteLine($"Top intent: {response.Value.Prediction.TopIntent}"); ``` -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][questionanswering_docs_chat], you can ask a follow-up question provided the previous question-answering ID and, optionally, the exact question the user asked: - -```C# Snippet:QuestionAnsweringClient_Chat -// Answers are ordered by their ConfidenceScore so assume the user choose the first answer below: -KnowledgeBaseAnswer previousAnswer = answers.Answers.First(); -QueryKnowledgeBaseOptions options = new QueryKnowledgeBaseOptions("How long should charging take?") -{ - Context = new KnowledgeBaseAnswerRequestContext(previousAnswer.Id.Value) -}; - -Response response = client.QueryKnowledgeBase("FAQ", options); - -foreach (KnowledgeBaseAnswer answer in response.Value.Answers) -{ - Console.WriteLine($"({answer.ConfidenceScore:P2}) {answer.Answer}"); - Console.WriteLine($"Source: {answer.Source}"); - Console.WriteLine(); -} -``` +You can set additional properties on `AnalyzeConversationOptions` to specify the language, verbosity, and more. ## 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][questionanswering_rest_docs] requests. +When you interact with the Cognitive Language Services Conversations client library using the .NET SDK, errors returned by the service correspond to the same HTTP status codes returned for [REST API][conversationanalysis_rest_docs] requests. -For example, if you submit a question to a non-existant knowledge base, a `400` error is returned indicating "Bad Request". +For example, if you submit a query to a non-existant project, a `400` error is returned indicating "Bad Request". ```C# Snippet:ConversationAnalysisClient_BadRequest try { - Response response = client.AnalyzeConversation("invalid-knowledgebase", options); + Response response = client.AnalyzeConversation("invalid-project", options); } catch (RequestFailedException ex) { @@ -136,29 +109,6 @@ catch (RequestFailedException ex) You will notice that additional information is logged, like the client request ID of the operation. -```text -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. @@ -172,9 +122,9 @@ To learn more about other logging mechanisms see [here][core_logging]. ## Next steps -* View our [samples][questionanswering_samples]. -* Read about the different [features][questionanswering_docs_features] of the Question Answering service. -* Try our service [demos][questionanswering_docs_demos]. +* View our [samples][conversationanalysis_samples]. +* Read about the different [features][conversationanalysis_docs_features] of the Conversations service. +* Try our service [demos][conversationanalysis_docs_demos]. ## Contributing @@ -198,15 +148,17 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con [contributing]: https://github.com/Azure/azure-sdk-for-net/blob/main/CONTRIBUTING.md [core_logging]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Diagnostics.md [nuget]: https://www.nuget.org/ -[questionanswering_client_class]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/cognitivelanguage/Azure.AI.Language.QuestionAnswering/src/QuestionAnsweringClient.cs -[questionanswering_client_src]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.QuestionAnswering/src/ -[questionanswering_docs]: https://docs.microsoft.com/azure/cognitive-services/qnamaker/ -[questionanswering_docs_chat]: https://docs.microsoft.com/azure/cognitive-services/qnamaker/how-to/chit-chat-knowledge-base -[questionanswering_docs_demos]: https://azure.microsoft.com/services/cognitive-services/qna-maker/#demo -[questionanswering_docs_features]: https://azure.microsoft.com/services/cognitive-services/qna-maker/#features -[questionanswering_nuget_package]: https://nuget.org/packages/Azure.AI.Language.QuestionAnswering/ -[questionanswering_refdocs]: https://docs.microsoft.com/dotnet/api/Azure.AI.Language.QuestionAnswering/ -[questionanswering_rest_docs]: https://docs.microsoft.com/rest/api/cognitiveservices-qnamaker/ -[questionanswering_samples]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.QuestionAnswering/samples/README.md - -![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-net%2Fsdk%2Fcognitivelanguage%2FAzure.AI.Language.QuestionAnswering%2FREADME.png) + + +[conversationanalysis_client_class]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/src/ConversationAnalysisClient.cs +[conversationanalysis_client_src]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/src/ +[conversationanalysis_nuget_package]: https://nuget.org/packages/Azure.AI.Language.Conversations/ +[conversationanalysis_samples]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/ + + +[conversationanalysis_docs]: https://docs.microsoft.com/azure/cognitive-services/qnamaker/ +[conversationanalysis_docs_demos]: https://azure.microsoft.com/services/cognitive-services/qna-maker/#demo +[conversationanalysis_docs_features]: https://azure.microsoft.com/services/cognitive-services/qna-maker/#features +[conversationanalysis_refdocs]: https://docs.microsoft.com/dotnet/api/Azure.AI.Language.QuestionAnswering/ +[conversationanalysis_rest_docs]: https://docs.microsoft.com/rest/api/cognitiveservices-qnamaker/ + diff --git a/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/Sample1_AnalyzeConversation.md b/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/Sample1_AnalyzeConversation.md index 68397bf8e3b4..8373c76b2382 100644 --- a/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/Sample1_AnalyzeConversation.md +++ b/sdk/cognitivelanguage/Azure.AI.Language.Conversations/samples/Sample1_AnalyzeConversation.md @@ -1,4 +1,4 @@ -# Ask a question +# Analyze a Conversation This sample demonstrates how to analyze an utterance. To get started, you'll need to create a Cognitive Language service endpoint and an API key. See the [README](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/cognitivelanguage/Azure.AI.Language.Conversations/README.md) for links and instructions. diff --git a/sdk/cognitivelanguage/Azure.AI.Language.Conversations/tests/Samples/Readme.cs b/sdk/cognitivelanguage/Azure.AI.Language.Conversations/tests/Samples/Readme.cs index a466e4c8e591..7f5a874ccf8e 100644 --- a/sdk/cognitivelanguage/Azure.AI.Language.Conversations/tests/Samples/Readme.cs +++ b/sdk/cognitivelanguage/Azure.AI.Language.Conversations/tests/Samples/Readme.cs @@ -29,7 +29,7 @@ public void BadArgument() #region Snippet:ConversationAnalysisClient_BadRequest try { - Response response = client.AnalyzeConversation("invalid-knowledgebase", options); + Response response = client.AnalyzeConversation("invalid-project", options); } catch (RequestFailedException ex) {