In our last article we introduced some of the helpful new tools from the Bot Builder tools suite. To recap, first we demonstrated how to create question/answer pairs using a new special markdown file format (.lu). Then, we used the new LUDown tool to parse the file to create a knowledge base (.json), and used the QnAMaker API tool to create and publish the knowledge base to a live endpoint. What we didn’t mention in the last post, was that .lu and LUDown support creating natural language components for both QnAMaker and LUIS. In this article, we’ll go over similar steps using the new BotBuilder tools to:
- Create some LUIS intents and entities using the .lu special markdown format
- Use LUDown to parse the .lu file to create a valid LUIS model (JSON)
- Use the new LUIS API tool to connect to a LUIS service and publish the language model
Before moving on, you need to be aware of what intents and entities are in LUIS, please click the links if you need a refresher.
Prerequisites
- Node.js
- LUIS Authoring key (to publish)
- LUDown
- LUIS API tool
All BotBuilder tools are available as npm modules, so Node.js is required. Please note that they must also be installed globally to your machine.
LUDown:
// install LUDown npm install -g ludown
LUIS API tool:
// install LUIS API tool npm install -g luis-apis
Create a LUIS Model with .lu
Adding Intents
Intents can be created in .lu by prefacing with the pound (#) sign. Subsequent lines define the sample utterances used to trigger the intent. Below, we define two intents, Greeting and Help. Under each intent, are different phrases that a user may express that intent.
# Greeting Hi Hello Good morning Good evening # Help help I need help please help
Adding Entities
Entities are defined in .lu by using the format: {<entityName>=<labelled value>}
The entity in question is assigned a label using the equal sign ‘ = ‘, and both are wrapped in curly braces. For example, below we create an intent of BookFlight, and in the sample utterances created two entities, fromCity and toCity.
# BookFlight
- book a flight to {toCity=seattle}
- book a flight from {fromCity=new york} to {toCity=seattle}
Adding Patterns
Patterns can also be added as well! Patterns are a new feature in LUIS that allows you to define a set of rules that augment the machine learned model. You can define patterns in the .lu file simply by defining an entity in an utterance without a labelled value.
# DeleteAlarm
- delete the {alarmTime} alarm
Click here to read more about the .lu format.
Parse with LUDown
When you’re satisfied with your .lu file, you can easily use LUDown to parse the file to create a LUIS model in JSON format. When using LUDown, you can specify to parse to either QnA or LUIS, by selecting one of two arguments: toluis, and toqna.
ludown parse ToLuis --in ludown-file-name.lu
LUDown will search your current working directory for a .lu file with the same name, and then parse it accordingly for the target format (QnA KB or LUIS model). This will also create a JSON file which models the natural language component we want use to train our services. The last thing we need to do, is connect to the service, consume the language model and publish.
Connect to LUIS
.luisrc file is a configuration file required to connect to the LUIS API endpoint. The LUIS API tool already provides the necessary template to create this for you, to initialize this simply enter luis init in the command line.
luis init
You will be prompted to provide your LUIS authoring key, along with your region. You can find your LUIS authoring key under your user settings in the LUIS web portal, or under the keys blade of your cognitive services resource on Azure. You should skip providing a LUIS App ID, and simply leave hit enter to leave this blank. A new LUIS app ID will be provisioned for you, after it is created. Unlike QnA Maker, you don’t need to provision the App ID in order to publish your LUIS application. The App ID is simply used for the endpoint URL when your app is ready to be consumed.
One final step – actually push up our LUIS model which we created using LUDown. In the command line, enter luis import application --in file-name.json .
luis import application --in luis-app.json
Upon successful completion you’ll be prompted with a JSON stamp with some meta data properties for your recent publish to LUIS.
This will create a new LUIS model using the supplied .json file. We can easily verify that our LUIS application was successfully created, simply login to the LUIS web portal and select My apps, and you should see it displayed on the center view of your web browser. Please note that at this point, the application has not yet been trained or published.
You can view your LUIS application’s published endpoint by selecting PUBLISH on the top right corner of the web portal, and scroll down to ‘Resources and Keys‘.
Train and Publish
You can easily train + publish your model by selecting Train in the web portal. If you’d like to instead use the LUIS API tool to train or publish from the command line, you’ll need to grab the App ID from the web portal.
Train your LUIS model:
luis train version --appId <appId> --versionId <versionId>
Publish your LUIS model:
luis publish version --in luis-sample.json --appId <string> --region <region> --staging
Summary
In this article we demonstrated how to use new command line tools to create and publish LUIS applications using LUDown and the LUIS API tool. These new tools allow a user to manage and edit their LUIS applications quickly using the local command line interface, without needing to deal with the web portal interface.
Happy Making!
The Azure Bot Service Team.