Create LUIS resources

Authoring and query prediction runtime resources provide authentication to your LUIS app and prediction endpoint.

LUIS resources

LUIS allows three types of Azure resources and one non-Azure resource:

Resource Purpose Cognitive service kind Cognitive service type
Authoring Resource Allows you to create, manage, train, test and publish your applications. Create a LUIS authoring resource if you intend to author LUIS apps programtically or from the LUIS Portal. You need to first migrate your LUIS account to be able to link your Azure authroring resources to your application. You can control permissions to the authoring resource by assigning people to the contributor role.

There is one tier avialable for the LUIS authoring resource:
* Free F0 Authoring resource whcih gives you 1M Free authoring transactions and 1000 free testing prediction endpoint requests monthly.
LUIS.Authoring Cognitive Services
Prediction Resource After you publish your LUIS application, use the prediction resource/key to query prediction endpoint requests. Create a LUIS prediction resource before your client app requests predictions beyond the 1,000 requests provided by the Authoring or the starter resource.

There are two tiers avialble for the prediction resource:
* Free F0 Prediction resource which gives you 10,000 free prediction endpoint requests monthly
* Standard S0 Prediction resource which is the paid tier. Learn more about the pricing details
LUIS Cognitive Services
Starter/Trial Resource Allows you to create, manage, train, test and publish your applications. This is created by deafult if you choose the starter resource option while first signing up tp LUIS. However, the starter key will eventually be deprecated and all LUIS users will need to migrate their accounts and link their LUIS applications to an authoring resource. This resource does not give you permissions for Azure role-based access control like the authoring resource.

Just as the authoring resource, the starter resource gives you 1M Free authoring transactions and 1000 free testing prediction endpoint requests.
- Not an Azure resource
Cognitive Service multi-service resource key Query prediction endpoint requests shared with LUIS and other supported Cognitive Services. CognitiveServices Cognitive Services

Note

There are two types of F0 (free tier) resources that LUIS provides. One for authoring transactions and one for prediction transactions. If you are running out of free quota for prediction transactions, make sure that you are in fact using the F0 prediction resource that gives you a 10,000 free transactions monthly and not the authoring resource that gives you 1000 prediction transactions monthly.

When the Azure resource creation process is finished, assign the resource to the app in the LUIS portal.

It is important to author LUIS apps in regions where you want to publish and query.

Resource ownership

An Azure resource, such as a LUIS, is owned by the subscription containing the resource.

To transfer ownership of a resource, you can either:

  • Transfer ownership of your subscription
  • Export the LUIS app as a file, then import app on a different subscription. Export is available from the My apps page in the LUIS portal.

Resource limits

Authoring key creation limits

You can create up to 10 authoring keys per region per subscription.

See Key Limits and Azure regions.

Publishing regions are different from authoring regions. Make sure you create an app in the authoring region corresponding to the publishing region you want your client application to be located.

Key usage limit errors

Usage limits are based on the pricing tier.

If you exceed your transactions-per-second (TPS) quota, you receive an HTTP 429 error. If you exceed your transaction-per-month (TPS) quota, you receive an HTTP 403 error.

Reset authoring key

For authoring resource migrated apps: if your authoring key is compromised, reset the key in the Azure portal on the Keys page for that authoring resource.

For apps that have not migrated yet: the key is reset on all your apps in the LUIS portal. If you author your apps via the authoring APIs, you need to change the value of Ocp-Apim-Subscription-Key to the new key.

Regenerate Azure key

Regenerate the Azure keys from the Azure portal, on the Keys page.

App Ownership, access, and security

An app is defined by its Azure resources, which is determined by the owner's subscription.

You can move your LUIS app. Use the following documentation resources in the Azure portal or Azure CLI:

Contributions from other authors

For authoring resource migrated apps: contributors are managed in the Azure portal for the authoring resource, using the Access control (IAM) page. Learn how to add a user, using the collaborator's email address and the contributor role.

For apps that have not migrated yet: all collaborators are managed in the LUIS portal from the Manage -> Collaborators page.

Query prediction access for private and public apps

For a private app, query prediction runtime access is available for owners and contributors. For a public app, runtime access is available to everyone that has their own Azure Cognitive Service or LUIS runtime resource, and has the public app's ID.

Currently, there isn't a catalog of public apps.

Authoring permissions and access

Access to the app from the LUIS portal or the authoring APIs is controlled by the Azure authoring resource.

The owner and all contributors have access to author the app.

Authoring access includes Notes
Add or remove endpoint keys
Exporting version
Export endpoint logs
Importing version
Make app public When an app is public, anyone with an authoring or endpoint key can query the app.
Modify model
Publish
Review endpoint utterances for active learning
Train

Prediction endpoint runtime access

Access to query the prediction endpoint is controlled by a setting on the Application Information page in the Manage section.

Private endpoint Public endpoint
Available to owner and contributors Available to owner, contributors, and anyone else that knows app ID

You can control who sees your LUIS runtime key by calling it in a server-to-server environment. If you are using LUIS from a bot, the connection between the bot and LUIS is already secure. If you are calling the LUIS endpoint directly, you should create a server-side API (such as an Azure function) with controlled access (such as AAD). When the server-side API is called and authenticated and authorization is verified, pass the call on to LUIS. While this strategy doesn't prevent man-in-the-middle attacks, it obfuscates your key and endpoint URL from your users, allows you to track access, and allows you to add endpoint response logging (such as Application Insights).

