> 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]
    end

    B[ConvaiVisionPublisher\nIConvaiModule]
    C[VisionPublishCoordinator]
    D[VideoTrackManager]
    E[LiveKit 房间\nWebRTC]
    F[Convai\nAI 视觉处理]

    A1 -->|RenderTexture| B
    A2 -->|RenderTexture| B
    A3 -->|RenderTexture| B
    B --> C
    C -->|policy: FPS + bitrate| D
    D -->|AsyncGPUReadback| E
    E -->|WebRTC video track| F
```

在 WebGL 上， `ConvaiVisionPublisher` 会完全绕过帧源，并直接通过 `canvas.captureStream()`。WebRTC 和 Convai 处理层在所有平台上都相同。

### 关键概念

| 概念          | 含义                                                                                                                                          |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **帧源**      | 一个 `MonoBehaviour` 用于捕获帧并将其作为一个 Y 轴翻转的 `RenderTexture`。三个内置实现分别覆盖 Unity 摄像机、物理网络摄像头和 Meta Quest 透视模式。                                       |
| **发布策略**    | 控制向 Convai 流式传输时使用的客户端帧率和比特率。不会控制后端使用哪个 AI 模型或视觉提供商。                                                                                        |
| **视频轨道**    | 发布到当前 Convai 房间的一条 WebRTC 视频轨道。通过以下项标识： **轨道名称** 上的字段 `ConvaiVisionPublisher` （默认： `“unity-scene”`).                                        |
| **房间连接**    | Vision 仅在以下情况下发布： `ConvaiRoomManager` 已使用 连接 **连接类型** 设置为 **视频**。仅音频连接不传输视频。                                                                |
| **动态视觉上下文** | 一种附加的、由后端驱动的采样模式。与其对每一帧已发布的画面在到达时就立即处理，不如由 Convai 将视频轨道采样到一个滚动缓冲区中，并决定哪些帧、在何时送达模型。通过以下方式配置 `ConvaiVisionContextMode` 在 `ConvaiRoomManager`. |

### 组件放置

了解哪个组件应该放在哪里，可以避免最常见的设置错误。

| 组件                        | 通过以下方式添加                                    | 放置位置                              | 备注                                             |
| ------------------------- | ------------------------------------------- | --------------------------------- | ---------------------------------------------- |
| `ConvaiRoomManager`       | —                                           | 任何持久场景 GameObject                 | **连接类型** 必须设置为 **视频**                          |
| `ConvaiVisionPublisher`   | —                                           | 任何持久场景 GameObject                 | 通常放在 NPC 根对象上或附近。没有 `添加组件` 菜单项——请直接将其作为脚本组件添加。 |
| `CameraVisionFrameSource` | `Convai/Vision/Camera Vision Frame Source`  | 与发布器相同的 GameObject 或其子 GameObject | 每个捕获源一个                                        |
| `WebcamVisionFrameSource` | `Convai/Vision/网络摄像头视觉帧源`                   | 与发布器相同的 GameObject 或其子 GameObject | 每个捕获源一个                                        |
| `QuestVisionFrameSource`  | `Convai/Vision/Quest 视觉帧源`                  | 与发布器相同的 GameObject 或其子 GameObject | 仅限 Meta Quest 3 / 3S；需要 Meta XR SDK            |
| `VisionDebugPreview`      | `Convai/Vision/Vision Debug Preview（仅限编辑器）` | 任何场景 GameObject                   | 仅限编辑器；在玩家构建中会自动禁用                              |

### 启动顺序

当 `ConvaiRoomManager` 与 连接时 **连接类型** 设置为 **视频**，以下操作会自动发生，适用于 `自动兼容`, `高响应性`，以及 `LowOverhead` 策略。如果 **动态视觉上下文** 设置为 `已启用`, `ConvaiRoomManager` 会在连接时自动将其实际连接类型解析为 Video，即使 **连接类型** 配置为 `音频`.

1. `ConvaiRoomManager` 会建立到 Convai 的 Video 连接。
2. `ConvaiVisionPublisher` 检测到活动房间，并通过以下方式解析帧源 `GetComponent` 或 `GetComponentsInChildren`.
3. 帧源开始捕获并发出信号 `Ready`。对于 `CameraVisionFrameSource`，这会渲染分配的摄像机（或 `Camera.main`）到一个 `RenderTexture`.
4. `VisionPublishCoordinator` 应用所选的发布策略（例如， `自动兼容`：10 fps，750 kbps），并开始将帧转发到视频流水线。
5. 名为 的 WebRTC 视频轨道 `“unity-scene”` 会发布到 Convai 房间。 `ConvaiVisionPublisher.IsPublishing` 变为 `true` 以及 `VideoTrackPublished` 领域事件被触发。

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

### 动态视觉上下文

动态视觉上下文是一种附加的、可选择启用的替代方案，用于取代对每一帧已发布画面在到达时都进行处理。客户端不再决定发布什么以及发布频率，而是由 Convai 对已经在发布的视频轨道进行采样，放入滚动帧缓冲区，并仅在需要时将最新的帧附加到模型轮次。它与以下项共享相同的输入通道模型： [动态上下文](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/how-dynamic-context-works.md)：vision 是其中一个通道，拥有自己的响应模式，并与以下通道并列： `context_update`, `trigger`，以及 `scene_metadata` 通道，全部使用相同的 `ConvaiRespondMode` 值（`Silent`, `自动`, `MustRespond`).

动态视觉上下文不会取代“架构”中描述的帧源流水线——它依赖于该流水线。帧源和 `ConvaiVisionPublisher` 仍必须发布一条 WebRTC 视频轨道，供 Convai 采样；动态视觉上下文只会改变 Convai 如何决定哪些采样帧送达模型，以及何时某次帧更新应让角色作出响应。

之所以存在这一机制，是为了控制 token 成本，而不是网络传输。附加的帧会在角色生成的每一个模型轮次中消耗图像 token——包括普通的语音和文本轮次，因为被静默吸收的视觉帧仍会随之传递。token 计费和提供商解析属于后端行为，而不是稳定的 SDK 契约，因此请将确认元数据（`ImageTokensEstimate` 在 `VisionContextTriggerReceived`）以及当前的 Convai 服务文档作为估算成本的权威依据，而不是固定的每帧数值。动态视觉上下文的存在，是为了让这种成本成为一个明确、可调的选择，而不是隐含的选择。

`ConvaiVisionContextMode` 在 `ConvaiRoomManager` 控制是否在连接时请求这种后端采样：

| 模式         | 效果                                                     |
| ---------- | ------------------------------------------------------ |
| `自动` （默认）  | 仅当以下情况时才启用视觉上下文 **连接类型** 已是 Video。仅音频房间绝不会自动升级。        |
| `已启用`      | 始终启用视觉上下文，并将房间的实际连接类型强制设为 Video。                       |
| `Disabled` | 从不发送视觉上下文配置。 **连接类型** 保持不变，因此标准的帧源发布路径会继续发布，而不会进行后端采样。 |

启用后， `ConvaiRoomManager` 会发送一个 `vision_input_config` 房间连接时的负载，描述采样间隔、每轮帧预算、缓冲区大小、时效窗口和分辨率上限。随后 Convai 会决定将哪些缓冲帧附加到某一轮，以及视觉更新应保持静默、由模型决定，还是强制响应——这些都通过以下方式按通道配置： `ConvaiVisionRespondModeSettings`.

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

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

### 下一步

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

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

{% content-ref url="/pages/4290d3b5bc8fff8787b36689dbdf110d6ebc4c11" %}
[动态视觉上下文](/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](/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.