Rasa3 domain官方文档翻译

背景

rasa 在2021年11月就升级到rasa3版本了，网上确实有很多rasa 官方文档的翻译资料，但都是以前的版本，那么有必要与时俱进，重新整理一下rasa3的官方文档资料了。以免在各类资料之中反复切换，费心费力。需要的小伙伴，直接拿走不谢！如果没有帮助到您，还请大佬勿喷！
原文链接

Domain

domian定义了机器人助手可操作的数据范围。在domain中可指定意图、实体、词槽、回复、表单等。并且还定义了会话session的配置。

下面是一个完整的domain示例

version: "3.1"

intents:
  - affirm
  - deny
  - greet
  - thankyou
  - goodbye
  - search_concerts
  - search_venues
  - compare_reviews
  - bot_challenge
  - nlu_fallback
  - how_to_get_started

entities:
  - name

slots:
  concerts:
    type: list
    influence_conversation: false
    mappings:
    - type: custom
  venues:
    type: list
    influence_conversation: false
    mappings:
    - type: custom
  likes_music:
    type: bool
    influence_conversation: true
    mappings:
    - type: custom

responses:
  utter_greet:
    - text: "Hey there!"
  utter_goodbye:
    - text: "Goodbye :("
  utter_default:
    - text: "Sorry, I didn't get that, can you rephrase?"
  utter_youarewelcome:
    - text: "You're very welcome."
  utter_iamabot:
    - text: "I am a bot, powered by Rasa."
  utter_get_started:
    - text: "I can help you find concerts and venues. Do you like music?"
  utter_awesome:
    - text: "Awesome! You can ask me things like \"Find me some concerts\" or \"What's a good venue\""

actions:
  - action_search_concerts
  - action_search_venues
  - action_show_concert_reviews
  - action_show_venue_reviews
  - action_set_music_preference

session_config:
  session_expiration_time: 60  # value in minutes
  carry_over_slots_to_new_session: true

---

多个 Domian文件

domain可以定义为单个YAML文件，也可以一个目录中的多个文件。当跨越多个文件时，domain内容将被读取并自动合并在一起。

使用命令行界面，你可以通过运行以下命令来训练模型:

rasa train --domain path_to_domain_directory

Slots是机器人的内存。存储为键值对的形式，可用于存储用户提供的信息(例如他们所在的城市)以及收集的关于外部世界的信息(例如数据库查询的结果)

Slots在domian中定义，包括它们的名称、类型以及它们是否以及如何影响助手的行为。下面的示例定义了一个名为“slot_name”和类型text的槽。

slots:
  slot_name:
    type: text

意图

domain中的intent列出了在NLU数据和会话训练数据中使用的所有intent

为特定意图忽略实体

为了忽略某些意图的特定实体，可以在domian文件中增加use_entities:[] 参数:

intents:
  - greet:
      use_entities: []

要忽略某些实体或显式地只考虑某些实体，你可以使用下面的语法:

intents:
- greet:
    use_entities:
      - name
      - first_name
- farewell:
    ignore_entities:
      - location
      - age
      - last_name

对于任何单一的意图，你只能使用use_entities或ignore_entities。

被意图排除的实体将不具有特征，因此不会影响下一个action预测。当您有一个意图，而您并不关心抽取的实体时，这是非常有用的。

如果你没有使用use_entities或ignore_entities参数来列出你的意图，实体将作为正常的特征。

也可以通过将实体本身的influence_conversation标志设置为false来忽略所有意图的实体。有关详细信息，请参阅实体部分。

如果你列出的意图中没有这个参数，并且没有将任何实体的influence_conversation设置为false，那么所有的实体将作为正常的特征。

注意：如果您希望这些实体也不通过槽影响动作预测，则为同名槽设置influence_conversation: false参数。

---

实体

3.1新特性
从3.1开始，您可以在实体下使用influence_conversation标志。该标志可以设置为false，以声明一个实体不应该被任何意图的特征化。这是一种将一个实体添加到domain中意图的ignore_entities列表的速记语法。该标志是可选的，默认行为保持不变。

实体部分列出了NLU pipline中任何实体提取器都可以提取的所有实体。

例如:

