> 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` 设置每条通道的响应模式默认值。参见 [视觉工作原理](/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`

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

| 值     | 说明                                             |
| ----- | ---------------------------------------------- |
| `自动`  | 遵循已配置的 `连接类型`：只有当房间已设置为 `视频`。绝不会将 `音频` 房间自动升级。 |
| `已启用` | 始终启用动态视觉上下文；强制房间连接为 `视频`.                      |
| `禁用`  | 从不发送动态视觉配置。已配置的 `连接类型` 保持不变，因此其他依赖视频的路径仍可正常工作。 |

### `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 像素，其他为 768 像素 | 设置时为 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](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/dynamic-context/dynamic-context-scripting-api.md#convairespondmode) — `静默`, `自动`，以及 `必须响应` 在这里与动态上下文中的含义相同。

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

响应模式也可以在会话中按通道更改，无需重新连接；参见 [动态上下文脚本 API](/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" %}
[视觉的工作原理](/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](/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](/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.