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

# 视觉的工作原理

了解 Unreal 视觉组件如何被发现、启动、限流，以及如何在 Convai 会话期间用于发送场景帧。

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

### 运行时会发生什么

内置流程由三部分组成：

1. **帧源** — **环境摄像头** (`UEnvironmentWebcam`）通过一个 `USceneCaptureComponent2D` 并写入到一个 `UTextureRenderTarget2D`.
2. **Vision 契约** — `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
```

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

### 关键概念

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

### 组件发现

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

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

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

### 捕获并上传

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

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

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

### Vision 状态和事件

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

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

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

### 后期 Vision 设置

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

启用 `AlwaysAllowVision` 在 **Edit > Project Settings > Plugins > Convai** （高级类别）仅当你的项目在初始连接设置之后注册或替换 vision 组件时使用。

### 下一步

{% 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" %}
[视觉 Blueprint 参考](/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 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/how-vision-works.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.