entities:
   - PERSON           # entity extracted by SpacyEntityExtractor
   - time             # entity extracted by DucklingEntityExtractor
   - membership_type  # custom entity extracted by DIETClassifier
   - priority         # custom entity extracted by DIETClassifier

当使用多个domain文件时，实体可以被指定在任何domain文件中，并且可以被任何domain文件中的任何意图使用或忽略。

如果您正在使用实体角色和组特性，您还需要列出实体的角色和组。

例如:

entities:
   - city:            # custom entity extracted by DIETClassifier
       roles:
       - from
       - to
   - topping:         # custom entity extracted by DIETClassifier
       groups:
       - 1
       - 2
   - size:            # custom entity extracted by DIETClassifier
       groups:
       - 1
       - 2

注意：实体角色和组需要在domain中列出

默认情况下，实体会影响动作预测。为了防止提取的实体影响特定意图的对话，可以忽略特定意图的实体。要忽略所有意图的一个实体，而不需要在每个意图的ignore_entities标志下列出它，你可以在该实体下设置influence_conversation标志为false:

entities:
- location:
    influence_conversation: false

此语法的效果与为domain中的每个意图将实体添加到ignore_entities列表相同。

显式设置influence_conversation: true不会改变任何行为。这是默认设置。

---

Slots

Slots是机器人的内存。存储为键值对的形式，可用于存储用户提供的信息(例如他们所在的城市)以及收集的关于外部世界的信息(例如数据库查询的结果)。

Slots在domian中定义，包括它们的名称、类型以及它们是否以及如何影响助手的行为。下面的示例定义了一个名为“slot_name”和类型text的槽。

slots:
  slot_name:
    type: text
    mappings:
    - type: from_entity
      entity: entity_name

词槽和对话行为

您可以使用influence_conversation属性指定词槽是否影响会话。

如果希望在词槽中存储信息而不影响会话，则在定义槽时设置influence_conversation: false。

下面的示例定义了一个词槽age，它将存储有关用户年龄的信息，但不会影响对话流。这意味着助手每次预测下一个动作时都会忽略槽的值。

slots:
  age:
    type: text
    # this slot will not influence the predictions
    # of the dialogue policies
    influence_conversation: false

在定义词槽时，如果您没有设置influence_conversation或将其设置为true，该槽将影响下一个动作预测，除非它的槽类型为any。词槽影响对话的方式将取决于它的词槽类型。

下面的示例定义了一个影响会话的词槽home_city。文本槽将根据槽是否具有值影响助手的行为。文本槽的具体值(例如Bangalore or New York or Hong Kong)没有任何影响。

slots:
  # this slot will influence the conversation depending on
  # whether the slot is set or not
  home_city:
    type: text
    influence_conversation: true

例如，考虑两个输入“天气怎么样?”和“班加罗尔的天气怎么样?”根据NLU是否自动设置home_city槽位，会话应该会发生分歧。如果槽已经设置，机器人可以预测action_forecast动作。如果词槽未设置，则需要获取home_city信息，然后才能预测天气。

Slot 类型

Text Slot

• Type

  text

• User For

  保存文本值

• 示例

  slots:
     cuisine:
        type: text
        mappings:
        - type: from_entity
          entity: cuisine
  

• 描述

如果influence_conversation 设置为true，机器人会根据词槽是否填充改变自身的行为。不同的文本不会进一步影响对话。

以下两个故事是一致的

stories:
- story: French cuisine
  steps:
  - intent: inform
  - slot_was_set:
    - cuisine: french

- story: Vietnamese cuisine
  steps:
  - intent: inform
  - slot_was_set:
    - cuisine: vietnamese

Boolean Slot

• Type

  bool

• User For

  保存true 或false值

• 示例

  slots:
     is_authenticated:
        type: bool
        mappings:
        - type: custom
  

• 描述

如果将influence_conversation设置为true，机器人的行为将根据词槽是空，为true还是为false而改变。请注意，空的bool词槽和设置为false的词槽对会话的影响不同。

categorical Slot

• Type

  categorical

• User For

  存储槽，可以取N个值中的一个。

• 示例

  slots:
    risk_level:
      type: categorical
      values:
        - low
        - medium
        - high
      mappings:
      - type: custom
  

• 描述

