Passing in wordsets

This reference topic clarifies the use of inline wordsets to improve Dialog’s ability to make sense of user inputs.

What is a wordset?

In ASRaaS and NLUaaS, wordsets are used to help boost performance of recognition and interpretation of values for dynamic list entities. Dynamic list entities are list entities where the entity can take on several different values, and where the set of possible values can only be fully specified at runtime. Wordsets are collections of words brought in at runtime to dynamically specify the allowed values for one or more entities. In DLGaaS, wordsets are passed in to data access nodes using dynamic entity data variables.

Use cases for wordsets

There are two different scenarios where wordsets can be useful:

  • Values personalized to or configured by the user, for example a banking customer’s list of cash transfer payees
  • Values specified by the application relevant to the current session, for example the specific drinks currently available from a coffee shop chain in the user’s location

Wordsets improve performance for interpretation and recognition by more completely delineating the possible values that ASRaaS and NLUaaS should expect to encounter in the present context for specified entities.

Inline vs compiled wordsets in ASRaaS and NLUaaS

In ASRaaS and NLUaaS, wordsets can be passed to the service in one of two ways:

  • Inline
  • Compiled

Inline wordsets are used for entities with a modest number of possible values (No more than 100 total items). Inline wordsets are:

  • Passed in at runtime along with ASRaaS RecognitionRequest and NLUaaS InterpretRequest messages as resources
  • Compiled at runtime
  • Used as aids for making sense of user inputs

Compiled wordsets are used in ASRaaS and NLUaaS for entities with a large number of possible values (hundreds to thousands of values). Examples of this could include all of a person’s personal contacts, the staff directory of a large hospital, or a list of possible medication names.

Because of the size of these wordsets, trying to pass them in to be compiled at runtime adds undesirable or impractical amounts of latency. As a solution, ASRaaS and NLUaaS provide APIs to compile wordsets ahead of time. The Training API in ASRaaS and the Wordset API in NLUaaS provide this functionality. Once compiled, the wordsets can be referenced by URN at runtime using the regular runtime APIs of each service. This reduces the amount of latency added by using the wordset.

For details on referencing compiled wordsets in DLGaaS, see Passing in compiled resource references. The rest of this section focuses on how to use inline wordsets.

Passing inline wordsets: client-side vs server-side

In DLGaaS, inline wordsets can be passed into the session at runtime through data transfers from external systems. This could either be from the client application or from a server-side data connection. For example:

  • Using a Dialog data access node with either server-side integration or client-side integration (data access action in DLGaaS API)
  • Through the data field in the payload of a StartRequest
  Dialog server-side integration diagram  
  Dialog client-side integration diagram  

When inline wordsets are used with Dialog, the accuracy and confidence levels for recognition and interpretation of dynamic list entities are boosted. This improves the overall ability of the Dialog to understand what your users want to do and to route the Dialog accordingly to fulfill that intent.

Using wordsets with Dialog

To use inline wordsets with Dialog:

  1. Define one or more dynamic list entities in Mix.dialog or Mix.nlu by creating list entities and marking them as dynamic.

  2. Add at least a few initial values and literals for the each dynamic list entity in Mix.dialog or Mix.nlu.

  3. In Mix.nlu, for each dynamic list entity, create some annotated samples containing the entity, and train your NLU model.

  4. Create a new dynamic entity data variable in Mix.dialog. Note that dynamic entity data objects are classified as simple objects in Mix.dialog.

  5. If a data access node is to be used for the data exchange, create and configureĀ a data access node in Mix.dialog to get the dynamic entity data variable created earlier. The data access node also needs to be configured for either server-side or client-side integration with the data source.

  6. Create a question and answer node in Mix.dialog to collect your dynamic list entity.

  7. Set up your data source, whether server-side or client-side, to provide the dynamic entity data variable containing the wordset data to the data access node.

Wordsets schema

The inline wordset data is passed in the form of a dynamic entity data variable object.

A dynamic entity data variable contains one field, variable_name. This corresponds to the name of the variable created in Mix.dialog and configured to be collected by a data access node. The value for this field is a dynamic entity data object.

A dynamic entity data object contains a wordset for boosting one or more dynamic list entities. It has one or more fields with names of the form entity_name. Here, each entity_name corresponds to the name of one dynamic list entity that is being provided with values. The value for each entity_name field is an array of dynamic entity data items. Each dynamic entity data item describes one value for the corresponding dynamic list entity. In DLGaaS, the following fields can be used:

Dynamic entity data item fields description
Element Type Description Used by
canonical String The value of the entity. Ignored by ASR. NLU, DLG
literal String The written form of the value, and the default for the canonical or spoken values. ASR, NLU, DLG
spoken Array (Optional) One or more spoken forms of the value. Ignored by NLU. ASR
label String (Optional) A label, such as the text to show on a button DLG
image_url String (Optional) A link (URL or relative path) for the image to use on a button DLG
description String (Optional) A description DLG

As can be seen in the table, some of these fields are used by NLU and/or ASR, while others are used only by DLG. For example, label, image_url, and description are used in DLGaaS only to identify how to display the options in an interactive element.

The example below shows the format for a dynamic entity data variable object holding a cold drinks wordset for a coffee shop application. Where:

  • moreCoffeeTypes is the dynamic entity data variable set in Dialog.

  • COFFEE_TYPE is an entity to be boosted with a wordset. Associated with this is an array. The two entries within the array hold details related to two possible values for the entity, cold brew coffee and iced cappuccino.

                "canonical": "cold_brew",
                "literal": "cold brew",
                    "cold brew"
                "label": "Cold brew coffee",
                "image_url": "",
                "description": "Cafe Italia's famous and refreshing cold brew coffee. Great for summer."
                "canonical": "ice_capp",
                "literal": "iced cappuccino",
                    "iced kapucheeno",
                    "iced kapacheeno"
                "label": "Iced cappuccino",
                "image_url": "",
                "description": "A frosty, slushy burst of coffee to beat the heat."

For more information, see Dynamic entity data specification.

Set up your data source

Your data source provides the wordset data to a data access node. The data source can use either server-side integration or client-side integration.

Server-side integration

Set up a RESTful endpoint at the server URL specified in the data access node. The endpoint will take in the specified inputs and return the specified dynamic entity data variable according to the the Wordsets schema.

For details on how to do this, see Exchanging data from the dialog application.

Client-side integration

Set up a script in your client application to handle the data access action. This script takes in specified inputs and returns the specified dynamic entity data variable according to the the Wordsets schema.

For details on how to do this, see Data access actions.

Behind the scenes behavior

Once the dynamic entity data variable is pulled into Dialog, it is available afterwards during the session for as long as needed.

Whenever a call to ASRaaS and/or NLUaaS is triggered by a DLGaaS ExecuteStream or Execute request, the wordset contained in the dynamic entity data variable will be added to the call.

For each such call to ASRaaS or NLUaaS, the dynamic entity data object is extracted from the dynamic entity data variable object, and added by Dialog as an inline wordset resource.

Recommendations and best practices

Wordsets with multiple different dynamic list entities can be passed into Dialog for use during the session.

If you’re unsure about the size of your inline wordset, test the latency.

For more details on setting up wordsets in Mix.dialog, see Dynamic list entities.