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

# 视觉的工作原理

了解 Vision 管线架构，包括帧来源、发布策略、到 Convai 的 WebRTC 轨道，以及动态视觉上下文如何融入其中。

Vision 会将实时摄像头画面从 Unity 流式传输到 Convai，并与音频对话一同处理。本页介绍其管线架构、各组件的作用，以及 Vision 启动时 SDK 在运行时执行的操作。

### 架构

帧源从场景中捕获图像，并将其传递给 `ConvaiVisionPublisher`，它通过 LiveKit 层管理 WebRTC 视频轨道。协调器会应用已配置的发布策略（帧率和比特率），然后将帧转发给 Convai，与音频对话一同进行 AI 处理。

```mermaid
flowchart LR
    subgraph Sources["帧源（任选其一）"]
        A1[CameraVisionFrameSource]
        A2[WebcamVisionFrameSource]
        A3[QuestVisionFrameSource]
    结束

    B[ConvaiVisionPublisher\nIConvaiModule]
    C[VisionPublishCoordinator]
    D[VideoTrackManager]
    E[LiveKit Room\nWebRTC]
    F[Convai\nAI Vision Processing]

    A1 -->|RenderTexture| B
    A2 -->|RenderTexture| B
    A3 -->|RenderTexture| B
    B --> C
    C -->|策略：FPS + 比特率| D
    D -->|AsyncGPUReadback| E
    E -->|WebRTC 视频轨道| F
```

在 WebGL 上， `ConvaiVisionPublisher` 会完全绕过帧源，直接通过 `canvas.captureStream()`发布浏览器画布。所有平台上的 WebRTC 和 Convai 处理层均相同。

### 关键概念

| 概念                | 含义                                                                                                                      |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **帧源**            | 一个 `MonoBehaviour` ，用于捕获帧，并将其作为 Y 轴翻转的 `RenderTexture`提供。内置的三种实现分别支持 Unity 摄像机、实体网络摄像头和 Meta Quest 透视画面。                |
| **发布策略**          | 控制向 Convai 流式传输时客户端使用的帧率和比特率。不控制后端使用的 AI 模型或视觉服务提供商。                                                                    |
| **视频轨道**          | 发布到当前 Convai 房间的 WebRTC 视频轨道。通过 **轨道名称** 字段进行标识，该字段位于 `ConvaiVisionPublisher` （默认值： `"unity-scene"`).                   |
| **房间连接**          | 只有当 `ConvaiRoomManager` 已连接，且 **连接类型** 设置为 **视频**时，Vision 才会发布视频。仅音频连接不传输视频。                                            |
| **动态 Vision 上下文** | 一种由后端驱动的加性采样模式。Convai 不会处理每个到达的视频帧，而是将视频轨道采样到滚动缓冲区中，并决定哪些帧以及何时发送给模型。通过 `ConvaiVisionContextMode` 在 `ConvaiRoomManager`. |

### 组件放置位置

了解各组件应放置的位置，可以避免最常见的设置错误。

| 组件                        | 通过以下方式添加                                           | 放置位置                     | 备注                                                        |
| ------------------------- | -------------------------------------------------- | ------------------------ | --------------------------------------------------------- |
| `ConvaiRoomManager`       | —                                                  | 任意持久场景 GameObject        | **连接类型** 必须设置为 **Video**                                  |
| `ConvaiVisionPublisher`   | —                                                  | 任意持久场景 GameObject        | 通常放置在 NPC 的根对象上或其附近。没有 `Add Component` 菜单项——请将其直接添加为脚本组件。 |
| `CameraVisionFrameSource` | `Convai/Vision/Camera Vision Frame Source`         | 与发布器相同的 GameObject 或其子对象 | 每个采集源添加一个                                                 |
| `WebcamVisionFrameSource` | `Convai/Vision/Webcam Vision Frame Source`         | 与发布器相同的 GameObject 或其子对象 | 每个采集源添加一个                                                 |
| `QuestVisionFrameSource`  | `Convai/Vision/Quest Vision Frame Source`          | 与发布器相同的 GameObject 或其子对象 | 仅适用于 Meta Quest 3 / 3S；需要 Meta XR SDK                     |
| `VisionDebugPreview`      | `Convai/Vision/Vision Debug Preview (Editor Only)` | 任意场景 GameObject          | 仅限编辑器；在玩家版本构建中会自动禁用                                       |

### 启动顺序

当 `ConvaiRoomManager` 连接时，且 **连接类型** 设置为 **Video**，以下操作会在 `AutoCompatible`, `HighResponsiveness`和 `LowOverhead` 策略下自动执行。如果 **动态视觉上下文** 设置为 `Enabled`, `ConvaiRoomManager` 会在连接时自动将有效连接类型解析为 Video，即使 **连接类型** 配置为 `Audio`.

