> 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/unity-plugin-beta-overview/features/vision.md).

# 视觉

## 面向 Convai 角色的实时场景视觉

Vision 让 Convai 角色能够看到 Unity 场景中正在发生的事情。启用 Vision 时，会从一个可配置的来源持续捕获视频流——场景摄像机、物理网络摄像头，或 Meta Quest 头显的穿透画面——并将其发布到 Convai，在那里与角色的对话上下文一起处理。随后，角色可以根据它们观察到的内容作出回应、描述物体、标记危险，或基于实时视觉输入引导用户。

Vision 是一种模块级功能，依赖于 `ConvaiRoomManager` 运行于 **视频** 连接模式。在原生平台上，视频流来源于 `RenderTexture`；在 WebGL 中，它通过以下方式从可见的浏览器画布获取： `canvas.captureStream()`.

## Vision 如何融入 SDK

```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` 会完全绕过帧源，直接发布浏览器画布。其余管线保持不变。

## 关键概念

| 概念       | 含义                                                                                     |
| -------- | -------------------------------------------------------------------------------------- |
| **帧源**   | 一个 `MonoBehaviour` 用于捕获帧并将其作为 Y 轴翻转的 `RenderTexture`。三个内置实现覆盖摄像头、网络摄像头和 Meta Quest 穿透。 |
| **发布策略** | 控制向后端流式传输时使用的客户端帧率和比特率。不控制后端使用哪个 AI 模型或提供方。                                            |
| **视频轨道** | 发布到当前 Convai 房间的 WebRTC 视频轨道。由 **视频轨道名称** 字段标识（默认 `"unity-scene"`).                    |
| **房间连接** | Vision 仅在 `ConvaiRoomManager` 已使用以下方式连接时才会发布： `连接类型` 设为 `视频`。仅音频连接不承载视频。               |

## 各项放在哪里

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

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

## 前提条件

{% hint style="info" %}
Vision 需要 `ConvaiRoomManager.Connection Type` 被设置为 **视频**。如果它设置为 `音频`，即使其他所有组件都已正确配置，发布器也会保持空闲。
{% endhint %}

## 平台行为

| 平台            | 支持的帧源                                                | 说明                                                |
| ------------- | ---------------------------------------------------- | ------------------------------------------------- |
| PC / Mac / 主机 | `CameraVisionFrameSource`, `WebcamVisionFrameSource` | 完整的 RenderTexture 管线                              |
| Android / iOS | `CameraVisionFrameSource`, `WebcamVisionFrameSource` | 网络摄像头源会在启动时请求相机权限                                 |
| WebGL         | *（画布，自动）*                                            | `canvas.captureStream()` 路径——无需帧源组件；帧率上限为 15 fps  |
| Meta Quest    | `QuestVisionFrameSource`                             | 需要 Meta XR SDK；绑定到 `PassthroughCameraAccess` 通过反射 |

## 本节内容

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>快速开始</strong></td><td>通过分步 Inspector 演示，让角色接收实时摄像头画面——无需编写代码。</td></tr><tr><td><strong>帧源</strong></td><td>为每个平台和使用场景配置 CameraVisionFrameSource、WebcamVisionFrameSource 和 QuestVisionFrameSource。</td></tr><tr><td><strong>发布与策略</strong></td><td>选择发布策略，调整帧率和比特率，并控制视频轨道生命周期。</td></tr><tr><td><strong>调试预览</strong></td><td>将当前活动帧源可视化为屏幕叠加层，并在编辑器中监控捕获状态。</td></tr><tr><td><strong>使用示例</strong></td><td>用于安全培训、设备上手、VR 演示和手动触发会话的端到端示例。</td></tr><tr><td><strong>高级主题</strong></td><td>脚本 API、自定义 IVisionFrameSource、领域事件、WebGL 深入解析以及平台兼容性矩阵。</td></tr><tr><td><strong>故障排查与诊断</strong></td><td>借助结构化检查清单和决策树，诊断发布失败、空白画面、权限错误和平台特定问题。</td></tr></tbody></table>

## 结论

Vision 将你的 Unity 场景直接连接到角色的感知能力，使其能够基于角色所见做出回应。先从快速入门开始，获取来自场景摄像机的可用流，然后使用帧源为你的平台和使用场景选择合适的捕获方式。


---

# 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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/unity-plugin-beta-overview/features/vision.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.