Passing in compiled resource references

Self-hosted environments: The ExternalResourceReferences variable requires version 1.1 (or later) of the Dialog service. This corresponds to engine pack 3.8 for self-hosted Mix deployments. IVR applications using Nuance Speech Suite with VoiceXML Connector require engine pack 2.4 (or later) to support external NLU and ASR precompiled resources (including compiled wordsets). IVR applications in self-hosted environments don’t support this feature. Self-hosted IVR projects and projects using an earlier version of VoiceXML Connector only support inline wordsets

This topic clarifies how to pass in compiled resources by reference. Compiled resources improve Dialog’s ability to make sense of user speech and text inputs.

As mentioned in the wordsets topic, the APIs of NLUaaS and ASRaaS allow you to compile resources ahead of time and then reference these resources by URN at runtime. The resources are then shared with ASRaaS and NLUaaS to improve recognition and interpretation.

DLGaaS supports passing in ASRaaS and NLUaaS references at runtime. These are then used in calls made by DLGaaS to ASRaaS and NLUaaS. This is accomplished using a session variable called ExternalResourceReferences.

Types of resources

The following types of resources can be referenced using an ExternalResourceReferences variable.

Where:

• context_tag is an application context tag from Mix
• name is a name for the resource
• lang is the six-letter language and country code for which the wordset applies; for example, eng-USA
• userId is a unique identifier for the user

Note that speaker profiles do not need a URI. Speaker profiles are specified by the current user_id, which is passed in with requests in the DLGaaS API.

For more information on recognition and interpretation resources, see:

• NLU wordsets
• ASR wordsets and other resources

Passing in ExternalResourceReferences

An ExternalResourceReferences variable can be passed into Dialog in three different ways:

• Via a data access node, using either client-side or server-side data access
• Via an external actions node using a Transfer action
• Via the data field in the payload of a StartRequest or UpdateRequest

Using compiled resources with Dialog

To use compiled resources by reference with Dialog:

1. If using compiled wordset resources:
   • 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 build and deploy an NLU model and DLM.
   • Compile a wordset for ASRaaS and/or NLUaaS using the Training gRPC API or Wordset gRPC API
2. If applicable, create and configure a data access node or an external actions node of Transfer action type. Use the predefined ExternalResourceReferences variable as a get data parameter to fetch references to the compiled resources.
3. Create a question and answer node in Mix.dialog to collect your inputs on which the compiled resources will be applied.
4. If using a data access node or external actions node, set up a data source to provide the value for the ExternalResourceReferences variable to be sent to Dialog.

ExternalResourceReferences schema

The value of ExternalResourceReferences is an object with two fields:

• NLUResources: A list of NLU resource reference entries
• ASRResources: A list of ASR resource reference entries

Each resource entry can have up to three fields:

• uri (required, except for speaker profiles): URN for the resource. Speaker profiles do not require a URN, because they are based on the current user_id, which is passed into the session as part of a StartRequest or UpdateRequest.
• resourceType (required): The type of resource as described in the types of resources above.
• weightValue (optional): Relative weighting to give to the resource in comparison to other resources. Applies to DLMs and compiled wordsets for ASR. See Resource weights in the ASRaaS documentation for more details.

Not all resource types will use all three fields.

The code sample below shows the format of an ExternalResourceReferences object. See above for the details that need to be specified for each URN to identify the resource.

{
	 // Resources to improve NLU interpretation
     "NLUResources": [
     {
         // NLU compiled wordset
         "uri": "urn:nuance-mix:tag:wordset:lang/contextTag/resourceName/lang/mix.nlu?=user_id=userId",
         "resourceType": "COMPILED_WORDSET"
     }],
     // Resources to improve ASR recognition
     "ASRResources": [
     {
         // ASR compiled wordset
         "uri": "urn:nuance-mix:tag:wordset:lang/contextTag/resourceName/lang/mix.asr",
         "resourceType": "COMPILED_WORDSET",
         "weightValue": 0.2
     },
     {
         // ASR domain language model
         "uri": "urn:nuance-mix:tag:model/contextTag/mix.asr?=language=lang",
         "resourceType": "DOMAIN_LM",
         "weightValue": 0.7
     },
     {
         // ASR speaker profile
          "resourceType": "SPEAKER_PROFILE"
     },
     {
         // ASR settings
         "uri": "urn:nuance-mix:tag:settings/contextTag/asr",
         "resourceType": "SETTINGS"
     }]
}

ExternalResourceReferences and the Dialog session

As with other session variables, once the set of resources is passed in, they will be available for use for the remainder of the session when DLGaaS orchestrates with ASRaaS and NLUaaS. DLGaaS will add references to these resources in any subsequent calls to ASRaaS and NLUaaS.

Updating ExternalResourceReferences values

If the client application passes in a value for the ExternalResourceReferences variable again, this will overwrite the earlier values, and the new values will be used from that point forward.