Description
This article clarifies the purpose of vocabulary and vocabulary sources in the NLU Workbench and gives examples for when to use each of them.
In general, vocabulary and vocabulary sources should be used to make sure NLU Service can understand specific terms to improve predictions. Vocabulary is used to provide a generic synonym for a company or industry specific term or acronym. Vocabulary sources are used when you have a list of values (either in a ServiceNow table or your own customized list) that you want to be interpreted the same way.
This article applies to releases from Quebec onwards.
VOCABULARY
1. The synonym you provide for a vocabulary should be a replacement for the word or phrase, not a definition.
The NLU system understands vocabulary by replacing the vocabulary word in an utterance with the synonym that you provide.
DO: give the synonym “vacation” for the vocabulary “PTO”. If a user asks “How many days of PTO do I have left?”, the system understands it as “How many days of vacation do I have left?”
DON'T: give a definition for PTO, such as “employee taking time off”. In the same example as above, the system would replace it as synonym and interpret it as “How many days of employee taking time off do I have left?”, which does not make sense.
The word replacement is one-directional, meaning that “PTO” will get replaced by “vacation”, but “vacation” will not be replaced by “PTO” in utterances.
2. Only provide one synonym for each vocabulary. If you provide multiple comma separated synonyms, the system will only pick up on the first value.
The NLU model picks up the first synonym value. If you have multiple synonyms, the system will not associate the vocabulary word with the synonyms after the first one. If you really need multiple synonyms for one given word, vocabulary sources are a better choice, since you can add many alternative values for one given item.
DO: Add one synonym, such as “service desk”, for the vocabulary term “live agent”.
DON'T: Add multiple synonyms for “live agent”, such as “service desk, customer agent, operator, manager”. The system will only recognize the first synonym for “live agent” and not the additional synonyms (“customer agent”, “operator”, “manager”).
3. Ensure that the vocabulary does not introduce confusion between multiple intents.
Example: You may have multiple tax intents for software issues, such as “collaboration issues” and “general software issues”. Let’s say you have “Zoom” and “Adobe Acrobat” as software, and you want the Zoom utterances to go to “collaboration issues” intent and the Adobe Acrobat utterances to go to “general software issues”. When you are defining vocabulary, the synonym you provide for each software should be specific enough so that it goes to the correct software intent. For example, you can give the synonym “collaboration application” for “Zoom”, and “document reader software” for “Adobe Acrobat”.
Example: The vocabulary you select may have different meanings in different contexts. If you introduce a vocabulary word “Teams” and give the synonym “MS Teams”, you can create confusion if a user says “new DL for two teams”, since it will be understood as “new DL for two MS Teams”. You need to be careful of using vocabulary that may affect regular meanings of words that will be used in your domain like "teams". In this case, using a Vocabulary Source that is tied to the intent might be better than using a Vocabulary.
4. For multilingual NLU, you should pay special attention to the vocabulary and may need to spend time localizing it.You should also provide the synonym in the same language as the vocabulary word.
Example: if English model has vocabulary PTO = vacation, you cannot put it in the French model as PTO = vacances, since PTO is not a term used in French. You should see if French has an equivalent for PTO that requires a synonym and change the entire vocabulary. If it is not needed, then remove the model’s vocabulary altogether.
Additional FAQ for Vocabulary
When should I use pattern vocabulary?
When certain words follow a specific format (i.e. email address, incident number) or there are multiple ways that a user may type a word, then you should use pattern vocabulary to capture all the possibilities. For example, a user may be able to type a case number in a variety of ways:
- CS1234
- Cs817270
- Cs5290, etc.
You can capture these variations in the vocabulary by creating a regex and then giving it the synonym “case”:
Is vocabulary case sensitive?
Vocabulary is case insensitive unless you provide a pattern. You do not need to create vocabulary to capture case variations of a word.
For example, if you have an acronym that is case sensitive, such as “IT” (Information Technology), then you should create a pattern vocabulary to capture case variations of the acronym. On the other hand, if you have an acronym that is not case sensitive, such as “HR”, then you do not need to create a pattern vocabulary.
VOCABULARY SOURCES
Vocabulary sources should be used when you have a list of values and want to set a common synonym for the list of values. A vocabulary source is assigned a “handle” at the time of creation, making it easy to reference it in an utterance using @handle.
There are two types of vocabulary sources:
A table vocabulary source points to a ServiceNow table of records. You can regularly sync the table vocabulary source to get the most recent values in the table, which may be continuously changing. For example, you can create a vocabulary handle “@catalogItem” that points to the catalog table of items. Table vocabulary sources need to be synced before they can be used in an NLU model, and it is important to regularly sync your vocabulary table so that the NLU model can pull the latest data from the table. The time it takes to sync differs based on the server bandwidth, so it may take longer sometimes.
Note: Do NOT create 2 vocabulary sources with different synonyms that reference the same table and columns, because that will cause confusion in the model.
A list vocabulary source points to a static list that you create. For example, you can create a handle called “@dayOfWeek” that refers to a list of the days in the week.
Once created, vocabulary sources can be used across multiple models. Vocabulary, on the other hand, is defined at the specific model level.
There are a few key benefits to using vocabulary sources:
1. Using vocabulary sources can make the model creation process easier because you can refer to the vocabulary handle in an utterance rather than list out all the individual values.
Example: Instead of creating multiple utterances with exhaustive list of catalog items, you can create one utterance linked to the vocabulary source: “I need to order a @catalogItem.”
2. The system will only recognize the intent for the values provided in the vocabulary source. For similar values that are not in the vocabulary source, it will not be recognized unless:
a) you add it as a value to the vocabulary source OR
b) add additional utterances to the intent with values not in the list for training
Example: Your table @catalogItem has a list of hardware.
If the utterance “I need to order a @catalogItem” is added to the intent “order catalog item”, the intent will be predicted only if a value in catalogItem appears in the utterance.
If the user says “I need to order a mouse pad”, the intent will not be predicted as “order catalog item” using vocabulary sources alone. You will need to make sure the intent has additional utterances other than “I need to order a @catalogItem” in the training data, such as “I need to order charger”, “I need to order adapter”, etc. By doing this, the system will generalize to other hardware items.
If you want to generalize the utterance to identify similar values that are outside of the vocabulary source, then you must provide a few additional utterances with example values outside of the vocabulary source.
If you want the system to only recognize the values in your vocabulary source, then only one utterance containing the vocabulary handle is sufficient. You can, of course, add variations of the sentence itself to improve the intent. For example: “Need @catalogItem”, “Can I order a @catalogItem”, etc.
3. Vocabulary sources help improve intent prediction when an end-user types an utterance by replacing the term with the synonym provided for vocabulary source. You need to provide a single synonym to replace an individual item in the vocabulary source, not multiple synonyms or a definition. Both the vocabulary source and its synonym should be in the same language as the model language.
Example: The utterance “I need a mouse” would be interpreted by the system as “I need a catalog item” rather than interpret “mouse” as an animal. The system does this by replacing “mouse” with the synonym for the vocabulary source, “catalog item”.
4. Once Vocabulary sources are defined, you can use them to create a simple or mapped entity to extract the value from the utterance.
Once you have used the vocabulary handle (@catalogItem) in an utterance, you can select that word and annotate it as an entity. (learn more here)
Additional FAQ on Vocabulary Sources
Do vocabulary sources capture case sensitivity?
You can configure case sensitivity settings for vocabulary sources under “Advanced Options”. By default, vocabulary sources are case insensitive, unless you check the “make case sensitive box”. Fuzzy matching is always case insensitive.
I clicked on “sync vocabulary” and it is taking a long time. What's going on?
If the vocabulary source is taking a while, it is likely that it is currently in a queue waiting to be picked up by the NLU service when there is bandwidth. The sync process can take anywhere from around 30 minutes to a few hours depending on server traffic.
What is fuzzy matching and when should I use it?
Fuzzy matching can improve prediction by matching records with slight misspellings or partial matches. Our system implements relatively conservative rules for fuzzy matching, but it may still return false matches in some cases. We recommend that you use it sparingly and test out your model with fuzzy matching before using it.
You should use fuzzy matching depending on your tolerance for variations or partial matches of the vocabulary word. For example, if it is important to have an exact match for conference room names, then do not enable fuzzy matching. On the other hand, you may want to allow variations of names and therefore use fuzzy matching.
An alternative to fuzzy matching is to create alternate values in the vocabulary source, and you can put in multiple values that you would like to capture. Below are examples of doing so for both list and table vocabulary sources.
- Adding alternate values for list vocabulary source:
- Adding alternate values for table vocabulary source:
What are the limitations for vocabulary sources?
Table vocabulary sources currently can accommodate up to 100,000 records per table. Although we have a property that is configurable, we do not recommend increasing this limit as it will have a negative impact on performance. We recommend you apply filters to your vocabulary source table to reduce the number of values and hence runtime.
List vocabulary sources support up to 1,000 values per list.
I'm going to jump on here and ask for some help - I'm trying to utilise our companies Synonym Dictionary terms with our Virtual Agent, as (for some reason), it is incorrectly assuming one acronym means another. It's only come about recently and we're using Washington DC. We've had VA since Utah and didn't have this issue.
When I try use a SN table as a Vocab source, the sync always fails. If I try a list, it adds (albeit a manual process compared to the former), but I have no idea how to add it to the NLU's vocab list.
Ideally, I want the NLU model to use our synonym dictionary to determine utterances, but I'm at a loss for making that happen.
Any help is appreciated.
@Brian Bakker Yes I am aware of that. There is a particular AI Search Dictionary (ais_dictionary table, Type: Synonym) that I want the NLU model to refer to - I want it to use the same AI Search Dictionary Terms (ais_dictionary_term).
Example: in this AI Search Dictionary we have this entry - I want the term and all payloads to be picked up/used by the NLU model. To add this particular AI Search Dictionary as a Vocabulary source in the NLU.
To associate a vocabulary source to a new model, you reference it when creating a new utterance in the desired intent using the @ symbol, which will provide a drop down list of all the Table/List Vocabulary Sources available.
