For the complete documentation index, see llms.txt. This page is also available as Markdown.

运行时架构

了解 Convai Chatbot、Player、Object、Face Sync 组件与 Convai Subsystem 之间的角色、所有权和关系。

Convai Unreal Engine 插件将职责分为五种不同类型:聊天机器人组件、玩家组件、对象组件、面部同步组件,以及游戏实例子系统。每种类型只负责系统中的一小部分;彼此之间没有重复职责。

组件层级

所有具备对话能力的组件都共享一个两层基础:

  • UConvaiAudioStreamer ——最底层。它负责管理来自程序化声音波形的音频播放,并向任何实现了 IConvaiLipSyncInterface的组件传递逐帧混合形状面部数据。它还提供一个视觉插槽(IConvaiVisionInterface)用于摄像头或渲染目标输入。这两个接口都是扩展点: IConvaiLipSyncInterface 是 UConvaiFaceSyncComponent (以及任何自定义口型同步驱动)接收面部数据的方式,而 IConvaiVisionInterface 是摄像头视频流或渲染目标组件向 AI 提供视觉上下文的方式。聊天机器人和玩家都从该类继承音频和面部能力。

  • UConvaiConversationComponent ——扩展自 UConvaiAudioStreamer。它添加了共享的对话名称辅助函数(GetConversationalName)以及聊天机器人和玩家都继承的两个委托: OnTranscriptionReceivedDelegate 和 参与者连接状态变化事件.

Convai Chatbot 组件

UConvaiChatbotComponent (Blueprint 显示名称 Convai 聊天机器人)是面向 AI 驱动角色的核心组件。它负责:

  • 身份。 CharacterID 用于标识要加载的角色,而 CharacterName 保存已加载的角色名称。更广泛的角色配置管理不在本运行时架构页面中处理。

  • 会话。 该 bAutoInitializeSession 标志位和 StartSession / StopSession 函数通过子系统管理 WebRTC 通道。详见 会话生命周期 了解详情。

  • 对话状态。 诸如 GetIsTalking, IsListening, IsProcessing,以及 IsInConversation 之类的只读状态函数会暴露当前的辅助函数集合。在当前 SDK 中, GetIsTalking 反映音频播放;请参见 对话流程 了解每个辅助函数的确切行为。

  • 动作队列。 当 Convai 发送一系列动作时,它们会进入 动作队列 为 FConvaiResultAction 条目中。Blueprint 通过调用 获取第一个动作读取当前队首条目,执行该动作,然后调用 处理动作完成。成功完成后会将当前动作出队,并推进队列。当某个动作发生无法恢复的失败时,请调用 中止动作序列 来清空队列。

  • 情感状态。 情绪状态 (类型 FConvaiEmotionState)会被复制。 锁定情绪状态 可防止传入更新覆盖手动设置的情感。

  • 环境。 EnvironmentData (类型 FConvaiEnvironmentData)保存 AI 可引用的动作模板、对象和角色。请在运行时通过更细粒度的方法修改它 AddObject, RemoveObject, AddCharacter,以及 设置注意对象 ——而不是直接写入该属性。动作模板位于 EnvironmentData.Actions 在 /connect 创建时固定;只有对象和角色可以在会话中途更新。

  • 动态上下文。 UpdateContext, SetContextState, SetContextStates, AddContextEvent,以及 ResetDynamicContext 在实时会话期间将实时世界状态推送给 AI。更新会使用由 ContextDebounceWindow 和 ContextMaxDebounceWindow.

  • 会话值重置。 SessionID 默认为 "-1",以及 ResetConversation 将其重置为 "-1"。当前的 WebRTC 连接路径不提供 SessionID 作为恢复参数。

  • 注意目标。 ConversationPartner, 注视目标,以及 指向目标 是已复制的属性,用于跟踪角色正在与哪位玩家交谈,以及它正在注视或指向什么。

聊天机器人组件还实现了 IConvaiConnectionInterface,子系统正是通过它将传入的音频、动作、情感数据和面部数据路由到正确的组件。

Convai Player 组件

UConvaiPlayerComponent (Blueprint 显示名称 Convai Player)代表对话中的人类一侧。它负责:

  • 身份。 PlayerName 通过 SetPlayerName 及其对应的服务器 RPC 进行复制。 EndUserID 和 EndUserMetadata 都有 setter 函数及其对应的服务器 RPC,但在当前 SDK 构建中未注册用于复制。

  • 会话。 同样的 bAutoInitializeSession, StartSession, StopSession,以及 IsPlayerConnected 接口与聊天机器人相同,但面向玩家端的 WebRTC 通道。

  • 麦克风。 UnmuteStreamingAudio / MuteStreamingAudio 控制实时流式传输。 StartRecording / FinishRecording 将完整的一段话捕获为一个 USoundWave。可通过 SetCaptureDeviceByIndex, SetCaptureDeviceByName以及相关查询函数进行设备选择。

  • 凝视注意力。 当 bEnableGazeAttention 是 true时,该组件会在每个 tick 从玩家摄像机进行射线检测。持续凝视某个 UConvaiObjectComponent 会通过对象组件转发给符合条件的已注册聊天机器人,而每个聊天机器人都可将其接纳为当前注意对象。

  • 按住说话和 VAD。 bMute 会静音麦克风提交。 UpdateVadBP 切换语音活动检测。

玩家组件实现了两个接口: IConvaiConnectionInterface (与聊天机器人相同——供子系统用于会话路由和事件分发)以及 IConvaiProcessedAudioReceiver。音频处理中间件实现了 IConvaiAudioProcessingInterface;玩家组件是已处理音频的接收端,会在这些帧转发给子系统之前接收它们。

