> 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 会自动添加并连接所需的组件 `ConvaiRoomManager` 为视频模式。

### 前提条件

开始之前，请确认：

* [ ] 某个 `ConvaiCharacter` 已在场景中，并且在 Play 模式下会对语音做出响应

{% stepper %}
{% step %}

#### 将连接类型设为视频

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

<figure><img src="/files/6a3b89748bee39b21eca9722ad6109086352212f" alt="Connection Type set to Video on ConvaiRoomManager in the Inspector"><figcaption><p>在 ConvaiRoomManager 上将连接类型设为视频。</p></figcaption></figure>

会立即出现一个对话框：

> **Convai Vision 设置** — 动态视觉上下文需要视频发布器和帧源。添加 `ConvaiVisionPublisher` 和 `CameraVisionFrameSource` 到这个 ConvaiRoomManager 下？

点击 **添加组件**.

<figure><img src="/files/ca344105500614f945561b927d3d0c9e2a5d5ad6" 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` 组件中，找到 **目标摄像机** 字段。

* 如果你的场景中有一个 `摄像机` 带有标签 **MainCamera**，则将该字段留空——该组件会在运行时自动解析它。
* 若要捕获特定摄像机（俯视图、监控摄像头），请将该摄像机拖到 **目标摄像机** 字段。

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

如果 **目标摄像机** 为空，且场景中没有任何摄像机标记为 **MainCamera**，帧源会进入 `Failed` 状态。请务必显式分配一个摄像机，或者确保有一个摄像机具有 **MainCamera** 标签的过场摄像机来说，都是错误的锚点。

<figure><img src="/files/ac34c7bb48871e5d56d4ef15a7e83503af861922" alt="Target Camera assigned on CameraVisionFrameSource in the Inspector"><figcaption><p>在 CameraVisionFrameSource 上分配了目标摄像机。</p></figcaption></figure>
{% endstep %}

{% step %}

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

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

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

<figure><img src="/files/90229f8dc121bfae0cd5e1d796e04aecabb1da9c" alt="Vision Debug Preview component added to a scene GameObject"><figcaption><p>已添加 Vision 调试预览组件。</p></figcaption></figure>
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**成功：** 调试预览叠加层显示实时图像和一个非零 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. **Add Component** → 搜索 **Convai Vision 发布器**.
3. 在同一个 GameObject（或其子对象）上， **Add Component** → **Convai/Vision/Camera Vision Frame Source**.
4. 分配 **目标摄像机** 如果未使用 `Camera.main`.
5. 将 **来源** 字段在 `ConvaiVisionPublisher` 留空——发布器会自动发现 `CameraVisionFrameSource` 运行时同一 GameObject 上的对象。只有当场景中有多个帧源时，才显式分配它。

<figure><img src="/files/e969d94e4fd680a706f68678cd75462e5fd01cd2" 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 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/quick-start.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.