Runtime security for private apps

A private app's runtime is only available to the following:

Key and user Explanation
Owner's authoring key Up to 1000 endpoint hits
Collaborator/contributor authoring keys Up to 1000 endpoint hits
Any key assigned to LUIS by an author or collaborator/contributor Based on key usage tier

Runtime security for public apps

Once an app is configured as public, any valid LUIS authoring key or LUIS endpoint key can query your app, as long as the key has not used the entire endpoint quota.

A user who is not an owner or contributor, can only access a public app's runtime if given the app ID. LUIS doesn't have a public market or other way to search for a public app.

A public app is published in all regions so that a user with a region-based LUIS resource key can access the app in whichever region is associated with the resource key.

Securing the query prediction endpoint

You can control who can see your LUIS prediction runtime endpoint key by calling it in a server-to-server environment. If you are using LUIS from a bot, the connection between the bot and LUIS is already secure. If you are calling the LUIS endpoint directly, you should create a server-side API (such as an Azure function) with controlled access (such as AAD). When the server-side API is called and authentication and authorization are verified, pass the call on to LUIS. While this strategy doesn't prevent man-in-the-middle attacks, it obfuscates your endpoint from your users, allows you to track access, and allows you to add endpoint response logging (such as Application Insights).

Sign in to LUIS portal and begin authoring

  1. Sign in to LUIS portal and agree to the terms of use.

  2. Begin your LUIS app by choosing your Azure LUIS authoring key.

    Choose a type of Language Understanding authoring resource

  3. When you are done with your resource selection process, create a new app.

Create LUIS resources in Azure portal

  1. Use this link to begin creating LUIS resources in the Azure portal.

  2. Enter all required settings:

    Name Purpose
    Subscription name the subscription that will be billed for the resource.
    Resource group A custom resource group name you choose or create. Resource groups allow you to group Azure resources for access and management.
    Name A custom name you choose, used as your custom subdomain for your authoring and prediction endpoint queries.
    Authoring location The region associated with your model.
    Authoring pricing tier The pricing tier determines the maximum transaction per second and month.
    Runtime location The region associated with your published prediction endpoint runtime.
    Runtime pricing tier The pricing tier determines the maximum transaction per second and month.

    Create the language understanding resource

  3. Click Review + create and wait for the resource to be created.

  4. After both resources are created, still in the Azure portal, select the new authoring resource, then Quickstarts to get the authoring endpoint URL and key for authoring programmatically.

Tip

To use the resources, in the LUIS portal, assign the resources.

Create resources in Azure CLI

Use the Azure CLI to create each resource individually.

Resource kind:

  • Authoring: LUIS.Authoring
  • Prediction: LUIS
  1. Sign in to the Azure CLI:

    az login
    

    This opens a browser to allow you to select the correct account and provide authentication.

  2. Create a LUIS authoring resource, of kind LUIS.Authoring, named my-luis-authoring-resource in the existing resource group named my-resource-group for the westus region.

    az cognitiveservices account create -n my-luis-authoring-resource -g my-resource-group --kind LUIS.Authoring --sku F0 -l westus --yes
    
  3. Create a LUIS prediction endpoint resource, of kind LUIS, named my-luis-prediction-resource in the existing resource group named my-resource-group for the westus region. If you want a higher throughput than the free tier, change F0 to S0. Learn more about pricing tiers and throughput.

    az cognitiveservices account create -n my-luis-prediction-resource -g my-resource-group --kind LUIS --sku F0 -l westus --yes
    

    Note

    This keys are not used by the LUIS portal until they are assigned in the LUIS portal on the Manage -> Azure resources.

Assign resource in the LUIS portal

You can assign an authoring resource for a single app or for all apps in LUIS. The following procedure assigns all apps to a single authoring resource.

  1. Sign in to the LUIS portal.
  2. At the top navigation bar, to the far right, select your user account, then select Settings.
  3. On the User Settings page, select Add authoring resource then select an existing authoring resource. Select Save.

Assign a resource to an app

Please note that if you do not have an Azure subscription, you will not be able to assign or create a new resource. You will have to first go and create an Azure Free Trial then return to LUIS to create a new resource from the portal.

You can assign or create an authoring or a prediction resource to an application with the following procedure:

  1. Sign in to the LUIS portal, then select an app from the My apps list

  2. Navigate to the Manage -> Azure resources page

    Select the Manage -> Azure resources in the LUIS portal to assign a resource to the app.

  3. Select the Prediction or Authoring resource tab then select the Add prediction resource or Add authoring resource button

  4. Select the fields in the form to find the correct resource, then select Save

  5. If you dont have an exisiting resource, you can create one by selecting "Create a new LUIS resource?" from the bottom of the window

Assign query prediction runtime resource without using LUIS portal

For automation purposes such as a CI/CD pipeline, you may want to automate the assignment of a LUIS runtime 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 runtime resources across subscriptions, from the Get LUIS Azure accounts API, which 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.

Unassign resource

  1. Sign in to the LUIS portal, then select an app from the My apps list.
  2. Navigate to the Manage -> Azure resources page.
  3. Select the Prediction or Authoring resource tab then select the Unassign resource button for the resource.

When you unassign a resource, it is not deleted from Azure. It is only unlinked from LUIS.

Delete account

See Data storage and removal for information about what data is deleted when you delete your account.

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.

Viewing Azure resource metrics

Viewing Azure resource 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 Azure resource 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