标准事件和动作#

UMIM 规范定义了一组标准事件、动作和上下文数据。它们分为几个部分，每个部分对应于特定的输入模态、输出模态或功能。

用例#

虽然 UMIM 旨在易于扩展并支持各种交互系统和多模态交互类型，但标准模态、事件和动作针对以下用例进行了优化。

用例#
交互系统类型	描述	IM 功能	支持的通道	支持的 UMIM 动作
聊天机器人	以文本为中心的聊天界面，严格的轮流交互（用户、机器人、用户、机器人，...）	以对话为中心的会话逻辑清晰的轮流结构	文本输入/文本输出可能支持向用户显示图像、URL 等	`UtteranceBotAction` `UtteranceUserAction` `GestureBotAction` `VisualInformationSceneAction` `PresenceUserAction`
语音助手	与聊天机器人相同，但具有语音界面（语音输入/语音输出）	以对话为中心的对话清晰的轮流结构	音频输入/输出 ASR TTS	`UtteranceBotAction` `UtteranceUserAction` `PresenceUserAction`
带有头像的聊天机器人	核心是一个驱动头像体验的基于对话的系统，仍然专注于轮流逻辑	以对话为中心的对话，但可以发出额外的事件来控制头像（例如，在某些点更改动画）	头像可视化 ASR TTS 音频输入/输出 UI 摄像头/视觉	`UtteranceBotAction` `UtteranceUserAction` `PresenceUserAction`
交互式头像	具有头像的多模态体验，IM 可以在生成多模态输出时考虑多种模态。交互不局限于轮流结构	多模态 IM，可以实时响应事件并协调多个依赖事件，依赖于不同的模态	头像可视化 ASR TTS 音频输入/输出 UI 摄像头/视觉	`UtteranceBotAction` `UtteranceUserAction` `PresenceUserAction` `GestureBotAction` `PostureBotAction` `FacialExpressionBotAction` `ShotCameraAction` `EffectCameraAction` `VisualInformationSceneAction` `VisualChoiceSceneAction` `VisualFormSceneAction`

核心事件#

UMIM 中的所有事件类型都基于一些通用核心事件构建。本节定义这些通用事件。作为开发人员，您很可能很少直接与这些基本事件交互，而是使用更具体的事件。

事件( event_created_at: datetime, source_uid: str, tags: Dict[str, Any], type: str, uid: str, )#

基本事件类。所有其他事件都从此基本规范继承属性。默认情况下，我们允许额外的属性，但规范中存在的属性应遵循规范。

参数:

event_created_at (datetime) – 事件创建时的时间戳。
source_uid (str) – 生成事件的源组件的唯一 ID。
tags (Dict[str, Any]) – 与事件关联的键值对列表。标签从输入事件传播到输出事件。
type (str) – 事件的类型。
uid (str) – 事件的唯一标识符。

CustomEvent(data: Dict[str, Any], name: str)#

除了标准化事件之外，还可以使用的自定义事件。

参数:

data (Dict[str, Any]) – 与事件相关的任何数据。
name (str) – 自定义事件的名称。
... – 从 Event() 继承的附加参数/有效负载。

UserIntent(intent: str)#

用户意图的结构化表示。当 IM 推断出用户意图时，应生成此事件。用户意图可以根据用户的口头或非口头交流来推断。

参数:

intent (str) – 用户意图的规范形式
... – 从 Event() 继承的附加参数/有效负载。

BotIntent(intent: str)#

Bot 意图的结构化表示。如果 IM 传达 Bot 的当前意图，则应生成此事件。Bot 意图可能导致该意图的不同多模态表达。

参数:

intent (str) – Bot 意图的规范形式
... – 从 Event() 继承的附加参数/有效负载。

基本动作规范#

本节定义了动作可以从中继承的抽象基本动作事件。所有动作事件都从这些基本规范之一继承。

动作生命周期和动作 ID。 动作通过称为 action_uid 的唯一 ID 引用。与同一动作相关的所有事件都需要引用相同的 action_uid 。通过这种方式，具有相同 action_uid 的各个事件代表了从开始到结束的动作生命周期，以及可能在两者之间的更新。发送 StartAction 和 ActionStarted 事件的组件应生成新的唯一 action_uid 。最初生成 UID 的事件取决于动作是 Bot 动作还是用户动作。对于 Bot 动作（由 IM 启动），IM 负责生成唯一 ID。另一方面，对于用户动作，一旦用户动作开始，Action Server 负责生成 UID。一旦为动作生成了 UID，同一动作的所有未来事件都需要引用生成的 action_uid。通过这种方式，所有单个事件都可以与特定的动作“实例”关联。