如果将influence_conversation设置为true，助理的行为将根据词槽的具体值而改变。这意味着根据上面示例中的槽的值是低、中还是高，助手的行为是不同的。

默认值__other__会自动添加到用户定义的值中。所有遇到的没有明确定义在槽值中的值都映射到__other__。__other__不应该用作用户定义的值;如果是，它仍将作为所有未见值映射到的默认值行事。

Float Slot

• Type

  float

• User For

  存储数值

• 示例

  slots:
    temperature:
      type: float
      min_value: -100.0
      max_value:  100.0
      mappings:
      - type: custom
  

• 默认

  max_value=1.0,  min_value=0.0
  

• 描述

如果influence_conversation设置为true，助理的行为将根据词槽的值而改变。如果值在min_value和max_value之间，则使用具体的数值。所有低于min_value的值将被视为min_value，所有高于max_value的值将被视为max_value。因此，如果max_value设置为1，则槽值2和3.5之间没有区别。

List Slot

• Type list

• User For 保存列表

• 示例

  slots:
    shopping_items:
      type: list
      mappings:
      - type: from_entity
        entity: shopping_item
  

• 描述

如果将influence_conversation设置为true，助理的行为将根据列表是否为空而改变。存储在词槽中的列表的长度不会影响对话框。它只与列表长度是否为零或非零有关。

Any Slot

• Type any

• User For 存储任意值(它们可以是任何类型，如字典或列表)

• 示例

  slots:
    shopping_items:
      type: any
      mappings:
      - type: custom
  

• 描述

任何类型的槽在对话中总是被忽略。此词槽类型的属性influence_conversation不能设置为true。如果要存储应该影响会话的自定义数据结构，请使用自定义槽类型。

Custom Slot 类型

也许你的餐厅预订系统最多只能处理6个人的预订。在本例中，您希望槽的值影响下一个选择的操作(而不仅仅是是否指定了它)。您可以通过定义一个自定义槽类来实现这一点。

下面的代码定义了一个名为NumberOfPeopleSlot的自定义槽类。特征定义如何将这个槽的值转换为向量，以便Rasa开源机器学习模型可以处理它。NumberOfPeopleSlot有三个可能的“值”，可以用长度为2的向量表示。

(0,0)	not yet set
(1,0)	between 1 and 6
(0,1)	more than 6

# my_custom_slots.py
from rasa.shared.core.slots import Slot
​
class NumberOfPeopleSlot(Slot):
​
    def feature_dimensionality(self):
        return 2
​
    def as_feature(self):
        r = [0.0] * self.feature_dimensionality()
        if self.value:
            if self.value <= 6:
                r[0] = 1.0
            else:
                r[1] = 1.0
        return r

您可以将自定义槽类实现为独立的python模块，与自定义操作代码分离。将自定义槽的代码保存在一个名为"init.py"的空文件旁边的目录中，以便它将被识别为python模块。然后，您可以通过自定义槽类的模块路径来引用它。

例如，假设你将上面的代码保存在"addons/my_custom_slots.py"中，这是一个相对于你的bot项目的目录:

└── rasa_bot
    ├── addons
    │   ├── __init__.py
    │   └── my_custom_slots.py
    ├── config.yml
    ├── credentials.yml
    ├── data
    ├── domain.yml
    ├── endpoints.yml

自定义槽类型的模块路径是addons.my_custom_slots.NumberOfPeopleSlot。在domian文件中使用模块路径来引用自定义槽类型:

slots:
  people:
    type: addons.my_custom_slots.NumberOfPeopleSlot
    influence_conversation: true
    mappings:
    - type: custom

既然Rasa Open Source可以使用您的定制槽类，那么您可以根据people不同的值增加训练故事。你可以为people的值在1到6之间的情景写一个故事，为值大于6的情景写一个故事。您可以在这些范围内选择任何值放入您的故事中，因为它们的功能都是相同的(参见上面的功能表)。

stories:
- story: collecting table info
  steps:
  # ... other story steps
  - intent: inform
    entities:
    - people: 3
  - slot_was_set:
    - people: 3
  - action: action_book_table
​
- story: too many people at the table
  steps:
  # ... other story steps
  - intent: inform
    entities:
    - people: 9
  - slot_was_set:
    - people: 9
  - action: action_explain_table_limit

