动态视觉上下文

动态视觉上下文类型参考，用于配置后端驱动的摄像机帧采样以及每条通道的 respond-mode 默认值。

用于配置动态视觉上下文的三种类型的字段级参考： ConvaiVisionContextMode 按房间启用它， ConvaiVisionInputSettings 调整后端帧采样，并且 ConvaiVisionRespondModeSettings 设置每个通道的响应模式默认值。参见 Vision 的工作原理 了解什么是动态视觉上下文、它存在的原因，以及如何在房间中启用它。

动态视觉上下文是一个受账户权限限制的后端功能，并且需要支持视觉的非实时模型（Gemini 或 GPT 类）。在依赖它之前，请先确认该项目是否可用。

ConvaiVisionContextMode

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

值	描述
Auto	遵循已配置的 Connection Type: 仅当房间已设置为 Video时才启用视觉。绝不会单独升级一个 音频 房间。
启用	始终启用动态视觉上下文；强制房间连接为 Video.
已禁用	绝不发送动态视觉配置。已配置的 Connection Type 保持不变，因此其他依赖视频的路径仍可正常工作。

ConvaiVisionInputSettings

用于动态视觉上下文的后端帧采样配置，作为 vision_input_config 在连接房间时发送。每个字段都会被限制在后端已验证的范围内，因此 Inspector 编写的配置在连接时绝不会被拒绝。这些设置只会在连接时读取一次——更改任何采样字段都需要重新连接。响应模式是例外；参见 ConvaiVisionRespondModeSettings.

字段	字段对应	类型	默认值	范围
采样间隔秒数	sample_interval_secs	float	1	0.1–60
每回合帧数	frames_per_turn	int	5	1–20
缓冲帧数	buffer_frames	int	0 （后端默认值 = 每轮帧数）	设置后为每轮帧数–120
采样窗口	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 — Silent, Auto，以及 MustRespond 在这里与动态上下文中的含义相同。

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

响应模式也可以在会话中按通道更改而无需重新连接；参见 动态上下文脚本 API 以了解共享的 ConvaiRespondMode 参考信息。

下一步

视觉如何工作动态上下文脚本 APIVision 脚本 API