What the FAQ: Part 1 – QnA Maker

Recently I’ve been writing documentation for a new service that we built for our internal needs. Needless to say, as an integral part of the whole bunch of documentation produced, two of the documents are of a special interest to the users of the service. I am talking about user’s guide and troubleshooting guide.

Now, both of them have to provide enough information about using the service and what to do if things, from whatever reason, go south. And don’t get me wrong, they do provide all the information needed. And yet, somehow, that’s exactly the problem. With the first one being a Word document with over 80 pages and the second one an Excel sheet with a couple of dozens of scenarios described, finding the right information fast is sometimes challenging. So, there must be a better way, right? And sure enough, there is.

The central piece of our communication within my team, apart of good ol’ Outlook, is Microsoft Teams. Teams offers some quite neat features and is very extensible via constantly growing number of apps, connectors and bots. For the exercise I will describe in the next couple of articles, the last one is specially important. The question I asked myself was, how to bring that vast amount of information nearer to our users and team members. I found the answer in the QnA Maker.

QnA Maker

Microsoft QnA Maker is a web-based AI service which can be fed and trained with masses of information with a purpose of providing a fast and easy access to it, in form of the natural language interaction. Back to our case, we want to extract the information from the documentation, put it in the form of questions and appropriate answers, train the service and make it available via the REST API for consumption. Let’s see how it works.


QnA Maker has a dependency on three Azure services for different means and purposes.

  • Azure App Service – this is where the service is going to run. The App Service will provide the endpoints for accessing the knowledge base
  • Azure Search Service – this is the place where the knowledge base is stored
  • Application Insights – optional component which is used for storing chat protocols and for analytics

So, if you don’t have an Azure subscription, go ahead and create one under https://azure.microsoft.com. If you already have a subscription, you can go directly to https://portal.azure.com and log on to your Azure subscription. Then, click on Create a resource link, type QnA Maker in the search box and select QnA Maker from the list of results. Click Create.

QnA-P1-01On the Create blade, define the service name, select subscription in which you want to create the resource, and choose management and search pricing tiers.

There are a couple of things to think about here. First of all, you can start with free tiers and test the service. You will have to count with some limitations though. The service will be limited to 2 knowledge bases and 50 MB of size and in free tier, it is not recommended for the production. However, you can scale up whenever you want and choose one of the paid plans.

Second, you’ll have to choose the app name which will later on represent a part of the URL to your endpoint. In addition to that, consider placing the services in the location geographically nearest to your users. Finally, click Create to create the QnA Maker resources.

Creating your first knowledge base

To create a knowledge base, navigate to https://www.qnamaker.ai, sign in and click Create new service. First, connect the QnA service to the knowledge base.


Then, provide the name of the service, which is for your reference only and which you can modify later if you want.

From here you can take one of three paths:

  • Provide knowledge base URL(s). If you already have a knowledge base published on web, you can provide the URLs to sites and documents containing knowledge base or the documentation. You can provide links to http(s) sites or Word, Excel and PDF documents
  • Upload a local file. You can upload Word, Excel and PDF documents.
  • Start from scratch. If you have no files at hand, no worries. You can start with a blank service and feed in the information manually.

Once you decided which path to take, provide the required information and click Create button to create the service.


Content, content, content

So, you’ve created your first service. Now what? That depends a bit on the route you’ve taken. If you’ve decided to provide some ready documents, you will probably end up with some pre-populated questions and answer pairs. Otherwise, you’ll have to start creating question and answer pairs manually. In the above example, we’ve specified the download link to the Surface Pro 4 User’s Guide. Let’s see what have we got.


As we see in the screenshot above, the QnA Maker managed to extract the question and answer pairs from the document. To see it in action, go to the Test tab and start asking some questions.


As you can see, you can interact with QnA Maker completely in natural language. The machine learning algorithms behind the whole thing will do their best to get the context out of your questions and find appropriate answers. You can even add the alternate phrasing to the questions which are not always understood properly. To do so, click on a plus (+) link on the question and type in the alternate question for the given answer.


