Constructing a TRSX file

This section describes how to construct a training set XML (TRSX) file from which you can buld a DLM in Mix.

What is a TRSX file?

A TRSX file is an XML file that can be imported to create the content of a Mix.nlu project. A TRSX file represents the Mix.nlu component of a project, for a specific language, in XML form. It defines intents and entities for a project, and can contain training samples, including annotations. The TRSX format is a Nuance specification. For full details on the format, see the TRSX specification reference.

Mix provides a front-end GUI to edit the DLM samples and entities, but you can also create the TRSX using an external tool and import it into Mix if preferred.

TRSX requirements for DLMs

A TRSX file created specifically to build a DLM only can often be simpler than that for a project from which an NLU model will also be built. However, some elements are either required by Mix or are useful to creating a more effective DLM.

Project language

The xml:lang attribute of the project tag must be specified with the language and locale, in abc-DEF format. For example, eng-USA.

A single TRSX file can only handle samples for one language/locale. If your project will use multiple languages, you need to build a separate TRSX file for each one.

For Mix hosted applications, the languages available depend on the geography where you are deploying your application. For more information, see Geographies.

For self-hosted applications, the languages available depend on the Nuance language data packs that are included in your installation.

Intents

NLU intents relate to helping an NLU model learn to interpret the semantic meaning of a user utterance using the NLU service. They do not generally play a part in speech recognition. However, Mix does not build, even for a DLM-only build, unless a Mix.nlu project contains at least one custom intent. For DLM-only builds, this can be a “dummy” intent like SOME_INTENT.

Intents and sample sentences

Mix also requires that you assign an intent to sample sentences to include them in training or a build. If no sentences are assigned an intent, you are not able to train or build. For a DLM-only build, assign all samples to the custom dummy intent by marking the sample elements with intentref tags.

Entities and sample sentences

Entities, and entity annotations can be included in sample sentences, but are not stricly required for a DLM-only build.

Tip:

While entities are not needed to build a DLM, you do need to define entities in order to use wordsets. Wordsets in speech applications build on entities defined in DLMs.

Sample counts

Each sample in the TRSX can be assigned an associated count. If not set, by default the count is set to one. Setting the count value higher than one increases the relative weight of the sample in comparison to other samples. Ideally, these counts should be derived from the frequencies in existing deployment data so that it recognizes that certain utterances come up often. But if this data is not available the developer can also set the count manually to distinguish common samples from rare samples.

Dictionary node and entity literals

There are two ways you can curate your DLM training data in a TRSX file:

Explicit samples
Implicit grammar-based samples

You can explicitly spell out each distinct possible sample you want to train on.

<sample intentref="SOME_INTENT">A coffee please</sample>
<sample intentref="SOME_INTENT">An americano please</sample>
<sample intentref="SOME_INTENT">An espresso please</sample>
<sample intentref="SOME_INTENT">Can you get me a large coffee</sample>

Notice here that the first three utterances are the same except for the type of coffee. They share a common grammar.

Alternatively, you can include an entity dictionary defining entity literals and samples that use that entity. This allows Mix to create implicit grammar-based samples. Similar to NLU intents, canonical entity values are related to semantic meaning and do not play a role in speech recognition. However, entity literals just describe the specific wordings that can be used to instantiate the entity. For list collection type entities, defining literals can be useful when samples include list entity annotations. The literals help the DLM generalize to recognize new utterances similar to ones in the training set, but with one literal substituted for another.

For example:

<dictionary conceptref="DRINK_TYPE">
    <entry literal="coffee" value="filter_coffee"/>
    <entry literal="americano" value="filter_coffee"/>
    <entry literal="espresso" value="espresso"/>
</dictionary>

<sample intentref="SOME_INTENT">An <annotation conceptref="DRINK_TYPE">espresso</annotation> please</sample>

In the implicit example, ASRaaS/Krypton will boost the following sentences based on enumerating the grammar:

An coffee please
An americano please
An espresso please

Allowing Mix to construct samples from your grammar can save significant development time and provide additional coverage of sentences that may be spoken to your application. However, here are some notes to keep in mind:

