Create a QnA Maker knowledge base

APPLIES TO: Composer v1.x and v2.x

You can create, edit, and publish QnA Maker knowledge bases (KB) in Bot Framework Composer, as well as use knowledge bases already published to Azure. This article shows the basic steps to create a QnA knowledge base or connect to an existing one, edit a knowledge base, publish a knowledge base to a QnA Maker service, and test the published knowledge base, all within the Composer environment.

Note

If you're looking for how to add a QnA Maker knowledge base to your bot, read Add a QnA Maker knowledge base to your bot. You have the following ways for using QnA Maker in Composer:

  • Authoring QnA content from Composer. This allows and requires authoring from Composer, as well as recognition of QnA intents and dialog triggers, as described in this article. This option allows publishing.
  • Using an action. This approach allows you to make a specific and explicit call to the QnA service with an action, from within a dialog. This option does not allow any authoring or two-way connectivity. It is a simple way to query an existing and already published QnA KB, created from outside of Composer. It does not allow publishing. This is described in the Add a QnA Maker knowledge base to your bot article.

Prerequisites

Important

If you built Composer from source, you need to run a command before you can create a QnA Maker knowledge base in Composer. Before running yarn startall to start your Composer:

  • On Windows, set QNA_SUBSCRIPTION_KEY=<Your_QnA_Subscription_Key>
  • On macOS or Linux, export QNA_SUBSCRIPTION_KEY=<Your_QnA_Subscription_Key>

If you are using the desktop application version of Composer, this step is not necessary.

About QnA Maker

QnA Maker is a cloud-based natural language processing service that creates a natural conversational layer over your data. QnA Maker is especially useful when you have static information to manage in your bot. The static question-and-answer pairs are referred to as a QnA Maker knowledge base, which the QnA Maker service uses to process the questions and respond with the matching answers.

Create or access your QnA Maker resource in Azure Cognitive Services

  1. Open the Configure page in Composer. Then select the Development resources, and scroll down to Azure QnA Maker.
  2. Select Set up QnA Maker.

There are three ways to add a QnA Maker resources in Composer:

Use existing resources

Select this option if you already have a QnA Maker resource.

  1. Select User existing resources and select Next on the bottom right. Then sign into Azure when prompted.

  2. Select the Azure Directory, Azure subscription, and QnA Maker resource name for your bot. Then select Next on the bottom.

  3. Composer will add the keys from your existing resource to your bot. The following window will appear once your key has been successfully added:

  4. Press Done to finish. You now can start adding QnA capabilities to your bot.

Create and configure new Azure resources

Select this option if you have access to Azure and need to create a new QnA Maker resource

  1. Select Create and configure new Azure resources and select Next on the bottom right. Then sign into Azure when prompted.

  2. Select the Azure Directory and Azure subscription for your new resource. Then select Next on the bottom.

  3. On the next window, select a Resource group, Region, and Pricing tier. Also enter the QnA Maker resource name. Then select Next.

  4. Press Done to finish. You now can start adding QnA capabilities to your bot.

Generate instruction for Azure administrator

Select this option if you are working with an Azure administrator. They will provision your QnA Maker resource

  1. Select Generate instruction for Azure administrator.

  2. Copy the instructions on the next page and send them to your administrator. They will provision the resources you need. Then press Okay.

  3. Your administrator will generate a JSON for you. On the Configure page in Composer, toggle on the Advanced settings view (json).

  4. Replace the existing JSON with the one from your administrator. You now can start adding QnA capabilities to your bot.

Create and add a knowledge base

There are three places to create a knowledge base in Composer, explained in the sections below:

With all options, you can either:

Create a Core Bot with QnA Maker

Select this option if you want to create a new bot with QnA capabilities.

  1. Open Composer.

  2. Select + Create on the homepage. The templates window will open.

  3. Select the Core Bot with QnA Maker template under the C# section. Then select Next.

  4. Enter the Name of your bot project. Set the Runtime type to Azure Web App, and choose a location for your bot project. Then select Next on the bottom right.

  5. It will take a few moments for Composer to create your bot project. After it's done, a page will appear with two options, described in the sections below Choose the option that's best for your bot project:

Add knowledge base from the authoring canvas

Select this option if you already have a bot and want to add QnA capabilities to it.

  1. Open a bot project in Composer.

  2. Select the three dots next to a dialog. Then select + Add QnA Maker knowledge base.

  3. On the next page you have two options, described in the sections below. Choose the option that's best for your bot project.:

Add knowledge base from the Knowledge base page

Select this option if you already have a bot and want to add QnA capabilities to it.

  1. Open a bot project in Composer.

  2. Select the Knowledge base in the navigation pane.

  3. Composer will open the Knowledge (QnA) page. To add a knowledge base, you can either select the Create new KB button on the bottom, or you can select the three dots next to your bot and then + Add QnA Maker knowledge base. They will take you to the same place.

    Add or create knowledge base buttons.

  4. On the next pages you have three options, described in the sections below. Choose the option that's best for your bot project.:

Add knowledge base from a URL

Select this option if you already have a URL of a file with QnA pairs, like https://download.microsoft.com/download/2/9/B/29B20383-302C-4517-A006-B0186F04BE28/surface-pro-4-user-guide-EN.pdf, that you want to use to create a knowledge base

  1. Enter a Knowledge base name. Then select Next.
  2. Enter the value of the Source URL and select a language for What language is this content in?. Also select if you want to Enable multi-turn extraction.
  3. Select Next to create the knowledge base.

Import existing knowledge base from the QnA Maker portal

Select this is you want to important an already existing knowledge base on the QnA Maker portal.

  1. Enter a Knowledge base name. Then select Next.
  2. Select Import existing knowledge base from the QnA Maker portal.
  3. On the next page, enter the QnA values for your knowledge base. Once done select Next to import the knowledge base.
  4. Once Composer has imported the knowledge base, a message will appear on the top right indicating so. Select View KB to view your new knowledge base.

Create blank knowledge base

Select this if don't have any QnA resources and want to add question and answer pairs manually.

  1. Enter a Knowledge base name. Then select Next.
  2. You will be taken to the Knowledge base page. Select + Add QnA Pair to add a question and answer pair.

Edit a knowledge base

  1. Select Knowledge base from the navigation pane and navigate to the Knowledge (QnA) page.

  2. Select a dialog from the bot explorer. You can see all the knowledge bases you created in the selected dialog.

  3. Select a knowledge base you want to edit.

  4. To edit a knowledge base name, Select the pencil icon to the right of the name to edit your knowledge base name.

  5. To add a question-and-answer pair:

    1. Select + Add QnA Pair under your desired knowledge base
    2. Enter questions and answers in the Question and Answer columns respectively.
  6. To include alternative phrases of a question:

    1. Hover over a question and answer pair and then select + Add alternative phrasing from the Question column.
    2. Enter your desired alternative phrases of the question.
  7. To delete a question-and-answer pair, hover over the pair and select the delete icon on the right.

  8. To edit the .qna file of a knowledge base:

    1. Select the three-dot icon right to the knowledge base name.

    2. Select Show code to view and edit the knowledge base in .qna file format.

      Tip

      For complete documentation of the .qna file format, see the Bot Framework SDK .qna file format reference article.

    3. Select the left arrow on top to exit from the edit mode.

  9. To import a new URL and overwrite:

    1. Select the three-dot icon right to the knowledge base name.

    2. Select Import new URL and overwrite.

    3. Enter the URL of the file to overwrite the existing knowledge base in FAQ website (Source). Then select Done on the bottom right.

Delete a knowledge base

  1. Select Knowledge base from the navigation pane.
  2. On the Knowledge (QnA) page, select the dialog from the bot explorer that contains the knowledge base you want to delete.
  3. Select the knowledge base you want to delete, then select the three-dot icon right to the knowledge base name. Select Delete knowledge base to delete the knowledge base.

Publish knowledge base

After you have created you QnA Maker resource in Azure and finished creating the QnA Maker knowledge base, you can proceed to publish it to the QnA Maker service.

Note

When you create a bot using the QnA Maker template, the information for your QnA Maker database is imported into Composer. When you follow the steps here to publish your knowledge base, Composer uses that to create a database for you in the QnA Maker service. If you have an existing bot and wish to add an existing QnA Maker database, you will need to follow the steps given in the Add a QnA Maker knowledge base to your bot article.

  1. Select Configure from the navigation pane. Then select Development resources and scroll down to Azure QnA Maker.

  2. Enter your QnA Maker Subscription key.

  3. Go back to the Create page. Select Start bot.

  4. After publishing the knowledge base successfully, you can navigate to your QnA Maker portal to view the knowledge base just published.

Test

  1. Select Start bot in the top right. Then select Open Web Chat.

  2. Type a question in Web Chat to have the bot respond with the matching answer from the knowledge base.

    QnA test in Web Chat

Additional information