动作的生命周期 除了受影响的模态之外，UMIM 动作还可以根据交互系统通常执行动作的方式或系统如何识别这些动作分为两个主要类别。

效果动作。效果动作（例如 GestureBotAction 或 UtteranceBotAction）具有有限的生命周期和即时效果。由于生命周期有限，这些动作通常只由 IM 启动，但不会主动停止。
状态动作。导致临时状态更改的动作（例如 PostureBotAction, PositionBotAction）。这些动作不会“自行”完成，而必须停止。当停止此类动作时，受影响的状态将恢复到运行动作之前的状态（例如，覆盖模态）。

这两种动作类型之间的主要区别在于，状态动作会一直运行到显式停止，而效果动作会一直运行到自然完成。为了使动作的此属性对程序员和故事设计者可用，所有动作都具有属性 action_info_lifetime，该属性为 indefinite 或 limited

ActionEvent( action_info_modality: ActionModality, action_info_modality_policy: ActionModalityPolicy, action_uid: str, action_info_lifetime: umim.messages.types.ActionLifetime | None, )#

与动作生命周期相关的事件

参数:

action_info_modality (ActionModality) – 模态的名称。特定于每个动作。无法更改。
action_info_modality_policy (ActionModalityPolicy) – 模态的策略。特定于每个动作及其模态。
action_uid (str) – 动作的唯一 ID。
action_info_lifetime (Optional[umim.messages.types.ActionLifetime]) – 指示动作的生命周期是有限的还是无限期的，直到被 IM 主动停止
... – 从 Event() 继承的附加参数/有效负载。

StartAction()#

启动动作的事件。所有其他可以启动的动作都从此基本规范继承。action_uid 用于区分同一动作的多次运行。

参数:: ... – 从 ActionEvent() 继承的附加参数/有效负载。

ActionStarted(action_started_at: datetime)#

动作的执行已开始。

参数:

action_started_at (datetime) – 动作开始时的时间戳。
... – 从 ActionEvent() 继承的附加参数/有效负载。

ChangeAction()#

需要更改正在运行的动作的参数。更新正在运行的动作对于运行时间较长的动作（例如头像动画）很有用，这些动作可以动态地调整其行为。例如，点头动画可以根据语音活动级别更改其速度。

参数:: ... – 从 ActionEvent() 继承的附加参数/有效负载。

ActionUpdated(action_updated_at: datetime)#

正在运行的动作提供（部分）结果。正在进行的动作可以提供有关动作当前状态的部分更新。ActionUpdated 应始终更新动作对象的有效负载并提供更新类型。

参数:

action_updated_at (datetime) – 动作更新时的时间戳。
... – 从 ActionEvent() 继承的附加参数/有效负载。

StopAction()#

需要停止动作。这应该用于主动停止可能需要较长时间的动作，例如手势。

参数:: ... – 从 ActionEvent() 继承的附加参数/有效负载。

ActionFinished( action_finished_at: datetime, is_success: bool, failure_reason: str | None, was_stopped: bool | None, )#

动作已完成执行。动作完成可能是因为动作已完成或失败（自然完成），也可能是因为被 IM 停止而完成。执行的成功（或失败）使用 status_code 属性标记。

参数:

action_finished_at (datetime) – 动作完成时的时间戳。
is_success (bool) – 动作是否成功完成
failure_reason (Optional[str]) – 动作未成功执行的情况下，动作失败的原因
was_stopped (Optional[bool]) – 动作是否被 Stop 事件停止
... – 从 ActionEvent() 继承的附加参数/有效负载。

Bot 动作#

所有 Bot 动作都基于 BotAction 基本规范。Bot 动作表示由 IM 发起的 UMIM 动作。

StartBotAction(bot_id: str | None)#

参数:

bot_id (Optional[str]) – 标识执行动作的 Bot 的 ID。如果您支持多 Bot 交互，则此字段是必需的。
... – 从 ActionEvent() 继承的附加参数/有效负载。