With the example above, the ungrammatical sentence “An coffee please” is generated, which is not desired. You may also encounter other phrases with improper agreement, for example with singular versus plural. To work around this you can split your entities into two—for example DRINK_TYPE and DRINK_TYPE_INIT_VOWEL with two corresponding samples.
The DLM created by your TRSX does not define a strict grammar of words or phrases that can be recognized by Mix.asr. Instead, the likelihood of these sentences is boosted, so even if “An coffee please” is a sample in your TRSX, the sentence “A coffee please” could still be recognized if spoken clearly.
If a sample contains multiple instances of very large entities lists e.g. “flight from <CITY> to <CITY> between <DATE> and <DATE>”, Mix does not enumerate all possibilities, but instead samples intelligently from this distribution.
Sentences explicitly appearing in the training set are trained with a higher probability than implicit grammar-based sentences.

Ontology node

The TRSX must include an ontology node to declare any intents and entities referenced in the training samples.

File naming

TRSX files are saved using the .trsx file extension.

A TRSX file must be named in the format locale.trsx, where locale indicates the language and locale for the file. For example, en_us.trsx.

Multi-language projects

If you have a multi-language project, you will need to create and upload a separate TRSX file for each language in the project, with the file named corresponding to the language as described above.

TRSX structure

For more information on the TRSX file structure, see Mix TRSX Mode Spec.

TRSX requirements for DLM and NLU model

If your application requires both a DLM for speech recognition and an NLU model that can distinguish different intents, you need to use one project to create these. The TRSX for that project in particular needs to include all the elements mentioned above. However, in addition to this, intent and entity annotations in samples are important, and need to be more elaborate than for a DLM-only project. You also need to give additional thought to the design of the ontology and the creation of your training samples. For more details, see the NLU modeling best practices documentation.

Creating TRSX files

Contact Nuance for other tips on creating TRSX files, including tips on automating the generation of TRSX files from easier to work with text files.

Example TRSX file for DLM-only project

The following is a very simple example showing the format for a TRSX file to be used to build a DLM. Note that for the purposes of building a real production-grade DLM, the TRSX will generally be much larger, including many more samples.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<project xmlns:nuance="https://developer.nuance.com/mix/nlu/trsx" xml:lang="eng-USA" nuance:version="2.5" nuance:enginePackVersion="hosted">
    <sources>
        <source name="nuance_custom_data" displayName="nuance_custom_data" version="1.0" type="CUSTOM" useForOOV="true"/>
    </sources>
    <ontology base="http://localhost:8080/resources/ontology-1.0.xml">
        <intents>
            <intent name="SOME_INTENT"/>
        </intents>
        <concepts>
            <concept name="DRINK_TYPE" dataType = "alphanum"/>
            <concept name="DRNK_SIZE" dataType = "alphanum"/>
        </concepts>
    </ontology>
    <dictionaries>
        <dictionary conceptref="DRINK_SIZE">
            <entry literal="extra large" value="xlarge"/>
            <entry literal="large" value="large"/>
            <entry literal="medium" value="medium"/>
            <entry literal="small" value="small"/>
        </dictionary>
        <dictionary conceptref="DRINK_TYPE">
            <entry literal="coffee"/>
            <entry literal="americano"/>
            <entry literal="espresso"/>
            <entry literal="cappuccino"/>
            <entry literal="latte"/>
            <entry literal="frappuccino"/>
            <entry literal="tea"/>
            <entry literal="water"/>
        </dictionary>
    </dictionaries>
    <samples>
        <sample intentref="SOME_INTENT" count="1">An <annotation conceptref = "DRINK_TYPE">espresso</annotation> please</sample>
        <sample intentref="SOME_INTENT" count="1">Can I have a <annotation conceptref = "DRINK_SIZE">medium</annotation> <annotation conceptref = "DRINK_TYPE">coffee</annotation></sample>
        <sample intentref="SOME_INTENT" count="1"><annotation conceptref = "DRINK_SIZE">Large</annotation> <annotation conceptref = "DRINK_TYPE">coffee</annotation></sample>
        <sample intentref="SOME_INTENT" count="1">I would like a <annotation conceptref = "DRINK_SIZE">medium</annotation> <annotation conceptref = "DRINK_TYPE">cappuccino</annotation></sample>
        <sample intentref="SOME_INTENT" count="1">Get me a cup of <annotation conceptref = "DRINK_TYPE">tea</annotation></sample>
        <sample intentref="SOME_INTENT" count="1">I want a bottle of <annotation conceptref = "DRINK_TYPE">water</annotation></sample>
        <sample intentref="SOME_INTENT" count="1">I would like a <annotation conceptref = "DRINK_SIZE">small</annotation> <annotation conceptref = "DRINK_TYPE">frappuccino</annotation> please</sample>
        <sample intentref="SOME_INTENT" count="1"><annotation conceptref = "DRINK_TYPE">Coffee</annotation></sample>
    </samples>
</project>