Adding the new content manually is really straightforward. From the Knowledge Base page, click Add new QnA pair. Specify a question and answer in the designated fields. Although not directly specified on the page, you have some formatting options for answers. The knowledge base supports Markdown for which you can find a neat cheat sheet in the Markdown Wikipedia article, also linked below. Be aware that not all formatting features are going to work, at least not at the time of writing this article.

When you’re done editing, click the Save and retrain button to make the knowledge base aware of the changes you’ve made and to retrain the machine learning model. Click the Test button to test the changes you made.


Congratulations! If you followed along, you’ve just made your first QnA service. Easy, isn’t it? So, what to do with it now? As mentioned earlier, the QnA Maker offers a REST API you can consume from within your apps, applications and scripts. But before you can do any of that, you have to publish an endpoint. If it sounds scary and a lot of work, worry not – it isn’t.

To publish an endpoint, click the Publish button.


Click the Publish button to create the endpoint. After a couple of seconds, you will be presented with the details. Note that you will have to publish the data each time you make a change in your knowledge base. The existing endpoint will remain, you’ll just make your changes “official” and available for consumption.


To access the knowledge base, you will have to send a POST HTTP request to the REST API. To successfully access the correct knowledge base, you need a knowledge base ID and subscription key, both presented on the details page above. You can also read this information from the settings page of your QnA service.

In the next step, we will test the service. The choice of the language is yours – I will use PowerShell here just for the sake of simplicity. Note that you won’t have to write any line of code for the integration with Teams, which is our final goal for the series. The following example just reveals what happens in the background.

$Question = "What's the warranty on my Surface Pro?"
$hostUrl = "https://YourKBName.azurewebsites.net/qnamaker"
$kbId = "insert-your-knowledge-base-id-here"
$subscriptionKey = "EndpointKey insert-endpoint-key-here"

$endpointUri = [string]::Format("{0}/knowledgebases/{1}/generateAnswer", $hostUrl, $kbId)
$query = "{ ""question"": ""$Question"" }"

$res = Invoke-WebRequest -Uri $endpointUri `
   -Method Post `
   -Body $query `
   -ContentType "application/json" `
   -Headers @{"Authorization"=$subscriptionKey}

if ($res.StatusCode -eq 200)
   $answer = ConvertFrom-Json $res.Content

Now let’s go through the code. Lines 1-7 are just an initialization part. We are defining the question we are sending to the endpoint, along with the host URL, knowledge base ID and the subscription key for the authentication. Then, we are building a full URI to the endpoint by using provided host URL and knowledge base ID. Finally, we are building a query in the JSON format. Note that I am not escaping JSON data just for the sake of keeping the example light and simple.

Next, we will invoke the request to the endpoint. This is happening in the command in lines 9-13. We are using the endpoint URI we just built above to make a POST request and passing the JSON query as the body of the request. We are setting the content type to application/json and providing the subscription key in the request header, in the Authorization field.

Once the request is executed, we will receive the result in form of a Microsoft.PowerShell.Commands.HtmlWebResponseObject object. For this example, we are interested in two properties – Status and Content. If everything went well, Status property will be set to 200 and Content property will contain a data string generated by the web service in JSON format.


To deserialize the JSON string into an object, pass the Content property contents to the ConvertFrom-Json cmdlet. The object will contain answers, related questions and the scored probability in percent. Scored probability defines how certain the algorithm is that the answer matches the question you provided.


So, what now?

As demonstrated above, you can use the REST API to access the knowledge base information from your code. However, for my case it wasn’t enough. I had to integrate it somehow in our daily toolset, in order for us to have the information immediately, at our fingertips. How did I do it? For now let’s just say that Azure Bot Framework is involved and that’s much easier to do than it sounds. So easy in fact, that there is no code involved. More about that next time. Stay tuned!

More information

QnA Maker – https://www.qnamaker.ai
Pricing – https://aka.ms/qnamaker-pricing
Markdown – https://en.wikipedia.org/wiki/Markdown
Markdown Cheatsheet – https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

One Comment Add yours

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s