BotActionStarted(bot_id: str | None)#

参数:

bot_id (Optional[str]) – 标识执行动作的 Bot 的 ID。如果您支持多 Bot 交互，则此字段是必需的。
... – 从 ActionStarted() 继承的附加参数/有效负载。

BotActionUpdated(bot_id: str | None)#

参数:

bot_id (Optional[str]) – 标识执行动作的 Bot 的 ID。如果您支持多 Bot 交互，则此字段是必需的。
... – 从 ActionUpdated() 继承的附加参数/有效负载。

StopBotAction(bot_id: str | None)#

参数:

bot_id (Optional[str]) – 标识执行动作的 Bot 的 ID。如果您支持多 Bot 交互，则此字段是必需的。
... – 从 ActionEvent() 继承的附加参数/有效负载。

BotActionFinished(bot_id: str | None)#

参数:

bot_id (Optional[str]) – 标识执行动作的 Bot 的 ID。如果您支持多 Bot 交互，则此字段是必需的。
... – 从 ActionFinished() 继承的附加参数/有效负载。

自定义用户动作#

本节定义了一个自定义用户动作，除了标准化动作之外，还可以使用它。如果交互系统可以识别来自用户的动作，而这些动作不是 UMIM 标准的一部分，则可以使用自定义用户动作来允许 IM 与此类动作进行交互。这也可以作为如何将新动作集成到 UMIM 中的机制。

CustomUserActionStarted( custom_action_name: str, parameters: Dict[str, Any], )#

自定义用户动作的执行已开始。

参数:

custom_action_name (str) – 自定义动作的名称。
parameters (Dict[str, Any]) – 动作的任何参数。
... – 从 UserActionStarted() 继承的附加参数/有效负载。

ChangeCustomUserAction( custom_action_name: str, parameters: Dict[str, Any], )#

需要更改正在运行的动作的参数。更新正在运行的动作对于运行时间较长的动作（例如头像动画）很有用，这些动作可以动态地调整其行为。例如，点头动画可以根据语音活动级别更改其速度。

参数:

custom_action_name (str) – 自定义动作的名称。
parameters (Dict[str, Any]) – 动作更改的任何参数。
... – 从 ChangeUserAction() 继承的附加参数/有效负载。

CustomUserActionUpdated( custom_action_name: str, updates: Dict[str, Any], )#

正在运行的动作提供（部分）结果。正在进行的动作可以提供有关动作当前状态的部分更新。ActionUpdated 应始终更新动作对象的有效负载并提供更新类型。

参数:

custom_action_name (str) – 自定义动作的名称。
updates (Dict[str, Any]) – 来自动作的任何更新。
... – 从 UserActionUpdated() 继承的附加参数/有效负载。

CustomUserActionFinished( custom_action_name: str, results: Dict[str, Any], )#

动作已完成执行。动作完成可能是因为动作已完成或失败（自然完成），也可能是因为被 IM 停止而完成。执行的成功（或失败）使用 status_code 属性标记。

参数:

custom_action_name (str) – 自定义动作的名称。
results (Dict[str, Any]) – 来自动作的任何结果。
... – 从 UserActionFinished() 继承的附加参数/有效负载。

自定义 Bot 动作#

本节定义了一个自定义 Bot 动作，除了标准化动作之外，还可以使用它。如果交互系统能够执行不属于 UMIM 标准的其他动作，则可以使用自定义 Bot 动作来允许 IM 进行交互并执行此类动作。这也可以作为如何将新动作集成到 UMIM 中的机制。

StartCustomBotAction( custom_action_name: str, parameters: Dict[str, Any], )#

启动动作的事件。所有其他可以启动的动作都从此基本规范继承。action_uid 用于区分同一动作的多次运行。

参数:

custom_action_name (str) – 自定义动作的名称。
parameters (Dict[str, Any]) – 动作的任何参数。
... – 从 StartBotAction() 继承的附加参数/有效负载。

CustomBotActionStarted( custom_action_name: str, parameters: Dict[str, Any], )#

自定义用户动作的执行已开始。

参数:

custom_action_name (str) – 自定义动作的名称。
parameters (Dict[str, Any]) – 动作的任何参数。
... – 从 BotActionStarted() 继承的附加参数/有效负载。

