Using subscription keys with your LUIS app

When you first use Language Understanding (LUIS), you do not need to create subscription keys. You are given 1000 endpoint queries to begin with.

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 prediction endpoint runtime resource in the Azure portal

You create the prediction endpoint resource in the Azure portal. This resource should only be used for endpoint prediction queries. Do not use this resource for authoring changes to the app.

You can create a Language Understanding resource or a Cognitive Services resource. If you are creating a Language Understanding resource, a good practice is to postpend the resource type to the resource name.

Using resource from LUIS portal

If you are using the resource from the LUIS portal, you do not need to know your key and location. Instead you need to know your resource tenant, subscription, and resource name.

Once you assign your resource to your LUIS app in the LUIS portal, the key and location are provided as part of the query prediction endpoint URL in the Manage section's Keys and Endpoint settings page.

Using resource from REST API or SDK

If you are using the resource from the REST API(s) or SDK, you need to know your key and location. This information is provided as part of the query prediction endpoint URL in the Manage section's Keys and Endpoint settings page as well as in the Azure portal, on the resource's Overview and Keys pages.

Assign resource key to LUIS app in LUIS Portal

Every time you create a new resource for LUIS, you need to assign the resource to the LUIS app. After it's assigned, you won't need to do this step again unless you create a new resource. You might create a new resource to expand the regions of your app or to support a higher number of prediction queries.

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 do 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.

Fix HTTP status code 403 and 429

You get 403 and 429 error status codes when you exceed the transactions per second or transactions per month for your pricing tier.

When you receive an HTTP 403 error status code

When you use all those free 1000 endpoint queries or you exceed your pricing tier's monthly transactions quota, you receive an HTTP 403 error status code.

To fix this error, you need to either change your pricing tier to a higher tier or create a new resource and assign it to your app.

Solutions for this error include:

  • In the Azure portal, on your Language Understanding resource, on the Resource Management -> Pricing tier, change your pricing tier to a higher TPS tier. You don't need to do anything in the Language Understanding portal if your resource is already assigned to your Language Understanding app.
  • If your usage exceeds the highest pricing tier, add more Language Understanding resources with a load balancer in front of them. The Language Understanding container with Kubernetes or Docker Compose can help with this.

When you receive an HTTP 429 error status code

This status code is returned when your transactions per second exceeds your pricing tier.

Solutions include:

  • You can increase your pricing tier, if you are not at the highest tier.
  • If your usage exceeds the highest pricing tier, add more Language Understanding resources with a load balancer in front of them. The Language Understanding container with Kubernetes or Docker Compose can help with this.
  • You can gate your client application requests with a retry policy you implement yourself when you get this status code.

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.