Slot Mappings(3.0新增)

3.0更新
从3.0开始，槽映射在domain中的slots 部分定义。这个更改删除了通过自动填充来设置槽位的隐式机制，并将其替换为在每个用户消息之后设置槽位的新的显式机制。您需要在domain.yml的slots部分显式地为每个slot定义槽映射。如果您正在从早期版本迁移，请阅读迁移指南来更新您的助手。

Rasa Open Source提供了四个预定义的映射，以根据最新的用户消息填充词槽。

除了预定义的映射外，还可以定义自定义槽位映射。所有自定义槽位映射都应该包含一个自定义类型的映射。

缺省行为是槽映射在每个用户消息之后应用，而不管对话上下文是什么。要使槽映射仅应用于表单的上下文中，请参见映射条件。在窗体的上下文中应用from_entity槽映射还有一个默认限制;详细信息请参见unique from_entity mapping matching。

注意，你也可以为可选参数intent和not_intent定义意图列表。

from_entity

from_entity映射根据提取的实体填充槽。所需参数如下：

• entity: 填充槽的实体

以下参数是可选的，可用于进一步指定何时应用映射:

• intent: 仅在预测到此意图时应用映射。
• not_intent: 当这个意图被预测时不应用映射
• role: 仅当提取的实体具有此角色时应用映射
• group: 仅当提取的实体属于该组时应用映射。

entities:
- entity_name
slots:
  slot_name:
    type: any
    mappings:
    - type: from_entity
      entity: entity_name
      role: role_name
      group: group name
      intent: intent_name
      not_intent: excluded_intent

Unique from_entity mapping matching

在表单上下文中应用from_entity槽映射有一个有意的限制。当窗体处于激活状态时，from_entity槽映射仅在满足以下一个或多个条件时才会被应用:

• 表单刚刚请求了带有from_entity映射的词槽
• 只有一个活动表单的required_slots具有特定的from_entity映射，包括提取的实体的所有属性(例如，实体名称、角色、组)。这被称为表单的唯一实体映射。如果映射在required_slots列表中不是唯一的，那么提取的实体将被忽略。

这种限制的存在是为了防止表单用提取的相同实体值填充多个所需的槽。

在下面的示例中,实体date 唯一填充词槽arrival_date, 实体city对应角色from 唯一填充词槽departure_city，实体city对应角色to唯一填充词槽arrival_city,因此如果其中某个词槽没有请求他们可以用来配合来进行相应的词槽填充。但是，实体city不包含角色可以填充词槽departure_city和arrival_city，这取决于请求的是哪个词槽，所以如果在请求词槽arrival_date时提取了一个实体city，那么它将被form忽略。

slots:
  departure_city:
    type: text
    mappings:
    - type: from_entity
      entity: city
      role: from
    - type: from_entity
      entity: city
  arrival_city:
    type: text
    mappings:
    - type: from_entity
      entity: city
      role: to
    - type: from_entity
      entity: city
  arrival_date:
    type: any
    mappings:
    - type: from_entity
      entity: date
forms:
  your_form:
    required_slots:
    - departure_city
    - arrival_city
    - arrival_date

注意，唯一的from_entity映射约束不会阻止填充不在活动表单的required_slots中;这些映射将照常应用，而不管映射的唯一性。要限制槽映射对特定表单的适用性，请参见映射条件。

form_text

from_text映射将使用下一个用户语句来填充词槽slot_name。如果intent_name为None，则无论意图名称如何，槽都将被填满。否则，只有当用户的意图是intent_name时，这个槽才会被填满。

如果消息的意图是exclusided_intent，则槽映射将不应用。

slots:
  slot_name:
    type: text
    mappings:
    - type: from_text
      intent: intent_name
      not_intent: excluded_intent

注意
为了保持了2.0的特性，当使用from_text槽映射时，必须使用映射条件，其中定义了active_loop和requestd_slot键。

form_intent

如果用户意图是intent_name, from_intent映射将用值my_value填充slot_name槽位。如果您选择不指定参数intent，那么无论什么意图槽位映射将应用，只要意图没有在not_intent参数下列出。

需要输入以下参数:

• value: 填充slot_name槽位的值

