视觉故障排查

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

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

诊断顺序

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

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: 正在发送原始图像 在帧捕获成功后。

下一步

视觉 Blueprint 参考视觉使用示例视觉快速开始