Tutorial: Build LUIS app to determine user intentions

In this tutorial, you create a custom app that predicts a user's intention based on the utterance (text).

Note

This document uses the preview LUIS portal.

In this tutorial, you learn how to:

  • Create a new app
  • Create intents
  • Add example utterances
  • Train app
  • Publish app
  • Get intent prediction from endpoint

For this article, you can use the free LUIS account and its starter key in order to author your LUIS application.

User intentions as intents

The purpose of the app is to determine the intention of conversational, natural language text:

I'd like to order a veggie pizza with a salad on the side.

These intentions are categorized into Intents.

Intent Purpose
ModifyOrder Determine user's pizza order.
Greeting Begin bot conversation.
ConfirmOrder Confirm pizza order.
None Determine if user is asking something the app is not supposed to answer. This intent if provided as part of app creation and can't be deleted.

Create a new app

  1. Sign in to the preview LUIS portal with the URL of https://preview.luis.ai.

  2. Select Create new app.

    Screenshot of Language Understanding (LUIS) My Apps page

  3. In the pop-up dialog, enter the name Pizza tutorial and keep the default culture, English. The other fields are optional, do not set them. Select Done.

    Enter name of new LUIS app

Create a new intent

  1. In the preview LUIS portal, inside the app's Build section, select + Create. Enter the new intent name listed below then select Done.

    The OrderPizza intent is predicted when: a user wants to order a pizza.

  2. Add several example utterances to this intent that you expect a user to ask:

    OrderPizza example utterances
    can i get a pepperoni pizza and a can of coke please
    can i get a small pizza with onions peppers and olives
    delivery for a small pepperoni pizza
    pickup a cheddar cheese pizza large with extra anchovies
    i need 2 large cheese pizzas 6 large pepperoni pizzas and 1 large supreme pizza

    Add example utterances

    By providing example utterances, you are training LUIS about what kinds of utterances should be predicted for this intent.

    These few utterances are for demonstration purposes only. A real-world app should have at least 15 utterances of varying length, word order, tense, grammatical correctness, punctuation, and word count.

Create remaining intents

  1. Create the Greeting intent and add the following example utterances. This is the intent to determine if a user is beginning a new pizza order conversation.

    Greeting example utterances
    Hi
    Hello
    Hey
    Start
    Begin
  2. Create the Confirm intent and add the following example utterances. This is the intent to determine if a user is done ordering and accepts the order details.

    Confirm example utterances
    Go ahead
    ok
    Yes
    Sure

None intent example utterances

The client application needs to know if an utterance is not meaningful or appropriate for the application. The None intent is added to each application as part of the creation process to determine if an utterance can't be answered by the client application.

If LUIS returns the None intent for an utterance, your client application can ask if the user wants to end the conversation or give more directions for continuing the conversation.

If you leave the None intent empty, an utterance that should be predicted outside the subject domain will be predicted in one of the existing subject domain intents. The result is that the client application, such as a chat bot, will perform incorrect operations based on an incorrect prediction.

  1. Select Intents from the left panel.

  2. Select the None intent. Add three utterances that your user might enter but are not relevant to your app:

    None example utterances
    Barking dogs are annoying
    Order a pizza for me
    Penguins in the ocean

Train the app

  1. In the top right side of the LUIS website, select the Train button.

    Train button

  2. Training is complete when you see the status confirming success.

    Tip

    Notifications is available in the top-right navigation and includes a history.

Publish the app

In order to receive a LUIS prediction in a chat bot or other client application, you need to publish the app to the endpoint.

  1. Select Publish in the top right navigation.

    LUIS publish to endpoint button in top right menu

  2. Select the Production slot and the Publish button.

    LUIS publish to endpoint

  3. Publishing is complete when you see the green status bar at the top of the website confirming success.

    LUIS publish to endpoint

  4. Select the Access your endpoint URLs link in the notification to go to the Azure Resources page. The endpoint URLs are listed as the Example Query.

Get intent prediction

  1. In the Manage section (top right menu), on the Azure Resources page (left menu), copy the Example Query URL then paste into a new browser tab.

    The endpoint URL looks like the following format, with your own app ID and endpoint key replacing APP-ID and KEY-ID:

    https://westus.api.cognitive.microsoft.com/luis/prediction/v3.0/apps/APP-ID/slots/production/predict?subscription-key=KEY-ID&verbose=true&show-all-intents=true&log=true&query=YOUR_QUERY_HERE
    
  2. Go to the end of the URL in the address bar and enter:

    get a medium vegetarian pizza for delivery

    This is not exactly the same as an example utterance so it is a good test to see if LUIS can learn what should be predicted with this intent.

    The last query string parameter is q, the utterance query. This utterance is not the same as any of the example utterances. It is a good test and should return the OrderPizza intent as the top scoring intent.

    {
        "query": "get a medium vegetarian pizza for delivery",
        "prediction": {
            "topIntent": "OrderPizza",
            "intents": {
                "OrderPizza": {
                    "score": 0.6488959
                },
                "None": {
                    "score": 0.139966831
                },
                "Confirm": {
                    "score": 0.00736504374
                },
                "Greeting": {
                    "score": 0.003970454
                }
            },
            "entities": {}
        }
    }
    

    The entities array is empty because this app currently does not have any entities.

    The JSON result identifies the top scoring intent as prediction.topIntent property. All scores are between 1 and 0, with the better score being closer to 1.

  3. Change the URL query parameter to target the Greeting intent:

    Howdy

    This is not exactly the same as an example utterance so it is a good test to see if LUIS can learn what should be predicted with this intent.

    {
        "query": "howdy",
        "prediction": {
            "topIntent": "Greeting",
            "intents": {
                "Greeting": {
                    "score": 0.446016937
                },
                "Confirm": {
                    "score": 0.2390079
                },
                "None": {
                    "score": 0.09119555
                },
                "OrderPizza": {
                    "score": 0.00109590159
                }
            },
            "entities": {}
        }
    }    
    

    This prediction has a 44% confidence score. To increase the confidence score, add between 15 and 30 example utterances.

Client-application next steps

After LUIS returns the JSON response, LUIS is done with this request. LUIS doesn't provide answers to user utterances, it only identifies what type of information is being asked for in natural language. The conversational follow-up is provided by the client application such as an Azure Bot.

Clean up resources

When no longer needed, delete the LUIS app. To do so, select My apps from the top left menu. Select the ellipsis (...) to the right of the app name in the app list, select Delete. On the pop-up dialog Delete app?, select Ok.

Next steps

This tutorial created a LUIS app, created intents, added example utterances to each intent, added example utterances to the None intent, trained, published, and tested at the endpoint. These are the basic steps of building a LUIS model.