> 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).

# 排查视觉问题

修复常见 Unreal 视觉问题，包括缺少视觉上下文、启动失败、空白渲染目标和无效源注册。

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

### 诊断顺序

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

1. 在 **Convai Chatbot** 组件，调用 **支持视觉**.
2. 当 **环境摄像头**，调用 **获取状态**.
3. 当 **环境摄像头**，调用 **获取上一个错误消息** 和 **获取上一个错误代码**.
4. 确认 **Convai 渲染目标** 已分配在 **详情** 面板中。
5. 在 **内容浏览器** 中于编辑器内运行期间打开渲染目标资产，并确认预览更新。
6. 在 **输出日志**，按 `ConvaiChatbotComponentLog` 过滤，并查找 `SendImage: 正在发送原始图像` 或 `SendImage: 无法捕获原始数据`.

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

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

**症状：** 角色会回应语音，但会忽略场景中可见的对象。

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

**修复：**

1. 将 **环境摄像头** 放在同一 `Actor` 与 **Convai Chatbot** 组件，或者调用 **Set Vision Component** 并传入摄像头引用。
2. 调用 **获取状态**。如果它返回 `已停止`，调用 **Start** 来自 `BeginPlay` 或者启用 `bAutoStartVision`.
3. 分配一个 `UTextureRenderTarget2D` 到 **Convai 渲染目标**.
4. 如果在初始连接设置后添加视觉组件，请启用 **始终允许视觉** 在 **Edit > Project Settings > Plugins > Convai** （高级类别），然后重新连接会话。

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

### Start 没有效果——组件保持在 Stopped

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

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

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

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

**诊断消息：** **获取上一个错误消息** 返回 `ConvaiRenderTarget 为空。无法开始捕获。` 当出现此失败时。

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

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

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

**修复：**

1. 选择 **环境摄像头** 并确认其 `+X` 轴朝向你希望角色看到的场景区域。
2. 调用 **获取状态**。如果状态是 `已停止`，调用 **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` 不是有效的帧源。

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

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

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

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

**修复：**

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

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

### 下一步

{% content-ref url="/pages/ec5b9bfb145ddc8145050976e8e8db28d33fc076" %}
[视觉 Blueprint 参考](/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 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/vision/troubleshoot-vision.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.