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

# 排查 Vision 问题

当场景视觉未按预期工作时使用此页。每条记录列出症状、可能原因、修复方法以及如何验证修复。

### 诊断顺序

在逐一排查单个问题之前，请先检查这些信号：

1. 在 **Convai Chatbot** 组件，调用 **支持视觉**.
2. 开启 **环境摄像头**，调用 **获取状态**.
3. 开启 **环境摄像头**，调用 **获取最后错误消息** 和 **获取最后错误代码**.
4. 确认 **Convai 渲染目标** 已在 **详细信息** 面板中分配。
5. 在 **内容浏览器** 中打开渲染目标资源，在编辑器内运行（Play In Editor）期间，并确认预览会更新。
6. 在 **输出日志**，按 `ConvaiChatbotComponentLog` 筛选并查找 `SendImage: 正在发送原始图像` 或 `SendImage: 无法捕获原始数据`.

| 信号           | 正常值                   |
| ------------ | --------------------- |
| **支持视觉**     | `true`                |
| **获取状态**     | `正在捕获` 在活动捕获会话期间      |
| **获取最后错误消息** | 成功启动后为空字符串            |
| 渲染目标预览       | 在编辑器内运行期间显示场景内容       |
| 输出日志         | `SendImage: 正在发送原始图像` |

### 角色不会对视觉上下文作出响应

**症状：** 角色会对语音做出响应，但会忽略场景中可见的物体。

**原因：** 帧源未在聊天机器人中注册，捕获未处于 `正在捕获` 状态，或者会话是在视觉功能可用之前创建的。

**修复：**

1. 放置 **环境摄像头** 在同一 `Actor` 上，和 **Convai Chatbot** 组件上，或者调用 **Set Vision Component** 并传入摄像头引用。
2. 调用 **获取状态**。如果它返回 `Stopped`，调用 **Start** 从 `BeginPlay` 或启用 `bAutoStartVision`.
3. 分配一个 `UTextureRenderTarget2D` 设为 **Convai 渲染目标**.
4. 如果在初始连接设置后添加视觉组件，请启用 **始终允许视觉** 在 **编辑 > 项目设置 > 插件 > Convai** （高级类别），然后重新连接会话。

**验证：** **支持视觉** 返回 `true`, **获取状态** 返回 `正在捕获`，且角色会在响应中引用可见的场景内容。

### Start 无效——组件保持在 Stopped 状态

**症状：** 调用 **Start** 不会将组件移动到 `正在捕获`. **获取状态** 仍然返回 `Stopped`.

**原因：** **Convai 渲染目标** 未分配。 `UEnvironmentWebcam` 检查 `CanStart()` 在转换之前。

**修复：** 分配一个 `UTextureRenderTarget2D` 设为 **Convai 渲染目标**。从 **Convai > Vision Render Target** 中创建该资源 **内容浏览器** 以使用插件默认值（`512 x 512`, `RTF_RGBA8`，黑色清除颜色）。

**验证：** 调用 **Start** 再次。 **获取状态** 应返回 `正在捕获` 在一个 tick 内。

**诊断消息：** **获取最后错误消息** 返回 `ConvaiRenderTarget 为空。无法开始捕获。` 当发生此失败时。

### 渲染目标显示为黑色或空白

**症状：** 在 **内容浏览器** 中的渲染目标预览或调试小部件显示完全黑色的图像。

**原因：** **环境摄像头** 未朝向可见的场景几何体、捕获尚未开始，或者内部捕获源已更改。

**修复：**

1. 选择 **环境摄像头** 并确认其 `+X` 轴面向你希望角色看到的场景区域。
2. 调用 **获取状态**。如果状态是 `Stopped`，调用 **Start** 或启用 `bAutoStartVision`.
3. 选择嵌套的 `EnvironmentSceneCapture2D` 子组件（ `CaptureComponent` 属性），并确认 **捕获源** 是 `SCS_FinalToneCurveHDR`.
4. 如果 `bCopyPostProcessProperties` 是 `true`，请确认关卡中存在后期处理体积。如果没有，请禁用该属性。

**验证：** 在编辑器内运行时，渲染目标预览应随场景内容更新。

### 开启视觉时角色响应延迟较高

**症状：** 与不使用视觉的对话相比，角色响应时间明显增加。

**原因：** 帧正以默认 `15` FPS 发送。

**修复：** 降低捕获频率。将 **最大 FPS** (`m_MaxFPS`）设置为 `5` 中创建该资源 **详细信息** 面板，或调用 **设置最大 FPS** 值设为 `5`.

**验证：** 在更改前后测量响应时间。该 **输出日志** 仍应显示 `SendImage: 正在发送原始图像` 以降低后的频率。

### 调用 Set Vision Component 后，Supports Vision 返回 false

**症状：** **Set Vision Component** 返回 `false` 且聊天机器人仍报告不支持视觉。

**原因：** 传入的组件未实现 `UConvaiVisionInterface`.

**修复：** 传入一个 `UConvaiWebcamBase` 子类，例如 `UEnvironmentWebcam`，或其他实现了 `IConvaiVisionInterface`。普通的 `USceneCaptureComponent2D` 不是有效的帧源。

**验证：** 在 Blueprint 中将该组件转换为 `UConvaiWebcamBase` 。如果转换成功，将其传入 **Set Vision Component** 并确认返回值为 `true`.

### 控制台警告无法捕获原始数据

**症状：** 该 **输出日志** 显示 `SendImage: 无法捕获原始数据`.

**原因：** `UConvaiChatbotComponent::SendImage()` 被调用 `CaptureRaw()`，但活动帧源返回了 `false` 或空的帧数据。

**修复：**

1. 确认 **获取状态** 返回 `正在捕获`.
2. 确认 **Convai 渲染目标** 已分配。
3. 打开渲染目标预览并验证其中包含场景内容。
4. 对于自定义视觉组件，请确认 `CaptureRaw()` 填充 `宽度`, `高度`，和 `数据`，并返回 `true`.

**验证：** 该 **输出日志** 应切换为 `SendImage: 正在发送原始图像` 在帧捕获成功后。

### 下一步

{% content-ref url="/pages/ec5b9bfb145ddc8145050976e8e8db28d33fc076" %}
[视觉蓝图参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/vision-blueprint-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/cf86fde91936bc6994c59ccac11271cc09e11fea" %}
[视觉使用示例](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/vision-usage-examples.md)
{% endcontent-ref %}

{% content-ref url="/pages/ffb5a5d9ba2394107ce64c0b07938a181186f763" %}
[视觉快速开始](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/vision-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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/troubleshoot-vision.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.