article by Frank Nmphius, May 2022

Frequently Asked Questions is a feature every digital assistant needs. This article explains how to use a pre-built template to create Frequently Asked Questions skills for Oracle Digital Assistant. 

Note: You can download the FAQ skill template as well as the FAQ example created in the hands-on section of this article at the bottom of this article.

The image below shows the sample skill created from the FAQ skill template at runtime: A user sends a message to Oracle Digital Assistant, which is resolved by an answer intent in the skill created from the template. The answer that resolves best and is above the confidence threshold is displayed to the user.

Then, if other answers fall within a configurable range, the user is presented with a "Show more of these" button. Upon pressing the button, the top-n runners-up answers will be displayed in a carousel for the user to select an answer from. The top-n number of cards can also be configured declaratively.

To select an answer from the carousel of cards, the user can either tap on the button associated with a card, or use the cards index number in a message like "show 1", "show first", "select second" etc.

Steps Involved In Creating A FAQ Sklll From The Template

Good news is that for using the template to create a custom FAQ skill, no coding is required. Below are the 3 steps you need to follow to implement a FAQ skill based on the template. Each of the steps is covered in the following hands-on oriented sections

1. Clone the template
2. Create or generate answer intents
3. Create a resource bundle keys for each answer intent

Hands-on: Create A New FAQ Skill From The Template

To start with, you need to import the provided FAQ template skill to your Oracle Digital Assistant instance of version 22.04 or later. For this, download the skill template and use the Import button that shows when, in your Oracle Digital Assistant instance, you switch to the skill overview panel.

Choose Clone from the skill menu to create a copy of the skill as shown in the image below.

Provide a display name for the skill. The name should indicate what type of FAQ you are creating. In the example below, the FAQ is about the Oracle OCI Free Tier cloud. The conversation name, without blanks, will become te name of the skill. 

Note that once the cloned skill is created and opened, only one intent is defined, which is the unresolved intent. The unresolved intent doesn't do anything in this template, but needs to be created for implementation reasons. This article does not cover the implementation of the article but focuses on how to use it in a custom project.

Hands-on: Build Answer Intents From An Existing FAQ Web Page

As mentioned earlier, the FAQ skill is based on answer intents that you create for each question.

An answer intent represents a question, provides the answer to that question, and contains example phrases (utterances) of how users would ask for a specific answer. The NLP model is trained with the utterances, which is why you should have as many of them as possible. For production FAQ skills, 70-80 utterances per answer intent would be a good start

To create answer intents you could

1. Create answer intents in the intent panel. This approach is certainly the slowest when building an FAQ skill, but gives you maximum control over the quality of the utterances and the quality of the answers. The quality of an answer lies not only in the correctness of the content, but also in the way it implements a conversational voice and how it integrates with the persona of your digital assistant.
2. Use the new Knowledge feature in Oracle Digital Assistant 22.04 and later to extract FAQ from an uploaded document or a URL reference to a FAQ website. The Knowledge feature is easy to use and probably the quickest option to a fully functional FAQ skill. Note, however, that you may need to curate the generated questions and answers, and also need to add more utterances to each answer intent.

The following image shows the new Knowledge feature panel in the Oracle Digital Assistant skill and the icon to use in the toolbar menu. To generate answer intents from an existing FAQ document, click the + Knowledge Document button.

To demonstrate the use of the FAQ skill template, I am using the Knowledge feature with the the Oracle Cloud FreeTier FAQ reference: https://www.oracle.com/cloud/free/faq.html

1. The Name you provide determines the intent names that are getting generated from the questions on the referenced FAQ page. The names will be appended by 3 digits (000 – 999). Especially if you plan to use answer intents in skills with regular (transactional) intents, it is recommended to use a naming convention that indicates an intent as an answer intent. In the example shown in the image below, I am using ".ans." to identify an answer intent. I recommend to use a similar naming convention. 
2. In the New Knowledge Document sialog, select the URL tab. Then enter the FAQ page URL to read the questions and answers from. 

After pressing the Create button, it will take a few minutes for the Knowledge feature to download the questions and answers 

Before the answer intents are getting created, you have the option to review them and to select those you don't want to add to the skill. Notice how the intent names contain the provided name string and a 3 digit number.

Hands-on: Review And Curate The Created Intents

Without going into a full discussion about best practices in conversation design and machine learning model training, here are some things to consider when curating the generated questions and answers

1. In a production environment, intents should be trained using the Trainer TM model. For the Trainer TM model to perform best, you will need to create between 70-80 utterances. Utterances are sample phrases representing how a user would ask a question. For example, if the question was about what Oracle Cloud Free Tier is, then utterances probably would include
   – what is oracle cloud free tier
   – tell me about oracle cloud free tier
   – is there a free offering of the Oracle Cloud
   – what is the name of the Oracle free cloud offering
   – can I use Oracle Cloud for free?
   – is Oracle Cloud free?
   
   For complete documentation on best practices when training your model, see the Oracle Digital Assistant product documentation.
    
2. Curate the answers considering the following aspects
   – Make sure answers are conversational and that they match the overall tone of voice used by your digital assistant
   – Answers should be kept short. A digital assistant runs within  messenger window that does not provide the same real estate as a web page
   – change text formatting contained in an answer so it works with many messenger channels
    
