排查场景元数据问题

诊断并修复场景对象无法被识别、环境数据过旧以及被跟踪属性无法更新等常见问题。

使用此页面诊断 Convai Unreal Engine 插件中场景元数据最常见的问题。每个部分都描述一个症状、其可能原因以及修复方法。

初步诊断

在阅读各个症状部分之前，请先确认以下内容。这三个条件涵盖了大多数场景元数据问题：

1. ObjectEntry.Name 非空 —— 名称为空的对象会被拒绝，并记录为 ConvaiObjectComponent on %s skipped: ObjectEntry.Name is empty。在 UConvaiObjectComponent Details 面板中选择该项，并确认 名称 字段已设置。
2. bEnableActions 为 true 用于连接时动作和注意力 —— 当 false, action_config 未在 /connect，以及 SetObjectInAttention 没有效果。检查 EnvironmentData.bEnableActions 在 UConvaiChatbotComponent.
3. 在会话开始前或之后添加的对象 —— 任何 Actor 以及 UConvaiObjectComponent 在之前处于激活状态的 StartSession() 都会包含在初始快照中； Actor在会话开始后生成或添加的对象必须使用 AddObject 在聊天机器人组件上才能到达 Convai。

打开 输出日志 在 Unreal Engine 中，并按 ConvaiSubsystemLog 过滤以查看对象注册和重名警告，或 ConvaiObjectComponentLog 以查看已跟踪属性和注视警告。

角色没有提到该对象

症状： 角色从未引用一个 Actor 其具有一个 UConvaiObjectComponent.

空名称

原因： 名称为空的对象 ObjectEntry.Name 会被该子系统拒绝。该组件必须具有非空名称。

修复： 打开 Actor的 Details 面板中，选择 UConvaiObjectComponent，并确认 ObjectEntry.Name 已设置。

验证： 进入 Play 模式，并使用你设置的名称询问该对象。如果回答没有使用该对象上下文，请在 Output Log 中检查空名称警告。

运行时添加的对象未附带对象组件

原因： 一个生成的 Actor 带有有效的 UConvaiObjectComponent 会在 BeginPlay处自行注册。如果你在没有 UConvaiObjectComponent的情况下手动管理环境条目，聊天机器人需要一个匹配的 AddObject 调用来处理新条目。

修复： 将一个已配置的 UConvaiObjectComponent 添加到该生成的 Actor，或者调用 AddObject 在创建手动 FConvaiObjectEntry后，在聊天机器人组件上执行。 bFlushImmediately = true 当会话已经激活且角色需要在下一次运行时更新中获取该对象时使用。

验证： 在调用 AddObject后，询问该对象，并检查回复是否使用了新的对象上下文。

防抖延迟

原因： AddObject 与 bFlushImmediately = false 会将更新排入防抖窗口。该更新要到下一次环境刷新时才会发送。

修复： 等待防抖窗口刷新，或者使用 bFlushImmediately = true 用于对时效性敏感的运行时添加。

验证： 确认聊天机器人会话处于 Connected 状态，然后再期待实时 update-scene-metadata 推送。

对象引用解析到了错误的 Actor

症状： 角色使用了意外的名称引用对象，或者导航目标指向了错误的 Actor.

原因： 两个 UConvaiObjectComponent 实例共享相同的 ObjectEntry.Name. UConvaiSubsystem 会自动重命名重复项，但重命名后的标签可能与告诉角色的名称不一致。

修复： 按 ConvaiSubsystemLog 筛选 Output Log，并查找位于 BeginPlay处的重名警告。确保每个 UConvaiObjectComponent 在关卡中的 ObjectEntry.Name.

验证： 修正名称后，重新进入 Play 模式，并确认该 Actor.

已跟踪属性未更新

症状： 当某个 Actor 属性在运行时发生变化时，聊天机器人没有收到新值。

手动路径输入

原因： 手动输入 PropertyPath 如果该路径无法在运行时针对 Actor 进行解析，手动输入可能会失败。 Bind 按钮会在编辑时执行解析，是可靠的方法。

修复： 删除手动输入的条目，点击 Bind，然后从选择器中选择该属性。

验证： 在 Play 模式下更改属性值，并按 ConvaiObjectComponentLog 筛选 Output Log 中的已跟踪属性警告。或者，询问该属性，并检查回复是否使用了当前值。

不支持的属性类型

原因： TrackedProperties 支持诸如以下的叶子值 bool、数值类型、 FString, FName, FText、枚举、白名单内的值结构体、受支持叶子类型的容器、结构体成员路径，以及返回受支持叶子值的纯无参函数。对象引用、类引用、委托和多播委托不受支持；不受支持的路径会被跳过并记录警告。

修复： 确认该属性类型受支持。对于复杂状态，公开一个返回受支持叶子值的纯无参函数，然后绑定到该函数名。

验证： 切换到受支持的类型或函数后，在 Play 模式下更改值，并检查是否不再出现不受支持路径警告。

路径已被跟踪

原因： AddTrackedProperty 返回 false 如果该路径已在列表中，则会拒绝重复路径。

修复： 检查 AddTrackedProperty的返回值。在添加同一路径的新条目之前，先移除现有条目。

验证： 确认 AddTrackedProperty 返回 true ，然后更改属性值并检查是否出现动态上下文更新。

后BeginPlay 宽限窗口

原因： 在之后约最初一秒内发生的更改 BeginPlay 会被强制设为 EC_RunLLMOption::Never ，无论属性设置如何都是如此。这样可防止启动噪声让每个聊天机器人都对初始游戏状态作出反应。

修复： 这是预期行为。如果某个属性具有有意义的初始值，会话开始时的种子（始终使用 从不）会正确携带它。

验证： 在 Play 开始超过一秒后更改属性值，并检查更新是否遵循已配置的 ShouldRespond 设置。

聊天机器人对属性变化没有反应

症状： 已跟踪的属性值在运行时发生变化，但角色什么也没说。

原因： ShouldRespond 被设置为 从不.

修复： 将 ShouldRespond 到 Always 或 自动 用于你希望角色对其变化进行描述的属性。

验证： 在会话开始后一秒以上于 Play 模式下更改属性值，并确认该更新不再被配置为静默传递。

会话开始时的初始种子始终使用 EC_RunLLMOption::Never。后续更改使用已配置的 ShouldRespond 在后置BeginPlay 宽限窗口之后。

运行时更新后的环境仍然过期

症状： 运行时对象更新似乎没有影响角色的场景上下文。

运行时更新仍在等待

原因： 使用 bFlushImmediately = false （默认），更新会在防抖窗口中等待。更新到达 Convai 之前可能会有短暂延迟。

修复： 等待防抖窗口过期，或者调用 AddObject 与 bFlushImmediately = true ，当需要即时生效时。

验证： 在防抖窗口过期后（或在使用 bFlushImmediately = true）之后，询问该对象并检查回复是否使用了新的对象上下文。

描述 会话中途的更改未反映

症状： 更新会话开始时已存在对象的描述，不会改变角色对该对象的理解。

原因： 如果该对象已经在 action_config 在 /connect，则该冻结快照中的描述无法通过 AddObject更改。实时 update-scene-metadata 通道只接受对该会话而言是新加入的对象。

修复： 调用 StopSession 然后 StartSession 重新连接。新会话会将更新后的描述在一个新的 action_config.

验证： 重新连接后，询问该对象并检查回复是否使用了更新后的描述。

邻近状态显示了错误的描述

症状： 聊天机器人收到某个 Actor.

没有 NavMesh

原因： 邻近计算使用 Unreal Engine 导航系统。如果没有 NavMesh 覆盖该区域，可达性将被标记为没有行走路径或不可达。

修复： 添加一个 NavMeshBoundsVolume 添加到关卡并重新构建导航（或启用动态导航）。确认聊天机器人 Actor 已配置导航代理。

验证： 启用 bDebugDrawProximityPaths 在 UConvaiObjectComponent 并进入 Play 模式。绿色路径表示对象可达，青色表示聊天机器人已在目标处，红色表示当前查询没有有效的行走路径。如果路径为红色，请检查 NavMeshBoundsVolume 覆盖范围和导航代理设置。

使用调试路径绘制进行诊断

原因： 如果看不到导航路径查询结果，可达性问题很难诊断。

修复： 临时启用 bDebugDrawProximityPaths 在 UConvaiObjectComponent 并进入 Play 模式。该插件会绘制每个聊天机器人到该对象的导航路径。发布前请关闭该标志。

验证： 绿色路径表示可达，青色表示聊天机器人已在目标处，红色表示当前查询没有有效的行走路径。

SetObjectInAttention 没有效果

症状： 调用 SetObjectInAttention 不会改变聊天机器人的注意力目标。

原因： bEnableActions 为 false。注意力系统是动作管线的一部分；当动作被禁用时，注意力更新没有效果。

修复： 启用 bEnableActions 在 UConvaiChatbotComponent.

验证： 重启会话并调用 SetObjectInAttention 再次。确认 AttentionSource 为 显式（Blueprint/C++） 在聊天机器人组件上。

改进对象描述

Convai 接收 描述 字段作为对象上下文。模糊的描述会给角色带来不太有用的场景信息。

避免	改用
“一个灭火器”	“红色 ABC 干粉灭火器，安装在南侧墙面与视线齐平的位置，紧挨着紧急出口。”
“门”	“带黄色警示条纹的厚重钢制压力门，通往去污室。”
“机器”	“3 号工位的工业液压机，用于压缩样品容器。安全护罩为橙色。”
“箱子”	“入口附近左侧货架上的灰色补给箱，带红色十字标记，内含医疗用品。”

从熟悉情况的向导或讲师会说的角度撰写描述。包括：

• 相对于地标或房间特征的位置
• 视觉标识——颜色、大小、材质
• 功能或用途（如适用）

每条描述都要足够简洁，便于快速浏览，同时又要足够具体，以便识别对象。文本会作为对象上下文发送，因此请包含角色进行对话所需的细节。

决策树

当 AI 在会话开始后没有对场景对象作出响应时，请使用此树：

UConvaiObjectComponent 上的 ObjectEntry.Name 是否非空？
├── 否  → 在 Details 面板中设置一个唯一且非空的 Name。
└── 是 → 生成的 Actor 是否具有有效的 UConvaiObjectComponent？
          ├── 否  → 添加该组件，或为手动 FConvaiObjectEntry 调用 AddObject。
          └── 是 → 在使用连接时动作或注意力时，聊天机器人的 EnvironmentData 中 bEnableActions 是否为 true？
                    ├── 否  → 启用 bEnableActions。
                    └── 是 → 描述是否具体且客观？
                              ├── 否  → 结合位置、视觉标识和用途重新撰写。
                              └── 是 → 按 ConvaiSubsystemLog 过滤 Output Log，并检查 BeginPlay 时是否有重名警告。

下一步

场景元数据如何工作场景元数据组件参考