Using Grammars in ASR Requests

In grammar-based recognition, the grammar is part of every request, so how you deliver it affects latency, reliability, and what the engine can match. The decisions are practical: send the grammar text or a URL, load a grammar once and reuse it or send it each time, run one grammar or several together, and use a lexicon to reconcile what the engine hears with the form your grammar expects. This article covers those decisions for both the gRPC and MRCP interfaces, and what the platform does behind the scenes so you can make them well.

Writing grammars is covered elsewhere. To learn to author grammars, start with A SRGS Introduction and A Simple Grammar, then see Intro to Semantic Interpretation for returning structured results. For the gRPC call sequence around these requests, see ASR gRPC Integration.

Ways to supply a grammar

A grammar reaches the engine in one of four ways. The right one depends on how often the grammar changes and how often it is used.

Grammars cannot be loaded at the deployment (global) level, and the global_grammar_label field is deprecated. For the built-in grammars, see Builtin Grammars. For the MRCP methods, see Recognizer DEFINE-GRAMMAR and Recognizer RECOGNIZE. A URL must include its scheme, such as https://. See URIs and Capacity.

Compiling and caching

The engine cannot read a grammar until it has been compiled into a binary form. It keeps compiled grammars in a cache, so a large grammar is compiled once and reused on later requests, as long as the grammar has not changed. Most compilation is nearly instant, so you notice it only on unusually large or complex grammars.

What happens when you supply a URL

When a grammar is supplied by URL, the platform fetches it over HTTP or HTTPS, and it caches what it fetches so that a grammar requested hundreds of times a second is not downloaded every time.

• The cache is keyed by the exact URL, including the query string. A different query string is a different cache entry.
• A cached grammar is reused without any network request while it is fresh. The default freshness is 300 seconds (5 minutes).
• When the entry is stale, the platform revalidates it with a conditional request if the server supplied an ETag. A 304 Not Modified response lets it reuse the cached content without downloading the grammar again.
• You can set the freshness for one grammar with a Cache-Control query parameter on the URL, such as ?Cache-Control=max-age%3D600. Percent-encode the equals sign.

The full mechanism, including the other URL parameters, is in HTTP Caching.

Practical guidance

• Load big grammars ahead of time. Loading a grammar before recognition starts (session_load_grammar in gRPC, DEFINE-GRAMMAR in MRCP) moves the download and compile work off the critical path of the recognition.
• To force a refresh, change the URL. Because the cache is keyed by the exact URL, adding or changing a query parameter fetches a fresh copy, which is useful when you publish a new grammar version.
• Keep the load timeout in mind. A grammar that takes too long to load raises a timeout error. The limit is grammar_settings.load_grammar_timeout_ms, and a grammar larger than grammar_threshold fails to load. See the ASR & Transcription Settings Reference.
• Verify certificates for HTTPS grammars. grammar_settings.ssl_verify_peer is true by default, so the server’s certificate must be trusted.

Using multiple grammars

You can use several grammars in the same request. The engine searches all of them for a match. For example, you could activate a yes/no grammar, a digits grammar, and a grammar containing the word “representative” at once, to catch whichever the caller says. In gRPC, list them in grammars, one entry for each root grammar to activate. In MRCP, specify them in the RECOGNIZE request.

Field names are shown as they appear in the API reference.

When grammars overlap

On rare occasions the same word appears in more than one grammar. If that is not intended, decide which grammar should keep the word and remove it from the others. If it is intended, the engine selects the first match it finds, and that match determines the final semantic interpretation. The other matches are still returned: they appear in the semantic_interpretations list of the result, and you can view them in the Analysis Portal.

Give each grammar a label. Each semantic interpretation reports the grammar_label of the grammar that produced it, so labels let your application tell which grammar matched. Labels can contain only letters, digits, hyphens, and underscores. To prefer one grammar over another, you can also set a grammar_weight. See Applying Grammar Weights.

Lexicons and aliases

Sometimes the engine hears a word correctly but not in the form your application or grammar expects. A lexicon lets you correct that. The most useful tool in a lexicon is the alias: it tells the platform that when it recognizes word A, it should treat it as word B. Aliases help predicted words match your grammar entries, and produce the written form of a domain term that the engine would otherwise spell differently.

The platform supports the W3C Pronunciation Lexicon Specification (PLS). Of its elements, these work in your lexicons:

Here is a lexicon with two aliases. The first replaces the recognized word “vulnerable” with “SHAKY”. The second makes the recognized text “eye phone” come out as “iPhone”:

Reference the lexicon from your grammar by URI, as you would an external grammar. A grammar can reference external grammars and lexicons by URL. See URIs and Capacity. For the exact syntax of the elements, see the W3C Pronunciation Lexicon Specification.

gRPC and MRCP at a glance

Troubleshooting

Related Articles

• A SRGS Introduction
• Using GrXML Grammars
• Intro to Semantic Interpretation
• Builtin Grammars
• HTTP Caching
• URIs and Capacity
• Recognizer DEFINE-GRAMMAR
• Recognizer RECOGNIZE
• Speech Products: ASR & Transcription
• Problems Loading or Using Grammars