> 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` 不为空** —— 名称为空的对象会被拒绝，并记录为 `位于 %s 的 ConvaiObjectComponent 已跳过：ObjectEntry.Name 为空`。在 `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`'s Details 面板中，选择 `UConvaiObjectComponent`，并确认 `ObjectEntry.Name` 已设置。

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

#### 运行时添加的对象却没有对象组件

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

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

**验证：** 在调用 `AddObject`之后，询问该对象，并检查响应是否使用了新的对象上下文。

#### 去抖延迟

**原因：** `AddObject` 并将 `bFlushImmediately = false` 会将更新排队到去抖窗口中。更新要到下一次环境刷新时才会发送。

**修复：** 等待去抖窗口刷新，或者在时间敏感的运行时添加中使用 `bFlushImmediately = true` 。

**验证：** 确认聊天机器人会话处于 `已连接` 状态，然后再期待实时的 `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` ，无论属性设置如何。这可防止启动噪声让每个聊天机器人都对初始游戏状态作出反应。

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

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

### 聊天机器人不响应属性变化

**症状：** 一个已跟踪属性的值在运行时发生变化，但角色没有说话。

**原因：** `ShouldRespond` 被设置为 `Never`.

**修复：** 更改 `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` 描述为距离错误、方向错误，或者本应可达却不可达。

场景元数据现在不再自行计算这一点——自 `4.0.0-beta.22`起，每个已注册对象的距离、方向和可达性都由 [空间感知](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness.md) 子系统集中计算，而不是由各个 `UConvaiObjectComponent`。请参阅 [排查空间感知](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/troubleshoot-spatial-awareness.md) 了解完整的症状与修复集合，包括空描述、错误的距离区间，以及对象被错误地隐藏在墙后。

#### 没有 NavMesh

**原因：** 可达性依赖于 Unreal Engine 导航系统。如果没有 NavMesh 覆盖该区域，则会将一个 `UConvaiObjectComponent` 报告为没有步行路径或不可达。

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

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

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

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

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

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

### `SetObjectInAttention` 没有效果

**症状：** 调用 `SetObjectInAttention` 在 Blueprint 中执行不会改变聊天机器人的注意力目标。

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

**修复：** 启用 `bEnableActions` 在 `UConvaiChatbotComponent`.

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

### 改进对象描述

Convai 接收 `说明` 字段作为对象上下文。模糊的描述会给角色提供较少有用的场景信息。

| 避免                      | 应改为使用                                |
| ----------------------- | ------------------------------------ |
| `“A fire extinguisher”` | `“位于南墙、眼睛高度处、紧邻紧急出口的红色 ABC 干粉灭火器。”`  |
| `“Door”`                | `“通往去污室的重型钢制压力门，带有黄色警示条纹。”`          |
| `“Machine”`             | `“3 号工位的工业液压压力机，用于压缩样品容器。安全防护罩为橙色。”` |
| `“Box”`                 | `“入口附近左侧架子上的灰色供应箱，带有红色十字标记，内含医疗用品。”` |

从知识渊博的向导或讲师会说的话的角度来编写描述。包括：

* 相对于地标或房间特征的位置
* 视觉识别标识——颜色、大小、材质
* 相关的功能或用途

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

### 决策树

当 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 %}

{% content-ref url="/pages/7ae0cd173a36a87a1546f41623ce3ca4da2a289b" %}
[排查空间感知问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/troubleshoot-spatial-awareness.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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.