> 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/quick-start.md).

# 视觉快速开始

通过 SDK 自动设置组件，为现有 Convai 场景添加 Vision，让角色能够查看并响应实时摄像头输入。

只需三步，即可为现有的 Convai 场景添加视觉功能。将 `ConvaiRoomManager` 设置为 Video 模式后，SDK 会自动添加并连接所需组件。

### 前提条件

开始之前，请确认：

* [ ] 场景中有一个 `ConvaiCharacter` ，且该角色会在 Play Mode 中响应语音

### 为角色启用视觉功能

{% stepper %}
{% step %}

#### 将 Connection Type 设置为 Video

在 Hierarchy 中选择 `ConvaiRoomManager` GameObject。在 Inspector 中，将 **Connection Type** 设置为 **Video**.

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FAGqzIpaAwPD1Da6QNEIo%2FScreenshot%202026-05-13%20225029.png?alt=media&amp;token=3399ca3f-5971-4b01-a7f7-b80a9364c747" alt="Connection Type set to Video on ConvaiRoomManager in the Inspector"><figcaption><p>ConvaiRoomManager 上的 Connection Type 已设置为 Video。</p></figcaption></figure>

随即会弹出一个对话框：

> **Convai Vision Setup** — 动态视觉上下文需要视频发布器和帧来源。是否在此 ConvaiRoomManager 下添加 `ConvaiVisionPublisher` 和 `CameraVisionFrameSource` ？

点击 **Add Components**.

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FWPUod620mDo92JTeiTmY%2FScreenshot%202026-05-13%20225326.png?alt=media&amp;token=9ffeb62a-20e7-48ef-810e-348d87048f03" alt="Convai Vision Setup dialog prompt"><figcaption><p>Convai Vision Setup 对话框提示。</p></figcaption></figure>

SDK 会在其下创建一个名为 **ConvaiVisionRoot** 的子 GameObject，并将 `ConvaiRoomManager` 添加到该对象下，同时添加 `ConvaiVisionPublisher` 和 `CameraVisionFrameSource` 。
{% endstep %}

{% step %}

#### 指定摄像机

选择 **ConvaiVisionRoot** GameObject（它是 `ConvaiRoomManager`的子对象）。在 `CameraVisionFrameSource` 组件上找到 **Target Camera** 字段。

* 如果场景中有一个标记为 `Camera` 且带有 **MainCamera**标记的摄像机，请将该字段留空——组件会在运行时自动获取该摄像机。
* 若要采集指定摄像机的画面（例如俯视摄像机或监控摄像机），请将该摄像机拖入 **目标摄像机** 字段。

默认的 **捕获预设** 为 **均衡** （1280 × 720，15 fps），适用于大多数场景。

如果 **目标摄像机** 为空，且场景中没有摄像机标记为 **MainCamera**，帧源会在运行时进入 `Failed` 状态。请务必明确指定摄像机，或确保有一台摄像机带有 **MainCamera** 标签。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FSKsfGOytkhfCDXxEhap7%2FScreenshot%202026-05-13%20230410.png?alt=media&amp;token=da13406b-02e2-4a30-b935-daf2a0467576" alt="Target Camera assigned on CameraVisionFrameSource in the Inspector"><figcaption><p>已为 CameraVisionFrameSource 指定目标摄像机。</p></figcaption></figure>
{% endstep %}

{% step %}

#### 使用调试预览进行验证

在任意场景游戏对象上，点击 **添加组件** → **Convai/Vision/Vision Debug Preview (Editor Only)**.

按下 **播放**。游戏视图中会显示一个叠加层，其中包含实时摄像机画面和统计信息面板。房间连接成功后，FPS 计数器会递增，帧数也会增加。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FOonKzrWyCeyDRscw3wAn%2FScreenshot%202026-05-13%20230509.png?alt=media&amp;token=b5069d36-1359-4a0a-9f7a-d859267b045b" alt="Vision Debug Preview component added to a scene GameObject"><figcaption><p>已添加 Vision Debug Preview 组件。</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**成功：** 调试预览叠加层会显示实时图像，且 FPS 计数器不为零。从任意脚本读取 `ConvaiVisionPublisher.IsPublishing` 会返回 `true`。现在，角色在进行音频对话的同时也会接收场景摄像机画面。
{% endhint %}

{% hint style="warning" %}
如果叠加层一直空白，或 FPS 计数器显示为零，请确认 `ConvaiRoomManager.Connection Type` 设置为 **视频** ，并且房间已完全连接。请参阅 [排查视觉问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/troubleshooting-and-diagnostics.md) 了解逐步诊断方法。
{% endhint %}

### 手动设置组件

如果你在对话框中点击了 **稍后** ，或者想将组件放到特定游戏对象上，可以手动添加：

1. 选择目标游戏对象（任意持久场景对象，通常位于 NPC 上或其附近）。
2. **添加组件** → 搜索 **Convai Vision Publisher**.
3. 在同一个游戏对象（或其子对象）上， **添加组件** → **Convai/Vision/Camera Vision Frame Source**.
4. 分配 **目标摄像机** 如果未使用 `Camera.main`.
5. 将 **源** 字段 `ConvaiVisionPublisher` 留空——发布器会在运行时自动发现 `CameraVisionFrameSource` 在同一 GameObject 上的组件。只有当场景中有多个帧源时，才需要显式分配。

<figure><img src="https://2402152281-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEtUJA212Zc1S9ACc8T4l%2Fuploads%2FR7I4FkErAM1E6mxWKNk7%2Fimage.png?alt=media&amp;token=3c1cfaec-5cdf-41e1-b9a8-b45be0c8a9cc" alt="Manual vision setup showing ConvaiVisionPublisher and CameraVisionFrameSource components"><figcaption><p>手动设置视觉——发布器和帧源组件。</p></figcaption></figure>

### 后续步骤

{% content-ref url="/pages/6ebd5ccda4df347e0fb3db3967023f01c8054427" %}
[视觉的工作原理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/how-vision-works.md)
{% endcontent-ref %}

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

{% content-ref url="/pages/b15c237537e3521d8e360ca90de5e9b15be340ec" %}
[发布策略](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/publishing-and-policies.md)
{% endcontent-ref %}

{% content-ref url="/pages/86612bc613c5a299a468b71b3fb8a40e625ee1fe" %}
[排查视觉问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/troubleshooting-and-diagnostics.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/quick-start.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.