1. `ConvaiRoomManager` 会与 Convai 建立 Video 连接。
2. `ConvaiVisionPublisher` 会检测当前活动房间，并通过 `GetComponent` 或 `GetComponentsInChildren`.
3. 帧源开始采集并触发 `Ready`。对于 `CameraVisionFrameSource`，它会将指定的摄像机（或 `Camera.main`）渲染到 `RenderTexture`.
4. `VisionPublishCoordinator` 会应用所选的发布策略（例如， `AutoCompatible`：10 fps、750 kbps），并开始将帧转发到视频管线。
5. 一个名为 `"unity-scene"` 的 WebRTC 视频轨道会发布到 Convai 房间。 `ConvaiVisionPublisher.IsPublishing` 会变为 `true` ，并触发 `VideoTrackPublished` 领域事件。

对于 `Manual` 策略，第 5 步不会自动执行——需要从脚本中调用 `EnablePublishing(true)` 以开始发布。

### 动态视觉上下文

动态视觉上下文是一种可选的附加方案，可替代对每一帧已发布帧到达时都进行处理的方式。客户端无需决定发布哪些帧以及发布频率，Convai 会对已发布的视频轨道进行采样，将采样帧存入循环帧缓冲区，并仅在需要时将最新帧附加到模型轮次中。它与 [动态上下文](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/how-dynamic-context-works.md)使用相同的输入通道模型：视觉是一个拥有独立响应模式的通道，与 `context_update`, `trigger`和 `scene_metadata` 通道并列，且全部使用相同的 `ConvaiRespondMode` 取值（`Silent`, `Auto`, `MustRespond`).

动态视觉上下文不会取代架构部分所述的帧源管线——它依赖于该管线。帧源和 `ConvaiVisionPublisher` 仍必须发布 WebRTC 视频轨道，供 Convai 采样；动态视觉上下文只会改变 Convai 决定哪些采样帧传给模型，以及帧更新何时应促使角色响应的方式。

引入此功能的原因是令牌成本，而非网络传输。角色产生的每个模型轮次中，附加帧都会消耗图像令牌——包括普通的语音和文本轮次，因为静默吸收的视觉帧也会随之传递。令牌计费和提供商解析属于后端行为，并非稳定的 SDK 契约，因此估算成本时，应以确认元数据（`ImageTokensEstimate` 位于 `VisionContextTriggerReceived`中）以及当前 Convai 服务文档为准，而不要采用固定的单帧数值。动态视觉上下文让这项成本成为明确且可调的选择，而不是隐式产生的成本。

`ConvaiVisionContextMode` 启用 `ConvaiRoomManager` 控制是否在连接时请求此后端采样：

| 模式          | 即可完全隐藏叠加层。                                           |
| ----------- | ---------------------------------------------------- |
| `Auto` （默认） | 仅当 **连接类型** 已为 Video 时，才会启用视觉上下文。仅音频房间绝不会自动升级。       |
| `Enabled`   | 始终启用视觉上下文，并强制将房间的有效连接类型设为 Video。                     |
| `已禁用`       | 从不发送视觉上下文配置。 **连接类型** 保持不变，因此标准帧源发布路径会继续发布，而不使用后端采样。 |

启用后， `ConvaiRoomManager` 会在连接房间时发送一个 `vision_input_config` 负载，其中描述采样间隔、每轮帧数上限、缓冲区大小、过期时间窗口和分辨率上限。随后，Convai 会决定将哪些缓冲帧附加到一轮对话中，以及视觉更新应保持静默、由模型决定是否响应，还是强制响应——这些行为可通过 `ConvaiVisionRespondModeSettings`.

{% hint style="info" %}
动态视觉上下文需要启用了此功能的 Convai 帐户，以及支持视觉的非实时模型。若该功能不可用，状态和触发确认会报告 `vision_not_enabled` 且会话会在不使用该功能的情况下继续。
{% endhint %}

有关采样设置、响应模式默认值，以及用于查询缓冲区状态或触发视觉响应的运行时 API，请参阅 [动态视觉上下文](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/dynamic-vision-context.md).

### 后续步骤

{% content-ref url="/pages/8688e51bd7c568104d68e6f3c42a8d7ef8b881e8" %}
[视觉快速开始](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/quick-start.md)
{% endcontent-ref %}

{% content-ref url="/pages/3c41ddceb11fc2af6b830a08a48c437b590c8882" %}
[视觉帧源](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/frame-sources.md)
{% endcontent-ref %}

{% content-ref url="/pages/4290d3b5bc8fff8787b36689dbdf110d6ebc4c11" %}
[动态视觉上下文](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/dynamic-vision-context.md)
{% endcontent-ref %}

{% content-ref url="/pages/9ee175b12da238182d707abd778abdc3a8706c80" %}
[Vision 脚本 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.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-unity-sdk/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.