ChangeCustomBotAction( custom_action_name: str, parameters: Dict[str, Any], )#

更改自定义动作的参数（如果自定义动作支持）

参数:

custom_action_name (str) – 自定义动作的名称。
parameters (Dict[str, Any]) – 动作更改的任何参数。
... – 从 ChangeBotAction() 继承的其他参数/有效载荷。

CustomBotActionUpdated( custom_action_name: str, updates: Dict[str, Any], )#

自定义动作执行期间发生了一些事情（如果自定义动作支持）。

参数:

custom_action_name (str) – 自定义动作的名称。
updates (Dict[str, Any]) – 来自动作的任何更新。
... – 从 BotActionUpdated() 继承的其他参数/有效载荷。

StopCustomBotAction( custom_action_name: str, parameters: Dict[str, Any], )#

需要停止一个动作。

参数:

custom_action_name (str) – 自定义动作的名称。
parameters (Dict[str, Any]) – 动作的任何参数。
... – 从 StopBotAction() 继承的其他参数/有效载荷。

CustomBotActionFinished( custom_action_name: str, results: Dict[str, Any], )#

自定义动作已完成执行。

参数:

custom_action_name (str) – 自定义动作的名称。
results (Dict[str, Any]) – 来自动作的任何结果。
... – 从 BotActionFinished() 继承的其他参数/有效载荷。

期望 Bot 动作#

为了优化多模态体验，交互系统了解交互管理器接下来期望从用户或系统接收哪些事件可能是有益的。这允许交互系统优化其功能，以更好地检测特定事件。UMIM 定义了一个特殊的动作来将这些期望传达给交互系统。这是一个完全可选的动作，交互系统无需实现。然而，能够做出反应的交互系统可以改善整体用户体验。

一些示例

IM 期望一个 UtteranceUserActionStarted() 事件（用户说了些什么）。因此，交互系统可以优化 ASR 管道，例如降低扬声器音量，提高麦克风灵敏度。在嘈杂的环境中，这甚至可能意味着 ASR 仅在 IM 期望用户说话时才处于活动状态（注意：这可能会严重影响与交互式化身对话的自然性）
在聊天机器人系统中，当机器人正在处理请求时，UI 可能希望显示一个思考指示器。通过传达期望来支持此用例，因为在处理期间，IM 会停止所有正在进行的期望。这允许 UI 指示“处理中”状态。如果 IM 期望例如文本答案，它将再次通过期望动作传达该信息。这与主动等待用户输入不同，主动等待用户输入是我们下面介绍的一个动作。
运行计算机视觉算法通常是资源密集型的。由于 IM 可以传达当前在与用户交互的此阶段期望的视觉事件类型，因此交互系统可以动态地禁用/启用视觉算法。这方面的示例包括 QR 码读取、对象识别、用户移动检测等等。

重要提示

传达机器人期望并不保证交互系统会采取任何行动。交互系统完全有责任决定在传达某些期望时采取哪些措施（或不采取任何措施）。

因此，即使交互系统支持此动作，IM 也不能对发出期望的效果做任何假设。

StartExpectationBotAction( expected_event: Annotated[Union[umim.messages.modalities.chat.ChangeUtteranceBotAction, umim.messages.modalities.chat.StartUtteranceBotAction, umim.messages.modalities.chat.StopUtteranceBotAction, umim.messages.modalities.chat.UtteranceBotActionFinished, umim.messages.modalities.chat.UtteranceBotActionStarted, umim.messages.modalities.chat.UtteranceBotActionScriptUpdated, umim.messages.modalities.chat.UtteranceUserActionFinished, umim.messages.modalities.chat.UtteranceUserActionStarted, umim.messages.modalities.chat.UtteranceUserActionTranscriptUpdated, umim.messages.modalities.chat.UtteranceUserActionIntensityUpdated], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})], )#

机器人期望在不久的将来在 UMIM 事件总线上发生某个事件。这个可选事件可以允许动作服务器优化其功能。例如，负责处理相机帧的 AS 可以根据 IM 期望的内容（例如，BotExpectation(event=PositionChangeUserActionStarted) 可以允许 AS 启动计算量更大的运动跟踪器，以获得更好的分辨率/精度）来启用/禁用某些视觉算法。

参数:

