> 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/spatial-awareness/troubleshoot-spatial-awareness.md).

# 排查空间感知问题

修复角色什么都不描述、把对象隐藏在墙后、把所有东西都读作很远，或混淆重复对象名称的问题。

使用此页面来诊断并修复最常见的空间感知问题。每个条目都遵循“症状 / 原因 / 修复 / 验证”的结构。

{% hint style="info" %}
如果你还没有完成基础设置，请先从 [空间感知快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/spatial-awareness-quick-start.md) 开始，并且只有在某个特定症状持续存在时才返回这里。
{% endhint %}

### 角色完全没有描述任何内容

**症状：** 该 **周围环境** 面板在为选定的聊天机器人显示时是空的，即使在 `UConvaiObjectComponent` 附近有演员。

**原因：** 以下条件之一：

* **启用空间感知** (`bEnableSpatialAwareness`) 在以下位置处于关闭状态： **编辑 > 项目设置 > 插件 > Convai > 空间感知** — 主开关。关闭时，不会为任何聊天机器人生成事实。
* 附近对象的 `UConvaiObjectComponent` 具有 **已启用** (`bConvaiEnabled`) 未勾选，或者 **包含在空间感知中** (`bIncludeInSpatialAwareness`) 未勾选。任一项都会将该单个对象从空间感知中移除，而不影响系统其他部分。
* 聊天机器人自身的 **接收周围环境** (`bReceiveSurroundings`) 处于关闭状态，位于 **Convai | 空间感知** （高级显示）在 `UConvaiChatbotComponent`.

**修复：**

1. 检查 **启用空间感知** 在以下位置 **编辑 > 项目设置 > 插件 > Convai > 空间感知**.
2. 选择对象的 `UConvaiObjectComponent` 并确认两者都 **已启用** 和 **包含在空间感知中** 已勾选。
3. 选择聊天机器人的 `UConvaiChatbotComponent`，展开 **Convai | 空间感知**，并确认 **接收周围环境** 已勾选。

**验证：** 进入播放模式，打开 [Convai 调试覆盖层](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay.md)，选择该聊天机器人，并确认对象行出现在 **周围环境**.

***

### 墙后面的对象仍会被描述

**症状：** 聊天机器人描述了一个它本不应能看到的对象——例如，在实体墙另一侧的对象。

**原因：** **启用视线** (`bEnableLineOfSight`) 默认未勾选。关闭后，不管对象与观察者之间有什么，都会描述每个主体。

**修复：** 在……下方 **编辑 > 项目设置 > 插件 > Convai > 空间感知**，勾选 **启用视线**。这会在每次轮询时为每个聊天机器人/主体对添加一次线性射线检测，因此仅在项目能接受该开销的地方启用它。

**验证：** 进入播放模式，将聊天机器人放置到被墙阻挡已注册对象视线的位置，并确认该对象的行从 **周围环境** 在 [Convai 调试覆盖层](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay.md).

***

### 所有内容都显示为“很远”

**症状：** 关卡中的每个对象在周围环境文本中都显示为“很远”，即使那些离聊天机器人很近的对象也是如此。

**原因：** **近距离** 和 **中等距离** 以厘米为单位设置，默认值为 `1000.0` 厘米和 `4000.0` 厘米。按不同尺度构建的关卡（更大的房间、车辆尺度的地图）可能会让每个主体都超出 `ModerateDistance` 的范围，即使看起来距离很近。

**修复：** 在……下方 **编辑 > 项目设置 > 插件 > Convai > 空间感知**，提高 **近距离** 和 **中等距离** 以匹配关卡的尺度。保持 **中等距离** 大于 **近距离** ——这些值不会彼此校验。

**验证：** 进入播放模式，让聊天机器人站在已注册对象附近，并确认其在 **周围环境** 中显示为“近旁”或“有一定距离”，而不是“很远”。

***

### 对象之间的关系从未出现

**症状：** 单个对象会在 **周围环境**中被描述，但聊天机器人从不提及两个对象之间如何关联（例如，“枪在箱子上面”）。