以下参数是可选的，可用于进一步指定何时应用映射:

• intent: 仅在预测到此意图时应用映射。
• not_intent: 当这个意图被预测时不应用映射

注意，如果选择不定义参数intent，那么无论什么意图，槽位映射都将应用，只要意图没有在not_intent参数下列出。

slots:
  slot_name:
    type: any
    mappings:
    - type: from_intent
      value: my_value
      intent: intent_name
      not_intent: excluded_intent

form_trigger_intent

如果表单被意图intent_name的用户消息激活，from_trigger_intent映射将用值my_value填充slot_name槽位。如果消息的意图是excluded_intent，词槽映射将不会应用。

slots:
  slot_name:
    type: any
    mappings:
    - type: from_trigger_intent
      value: my_value
      intent: intent_name
      not_intent: excluded_intent

Mapping Conditions(3.0新增)

若要仅在表单上下文中应用槽映射，请在槽映射的条件键中指定form的名称。条件列出active_loop键中适用于该映射的表单名称。

条件还可以包括被请求槽位的名称。如果未提到requestd_slot，那么在提取相关信息时将设置该slot，而不管表单正在请求哪个slot。

slots:
  slot_name:
    type: text
    mappings:
    - type: from_text
      intent: intent_name
      conditions:
      - active_loop: your_form
        requested_slot: slot_name
      - active_loop: another_form

请注意
如果槽映射中没有包含条件，那么无论表单是否激活，槽映射都将适用。只要一个槽列在表单的required_slots中，当激活表单时，如果它是空的，表单就会提示输入这个槽。

Custom Slot Mappings(3.0新增)

当没有一个预定义映射适合您的用例时，您可以使用槽验证操作定义自定义槽映射。您必须将这个槽位映射定义为自定义类型，例

slots:
  day_of_week:
    type: text
    mappings:
    - type: custom
      action: action_calculate_day_of_week

您还可以使用custom槽映射来列出将在对话过程中由任意自定义操作填充的槽，列出类型而不列出特定操作。例如:

slots:
  handoff_completed:
    type: boolean
    mappings:
    - type: custom

这个槽不会在每一个用户回合更新，但只有一次自定义动作，返回一个SlotSet事件的预测。

Slot Auto-fill（3.0弃用）

Initial slot values

你可以在你的domain文件中提供一个槽的初始值:

slots:
  num_fallbacks:
    type: float
    initial_value: 0
    mappings:
    - type: custom

---

Session configuration

一个会话session表示用户和机器人之间的对话。会话重启有以下三种方式：

1. 用户首次开启新的会话

2. 用户间隔一段时间（可配置的时间）之后开启新的会话

3. 发送/session_start意图

   可以通过在session_config中配置触发新会话的不同周期

• session_expiration_time
  定义了多长时间不活跃就重启新的session, 单位是分钟
• carry_over_slots_to_new_session
  决定了是否将词槽传递到新的session

默认配置如下

session_config:
  session_expiration_time: 60  # value in minutes, 0 means infinitely long
  carry_over_slots_to_new_session: true  # set to false to forget slots between sessions

这个表示如果用户60分钟后发送消息，就会触发新的会话session, 并且会将当前的词槽传递给新的session.

如果session_expiration_time 为 0表示当前会话session永远不会结束，只有在首次进入会话是才会激活action_session_start

NOTE

一个新的会话会触发默认 action_session_start.

它默认将所有已有的slots传递给新的session。需要注意的是所有的会话都需要以action_session_start开始.

action_session_start可以自定义。

默认 action_session_start会携带所有现有的slot, 并将其带入到下一个会话。如果我们不想保留所有的slot, 那么可以使用自定义action重写action_session_start

config

domain文件中的配置store_entities_as_slots参数。此参数仅用于阅读故事并将其转换为 trackers。如果参数设置为True，如果故事中存在适用的实体，这将导致从实体隐式地设置槽。当一个实体匹配from_entity槽映射时，store_entities_as_slots定义该实体值是否应该被放置在该槽中。因此，该参数跳过了在故事中手动添加显式的slot_was_set步骤。默认情况下,值 为true。

你可以通过将store_entities_as_slots参数设置为false来关闭这个功能:

config:
  store_entities_as_slots: false