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
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:
-
Define one or more dynamic list entities in Mix.dialog or Mix.nlu by creating list entities and marking them as dynamic.
-
Add at least a few initial values and literals for the each dynamic list entity in Mix.dialog or Mix.nlu.
-
In Mix.nlu, for each dynamic list entity, create some annotated samples containing the entity, and train your NLU model.
-
Create a new dynamic entity data variable in Mix.dialog. Note that dynamic entity data objects are classified as simple objects in Mix.dialog.
-
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.
-
Create a question and answer node in Mix.dialog to collect your dynamic list entity.
-
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:
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.
{
"moreCoffeeTypes":
{
"COFFEE_TYPE":
[
{
"canonical": "cold_brew",
"literal": "cold brew",
"spoken":
[
"cold brew"
],
"label": "Cold brew coffee",
"image_url": "https://www.cafeitalia.com/images/drinks.cold/cold_brew.png",
"description": "Cafe Italia's famous and refreshing cold brew coffee. Great for summer."
},
{
"canonical": "ice_capp",
"literal": "iced cappuccino",
"spoken":
[
"iced kapucheeno",
"iced kapacheeno"
],
"label": "Iced cappuccino",
"image_url": "https://www.cafeitalia.com/images/drinks/cold/ice_cap.png",
"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.
Warning:
Inline wordsets need to be compiled at runtime by NLUaaS and ASRaaS, so overly large wordsets can add undesirable latency at runtime. Inline wordsets should not have more than 100 total entries across all the entities supported by the wordset.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.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.