**原因：** 以下条件之一：

* **启用关系** (`bEnableRelations`) 在以下位置处于关闭状态： **编辑 > 项目设置 > 插件 > Convai > 空间感知**.
* 这两个对象之间的距离大于 **关系聚类距离** (`RelationClusterDistance`，默认 `600.0` 厘米）。
* 聊天机器人的 **接收关系** (`bReceiveRelations`) 处于关闭状态，位于 **Convai | 空间感知** 位于 `UConvaiChatbotComponent`.

**修复：**

1. 检查 **启用关系** 在以下位置 **编辑 > 项目设置 > 插件 > Convai > 空间感知**.
2. 将对象移动到小于 **关系聚类距离**，或者增大距离以将它们包含进去。
3. 选择聊天机器人的 `UConvaiChatbotComponent` 并确认 **接收关系** 已勾选。

**验证：** 进入播放模式，让两个相关对象处于 **关系聚类距离** 范围内，并确认它们的关系事实出现——检查 **事实** 在 [Convai 调试覆盖层](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay.md).

***

### 重复的对象名称会让角色感到困惑

**症状：** 聊天机器人指向了错误的箱子，或者其回复表明它无法区分两个同名对象。

**原因：** 以下条件之一：

* 这些对象本应被区分开，但 **重复名称后缀样式** (`ObjectNameSuffixStyle`) 生成了一个 AI 没有正确使用的后缀——请检查设置的是哪种样式（`数字` 或 `字母`) 在以下位置 **编辑 > 项目设置 > 插件 > Convai > 对象**.
* 这些对象本应被视为一个整体——一堆相同的道具——但 **与同名对象合并** 在它们的 `UConvaiObjectComponent`上处于关闭状态，因此它们仍会加后缀并被分别称呼，而不是合并。

**修复：**

* 要保持对象彼此独立，请确认 **重复名称后缀样式** 生成了你期望的名称，并且在编写必须针对某个特定成员的动作或对话时，请使用对象的完整后缀名称来引用它（例如，“Crate 2”）。
* 要将这些对象视为一个整体，请开启 **与同名对象合并** 在每个成员上——参见 [合并同名物体](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/merge-same-named-objects.md).

**验证：** 进入播放模式，打开 [Convai 调试覆盖层](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay.md)，并确认 **周围环境** 显示的是每个对象一行带后缀的条目（独立），还是一条合并后的条目（已合并），以符合你的意图。

***

### 空间文本过长

**症状：** 发送给 Convai 的上下文明显比预期更大，或者聊天机器人的回复表明它收到了冗余的位置资讯。

**原因：** **从玩家视角描述** (`bDescribePlayerPerspective`) 会为每条空间事实添加第二个分句，使其长度大约翻倍。默认已勾选。

**修复：** 在……下方 **编辑 > 项目设置 > 插件 > Convai > 空间感知**，取消勾选 **从玩家视角描述** 如果你的聊天机器人不需要从玩家自己的视角向玩家指路，请取消勾选。请参见 [从玩家视角描述物体](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/describe-from-player-perspective.md) 了解开启时该分句会添加什么。

**验证：** 进入播放模式，打开 [Convai 调试覆盖层](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay.md)，并确认其中的每一行在 **周围环境** 现在只显示聊天机器人自身的参照系，不再有“From `<Player>`'s position, ..." 分句。

***

### 下一步

{% content-ref url="/pages/7e106191f2eaa9dd6a1b3cfbbbf3a7e6e171e3bf" %}
[空间感知的工作原理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/how-spatial-awareness-works.md)
{% endcontent-ref %}

{% content-ref url="/pages/61357e0f0cdf694475bb5b1ab006fa4ae40d02e2" %}
[空间感知设置参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/spatial-awareness-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/280824f0950858984da0cf561a8148bbd7eee0e8" %}
[空间感知快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/spatial-awareness/spatial-awareness-quick-start.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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.