> 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 房间\nWebRTC]
    F[Convai\nAI 视觉处理]

    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"`).                                      |
| **房间连接**    | Vision 仅在以下情况下发布： `ConvaiRoomManager` 已连接为 **连接类型** 设置为 **视频**。仅音频连接不传输视频。                                                            |
| **动态视觉上下文** | 一种附加的、由后端驱动的采样模式。Convai 不会在每个发布的帧到达时都立即处理，而是将视频轨道采样到一个滚动缓冲区中，并决定哪些帧以及何时送达模型。通过以下项配置： `ConvaiVisionContextMode` 在 `ConvaiRoomManager`. |

### 组件放置

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

| 组件                        | 放置位置                              | 备注                                  |
| ------------------------- | --------------------------------- | ----------------------------------- |
| `ConvaiRoomManager`       | 任何持久场景 GameObject                 | **连接类型** 必须设置为 **视频**               |
| `ConvaiVisionPublisher`   | 任何持久场景 GameObject                 | 通常放在 NPC 根对象上或其附近                   |
| `CameraVisionFrameSource` | 与发布器相同的 GameObject，或其子 GameObject | 每个捕获源一个                             |
| `WebcamVisionFrameSource` | 与发布器相同的 GameObject，或其子 GameObject | 每个捕获源一个                             |
| `QuestVisionFrameSource`  | 与发布器相同的 GameObject，或其子 GameObject | 仅限 Meta Quest 3 / 3S；需要 Meta XR SDK |
| `VisionDebugPreview`      | 任意场景 GameObject                   | 仅限编辑器；在玩家构建中自动禁用                    |

### 启动顺序

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

1. `ConvaiRoomManager` 会与 Convai 建立视频连接。
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 不再由客户端决定发布什么以及发布频率，而是对已在发布的视频轨道进行采样，将其放入滚动帧缓冲区，并仅在需要时将最新帧附加到模型轮次。它与以下项共享相同的输入通道模型： [动态上下文](/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` 值（`静默`, `自动`, `MustRespond`).

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

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

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

| 模式         | 效果                                                    |
| ---------- | ----------------------------------------------------- |
| `自动` (默认)  | 仅当以下条件满足时，才启用视觉上下文： **连接类型** 已经是视频。仅音频房间绝不会自动升级。      |
| `Enabled`  | 始终启用视觉上下文，并强制将房间的有效连接类型设为视频。                          |
| `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" %}
[视觉脚本 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.