Convai 对象组件

UConvaiObjectComponent 会将任何 Actor 关卡中的对象注册为所有聊天机器人都可引用的命名对象。将其放到门、拉杆、房间或道具上,并填写 ObjectEntry (名称和描述)。该组件会在 BeginPlay时向子系统注册自身。 AddOrUpdateObjectFromComponent.

可选地, TrackedProperties 使设计者能够绑定 UPROPERTY 字段到拥有者 Actor 的 AI 上下文中。所有对象组件共享一个轮询时钟(大约每 0.25 秒一次)。每次轮询时,子系统都会评估每个被跟踪的属性,并推送一个 SetContextState 更新,仅在值发生变化时才发给已注册的聊天机器人——而不是每个 tick 都发。该组件不再自行生成针对每个聊天机器人的邻近描述;自从 4.0.0-beta.22,每个已注册对象的距离和方向——例如“附近、前方并偏右”——都由 空间感知 子系统集中计算,并连同其他上下文一起交付给每个聊天机器人。

该组件暴露四个凝视事件(OnGazedIn, OnGazedOut, OnAttentionGained, OnAttentionLost),这样 Blueprint 就可以独立于聊天机器人响应玩家焦点。

Convai 面部同步组件

UConvaiFaceSyncComponent (Blueprint 显示名称 Convai Face Sync)是一个 USceneComponent 实现了 IConvaiLipSyncInterface。它接收来自聊天机器人音频管线的预计算面部数据,并在每个 tick 驱动混合形状。

该 LipSyncMode 属性(EC_LipSyncMode)用于选择目标混合形状格式:

值
显示名称
用于

关闭

关闭

禁用口型同步

自动

自动

让插件选择

基于视素

基于音素口型

通用视素目标

BS_MHA

MetaHuman 混合变形

MetaHuman 骨骼绑定(默认)

BS_ARKit

ARKit 混合变形

兼容 ARKit 的骨骼绑定

BS_CC4_Extended

CC4 扩展混合变形

Reallusion CC4 骨骼绑定

面部同步组件是被动的——它不会发起任何网络活动。面部数据通过聊天机器人的音频流管线路由到实现 IConvaiLipSyncInterface的组件,而面部同步组件会在每个 tick 将得到的混合形状值暴露给角色的 Anim Blueprint。

若要从 Anim Blueprint 应用混合形状,请添加 Convai Face Sync AnimGraph 节点(FAnimNode_ConvaiFaceSync)到角色的动画图中。该节点接收一个 UConvaiChatbotComponent 引脚(默认显示),并在每个动画 tick 采样混合形状数据。它支持基于混合形状名称列表的上/下面部 alpha 控制,以及通过一个 BlendshapeMapping 表进行混合形状名称重映射、全局乘数和偏移,以及在最近没有面部数据到达时可配置的饥饿淡入/淡出。

Convai 子系统

UConvaiSubsystem 是一个 UGameInstanceSubsystem ——它随游戏实例启动和停止。它是插件 Unreal 层与底层 WebRTC 传输(convai::ConvaiClient).

该子系统负责:

  • 连接管理。 ConnectSession 和 DisconnectSession 由组件会话代理调用;无需 Blueprint 交互。

  • 组件注册表。 子系统维护已注册聊天机器人、玩家和对象组件的列表,以便将运行时数据转发给当前会话及相关组件回调。

  • 跟踪属性轮询。 子系统运行一个共享轮询时钟(大约每 0.25 秒一次),用于评估所有已注册的 UConvaiObjectComponent 跟踪属性,并同步执行。只有在值发生变化时才会将其推送给已注册的聊天机器人,从而避免不必要的上下文流量。

  • 全局连接状态。 GetServerConnectionState 返回当前 EC_ConnectionState 值。该枚举包含 已断开连接, 连接中, 已连接,以及 重新连接中,但当前运行时路径驱动 已断开连接, 连接中,以及 已连接. OnServerConnectionStateChangedEvent 在被驱动状态发生变化时触发。

  • 空闲管理。 ResetIdleTimer 和 InvalidateOrphanedConnection 让 Blueprint 在子系统检测到空闲或失效连接时介入。 OnUserIdleWarning 会在空闲超时到期前触发,以便游戏有机会阻止断开连接。

子系统的完整 Blueprint 接口在 会话生命周期.

所有权与生命周期

组件
所有者
生命周期

UConvaiChatbotComponent

NPC Actor

与 Actor 相同

UConvaiPlayerComponent

玩家 Actor (Pawn 或 Controller)

与 Actor 相同

UConvaiObjectComponent

场景中的任意 Actor

与 Actor 相同

UConvaiFaceSyncComponent

NPC Actor (与聊天机器人组件一起)

与 Actor 相同

UConvaiSubsystem

该 UGameInstance

整个游戏会话

聊天机器人、玩家和对象组件在 BeginPlay 并在 EndPlay中向子系统注册,并在中注销,因此在游戏中途被销毁的组件(例如被击杀的角色)会干净地从子系统注册表中移除自身。面部同步组件附加在角色上,但不会向子系统注册。

相关概念

当你需要控制连接时序时,请接着阅读生命周期页面;当你需要回合级行为时,请阅读流程页面;当你需要 Blueprint 委托详情时,请阅读事件页面。

会话生命周期对话流程事件系统

最后更新于

这有帮助吗?