> 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 角色实时感知并响应你的 Unity 场景。Vision 功能、其组件和平台支持概览。

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

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

视觉是一个模块级功能，依赖于 `ConvaiRoomManager` 在 **视频** 连接模式下运行。在原生平台上，视频流来源于一个 `RenderTexture`；在 WebGL 上，它通过 `canvas.captureStream()`.

## 视觉功能如何融入 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 -->|策略：FPS + 比特率| D
    D -->|AsyncGPUReadback| E
    E -->|WebRTC 视频轨道| F
```

在 WebGL 上， `ConvaiVisionPublisher` 会完全绕过帧来源，直接发布浏览器画布。其余管线保持一致。

## 关键概念

| 概念       | 这意味着什么                                                                                        |
| -------- | --------------------------------------------------------------------------------------------- |
| **帧来源**  | 一个 `MonoBehaviour` 用于捕获帧并将其作为一个 Y 翻转的 `RenderTexture`暴露出来。三种内置实现覆盖摄像机、网络摄像头和 Meta Quest 透视画面。 |
| **发布策略** | 控制向后端流式传输时使用的客户端帧率和比特率。不控制后端使用哪个 AI 模型或提供方。                                                   |
| **视频轨道** | 发布到活动 Convai 房间的 WebRTC 视频轨道。通过以下项标识： **视频轨道名称** 字段（默认 `"unity-scene"`).                      |
| **房间连接** | 视觉功能仅在以下情况下发布： `ConvaiRoomManager` 已连接并使用 `连接类型` 设为 `视频`。仅音频连接不传输视频。                          |

## 放在哪里

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

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

## 前提条件

{% hint style="info" %}
视觉功能要求 `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>

## 结论

视觉功能将你的 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 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/unity-plugin-beta-overview/features/vision.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.