An entity represents a class of object or a data type that is relevant to a user's purpose. By recognizing the entities that are mentioned in the user's input, the Conversation service can choose the specific actions to take to fulfill an intent.
An entity represents a term or object in the user's input that provides clarification or specific context for a particular intent. If intents represent verbs (something a user wants to do), entities represent nouns (such as the object of, or the context for, an action). Entities make it possible for a single intent to represent multiple specific actions. An entity defines a class of objects, with specific values representing possible objects in that class.
For example, suppose your application is a cognitive car dashboard that enables users to turn accessories on or off. Consider the following utterances:
Turn the radio off
Stop the air conditioner
These requests all represent the same intent (to turn something off), which you might call
#turn_off. You would then use an entity to represent what the user wants to turn off. To do this, you might create an entity called
@accessory, and give it the following possible values:
For each value, you can also specify synonyms. For example, you might specify
cooling as synonyms for
air conditioner. All three strings are treated as the same value. Listing multiple ways that users might refer to the same value helps improve your application's accuracy.
When the user's input is received, the conversation recognizes both intents and entities. Your dialog flow can then use these to provide the best answer. You should only create an entity for something that matters in terms of changing the way the application responds to an intent.
Tip: In addition to the entities you define, the service provides a set of system entities that are already defined and available for you to use. For more information, see Enabling system entities.
You use the Conversation tool to create entities. The number of entities, entity values, and synonyms you can create in a single service instance depends on your Conversation service plan:
|Service plan||Entities per service instance||Entity values per service instance||Entity synonyms per service instance|
In the Conversation tool, open your workspace and then click the Entities tab. If Entities is not visible, use the menu to open the page.
Click Create new.
In the Add the entity name field, type a descriptive name for the entity.
The entity name can contain letters (in Unicode), numbers, underscores, and hyphens. For example:
@character in the entity names when you create them in the Conversation tool.
sys-, which is reserved for system entities.
In the Value field, type the text of a possible value for the entity. An entity value can be any string up to 64 characters in length.
Important: Don't include sensitive or personal information in entity names or values. The names and values can be exposed in URLs in an app.
In the Synonyms field, type any synonyms for the entity value. A synonym can be any string up to 64 characters in length. Press Enter to save each synonym.
Click + and repeat the process to add more entity values.
When you are finished adding values and synonyms, click Create.
The entity you created is added to the Entities tab, and the system begins to train itself on the new data.
You can click any entity in the list to open it for editing. You can rename or delete entities, and you can add, edit, or delete values and synonyms.
If you have a large number of entities, you might find it easier to import them from a comma-separated value (CSV) file than to define them one by one in the Conversation tool.
Collect the entities into a CSV file, or export them from a spreadsheet to a CSV file. The required format for each line in the file is as follows:
where <entity> is the name of an entity, <value> is a value for the entity, and <synonyms> is a comma-separated list of synonyms for that value.
weekday,Monday,Mon weekday,Tuesday,Tue,Tues weekday,Wednesday,Wed weekday,Thursday,Thur,Thu,Thurs weekday,Friday,Fri weekday,Saturday,Sat weekday,Sunday,Sun month,January,Jan month,February,Feb month,March,Mar month,April,Apr month,May
Important: Save the CSV file using UTF-8 encoding, with no byte order mark (BOM).
In the Conversation tool, open your workspace and then click the Entities tab.
Click and then drag a file, or browse to select a file from your computer. The file is validated and imported, and the system begins to train itself on the new data.
You can view the imported entities on the Entities tab. You might need to refresh the page to see the new entities.
The Conversation service provides a number of system entities, which are common entities that you can use for any application. Enabling a system entity makes it possible to quickly populate your workspace with training data that is common to many use cases.
System entities can be used to recognize a broad range of values for the object types they represent. For example, the
@sys-number system entity matches any numerical value, including whole numbers, decimal fractions, or even numbers written out as words.
System entities are centrally maintained, so any updates are available automatically. You cannot modify system entities.
On the Entities tab, click System entities:
If you haven't created any entities, click Use system entities:
Browse through the list of system entities to choose the ones that are useful for your application.
Click the toggle switch next to a system entity to enable or disable it. You can also enable or disable all system entities by clicking the All toggle switch at the top of the list.
After you enable system entities, the Conversation service begins automatically retraining. After training is complete, you can use the entities.