> 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).

# 语音活动检测

了解 Convai Unity SDK 如何在连接时仅执行一次用户语音活动检测设置解析，使用 Convai 默认值或你的自定义值。

语音活动检测（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` 和 `置信度` 阈值，而安静的家庭办公室场景则不需要那么高，但这两种场景都不需要在对话已经进行时更改该阈值。SDK 体现了这一点：它会读取 `UserVadSettings` 一次，就在为会话构建连接请求之前，并且不提供任何 API 将更新后的值推送到一个已经 `已连接`.

这也意味着 `UserVadSettings` 的行为不同于 `TurnTakingOptions`. `RoomSessionConnectOptions` ——传递给连接调用的按次覆盖对象——包含一个 `TurnTaking` 字段，因此可以在每次连接尝试中覆盖轮流发言行为。它没有对应的字段用于 `UserVadSettings`。SDK 仅读取的来源是 `ConvaiRoomManagerProfile` 资源，或者位于 `ConvaiRoomManager` 上的等效内联字段——没有按次连接覆盖。

***

### `UserVadSettings` 字段参考

| 字段                 | 类型      | 默认值    | 有效范围    | 说明                                                                             |
| ------------------ | ------- | ------ | ------- | ------------------------------------------------------------------------------ |
| `UseServerDefault` | `bool`  | `true` | —       | 启用后，SDK 会省略 `vad_params` ，完全不在连接请求中包含该字段，而 Convai 会应用其自身的默认值。将其禁用即可改为发送下面四个字段。 |
| `置信度`              | `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{"使用服务器默认值？"}
    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 的内部日志器，并且仅在你的项目日志级别显示 `Debug`- 和 `Info`级别的消息。
{% endhint %}

***

### 使用以下方式编写自定义值： `ConvaiRoomManagerProfile`

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

若要发送自定义检测阈值而不是 Convai 的默认值，请打开 `ConvaiRoomManagerProfile` Inspector 中的资源，禁用 `使用服务器默认值`，然后将 `置信度`, `开始秒数`, `停止秒数`，以及 `最小音量` 为场景所需的值。任何 `ConvaiRoomManager` 将此配置文件作为配置来源进行引用的对象都会在下一次连接时发送这些值。这些相同字段也存在于 `ConvaiRoomManager` 本身上，供那些直接在组件上配置房间设置而不是通过共享配置文件资源的场景使用。

{% hint style="warning" %}
`UserVadSettings` 没有 public setter，也没有在 `RoomSessionConnectOptions`上的按连接覆盖。请将其设置在 `ConvaiRoomManagerProfile` 资源或位于 `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 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/core-concepts/voice-activity-detection.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.