Using subscription keys with your LUIS app

You do not need to create subscription keys to use your free first-1000 endpoint queries. Once those endpoint queries are used, create an Azure resource in the Azure portal, then assign that resource to a LUIS app in the LUIS portal.

If you receive an out of quota error in the form of an HTTP 403 or 429, you need to create a key and assign it to your app.

For testing and prototype only, use the free (F0) tier. For production systems, use a paid tier. Do not use the authoring key for endpoint queries in production.

Create Language Understanding endpoint key in the Azure portal

This procedure creates a Language Understanding resource. If you want a resource that can be used across Cognitive Services, create the all-in-one key Cognitive Service instead of the Language Understanding resource.

This key should only be used for endpoint prediction queries. Do not sure this key for changes to the model or app.

  1. Sign in to the Azure portal.
  2. Select the green + sign in the upper left-hand panel and search for Language Understanding in the marketplace, then select on Language Understanding and follow the create experience to create a LUIS subscription account.

    Azure Search

  3. Configure the subscription with settings including account name, pricing tiers, etc.

    Azure API Choice

  4. Once you create the Language Understanding resource, you can view the access keys generated in Resource Management->Keys. Do not the keys. The next section will show you how to connect this new resource to a LUIS app in the LUIS portal. You need the name of the LUIS resource from step 3.

    Azure Keys

Assign resource key to LUIS app in LUIS Portal

  1. Sign in to the LUIS portal, choose an app to add the new key to, then select Manage in the top-right menu, then select Keys and endpoints.

    Keys and endpoints page

  2. In order to add the LUIS, select Assign Resource +.

    Assign a resource to your app

  3. Select a Tenant in the dialog associated with the email address your login with to the LUIS website.

  4. Choose the Subscription Name associated with the Azure resource you want to add.

  5. Select the LUIS resource name.

  6. Select Assign resource.

  7. Find the new row in the table and copy the endpoint URL. It is correctly constructed to make an HTTP GET request to the LUIS endpoint for a prediction.

Unassign resource

When you unassign the endpoint key, it is not deleted from Azure. It is only unlinked from LUIS.

When an endpoint key is unassigned, or not assigned to the app, any request to the endpoint URL returns an error: 401 This application cannot be accessed with the current subscription.

Include all predicted intent scores

The Include all predicted intent scores checkbox allows the endpoint query response to include the prediction score for each intent.

This setting allows your chatbot or LUIS-calling application to make a programmatic decision based on the scores of the returned intents. Generally the top two intents are the most interesting. If the top score is the None intent, your chatbot can choose to ask a follow-up question that makes a definitive choice between the None intent and the other high-scoring intent.

The intents and their scores are also included the endpoint logs. You can export those logs and analyze the scores.

{
  "query": "book a flight to Cairo",
  "topScoringIntent": {
    "intent": "None",
    "score": 0.5223427
  },
  "intents": [
    {
      "intent": "None",
      "score": 0.5223427
    },
    {
      "intent": "BookFlight",
      "score": 0.372391433
    }
  ],
  "entities": []
}

Enable Bing spell checker

In the Endpoint url settings, the Bing spell checker toggle allows LUIS to correct misspelled words before prediction. Create a Bing Spell Check key.

Add the spellCheck=true querystring parameter and the bing-spell-check-subscription-key={YOUR_BING_KEY_HERE} . Replace the {YOUR_BING_KEY_HERE} with your Bing spell checker key.

{
  "query": "Book a flite to London?",
  "alteredQuery": "Book a flight to London?",
  "topScoringIntent": {
    "intent": "BookFlight",
    "score": 0.780123
  },
  "entities": []
}

Publishing regions

Learn more about publishing regions including publishing in Europe, and Australia. Publishing regions are different from authoring regions. Create an app in the authoring region corresponding to the publishing region you want for the query endpoint.

Assign resource without LUIS portal

For automation purposes such as a CI/CD pipeline, you may want to automate the assignment of a LUIS resource to a LUIS app. In order to that, you need to perform the following steps:

  1. Get an Azure Resource Manager token from this website. This token does expire so use it immediately. The request returns an Azure Resource Manager token.

    Request  Azure Resource Manager token and receive  Azure Resource Manager token

  2. Use the token to request the LUIS resources across subscriptions, from the Get LUIS azure accounts API, your user account has access to.

    This POST API requires the following settings:

    Header Value
    Authorization The value of Authorization is Bearer {token}. Notice that the token value must be preceded by the word Bearer and a space.
    Ocp-Apim-Subscription-Key Your authoring key.

    This API returns an array of JSON objects of your LUIS subscriptions including subscription ID, resource group, and resource name, returned as account name. Find the one item in the array that is the LUIS resource to assign to the LUIS app.

  3. Assign the token to the LUIS resource with the Assign a LUIS azure accounts to an application API.

    This POST API requires the following settings:

    Type Setting Value
    Header Authorization The value of Authorization is Bearer {token}. Notice that the token value must be preceded by the word Bearer and a space.
    Header Ocp-Apim-Subscription-Key Your authoring key.
    Header Content-type application/json
    Querystring appid The LUIS app ID.
    Body {"AzureSubscriptionId":"ddda2925-af7f-4b05-9ba1-2155c5fe8a8e",
    "ResourceGroup": "resourcegroup-2",
    "AccountName": "luis-uswest-S0-2"}

    When this API is successful, it returns a 201 - created status.

Change pricing tier

  1. In Azure, find your LUIS subscription. Select the LUIS subscription. Find your LUIS subscription
  2. Select Pricing tier in order to see the available pricing tiers. View pricing tiers
  3. Select the pricing tier and select Select to save your change. Change your LUIS payment tier
  4. When the pricing change is complete, a pop-up window verifies the new pricing tier. Verify your LUIS payment tier
  5. Remember to assign this endpoint key on the Publish page and use it in all endpoint queries.

How to fix out-of-quota errors when the key exceeds pricing tier usage

Each tier allows endpoint requests to your LUIS account at a specific rate. If the rate of requests is higher than the allowed rate of your metered account per minute or per month, requests receive an HTTP error of "429: Too Many Requests."

Each tier allows accumulative requests per month. If the total requests are higher than the allowed rate, requests receive an HTTP error of "403: forbidden".

Viewing summary usage

You can view LUIS usage information in Azure. The Overview page shows recent summary information including calls and errors. If you make a LUIS endpoint request, then immediately watch the Overview page, allow up to five minutes for the usage to show up.

Viewing summary usage

Customizing usage charts

Metrics provides a more detailed view into the data.

Default metrics

You can configure your metrics charts for time period and metric type.

Custom metrics

Total transactions threshold alert

If you would like to know when you have reached a certain transaction threshold, for example 10,000 transactions, you can create an alert.

Default alerts

Add a metric alert for the total calls metric for a certain time period. Add email addresses of all people that should receive the alert. Add webhooks for all systems that should receive the alert. You can also run a logic app when the alert is triggered.

Next steps

Learn how to use versions to manage changes to your LUIS app.