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

# 视觉的工作方式

视觉会向 Convai 对话中添加场景图像。角色上的帧源组件捕获关卡，并且 **Convai Chatbot** 该组件在会话处于活动状态时将这些帧发送到 Convai。

### 运行时会发生什么

内置路径有三个部分：

1. **帧源** — **环境摄像头** (`UEnvironmentWebcam`）通过一个 `USceneCaptureComponent2D` 并写入到一个 `UTextureRenderTarget2D`.
2. **视觉契约** — `IConvaiVisionInterface` 定义了聊天机器人期望任何帧源提供的方法。
3. **聊天机器人发送器** — `UConvaiChatbotComponent` 在同一个 `Actor`，按配置速率读取帧，并通过活动会话发送它们。

```mermaid
flowchart LR
    subgraph frameSourceLayer["帧源"]
        environmentWebcam["UEnvironmentWebcam"]
    end

    visionInterface["IConvaiVisionInterface"]
    chatbot["UConvaiChatbotComponent"]
    sendImage["SendImage"]
    sessionProxy["UConvaiConnectionSessionProxy"]
    convai["Convai"]

    environmentWebcam -->|"实现"| visionInterface
    visionInterface --> chatbot
    chatbot --> sendImage
    sendImage --> sessionProxy
    sessionProxy --> convai
```

视觉附加到 **聊天机器人角色**，而不是玩家 Pawn。玩家组件发起对话；聊天机器人组件负责帧发现和上传。

### 关键概念

| 概念        | 这意味着什么                                                         |
| --------- | -------------------------------------------------------------- |
| **帧源**    | 聊天机器人上的一个组件 `Actor` 实现了 `IConvaiVisionInterface` 并提供图像数据。      |
| **环境摄像头** | 随附的帧源。它将场景捕获到渲染目标中。它不是物理设备摄像头。                                 |
| **渲染目标**  | 该 `UTextureRenderTarget2D` 分配给 **Convai 渲染目标**。捕获组件将场景像素写入此资源。 |
| **视觉状态**  | `EVisionState` 跟踪捕获是否处于活动状态。随附实现只设置 `Stopped` 和 `正在捕获` 。       |
| **帧节流**   | 聊天机器人根据源组件的 **最大 FPS** (`m_MaxFPS`），并限制为 `1`–`60` 在上传期间。       |
| **视频连接**  | 会话设置使用连接类型 `video` 当支持视觉或当 `AlwaysAllowVision` 在项目设置中启用时。      |

### 组件发现

在 `BeginPlay`, `UConvaiChatbotComponent` 搜索所属的 `Actor` ，查找实现了 `UConvaiVisionInterface` 并注册第一个匹配项。

* **Set Vision Component** 当同一个 `Actor`.
* **支持视觉** 返回 `true` 当注册了有效源时。如果尚未注册任何源，聊天机器人会搜索 `Actor` 一次后再返回。
* 传入一个普通的 `USceneCaptureComponent2D` 设为 **Set Vision Component** 返回 `false`。捕获组件不是 Convai 帧源。

`Set Vision Component` 和 **支持视觉** 由 `UConvaiPlayerComponent`继承，但它们返回 `false` 在那里，因为只有 `UConvaiChatbotComponent` 才启用视觉注册。请在聊天机器人组件上使用这些节点。

### 捕获并上传

当 **环境摄像头** 处于 `正在捕获` 状态：

1. 其内部 `USceneCaptureComponent2D` 将场景渲染到 **Convai 渲染目标**.
2. 每次聊天机器人 tick 会累积时间，直到来自 `GetMaxFPS()` 达到。
3. 聊天机器人调用 `CaptureRaw()` 在活动源上，并通过 `SendImage`.
4. Convai 通过活动视频连接接收这些帧。

默认发送间隔为 `1.0f / 15.f`。如果 `GetMaxFPS()` 返回 `0` 或是无效值，聊天机器人会回退到 `15` FPS 作为上传计时。

### 视觉状态和事件

`EVisionState` 包括 `Stopped`, `启动中`, `正在捕获`, `停止中`，和 `已暂停`。在当前随附实现中， **环境摄像头** 仅在 `Stopped` 和 `正在捕获`.

Blueprint 用户可以绑定 **帧就绪时** 到帧源上。它会在 tick 期间广播，只要组件处于 `正在捕获` 且该事件至少有一个绑定。

C++ 集成也可以使用 `FOnVisionStateChanged`, `FOnFirstFrameCaptured`，和 `FOnFramesStopped` 在 `IConvaiVisionInterface`。这些委托不能在 Blueprint 中赋值。

### 延迟视觉设置

常规 Blueprint 设置会将 **环境摄像头** 放在聊天机器人上 `Actor` 之前 `BeginPlay`。在这种情况下， **支持视觉** 足以让会话设置选择 `video` 连接。

启用 `AlwaysAllowVision` 在 **编辑 > 项目设置 > 插件 > Convai** （高级类别）仅当你的项目在初始连接设置之后注册或替换视觉组件时使用。

### 下一步

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

{% content-ref url="/pages/a5aa237a7b13fb2c8d46ff004c1de14a2c4cda2a" %}
[视觉帧来源](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/vision-frame-sources.md)
{% endcontent-ref %}

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


---

# 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/how-vision-works.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.