> 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/dynamic-vision-context.md).

# 动态视觉上下文

用于配置后端驱动的摄像机帧采样以及按通道响应模式默认值的动态视觉上下文类型参考。

用于配置动态视觉上下文的三种类型的字段级参考： `ConvaiVisionContextMode` 用于按房间启用该功能， `ConvaiVisionInputSettings` 用于调整后端帧采样， `ConvaiVisionRespondModeSettings` 用于设置各通道的响应模式默认值。请参阅 [视觉的工作原理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/how-vision-works.md#dynamic-vision-context) 了解动态视觉上下文的含义、存在的原因，以及如何在房间中启用它。

{% hint style="info" %}
动态视觉上下文是受账户权限控制的后端功能，需要使用支持视觉的非实时模型（Gemini 或 GPT 系列）。请先确认项目是否具备使用权限，再依赖此功能。
{% endhint %}

### `ConvaiVisionContextMode`

控制房间是否启用后端动态视觉上下文。

| 值          | 说明                                                                       |
| ---------- | ------------------------------------------------------------------------ |
| `Auto`     | 遵循已配置的 `Connection Type`：只有房间已设为 `Video`时才会启用视觉功能。不会自行将 `Audio` 房间升级为视频。 |
| `Enabled`  | 始终启用动态视觉上下文；并强制将房间连接设为 `Video`.                                          |
| `Disabled` | 绝不发送动态视觉配置。已配置的 `Connection Type` 保持不变，因此其他依赖视频的路径仍可正常工作。                |

### `ConvaiVisionInputSettings`

动态视觉上下文的后端帧采样配置；在房间连接时作为 `vision_input_config` 发送。每个字段都会被限制在后端验证通过的范围内，因此通过 Inspector 编写的配置不会在连接时被拒绝。这些设置只会在连接时读取一次——更改采样字段后必须重新连接。响应模式是例外；请参阅 [`ConvaiVisionRespondModeSettings`](#convaivisionrespondmodesettings).

| 字段         | 连接字段                              | 类型      | 默认值                                     | 范围                            |
| ---------- | --------------------------------- | ------- | --------------------------------------- | ----------------------------- |
| 采样间隔（秒）    | `sample_interval_secs`            | `float` | `1`                                     | 0.1–60                        |
| 每轮帧数       | `frames_per_turn`                 | `int`   | `5`                                     | 1–20                          |
| 缓冲帧数       | `buffer_frames`                   | `int`   | `0` （后端默认值 = 每轮帧数）                      | 设置后为每轮帧数–120                  |
| 采样窗口       | `sampling_windows`                | 列表      | 为空时（按采样间隔〔秒〕均匀采样）                       | 请参阅 [采样窗口](#sampling-windows) |
| 陈旧时间（秒）    | `staleness_seconds`               | `float` | `10`                                    | 0.1–120                       |
| 最大分辨率      | `max_resolution`                  | `int`   | `0` （提供方默认值：Gemini 为 384 px，其他为 768 px） | 设置后取值范围为 64–2048              |
| 替换之前的视觉上下文 | `replace_previous_vision_context` | `bool`  | `true`                                  | —                             |

`采样间隔（秒）` 表示后端每隔多久抓取一帧并存入缓冲区。 `每轮帧数` 表示角色下次生成一轮内容时，会附加多少帧缓冲区中的帧。 `缓冲帧数` 表示滚动缓冲区本身的大小；将其留空时， `0` 会将缓冲区大小设为 `每轮帧数`. `过期时间（秒）` 会在附加帧时丢弃缓冲区中早于此时长的帧。 `替换之前的视觉上下文` 控制新的附加操作是否替换上下文中上一次附加的帧，而不是与其累积。

#### 采样窗口

采样窗口会按固定间隔选取固定数量的帧，因此项目可以将近期的密集动作与较早的稀疏上下文结合起来，例如，使用一个 `6`帧窗口，间隔为 `300` 毫秒，再加上一个间隔为 `6`帧窗口，间隔为 `1000` 毫秒的窗口（并将 `每轮帧数` 设为至少 `12`）。未配置窗口时，后端会改为按 `采样间隔（秒）` 均匀采样。

每个窗口的 `数量` 和 `间隔毫秒数` 默认为 `0`，窗口要么完整配置，要么完全舍弃，不存在部分配置状态。只设置 `数量` 或 `间隔毫秒数` 中的一个时，窗口另一字段仍为 `0` ，SDK 会在发送 `vision_input_config`之前舍弃该窗口；它绝不会将 `0` 毫秒的间隔向上调整到 `1` 毫秒的下限。这一点很重要，因为后端会按配置中最快窗口的间隔进行采样，因此一个意外配置的 `1` 毫秒窗口就会让整个会话请求最大采集负载。只有同时设置了 `数量` （1–20）和 `间隔毫秒数` （1–60000），窗口才会发送到后端。

如果已配置窗口的 `数量` 总和超过 `每轮帧数`，SDK 会按顺序填充窗口，直到用完预算，并截减其余窗口；同时只记录一次警告，而不会发送后端会拒绝的配置。

### `ConvaiVisionRespondModeSettings`

按通道设置的响应模式默认值，以 `respond_modes` 连接房间时。用户文本和语音始终会触发响应，且无法调低响应级别；只有以下四个通道可配置。取值与 `ConvaiRespondMode` 枚举相同，详见 [动态上下文脚本 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-scripting-api.md#convairespondmode) — `Silent`, `Auto`和 `MustRespond` 在此处的含义与动态上下文中的相同。

| 通道    | 默认值           | 控制内容                |
| ----- | ------------- | ------------------- |
| 视觉    | `Silent`      | 新采样的视觉帧如何影响语音       |
| 上下文更新 | `Auto`        | 动态上下文文本更新如何影响语音     |
| 触发器   | `MustRespond` | 显式视觉触发未设置自身模式时的默认行为 |
| 场景元数据 | `Silent`      | 场景元数据更新如何影响语音       |

也可以在会话进行期间按通道更改响应模式，无需重新连接；请参阅 [动态上下文脚本 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-scripting-api.md) 以查看通用的 `ConvaiRespondMode` 参考说明。

### 后续步骤

{% 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/5c3f9bcc544ac6f441fe54139ac1c670eeb5c958" %}
[动态上下文脚本 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-scripting-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/9ee175b12da238182d707abd778abdc3a8706c80" %}
[Vision 脚本 API](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/scripting-api.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/dynamic-vision-context.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.
