Skip to content

Commit afa8d62

Browse files
Court72Court72
authored
Merge pull request #163975 from mrbullwinkle/mrb_06_28_2021_qna_tutorials
[QnAMaker] New docs - Cog Svcs
2 parents 90edd4f + 7f13ddc commit afa8d62

26 files changed

+296
-0
lines changed

‎articles/cognitive-services/QnAMaker/Tutorials/active-learning.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Enrich your knowledge base with Active Learning
3+
description: In this tutorial, learn how to enrich your knowledge bases with action learning
4+
ms.service: cognitive-services
5+
ms.subservice: qna-maker
6+
ms.topic: tutorial
7+
author: mrbullwinkle
8+
ms.author: mbullwin
9+
ms.date: 06/29/2021
10+
---
11+
12+
# Enrich your knowledge base with Active Learning
13+
14+
This tutorial shows you how enhance your knowledge base with active learning. If you notice that customers are asking questions, which are not part of your knowledge base. There are often variations of question that are paraphrased differently.
15+
16+
These variations when added as alternate questions to the relevant QnA pair, help to optimize the knowledge base to answer real world user queries. You can manually add alternate questions to QnA pairs through the editor. At the same time, you can also use the active learning feature to generate active learning suggestions based on user queries. The active learning feature, however, requires that the knowledge base receives regular user traffic to generate suggestions.
17+
18+
## Enable Active Learning
19+
Active Learning is turned on by default for the Custom Question Answering feature. However, you need to manually update the Active Learning setting for QnA Maker GA. You can find more details here: [Turn on Active Learning](../how-to/use-active-learning.md#turn-on-active-learning-for-alternate-questions).
20+
21+
To try out Active Learning suggestions, you can import the following file to the knowledge base: [SampleActiveLearning.tsv](https://github.com/Azure-Samples/cognitive-services-sample-data-files/blob/master/qna-maker/knowledge-bases/SampleActiveLearning.tsv).
22+
For more details on importing knowledge base, refer [Import Knowledge Base](migrate-knowledge-base.md).
23+
24+
## View and add/reject Active Learning Suggestions
25+
Once the active learning suggestions are available, they can be viewed from **View Options** > **Show active learning suggestions**.
26+
27+
> [!div class="mx-imgBorder"]
28+
> [ ![Screenshot with view options and show active learning suggestions outlined in red boxes]( ../media/active-learning/view-options.png) ]( ../media/active-learning/view-options.png#lightbox)
29+
30+
Clicking on **Show active learning suggestions**, enables the option to filter QnA Pairs that have suggestions. If active learning is disabled or there aren’t any suggestions, **Show active learning suggestions** will be disabled.
31+
32+
> [!div class="mx-imgBorder"]
33+
> [ ![Screenshot with filter by options highlighted in a red box]( ../media/active-learning/filter-by-suggestions.png) ]( ../media/active-learning/filter-by-suggestions.png#lightbox)
34+
35+
We can choose to filter only those QnA pairs that have alternate questions as suggested by Active Learning, so the filtered list of QnA pairs is displayed:
36+
37+
> [!div class="mx-imgBorder"]
38+
> [ ![Screenshot with view help with surface pen highlighted in a red box]( ../media/active-learning/help.png) ]( ../media/active-learning/help.png#lightbox)
39+
40+
41+
We can now either accept these suggestions or reject them using the checkmark or cross-mark. This can be either done individually navigating to each QnA pair or using the **Accept / Reject** option at the top.
42+
43+
> [!div class="mx-imgBorder"]
44+
> [ ![Screenshot with option to accept or reject highlighted in red]( ../media/active-learning/accept-reject.png) ]( ../media/active-learning/accept-reject.png#lightbox)
45+
46+
The knowledge base does not change unless we choose to add or edit the suggestions as suggested by Active Learning. Finally, click on Save and train to save the changes.
47+
48+
> [!NOTE]
49+
> To check your version and service settings for active learning, refer the article on [how to use active learning](../how-to/use-active-learning.md)
50+
51+
## Add alternate questions using editor
52+
53+
While active learning automatically suggests alternate questions based on the user queries hitting the knowledge base, we can also add variations of a question using the editor.
54+
Select the QnA pair where alternate question is to be added and select **Add alternative phrasing**
55+
56+
> [!div class="mx-imgBorder"]
57+
> [ ![Screenshot with add alternative phrasing highlighted in red]( ../media/active-learning/add-alternative-phrasing.png) ]( ../media/active-learning/add-alternative-phrasing.png#lightbox)
58+
59+
Alternate questions added to the QnA pair is shown as
60+
61+
> [!div class="mx-imgBorder"]
62+
> [ ![Screenshot with drawing with pen highlighted in red]( ../media/active-learning/draw-with-pen.png) ]( ../media/active-learning/draw-with-pen.png#lightbox)
63+
64+
By adding alternate questions along with Active Learning, we further enrich the knowledge base with variations of a question that helps to provide the same response to a similar user query.
65+
66+
67+
> [!NOTE]
68+
> Alternate questions have many stop words, then they might not impact the accuracy of response as expected. So, if the only difference between alternate questions is in the stop words, these alternate questions are not required.
69+
70+
The list of stop words can be found here: List of [stop words](https://github.com/Azure-Samples/azure-search-sample-data/blob/master/STOPWORDS.md).
71+
72+
73+
## Next steps
74+
75+
> [!div class="nextstepaction"]
76+
> [Improve the quality of responses with synonyms](adding-synonyms.md)

‎articles/cognitive-services/QnAMaker/Tutorials/adding-synonyms.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: Improve the quality of responses with synonyms
3+
description: In this tutorial, learn how to improve response with synonyms and alternate words
4+
ms.service: cognitive-services
5+
ms.subservice: qna-maker
6+
ms.topic: tutorial
7+
author: mrbullwinkle
8+
ms.author: mbullwin
9+
ms.date: 06/29/2021
10+
---
11+
12+
# Improve quality of response with synonyms
13+
14+
This tutorial will show you how you can improve the quality of your responses by using synonyms. Let's assume that users are not getting an accurate response to their queries, when they use alternate forms, synonyms or acronyms of a word. So, they decide to improve the quality of the response by using [Alterations API](/rest/api/cognitiveservices-qnamaker/QnAMaker4.0/Alterations) to add synonyms for keywords.
15+
16+
## Add synonyms using Alterations API
17+
18+
Let’s us add the following words and their alterations to improve the results:
19+
20+
|Word | Alterations|
21+
|--------------|--------------------------------|
22+
| fix problems | `Troubleshoot`, `trouble-shoot`|
23+
| whiteboard | `white-board`, `white board` |
24+
| bluetooth | `blue-tooth`, `blue tooth` |
25+
26+
```json
27+
{
28+
"wordAlterations": [
29+
{
30+
"alterations": [
31+
"fix problems",
32+
"trouble shoot",
33+
"trouble-shoot",
34+
]
35+
},
36+
{
37+
"alterations": [
38+
"whiteboard",
39+
"white-board",
40+
"white board"
41+
]
42+
},
43+
{
44+
"alterations": [
45+
"bluetooth",
46+
"blue-tooth",
47+
"blue tooth"
48+
]
49+
}
50+
]
51+
}
52+
53+
```
54+
55+
## Response after adding synonyms
56+
57+
For the question and answer pair “Fix problems with Surface Pen” shown below, we compare the response for a query made using its synonym “trouble shoot”.
58+
59+
> [!div class="mx-imgBorder"]
60+
> [ ![Screenshot with fix problems with Surface Pen highlighted in red]( ../media/adding-synonyms/fix-problems.png) ]( ../media/adding-synonyms/fix-problems.png#lightbox)
61+
62+
## Response before addition of synonym
63+
64+
> [!div class="mx-imgBorder"]
65+
> [ ![Screenshot with confidence score of 71.82 highlighted in red]( ../media/adding-synonyms/confidence-score.png) ]( ../media/adding-synonyms/confidence-score.png#lightbox)
66+
67+
## Response after addition of synonym
68+
69+
> [!div class="mx-imgBorder"]
70+
> [ ![Screenshot with a confidence score of 97 highlighted in red]( ../media/adding-synonyms/increase-score.png) ]( ../media/adding-synonyms/increase-score.png#lightbox)
71+
72+
As you can see, when `trouble shoot` was not added as a synonym, we got a low confidence response to the query “How to troubleshoot your surface pen”. However, after we add `trouble shoot` as a synonym to “fix problems”, we received the correct response to the query with a higher confidence score. Once, these word alterations were added, the relevance of results improved thereby improving user experience.
73+
74+
> [!NOTE]
75+
> Synonyms are case insensitive. Synonyms also might not work as expected if you add stop words as synonyms. The list of stop words can be found here: [List of stop words](https://github.com/Azure-Samples/azure-search-sample-data/blob/master/STOPWORDS.md).
76+
77+
For instance, if you add the abbreviation **IT** for Information technology, the system might not be able to recognize Information Technology because **IT** is a stop word and filtered when query is processed.
78+
79+
## Next steps
80+
81+
> [!div class="nextstepaction"]
82+
> [Create knowledge bases in multiple languages](multiple-languages.md)

‎articles/cognitive-services/QnAMaker/Tutorials/guided-conversations.md

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: Add guided conversations with multi-turn prompts
3+
description: In this tutorial learn how to make guided conversations with multi-turn prompts.
4+
ms.service: cognitive-services
5+
ms.subservice: qna-maker
6+
ms.topic: tutorial
7+
author: mrbullwinkle
8+
ms.author: mbullwin
9+
ms.date: 06/29/2021
10+
---
11+
12+
# Add guided conversations with multi-turn prompts
13+
14+
In this tutorial, we use [Surface Pen FAQ](https://support.microsoft.com/surface/how-to-use-your-surface-pen-8a403519-cd1f-15b2-c9df-faa5aa924e98) to create a knowledge base.
15+
16+
For this example let's assume that users are asking for additional details about the Surface Pen product, particularly how to troubleshoot their Surface Pen, but they are not getting the correct answers. So, we add more prompts to support additional scenarios and guide the users to the correct answers using multi-turn prompts.
17+
18+
## View QnAs with context
19+
While creating the knowledge base for [Surface Pen FAQ](https://support.microsoft.com/surface/how-to-use-your-surface-pen-8a403519-cd1f-15b2-c9df-faa5aa924e98), we choose to enable multi-turn extraction from the source document. For more details, follow [Create multi-turn conversation from document](../how-to/multiturn-conversation.md#create-a-multi-turn-conversation-from-a-documents-structure). This lists the multi-turn prompts that are associated with QnA pairs, which can be viewed using **Show context** under **View Options**.
20+
21+
> [!div class="mx-imgBorder"]
22+
> [ ![Screenshot with view options show context outlined in red boxes]( ../media/guided-conversations/show-context.png) ]( ../media/guided-conversations/show-context.png#lightbox)
23+
24+
This displays the context tree where all follow-up prompts linked to a QnA pair are shown:
25+
26+
> [!div class="mx-imgBorder"]
27+
> [ ![Screenshot of Surface Pen FAQ page with answers to common questions]( ../media/guided-conversations/source.png) ]( ../media/guided-conversations/source.png#lightbox)
28+
29+
## Add new QnA pair with follow-up prompts
30+
31+
To help the user solve issues with their Surface Pen, we add follow-up prompts:
32+
33+
1. Add a new QnA pair with two follow-up prompts
34+
2. Add a follow-up prompt to one of the newly added prompts
35+
36+
**Step 1**: Add a new QnA pair with two follow-up prompts **Check compatibility** and **Check Pen Settings**
37+
Using the editor, we add a new QnA pair with a follow-up prompt by clicking on **Add QnA pair**
38+
39+
> [!div class="mx-imgBorder"]
40+
> [ ![Screenshot of UI with "Add QnA pair" highlighted in a red box]( ../media/guided-conversations/add-pair.png) ]( ../media/guided-conversations/add-pair.png#lightbox)
41+
42+
A new row in **Editorial** is created where we enter the QnA pair as shown below:
43+
44+
> [!div class="mx-imgBorder"]
45+
> [ ![Screenshot of UI with "add a follow-up prompt" highlighted in a red box]( ../media/guided-conversations/follow-up.png) ]( ../media/guided-conversations/follow-up.png#lightbox)
46+
47+
We then add a follow-up prompt to the newly created QnA pair by choosing **Add follow-up prompt**. Clicking on which, we fill the details for the prompt as shown:
48+
49+
> [!div class="mx-imgBorder"]
50+
> [ ![Screenshot of UI with "add a follow-up prompt" highlighted in a red box]( ../media/guided-conversations/follow-up.png) ]( ../media/guided-conversations/follow-up.png#lightbox)
51+
52+
We provide **Check Compatibility** as the “Display text” for the prompt and try to link it to a QnA. Since, no related QnA pair is available to link to the prompt, when we search “Check your Surface Pen Compatibility”, we create a new QnA pair by clicking on **Create new**. Once we **Save** the changes, the following screen is presented, where a new QnA pair for the follow-up prompt can be entered as shown below:
53+
54+
> [!div class="mx-imgBorder"]
55+
> [ ![Screenshot of a question and answer about checking your surface pen compatibility]( ../media/guided-conversations/check-compatibility.png) ]( ../media/guided-conversations/check-compatibility.png#lightbox)
56+
57+
Similarly, we add another prompt **Check Pen Settings** to help the user troubleshoot the Surface Pen and add QnA pair to it.
58+
59+
> [!div class="mx-imgBorder"]
60+
> [ ![Screenshot of a question and answer about checking your surface pen settings]( ../media/guided-conversations/check-pen-settings.png) ]( ../media/guided-conversations/check-pen-settings.png#lightbox)
61+
62+
**Step 2**: Add another follow-up prompt to newly created prompt. We now add “Replace Pen tips’ as a follow-up prompt to the previously created prompt “Check Pen Settings”.
63+
64+
> [!div class="mx-imgBorder"]
65+
> [ ![Screenshot of a question and answer about checking your surface pen settings with a red box around information regarding replacing pen tips]( ../media/guided-conversations/replace-pen-tips.png) ]( ../media/guided-conversations/replace-pen-tips.png#lightbox)
66+
67+
We finally save the changes and test these prompts in the Test pane:
68+
69+
> [!div class="mx-imgBorder"]
70+
> [ ![Screenshot of QnAMaker test pane]( ../media/guided-conversations/test-pane.png) ]( ../media/guided-conversations/test-pane.png#lightbox)
71+
72+
For a user query **Issues with Surface Pen**, the system returns an answer and presents the newly added prompts to the user. The user then selects one of the prompts **Check Pen Settings** and the related answer is returned to the user with another prompt **Replace Pen Tips**, which when selected further provides the user with more information. So, multi-turn is used to help and guide the user to the desired answer.
73+
74+
## Next steps
75+
76+
> [!div class="nextstepaction"]
77+
> [Enrich your knowlege base with active learning](active-learning.md)

‎articles/cognitive-services/QnAMaker/Tutorials/multiple-languages.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: Create knowledge bases in multiple languages
3+
description: In this tutorial you will learn how to create knowledge bases with multiple languages.
4+
ms.service: cognitive-services
5+
ms.subservice: qna-maker
6+
ms.topic: tutorial
7+
author: mrbullwinkle
8+
ms.author: mbullwin
9+
ms.date: 06/29/2021
10+
---
11+
12+
# Create knowledge bases in multiple languages
13+
14+
This tutorial will walk through the process of creating knowledge bases in multiple languages. We use the [Surface Pen FAQ](https://support.microsoft.com/surface/how-to-use-your-surface-pen-8a403519-cd1f-15b2-c9df-faa5aa924e98) URL to create knowledge bases in German and English. We then publish the knowledge bases and use the [GenerateAnswerAPI](/rest/api/cognitiveservices-qnamaker/QnAMaker4.0/Runtime/GenerateAnswer) to query them to get answers to FAQs in the desired language.
15+
16+
## Create Knowledge Base in German
17+
18+
To be able to create a knowledge base in more than one language, the language setting must be set at the creation of the first Knowledge Base (KB) of the QnA service.
19+
20+
> [!NOTE]
21+
> The option to enable adding knowledge bases in multiple languages to a service is only available as part of Custom Question Answering which is a feature of Text Analytics.
22+
>
23+
> If you are using the GA version of QnA Maker, a separate QnA Maker resource would need to be created for each distinct language.
24+
25+
> [!div class="mx-imgBorder"]
26+
> [ ![Screenshot of UI for Connect your QnA service to your knowledge base with add knowledge bases in multiple languages selected]( ../media/multiple-languages/add-knowledge-bases.png) ]( ../media/multiple-languages/add-knowledge-bases.png#lightbox)
27+
28+
In **Step 2**: Enable “Add knowledge bases in multiple languages to this service” and choose **German** as the language of the KB from “Language” drop-down list.
29+
Fill relevant details in Step 3 and 4 and finally select on **Create your KB**.
30+
31+
At this step, QnA maker reads the document and extracts QnA pairs from the source URL to create the knowledge base in the German language. The knowledge base page opens where we can edit the contents of the knowledge base.
32+
33+
> [!div class="mx-imgBorder"]
34+
> [ ![Screenshot of UI with German questions and answers]( ../media/multiple-languages/german.png) ]( ../media/multiple-languages/german.png#lightbox)
35+
36+
## Create Knowledge Base in English
37+
38+
We now repeat the above steps with language-specific changes in the Step 2 and Step 4 to create the knowledge base in English:
39+
1. **Step 2**: Choose language as **English**
40+
2. **Step 4**: Select source file in selected language to create a knowledge base in English.
41+
Once, the knowledge base is created, we can see the relevant QnA pairs generated by QnA maker in English as shown below:
42+
43+
> [!div class="mx-imgBorder"]
44+
> [ ![Screenshot of REST API response]( ../media/multiple-languages/english.png) ]( ../media/multiple-languages/english.png#lightbox)
45+
46+
## Publish and Query knowledge base
47+
48+
We are now ready to publish the two knowledge bases and query them in the desired language using the [GenerateAnswerAPI](/rest/api/cognitiveservices-qnamaker/QnAMaker4.0/Runtime/GenerateAnswer). Once a knowledge base is published, the following page is shown which provides details to query the knowledge base.
49+
50+
> [!div class="mx-imgBorder"]
51+
> [ ![Screenshot of UI with English questions and answers]( ../media/multiple-languages/postman.png) ]( ../media/multiple-languages/postman.png#lightbox)
52+
53+
The language for the incoming user query can be detected with the [Language Detection API](../../text-analytics/how-tos/text-analytics-how-to-language-detection.md) and the user can call the appropriate endpoint and knowledge base depending on the detected language.

‎articles/cognitive-services/QnAMaker/media/active-learning/accept-reject.png

20.6 KB
Loading

‎articles/cognitive-services/QnAMaker/media/active-learning/add-alternative-phrasing.png

49.5 KB
Loading

‎articles/cognitive-services/QnAMaker/media/active-learning/draw-with-pen.png

52.7 KB
Loading

‎articles/cognitive-services/QnAMaker/media/active-learning/filter-by-suggestions.png

23.2 KB
Loading

‎articles/cognitive-services/QnAMaker/media/active-learning/help.png

154 KB
Loading

‎articles/cognitive-services/QnAMaker/media/active-learning/view-options.png

32.5 KB
Loading

0 commit comments

Comments
 (0)