> 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 会将 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 Room\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 处理层在所有平台上都是相同的。

### 关键概念

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

### 组件放置

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

| 组件                        | 放置位置                     | 说明                                  |
| ------------------------- | ------------------------ | ----------------------------------- |
| `ConvaiRoomManager`       | 任何持久化场景 GameObject       | **Connection Type** 必须设置为 **Video** |
| `ConvaiVisionPublisher`   | 任何持久化场景 GameObject       | 通常放置在 NPC 根对象上或其附近                  |
| `CameraVisionFrameSource` | 与发布器相同的 GameObject 或其子对象 | 每个采集源一个                             |
| `WebcamVisionFrameSource` | 与发布器相同的 GameObject 或其子对象 | 每个采集源一个                             |
| `QuestVisionFrameSource`  | 与发布器相同的 GameObject 或其子对象 | 仅限 Meta Quest 3 / 3S；需要 Meta XR SDK |
| `VisionDebugPreview`      | 任何场景 GameObject          | 仅限编辑器；在玩家构建中会自动禁用                   |

### 启动顺序

当 `ConvaiRoomManager` 连接并且 **Connection Type** 设置为 **Video**，对于以下策略，以下内容会自动发生： `AutoCompatible`, `HighResponsiveness`，以及 `LowOverhead` 策略。如果 **动态视觉上下文** 被设置为 `启用`, `ConvaiRoomManager` 在连接时会自动将其有效连接类型解析为视频，即使 **Connection Type** 被配置为 `音频`.

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

对于 `手动` 策略，步骤 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`, `Auto`, `MustRespond`).

动态视觉上下文并不取代 Architecture 中描述的帧源管线——它依赖于该管线。帧源和 `ConvaiVisionPublisher` 仍然必须发布 WebRTC 视频轨道供 Convai 采样；动态视觉上下文只会改变 Convai 决定哪些采样帧送达模型，以及何时应让帧更新使角色作出响应的方式。

之所以存在这个机制，原因是 token 成本，而不是网络传输成本。附加的一帧会在角色产生的每一次模型轮次中产生图像 token——包括普通的语音和文本轮次，因为静默吸收的视觉帧也会一路携带。按照提供商的默认下采样（Gemini 的 384 px 接入大约每帧消耗 258 个图像 token），默认的五帧附加在启用动态视觉上下文时会为每一轮额外增加大约 1,290 个 token。动态视觉上下文的目的，是让这一成本成为一个显式、可调的选择，而不是隐性的。

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

| 模式          | 效果                                                               |
| ----------- | ---------------------------------------------------------------- |
| `Auto` （默认） | 仅当 **Connection Type** 已经是视频时才启用 Vision 上下文。仅音频房间绝不会自动升级。        |
| `启用`        | 始终启用视觉上下文，并强制房间的有效连接类型为视频。                                       |
| `已禁用`       | 从不发送视觉上下文配置。 **Connection Type** 保持不变，因此旧版原生视频路径会继续发布，而不会进行后端采样。 |

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

{% hint style="info" %}
动态视觉上下文需要一个已启用该功能的 Convai 账户，以及一个支持视觉的非实时模型。若不可用，状态和触发确认会报告 `未启用 vision` ，会话会在没有它的情况下继续。
{% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
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=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.