This year at Build 2018, we announced the general availability of QnAMaker as well as the new Bot Builder tools preview. One exciting new tool called LUDown allows you to easily create natural language components locally for both LUIS and QnAMaker. In this article, we’ll be providing an overview of how to use LUDown to create a QnA Maker knowledge base (KB), and publish it using the QnAMaker API command line tool.
To summarize the steps we’ll demonstrate:
- How to author QnA pairs in the new .lu format
- Create a KB model using LUDown
- Connect to a QnA service using the QnAMaker API tool
- Create a new KB and publish it
Prerequisites
Each tool in the Bot Builder tools preview is available as an npm module. Assuming you already have Node.js installed to your machine, you only need to install two npm modules to get started.
Install LUDown:
npm install -g ludown
Install QnAMaker tool:
npm install -g qnamaker
Author QnA pairs with .lu
A .lu file is a special type of markdown format, which LUDown reads and parses. Using any text editor, simply save a file using the .lu file extension. The following is the notation format to create question and answer pairs which LUDown can parse:
### ? <Question> ```markdown <The Answer> ```
In addition, you can easily define variations for a question and single answer:
### ? Who is the CEO? - who is the ceo of the company - name the CEO please - I want to know who the CEO is - tell me who's the ceo ```markdown Microsoft's CEO is Satya Nadella ```
For example, we’ll create a new sample file called qna-kb.lu :
qna-kb.lu
### ? Hello?
```markdown
Hello, I'm a bot. I'm here to anaswer your questions.
```
### ? Tell me about Redmond?
```markdown
Redmond is a city in King County, Washington, United States, located 16 miles east of Seattle.
[Click here](https://en.wikipedia.org/wiki/Redmond,_Washington) to learn more.
```
### ? Where can I learn more about QnAMaker?
```markdown
You can check out [this link](https://docs.microsoft.com/en-us/azure/cognitive-services/qnamaker/overview/overview) to
read the official QnA Maker Documentation.
```
Parse to .json with LUDown
What the LUDown tool does, is it parses a .lu file into a .json model. To parse the .lu file from above which defines our QnA pairs, within the same working directory enter the following command, passing in the name of the .lu file.
ludown parse toqna --in <file-name.lu>
The .lu file will be parsed to create a QnA Maker JSON file, which is ready for a QnA service to consume.
Create a QnA Service
You will need a live QnA service for our knowledge base to actually be published to. Click here to learn more about how to set up a QnAMaker service from the Azure marketplace. Alternatively, you can visit the QnA Maker web portal and select Create a knowledge base from the top menu, and follow the steps outlined.
Publishing your QnA Knowledge Base
The primary requirement to publish your knowledge base is a valid Azure subscription key, with an endpoint to the QnAMaker API.
Select ‘Keys’, or click on the link under step 1 of the under Resource Management menu of your service. Copy and save one of the two existing keys you’d like to use to deploy your knowledge base in the next step.
Click here to learn more about Keys in for QnA Maker.
QnAMaker API tool
The QnAMaker API tool allows you to interact with a QnA Maker service from the command line using the QnAMaker REST API. We’ll be using this tool to create and publish our KB.
In order to connect to your QnA service, you need to create a .qnamakerrc file. This is a special JSON format file which provides the configuration settings needed to connect to your service and publish your KB. To generate this file, simply enter ‘qnamaker init‘ in your command line:
qnamaker init
You should only provide your subscription key. Hit ‘enter’ to skip setting the knowledgebase ID, and leave it blank. The knowledgebase ID (kbId) will automatically be created for you after the KB is created.
Once you have created the .qnamakerrc file, you’ll be able to connect to your service to consume the knowledge base model defined in the .json file which LUDown created. In your command line, use the qnamaker create command, providing the name of the .json file and your subscription key.
qnamaker create kb --in qna-kb.json --subscriptionKey <key> --wait true
You will be prompted to provide a new name for your knowledge base. After the knowledge base is successfully created, you will automatically be provided with a new knowledge base ID (kbId). Enter ‘yes‘ following the next prompt to update your .qnamakerrc file with the new kbId.
To verify that our knowledge base was successfully created, we can simply refresh My knowledge bases in the web portal to see if simple-qna was created.
Voila! Our knowledge base was successfully created all from the command line. It’s important to note that at this point, the knowledge base has not been deployed, and still needs to be published in order for applications to use it.
To publish our knowledge base, in the command line enter:
qnamaker publish kb "Your-KnowledgeBase-ID"
This command triggers your KB to be trained and published, and is now ready for use. And that’s it!
One last helpful tip to mention, all Bot Builder command line tools include a global help argument, ” -h ” or “–help” which you can use with any argument to display the complete list of options and descriptions for any action.
Summary
In this article we demonstrated how you can use the LUDown tool to develop QnA knowledge bases. With this new tool, you have the ability to control and edit your knowledge bases using your favorite local text editor, and rapidly publish a knowledge base for a QnA Maker service without needing to visiting the web portal.
Happy Making!
The Azure Bot Service Team.