3. Provide a meaningful Conversation Name. The skill template uses the conversation name as the associated question when displaying an answer. So, make sure the Conversation Name is defined as a question that matches the Answer of the answer intent. In the image below, the Conversation Name is defined as What is Oracle Cloud Free Tier?

Hands-on: Create Resource Bundle Keys For The Intents

As shown earlier, the FAQ skill template prints the top-scoring answer to a question but also provides a button for users to see related questions and answers. The related questions and answers are displayed in a carousel of cards. The question becomes the title of the card and the card's description is a short summary of the answer so users get a feel for whether or not they want to follow up with a question to see the full answer.

To create the short summary, you need to create resource bundle entries for each intent. Not only does this allow to provide your FAQ skill in multiple languages, it also is very consistent as all the messages and prompts in the FAQ skil ltemplate are saved as resource bundles. 

To create the resource bundle entries, I suggest to open a seond tab for your FAQ skill. The first tab displays the intent panel and the second, the resource bundle panel (shown in the image below). You can now create new resource bundle keys and copy the intent name from the intent panel as the key name and parts of the answer as the answer summary.

Note: For the FAQ skill template to work, the resource bundle key names must match the intent names. The image below shows the resource bundle key name and text for the first answer intent created for the Oracle Cloud Free Tier FAQ

About The FAQ Skill Parameters To Configure The Template Behavior

The skil template defines 3 skill parameters:

• answerIdentifyingPattern – The skill parameter holds the naming convention you use to identify an answer intent. In the sample, the answer intent naming convention is '.ans.', which also is set as the default. If you want to use a different naming convention, then change this parameter value accordingly
• da.answerIntentMinimumThreshold – To resolve and display an answer, the model uses the confidence threshold defined on the skill settings, which usually is set to 0.7 (Out of 0 – 1). To find related answers you want to define a confidence threshold that must be met by an answer intent for a given question. In the image below, this value us set to 0.3. Note that the lower the value is the more likely it is that the answer is not really related to the top-scoring answer. 
• da.numberOfAnswersDisplayed –  This paremeter defines the number of cards and thus the number of related answers (if found) displayed to the user. If, for example, 10 runner-up answers resolve above the value set for the da.answerIntentMinimumThreshold parameter, then the top-n answers are displayed, where top-n is the value specified in this parameter. 

Note: skill parameters that start with a "da." in the name can be set in the digital assistant after adding the skill to the digital assistant.

Test Answer Intents In The Utterance Tester

You use the utterance tester in a skill to ensure a well-trained NLP model. In this article it is used in combination with the conversation tester to demonstrate how the FAQ skill created from the FAQ skill template works. If you followed the hands-on instructions and created a FAQ skill for the Oracle Cloud Free Tier FAQ, or if you just imported the provided sample skill, you can run the utterance tester and try the following message: "can I extend mytrial".

The image below shows the expected result, namely that oci.ans.freetier.019 resolves with 97% confidence as the top intent (0.97 in relation to the confidence threshold). Other questions (answer intentions) are resolved with 66.3% or less.

If then you run the same message in the conversation tester, you see the top-scoring answer intent printed in a message bubble. If other answer intents resolve above the confidence range configured using the da.answerIntentMinimumThreshold skill parameter then a Show more like this button is displayed.

Pressing the button brings up a carousel of related questions and answers. The number of cards displayed in the carousel is configured using the da.numberOfAnswersDisplayed skill parameter. The rule for the number of cards shown is: The number of answer intents shown includes all intents resolved above da.answerIntentMinimumThreshold minus the highest resolving intent, but no more than the number of cards limit set by the da.numberOfAnswersDisplayed parameter.

If no answer intent resolves as a related question, then the "Show more like this" button is not displayed as shown in the image below after setting the da.answerIntentMinimumThreshold skill parameter value to 0.8. 

Should You Create One or Many FAQ Skill?

A digital assistant in Oracle Digital Assistant combines multipe skills into a single chatbot solution. Each of the skills could have its own FAQ related to the business the skill handles. In this case it makes sense to create multiple FAQ skillls and ensures that the business skill(s) and the FAQ skill share the same skill group.

But even if you're just creating a digital assistant to edit FAQs, it makes sense to create multiple FAQ skills. For example, if you have FAQ categories (e.g. Oracle Cloud Free Tier FAQ and Digital Assistant FAQ), chances are each FAQ category contains similar questions (e.g. "Is Oracle Cloud free?" , "Is Oracle Digital Assistant free?"). If you create multiple FAQ skills, you can use the disambiguation dialogs generated by Oracle Digital Assistant to help users find the right answer.

Note: Don't partition FAQ into separate skills only so you partitioned them. If partitioning does not make sense to does not provide a benefit, then a single FAQ skill will do.

Download The Resources

Skill Template

FAQ Carousel Skill Template

OCI Cloud Free Tier Sample

Important disclaimer: Note that the sample skill uses trainer HT and also only uses the number of utterances generated by the Knowledge skill. To put a FAQ skill like this in production you must use Trainer TM as the model and have between 70-80 utterances per answer intent. In other words, the sample skill is undertrained as is. The reason it uses trainer HT and only a few utterances is that the sample skill is  meant to only demo the outcome of the FAQ skill for you to quickly test and explore.

CloudFreeTierFAQ Sample