Quickstart: Create, train, and publish your QnA Maker knowledge base

You can create a QnA Maker knowledge base (KB) from your own content, such as FAQs or product manuals. This article includes an example of creating a QnA Maker knowledge base from a simple FAQ webpage, to answer questions on BitLocker key recovery.

Include a chit-chat personality to make your knowledge more engaging with your users.


New resources created after July 1, 2019, will use custom subdomain names. For more information and a complete list of regional endpoints, see Custom subdomain names for Cognitive Services.


  • If you don't have an Azure subscription, create a free account before you begin.

Create a new QnA Maker knowledge base

  1. Sign in to the QnAMaker.ai portal with your Azure credentials.

  2. On the QnA Maker portal, select Create a knowledge base.

  3. On the Create page, select Create a QnA service. You are directed to the Azure portal to set up a QnA Maker service in your subscription.

  4. In the QnA Maker portal, select your QnA Maker service from the drop-down lists. If you created a new QnA Maker service, be sure to refresh the page.

    Screenshot of selecting a QnA Maker service knowledge base

  5. Name your knowledge base My Sample QnA KB.

  6. Add a sample word document as a URL:


  7. Select + Add URL.

  8. Add professional Chit-chat to your KB.

  9. Select Create your KB.

    The extraction process takes a few minutes to read the document and identify questions and answers.

    After QnA Maker successfully creates the knowledge base, the Knowledge base page opens. You can edit the contents of the knowledge base on this page.

Add a new question and answer set

  1. In the QnA Maker portal, on the Edit page, select Add QnA pair.

  2. Add the following question:

    How many Azure services are used by a knowledge base?

  3. Add the answer formatted with markdown:

    * Azure QnA Maker service\n* Azure Cognitive Search\n* Azure web app\n* Azure app plan

     Add the question as text and the answer formatted with markdown.

    The markdown symbol, *, is used for bullet points. The \n is used for a new line.

    The Edit page shows the markdown. When you use the Test panel later, you will see the markdown displayed properly.

Save and train

In the upper right, select Save and train to save your edits and train the QnA Maker model. Edits aren't kept unless they're saved.

Test the knowledge base

  1. In the QnA Maker portal, in the upper right, select Test to test that the changes you made took effect.

  2. Enter an example user query in the textbox.

    How many Azure services are used by a knowledge base?

     Enter an example user query in the textbox.

  3. Select Inspect to examine the response in more detail. The test window is used to test your changes to the knowledge base before publishing your knowledge base.

  4. Select Test again to close the Test panel.

Publish the knowledge base

When you publish a knowledge base, the contents of your knowledge base moves from the test index to a prod index in Azure search.

Screenshot of moving the contents of your knowledge base

  1. In the QnA Maker portal, select Publish. Then to confirm, select Publish on the page.

    The QnA Maker service is now successfully published. You can use the endpoint in your application or bot code.

    Screenshot of successful publishing

Create a bot

After publishing, you can create a bot from the Publish page:

  • You can create several bots quickly, all pointing to the same knowledge base for different regions or pricing plans for the individual bots.
  • If you want only one bot for the knowledge base, use the View all your bots on the Azure portal link to view a list of your current bots.

When you make changes to the knowledge base and republish, you don't need to take further action with the bot. It's already configured to work with the knowledge base, and works with all future changes to the knowledge base. Every time you publish a knowledge base, all the bots connected to it are automatically updated.

  1. In the QnA Maker portal, on the Publish page, select Create bot. This button appears only after you've published the knowledge base.

    Screenshot of creating a bot

  2. A new browser tab opens for the Azure portal, with the Azure Bot Service's creation page. Configure the Azure bot service.

    • Don't change the following settings in the Azure portal when creating the bot. They are pre-populated for your existing knowledge base:
      • QnA Auth Key
      • App service plan and location
    • The bot and QnA Maker can share the web app service plan, but can't share the web app. This means the app name for the bot must be different from the app name for the QnA Maker service.
  3. After the bot is created, open the Bot service resource.

  4. Under Bot Management, select Test in Web Chat.

  5. At the chat prompt of Type your message, enter:

    Azure services?

    The chat bot responds with an answer from your knowledge base.

    Enter a user query into the test web chat.

Clean up resources

Clean up the QnA Maker and Bot framework resources in the Azure portal.

Next steps

For more information: