> 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).

# 视觉快速开始

将 Vision 添加到现有 Convai 场景，使角色能够看到并响应实时摄像头输入，使用 SDK 的自动组件设置。

只需三步即可将 Vision 添加到现有的 Convai 场景中。当你将其设置为 `ConvaiRoomManager` 为 Video 模式。

### 前提条件

开始前，请验证：

* [ ] 一个 `ConvaiCharacter` 已在场景中，并在播放模式下响应语音

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

{% stepper %}
{% step %}

#### 将 Connection Type 设置为 Video

选择 `ConvaiRoomManager` 层级视图中的 GameObject。在 Inspector 中，设置 **连接类型** 到 **视频**.

<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 设置** — 动态视觉上下文需要视频发布器和帧源。添加 `ConvaiVisionPublisher` 和 `CameraVisionFrameSource` 到这个 ConvaiRoomManager 下吗？

点击 **添加组件**.

<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 设置对话框提示。</p></figcaption></figure>

SDK 会创建一个名为以下名称的子 GameObject **ConvaiVisionRoot** 在 `ConvaiRoomManager` 并将二者都添加到 `ConvaiVisionPublisher` 和 `CameraVisionFrameSource` 其中。
{% endstep %}

{% step %}

#### 分配一个摄像头

选择 **ConvaiVisionRoot** GameObject（作为……的子对象 `ConvaiRoomManager`）。在 `CameraVisionFrameSource` 组件中，找到 **目标摄像机** 字段从其他 GameObject 分配一个角色。

* 如果你的场景中有一个 `Camera` 标记 **MainCamera**，请将该字段留空——该组件会在运行时自动解析它。
* 要捕获特定摄像头（俯视视角、安防摄像头），请将该摄像头拖到 **目标摄像机** 字段从其他 GameObject 分配一个角色。

默认的 **Capture Preset** 是 **Balanced** （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 %}

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

在任意场景 GameObject 上，点击 **添加组件** → **Convai/Vision/Vision Debug Preview（仅限编辑器）**.

按 **播放**。Game 视图中会出现一个覆盖层，显示实时摄像头画面和统计面板。房间连接后，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" %}
**成功：** Debug Preview 覆盖层显示实时图像，且 FPS 计数不为零。读取 `ConvaiVisionPublisher.IsPublishing` 在任何脚本中都会返回 `true`。现在，角色除了音频对话外，还会接收场景摄像头画面。
{% endhint %}

{% hint style="warning" %}
如果覆盖层仍为空白，或 FPS 计数为零，请确认 `ConvaiRoomManager.Connection Type` 被设置为 **视频** 并且房间已完全连接。请参见 [排查视觉问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/troubleshooting-and-diagnostics.md) 以获得逐步诊断。
{% endhint %}

### 手动设置组件

如果你点击了 **稍后** 在对话框中，或者想将组件放在特定的 GameObject 上，请手动添加：

1. 选择目标 GameObject（任意持久化场景对象——通常位于你的 NPC 上或附近）。
2. **添加组件** → 搜索 **Convai Vision Publisher**.
3. 在同一个 GameObject（或其子对象）上， **添加组件** → **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" %}
[视觉的工作原理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/how-vision-works.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/b15c237537e3521d8e360ca90de5e9b15be340ec" %}
[发布策略](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/publishing-and-policies.md)
{% endcontent-ref %}

{% content-ref url="/pages/86612bc613c5a299a468b71b3fb8a40e625ee1fe" %}
[排查视觉问题](/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.