expected_event (Annotated[Union[umim.messages.modalities.chat.ChangeUtteranceBotAction, umim.messages.modalities.chat.StartUtteranceBotAction, umim.messages.modalities.chat.StopUtteranceBotAction, umim.messages.modalities.chat.UtteranceBotActionFinished, umim.messages.modalities.chat.UtteranceBotActionStarted, umim.messages.modalities.chat.UtteranceBotActionScriptUpdated, umim.messages.modalities.chat.UtteranceUserActionFinished, umim.messages.modalities.chat.UtteranceUserActionStarted, umim.messages.modalities.chat.UtteranceUserActionTranscriptUpdated, umim.messages.modalities.chat.UtteranceUserActionIntensityUpdated], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})])
... – 从 StartBotAction() 继承的附加参数/有效负载。

ExpectationBotActionStarted()#

交互系统向 IM 传达它可以处理对指定事件的期望。如果系统能够处理期望，则必须发送 ExpectationBotActionStarted 事件。接收 ActionStarted 事件并不保证如何处理期望，但它为 IM 提供了一种了解系统是否甚至能够处理期望的方法。对于交互系统中任何动作服务器都不支持的事件的期望，将不会发送 ExpectationBotActionStarted 事件。如果系统无法处理某些机器人期望，IM 可能会停止传达这些期望。

参数:: ... – 从 BotActionStarted() 继承的附加参数/有效负载。

StopExpectationBotAction()#

IM 传达它已停止其期望。这通常发生在期望得到满足（例如，已收到事件）或发生其他事情以改变交互过程时。

参数:: ... – 从 StopBotAction() 继承的其他参数/有效载荷。

ExpectationBotActionFinished()#

交互系统确认机器人期望已完成。

参数:: ... – 从 BotActionFinished() 继承的其他参数/有效载荷。

期望信号 Bot 动作#

除了向交互系统传达 IM 期望某些事件发生之外，向用户发出信号表明机器人正在等待对特定用户模态的输入可能也很重要。为此，UMIM 提供了 ExpectationSignaling 动作。此动作旨在允许交互系统向用户提供关于机器人期望用户做什么的细微线索（例如，如果头像正在等待用户输入，则其耳朵可能会变大）。此动作并非旨在向用户传达具体期望（例如，您不能传达诸如“请给我看一张大象的照片”之类的内容 - 为此，您必须将机器人期望明确地传达为交互的一部分）。

模态。 主动等待动作与其自身的模态“BotExpectationSignaling”相关联，并具有覆盖策略。

关于如何使用此动作的一些示例

在聊天机器人系统中，用户可能需要输入特定信息才能完成该过程。（例如，类似于“请输入您的出生日期以确认订单”的内容）。在这种情况下，IM 希望向用户发出信号，表明它正在积极等待用户回复。为此，IM 发送 StartExpectationSignalingBotAction(modality=UserSpeech) 事件
交互式头像可能正在等待用户的特定手势。IM 可能希望主动与用户沟通这一点（例如，显示动画）。为此，IM 发送 StartExpectationSignalingBotAction(modality=UserGesture)。如果存在其他具有冲突系统通道的正在进行的动作（例如，多个上半身动画），则动作服务器有责任解决任何潜在的冲突。

动作服务器实施注意事项

该动作并非旨在用于通过头像实现主动监听行为。对于交互式头像，IM 可以首先启动 ActiveWaiting for UserSpeech，一旦收到 UtteranceUserActionStarted，某个流程将处理启动小的头部点头并对某些事件做出声音爆发反应。

StartExpectationSignalingBotAction(modality: ActionModality)#

机器人正在等待特定模态的事件。

参数:

modality (ActionModality)
... – 从 StartBotAction() 继承的附加参数/有效负载。

ExpectationSignalingBotActionStarted()#

机器人已开始主动等待指定模态的事件。

参数:: ... – 从 BotActionStarted() 继承的附加参数/有效负载。

StopExpectationSignalingBotAction()#

停止等待模态上的事件。

参数:: ... – 从 StopBotAction() 继承的其他参数/有效载荷。

ExpectationSignalingBotActionFinished()#

机器人已停止主动等待。请注意，此动作仅在显式请求时停止，通过调用发送 StopExpectationSignalingBotAction。否则，该动作将无限期地继续。

参数:: ... – 从 BotActionFinished() 继承的其他参数/有效载荷。