> 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`

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

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

### `ConvaiVisionInputSettings`

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

| 字段               | 字段                                | 类型      | 默认值                                     | 范围                           |
| ---------------- | --------------------------------- | ------- | --------------------------------------- | ---------------------------- |
| 采样间隔秒数           | `sample_interval_secs`            | `float` | `1`                                     | 0.1–60                       |
| Frames Per Turn  | `frames_per_turn`                 | `int`   | `5`                                     | 1–20                         |
| 缓冲帧数             | `buffer_frames`                   | `int`   | `0` (后端默认值 = 每轮帧数)                      | 设置时为每轮帧数–120                 |
| Sampling Windows | `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`                                  | —                            |

`采样间隔秒数` 表示后端将帧抓取到其缓冲区的频率。 `Frames Per Turn` 表示在角色下次生成轮次时会附加多少这些已缓冲的帧。 `缓冲帧数` 表示滚动缓冲区本身的大小；将其保留为 `0` 会将缓冲区大小设为 `Frames Per Turn`. `陈旧秒数` 在附加时丢弃早于此时长的缓冲帧。 `替换之前的视觉上下文` 控制新的附加是否在上下文中替换上一次附加的帧，而不是与它们一起累积。

#### 采样窗口

采样窗口会选取固定数量、按固定间隔分布的帧，因此项目可以将密集的近期运动与稀疏的较早上下文结合起来——例如一个 `6`帧窗口，间隔 `300` 毫秒，再加一个 `6`帧窗口，间隔 `1000` 毫秒间隔（并且 `Frames Per Turn` 设置为至少 `12`）。当未配置窗口时，后端会按 `采样间隔秒数` 替代。

每个窗口的 `Count` 和 `Interval Ms` 默认为 `0`，并且一个窗口要么完全配置，要么完全丢弃——不存在部分状态。仅设置其中一个 `Count` 或 `Interval Ms` 会使窗口保持为 `0` ，而另一个字段上的值，SDK 会在发送前丢弃该窗口 `vision_input_config`；它绝不会将一个 `0` 毫秒间隔向上夹到 `1` 毫秒下限。这很重要，因为后端会按已配置窗口中最快的间隔进行采样，所以一个多余的 `1` 毫秒窗口会为整个会话请求最大的采集负载。只有当以下两者都设置时，窗口才会发送到后端： `Count` (1–20) 和 `Interval Ms` (1–60000)。

如果配置窗口中的总 `Count` 超过 `Frames Per Turn`，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) — `静默`, `自动`，以及 `MustRespond` 在这里的含义与动态上下文中的含义相同。

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

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