Edit

Share via

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

  • Article

Note

The QnA Maker service is being retired on the 31st of March, 2025. A newer version of the question and answering capability is now available as part of Azure AI Language. For question answering capabilities within the Language Service, see question answering. Starting 1st October, 2022 you won’t be able to create new QnA Maker resources. For information on migrating existing QnA Maker knowledge bases to question answering, consult the migration guide.

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.

Prerequisites

  • If you don't have an Azure subscription, create a free account before you begin.
  • A QnA Maker resource created in the Azure portal. Remember your Microsoft Entra ID, Subscription, QnA Maker resource name you selected when you created the resource.

Create your first QnA Maker knowledge base

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

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

  3. On the Create page, skip Step 1 if you already have your QnA Maker resource.

If you haven't created the service yet, select Stable and Create a QnA service. You are directed to the Azure portal to set up a QnA Maker service in your subscription. Remember your Microsoft Entra ID, Subscription, QnA resource name you selected when you created the resource.

When you are done creating the resource in the Azure portal, return to the QnA Maker portal, refresh the browser page, and continue to Step 2.

  1. In Step 2, select your Active directory, subscription, service (resource), and the language for all knowledge bases created in the service.

    Screenshot of selecting a QnA Maker service knowledge base

  2. In Step 3, name your knowledge base My Sample QnA KB.

  3. In Step 4, configure the settings with the following table:

    Setting Value
    Enable multi-turn extraction from URLs, .pdf or .docx files. Checked
    Multi-turn default text Select an option
    + Add URL https://www.microsoft.com/download/faq.aspx
    Chit-chat Select Professional

  4. In Step 5, Select Create your KB.

    The extraction process takes a few moments 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 from the context toolbar.

  2. Add the following question:

    How many Azure services are used by a knowledge base?

  3. Add the answer formatted with markdown:

    * Azure AI 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 QnA Maker. 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.

    I want to know the difference between 32 bit and 64 bit Windows

    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 move 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 AI Bot Service's creation page. Configure the Azure AI Bot Service. 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.

    • Do
      • Change bot handle - if it is not unique.
      • Select SDK Language. Once the bot is created, you can download the code to your local development environment and continue the development process.
    • 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

  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.

What did you accomplish?

You created a new knowledge base, added a public URL to the knowledge base, added your own QnA pair, trained, tested, and published the knowledge base.

After publishing the knowledge base, you created a bot, and tested the bot.

This was all accomplished in a few minutes without having to write any code or clean the content.

Clean up resources

If you are not continuing to the next quickstart, delete the QnA Maker and Bot framework resources in the Azure portal.

Next steps

Add questions with metadata

For more information: