> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/troubleshoot-scene-metadata.md).

# 排查场景元数据问题

使用此页面诊断 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。

{% hint style="info" %}
打开 **输出日志** 在 Unreal Engine 中，并按 `ConvaiSubsystemLog` 过滤以查看对象注册和重名警告，或 `ConvaiObjectComponentLog` 以查看已跟踪属性和注视警告。
{% endhint %}

### 角色没有提到该对象

**症状：** 角色从未引用一个 `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 模式下更改属性值，并确认该更新不再被配置为静默传递。

{% hint style="info" %}
会话开始时的初始种子始终使用 `EC_RunLLMOption::Never`。后续更改使用已配置的 `ShouldRespond` 在后置`BeginPlay` 宽限窗口之后。
{% endhint %}

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

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

#### 运行时更新仍在等待

**原因：** 使用 `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 时是否有重名警告。
```

### 下一步

{% content-ref url="/pages/a6fd7e3b5ee94be300d9c248743b197b93cc0c96" %}
[场景元数据如何工作](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/how-scene-metadata-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/5b34043c604b8f8fd8088c66f01ea7887fcd8846" %}
[场景元数据组件参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/scene-metadata-component-reference.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/troubleshoot-scene-metadata.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.