> 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/core-concepts/voice-activity-detection.md).

# 语音活动检测

语音活动检测（VAD）是 Convai 用来判断从用户麦克风传入的音频是否包含语音的方式。Convai Unity SDK 提供 `UserVadSettings` 因此场景可以调整这一判断——置信度、时序和音量阈值——而不是总是依赖 Convai 内置默认值。SDK 只会在会话连接的那一刻解析一次这些设置，并将它们作为连接请求的一部分发送。

`UserVadSettings` 适用于 Convai 的离散 LLM/STT 处理路径。它不会影响实时提供方自身的语音活动检测，也不会影响按住说话如何决定轮次何时结束——这些路径使用各自的轮次结束逻辑，在 [轮流发言模式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/turn-taking-modes.md).

***

### 为什么语音活动检测是一个连接时设置

`UserVadSettings` 它调优的是 Convai 的音频管线，而不是场景需要逐时刻变化的值。一个带有背景噪声的工厂车间培训模拟需要更高的 `MinVolume` 和 `Confidence` 阈值，而安静的家庭办公室场景则不需要这么高，但这两种情况都无需在对话已经进行时去更改该阈值。SDK 也体现了这一点：它会读取 `UserVadSettings` 一次，就在它为会话构建连接请求之前，并且不会提供任何 API 将更新后的值推送到一个已经 `已连接`.

这也意味着 `UserVadSettings` 其行为不同于 `TurnTakingOptions`. `RoomSessionConnectOptions` ——传递给 connect 调用的按次覆盖对象——携带一个 `轮流发言` 字段，因此轮流发言行为可以按每次连接尝试进行覆盖。它没有对应的字段用于 `UserVadSettings`. `ConvaiRoomManagerProfile` SDK 读取的唯一来源是 `ConvaiRoomManager` asset，或其在……上的对应内联字段

***

### `UserVadSettings` 字段参考

| 字段                 | 类型      | 默认值    | 有效范围    | 描述                                                                        |
| ------------------ | ------- | ------ | ------- | ------------------------------------------------------------------------- |
| `UseServerDefault` | `bool`  | `true` | —       | 启用后，SDK 会省略 `vad_params` 在连接请求中完全不发送，而由 Convai 应用其自身默认值。禁用它即可改为发送下面这四个字段。 |
| `Confidence`       | `float` | `0.7`  | `0`–`1` | Convai 的语音活动检测器在将传入音频视为语音之前所要求的置信度阈值。                                     |
| `StartSecs`        | `float` | `0.2`  | `≥ 0` 秒 | 在 Convai 将用户语音视为已开始之前所需的连续语音持续时间。                                         |
| `StopSecs`         | `float` | `0.2`  | `≥ 0` 秒 | 在 Convai 将用户语音视为已停止之前所需的静音持续时间。Convai 可能会将其限制为 `0.2` 秒，当免提智能轮次检测处于活动状态时。  |
| `MinVolume`        | `float` | `0.6`  | `0`–`1` | Convai 的语音活动检测器在将音频视为语音候选之前所要求的最小输入音量。                                    |

这四个数值默认值与 Convai 在服务端应用的默认值一致，因此保留 `UseServerDefault` 启用并省略 `vad_params` 会产生与显式发送这些精确值相同的检测行为。

***

### 连接时的服务端默认值与自定义值

每次会话连接时，SDK 都会解析 `UserVadSettings` 并决定要发送什么。

```mermaid
graph TD
    A["请求连接会话"] --> B["从 ConvaiRoomManagerProfile 或场景默认值解析 UserVadSettings"]
    B --> C{"UseServerDefault?"}
    C -->|"true (默认)"| D["从连接请求中省略 vad_params"]
    C -->|"false"| E["根据 Confidence、StartSecs、StopSecs、MinVolume 构建 vad_params"]
    D --> F["Convai 应用其自身默认值"]
    E --> G["Convai 应用你的自定义值"]
```

当 `UseServerDefault` 为 `true`，连接请求的 `vad_params` 字段保持为空 `null`，并且 SDK 的请求序列化器会省略 `null` 这些字段—— `vad_params` 根本不会出现在发送给 Convai 的负载中。当 `UseServerDefault` 为 `false`，SDK 会发送 `vad_params` 作为一个对象，其中包含 `confidence`, `start_secs`, `stop_secs`，以及 `min_volume`.

SDK 会在每次连接尝试时记录解析出的决策：

* 服务端默认值： `使用服务端默认的 vad_params（该字段从连接负载中省略）。`
* 自定义值： `发送自定义 vad_params：confidence=<value>, start_secs=<value>, stop_secs=<value>, min_volume=<value>`

{% hint style="info" %}
这些日志行来自 SDK 的内部日志器，并且只有在你的项目日志级别会显示 `调试`- 和 `信息`- 级别的消息时才会出现。
{% endhint %}

***

### 使用……来设置自定义值 `ConvaiRoomManagerProfile`

`ConvaiRoomManagerProfile` 是一个 `ScriptableObject` 用于存储已序列化的 `UserVadSettings` 字段的 asset，默认值为 `UseServerDefault = true`。其公开的 `UserVadSettings` 属性会返回该字段的一个克隆，因此读取它绝不会让调用方通过引用修改 asset 中存储的值。

若要发送自定义检测阈值而不是 Convai 的默认值，请打开 `ConvaiRoomManagerProfile` Inspector 中的 asset，禁用 `使用服务器默认值`，并设置 `Confidence`, `Start Secs`, `Stop Secs`，以及 `Min Volume` 并将其设置为你的场景所需的值。任何 `ConvaiRoomManager` 将此配置文件作为配置来源的对象都会在下一次连接时发送这些值。这些相同的字段也以内联形式存在于 `ConvaiRoomManager` 本身，适用于直接在组件上配置房间设置而不是通过共享 profile asset 的场景。

{% hint style="warning" %}
`UserVadSettings` 没有公开 setter，也没有在……上按连接覆盖 `RoomSessionConnectOptions`。请在 `ConvaiRoomManagerProfile` asset 或……上的内联字段中设置它 `ConvaiRoomManager` 在场景连接之前——在会话已经 `已连接` 期间所做的更改要到下一次连接尝试才会生效。
{% endhint %}

***

### 下一步

你现在已经了解 `UserVadSettings` 它控制什么、SDK 如何在 Convai 的默认值和你的自定义值之间做出选择，以及应在何处配置它。请阅读“轮次交替模式”，了解语音活动检测与免提轮次结束行为之间的关系，然后阅读“事件系统”，以便在运行时订阅会话和角色事件。

{% content-ref url="/pages/251e0bf7030a5f742a1182e15529c0604e3ee150" %}
[轮流发言模式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/turn-taking-modes.md)
{% endcontent-ref %}

{% content-ref url="/pages/0bd691fc4d8a06b0dbafd0f28b11f39be6f57f9a" %}
[事件系统](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/event-system.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/core-concepts/voice-activity-detection.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.