> 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/turn-taking-modes.md).

# 轮次切换模式

轮流发言决定谁说话、轮次何时结束，以及 SDK 如何处理用户发言与角色回应之间的过渡。SDK 支持两种模式：免手持自动检测和明确的按住说话。选择合适的模式——并正确调优——会直接影响你的训练模拟、交互体验或游戏中的对话自然度和可靠性。

有关基于 Inspector 的设置步骤，请参见 [配置对话输入模式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-conversation-input-mode.md)。本页是完整的字段参考。

***

### 模式对比

| 模式       | `ConversationInputMode` 值 | 最适合                      |
| -------- | ------------------------- | ------------------------ |
| **免手持**  | `HandsFree` (0)           | 具有自然对话、环境交互、优先无障碍体验的训练模拟 |
| **按住说话** | `PushToTalk` (1)          | 嘈杂环境、工厂安全演练、必须防止误触发的场景   |

***

### `TurnTakingOptions` — 根字段

`TurnTakingOptions` 是顶层配置对象。将其设置在 `ConvaiRoomManager` 的 Inspector 中（内联），或通过一个 `ConvaiRoomManagerProfile` 资源，或将其传递给 `RoomSessionConnectOptions` 以覆盖单次连接的设置。

| 字段                    | 类型                      | 默认值          | 说明                                      |
| --------------------- | ----------------------- | ------------ | --------------------------------------- |
| `模式`                  | `ConversationInputMode` | `HandsFree`  | 为此会话设置活动对话模式。                           |
| `TurnDetection`       | `TurnDetectionMode`     | `UseDefault` | 控制自动轮次结束检测。仅适用于免手持模式。                   |
| `CustomTurnDetection` | `SmartTurnSettings`     | 见下文          | 精细调优的智能轮次参数。仅在 `TurnDetection` 为 `自定义`. |
| `InitialServerStt`    | `ServerSttInitialState` | `UseDefault` | 控制会话开始时是否启用后端语音转文本。                     |
| `LocalAudioPolicy`    | `LocalAudioPolicy`      | 见下文          | 此设备上的麦克风行为。适用于两种模式。                     |
| `PushToTalkPolicy`    | `PushToTalkPolicy`      | 见下文          | 按住说话交互规则。仅适用于 PushToTalk 模式。            |

***

### 免手持模式

在免手持模式下，SDK 会持续采集麦克风音频，并检测用户何时说完。无需按按钮。

#### `TurnDetectionMode`

控制如何检测轮次结束。

| 值            | 行为                                         |
| ------------ | ------------------------------------------ |
| `UseDefault` | Convai 默认的服务器端语音活动检测。适用于大多数情况。             |
| `已禁用`        | 无自动轮次检测。SDK 不会自动结束用户轮次。仅当你完全在代码中管理轮次过渡时使用。 |
| `自定义`        | 使用 `SmartTurnSettings` 以自行配置检测参数。          |

#### `SmartTurnSettings`

在 `TurnDetection` 被设置为 `自定义`.

| 字段                | 类型      | 默认值   | 说明                                               |
| ----------------- | ------- | ----- | ------------------------------------------------ |
| `StopSecs`        | `float` | `3.0` | SDK 结束用户轮次前所需的静音秒数。降低可更快响应；在嘈杂环境中提高。             |
| `PreSpeechMs`     | `int`   | `0`   | 在检测到语音起点之前，需包含到捕获轮次中的音频毫秒数。如果轮次的第一个词经常被截断，可增加此值。 |
| `MaxDurationSecs` | `float` | `8.0` | 单次用户轮次的硬性上限（秒）。无论用户是否停止说话，轮次都会结束。                |

```csharp
var options = new TurnTakingOptions
{
    Mode = ConversationInputMode.HandsFree,
    TurnDetection = TurnDetectionMode.Custom,
    CustomTurnDetection = new SmartTurnSettings
    {
        StopSecs = 2.0f,       // 医疗评估流程中更快的响应
        PreSpeechMs = 100,
        MaxDurationSecs = 10.0f
    }
};
```

{% hint style="warning" %}
设置 `StopSecs` 过低会在用户句中停顿时导致轮次过早结束。在学习者思考后再回答的训练模拟中，请将 `StopSecs` 保持在 2.5 或更高。
{% endhint %}

***

### 按住说话模式

在按住说话模式下，用户通过按下和释放一个控件（按钮、按键或 UI 元素）明确地开始和结束自己的轮次。SDK 不使用语音活动检测来结束轮次。

#### `PushToTalkPolicy`

控制所有按住说话交互规则。将 `RequireTurnCompletionBeforeNextPress = true` 用于大多数训练模拟——它会强制自然的对话节奏，让角色先说完，学习者再回应。

| 字段                                           | 类型     | 默认值     | 说明                                                                     |
| -------------------------------------------- | ------ | ------- | ---------------------------------------------------------------------- |
| `EnableServerSttToggle`                      | `bool` | `true`  | 在按住说话控件被按下和释放时，静音和取消静音后端语音转文本。可降低服务器成本，并防止意外处理背景音频。                    |
| `InterruptBotOnPress`                        | `bool` | `true`  | 如果角色在用户按下按住说话时正在讲话，角色会立即被打断，以便用户开始发言。                                  |
| `RequireTurnCompletionBeforeNextPress`       | `bool` | `true`  | 用户必须等角色完整回答结束后，才能再次按下按住说话。防止轮次重叠。                                      |
| `TurnCompletionTimeoutMs`                    | `int`  | `5000`  | 回退超时（毫秒）。如果角色的轮次完成事件从未到达（例如网络小故障），则会在超时后释放按住说话锁。                       |
| `AllowSpeechStoppedFallbackAfterSpeechStart` | `bool` | `false` | 如果启用，在语音实际开始后，来自角色的 speech-stopped 事件也可释放按住说话等待状态。适用于轮次完成事件丢失等边缘情况的恢复。 |

```csharp
var options = new TurnTakingOptions
{
    Mode = ConversationInputMode.PushToTalk,
    PushToTalkPolicy = new PushToTalkPolicy
    {
        InterruptBotOnPress = false,       // 让角色先说完，用户再发言
        RequireTurnCompletionBeforeNextPress = true,
        TurnCompletionTimeoutMs = 8000
    }
};
```

***

### 本地音频策略

`LocalAudioPolicy` 控制本地设备上的麦克风行为。适用于免手持和按住说话两种模式。

| 字段                               | 类型                         | 默认值            | 说明                                            |
| -------------------------------- | -------------------------- | -------------- | --------------------------------------------- |
| `StartMutedInPushToTalk`         | `bool`                     | `true`         | 在按住说话模式激活时，麦克风默认静音。仅在按住说话控件被按住时才采集音频。         |
| `EnableAcousticEchoCancellation` | `bool`                     | `false`        | 启用声学回声消除。适用于 Android 和 iOS，在使用设备扬声器（免提）而非耳机时。 |
| `PushToTalkStartupMode`          | `PushToTalkMicStartupMode` | `PrewarmMuted` | 控制按住说话模式开始时麦克风如何初始化。                          |

#### `PushToTalkMicStartupMode`

| 值                  | 行为                            | 权衡                                           |
| ------------------ | ----------------------------- | -------------------------------------------- |
| `PrewarmMuted`     | 会话开始时打开并预热麦克风，但在用户按下控件之前保持静音。 | 消除首次按下的延迟；占用少量后台资源。                          |
| `OpenOnFirstPress` | 直到用户第一次按下按住说话之前，麦克风都不会打开。     | 节省资源；第一次按下时会带来短暂延迟（约 100–300 ms），因为麦克风需要初始化。 |

```csharp
var options = new TurnTakingOptions
{
    Mode = ConversationInputMode.PushToTalk,
    LocalAudioPolicy = new LocalAudioPolicy
    {
        EnableAcousticEchoCancellation = true,   // 工厂车间场景，设备扬声器
        PushToTalkStartupMode = PushToTalkMicStartupMode.PrewarmMuted
    }
};
```

***

### `ServerSttInitialState`

控制会话开始时是否启用 Convai 的语音转文本。

| 值            | 行为                                                 |
| ------------ | -------------------------------------------------- |
| `UseDefault` | 服务器端默认：免手持启用 STT，按住说话禁用。                           |
| `已启用`        | 无论模式如何，STT 都会在启动时启用。                               |
| `已禁用`        | 无论模式如何，STT 都会在启动时禁用。这是高级选项——当前公开 API 未暴露手动 STT 控制。 |

***

### 运行时模式切换

无需断开会话即可在免手持和按住说话之间切换：

```csharp
// 在会话中切换到按住说话
await _manager.SetConversationInputModeAsync(ConversationInputMode.PushToTalk);
```

`SetConversationInputModeAsync` 会返回一个 `IConvaiOperation<Unit>`。切换后的活动模式可通过 `_manager.ActiveConversationInputMode`.

{% hint style="warning" %}
运行时模式切换会应用新模式的 `LocalAudioPolicy` 默认设置。如果切换到按住说话，麦克风会根据 `StartMutedInPushToTalk`静音。会话不会重新连接。
{% endhint %}

***

### 使用示例

#### 示例 1：医疗培训模拟器——免手持，严格轮次检测

学习者进行患者评估。AI 角色扮演患者。较短的静音阈值让对话更流畅。

```csharp
var options = new TurnTakingOptions
{
    Mode = ConversationInputMode.HandsFree,
    TurnDetection = TurnDetectionMode.Custom,
    CustomTurnDetection = new SmartTurnSettings
    {
        StopSecs = 2.0f,
        PreSpeechMs = 80,
        MaxDurationSecs = 12.0f   // 学习者可以给出更长的回答
    }
};
```

**预期结果：** 学习者停止说话后大约 2 秒，角色会做出回应。学习者的更长回答（描述症状、提问）最多可捕获 12 秒。

***

#### 示例 2：工厂安全演练——带回声消除的按住说话

一位安全培训员在嘈杂的工厂模拟环境中与 AI 安全官互动。按住说话可防止环境噪声触发意外轮次。使用的是扬声器，因此启用 AEC。

```csharp
var options = new TurnTakingOptions
{
    Mode = ConversationInputMode.PushToTalk,
    PushToTalkPolicy = new PushToTalkPolicy
    {
        InterruptBotOnPress = true,
        RequireTurnCompletionBeforeNextPress = false,   // 安全场景中的紧急覆盖
        TurnCompletionTimeoutMs = 6000
    },
    LocalAudioPolicy = new LocalAudioPolicy
    {
        EnableAcousticEchoCancellation = true,
        PushToTalkStartupMode = PushToTalkMicStartupMode.PrewarmMuted
    }
};
```

**预期结果：** 培训员可随时通过按按钮打断 AI。无设备扬声器回声反馈。

***

#### 示例 3：通过 UI 按钮在模式之间运行时切换

一个以免手持开始，但允许主持人在直播会话中切换到按住说话的场景。

```csharp
public class InputModeToggle : MonoBehaviour
{
    [SerializeField] private ConvaiManager _manager;
    private bool _isPushToTalk;

    public async void ToggleMode()
    {
        _isPushToTalk = !_isPushToTalk;
        var mode = _isPushToTalk
            ? ConversationInputMode.PushToTalk
            : ConversationInputMode.HandsFree;

        await _manager.SetConversationInputModeAsync(mode);
    }
}
```

**预期结果：** 模式在会话中切换，不会中断连接。检查 `_manager.ActiveConversationInputMode` 以确认切换后的活动模式。

***

### 故障排查

| 症状               | 可能原因                                                           | 修复                                                                                            |
| ---------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| 角色在用户说完之前就插话回应   | `StopSecs` 对于此场景的节奏来说太低了                                       | 增加 `StopSecs` 调到 2.5–3.0，在 `SmartTurnSettings`                                                |
| 用户轮次的第一个词被截断     | 语音起点捕获得太晚                                                      | 增加 `PreSpeechMs` 调到 80–150 ms，在 `SmartTurnSettings`                                           |
| 角色说完后，按住说话按钮仍被锁定 | 未收到轮次完成事件（网络小故障）                                               | `TurnCompletionTimeoutMs` 超时后释放锁；降低该值，或设置 `AllowSpeechStoppedFallbackAfterSpeechStart = true` |
| 背景噪音在免手持模式下触发响应  | 环境对自动语音检测来说太嘈杂                                                 | 切换到按住说话模式，或提高 `StopSecs`                                                                      |
| 首次按住说话按下时有短暂延迟   | `PushToTalkMicStartupMode` 为 `OpenOnFirstPress` — 麦克风在首次按下时初始化 | 切换为 `PrewarmMuted`                                                                            |

***

### 下一步

你现在已经拥有轮流发言配置的完整字段参考。接下来阅读事件系统，了解如何在运行时对语音、转录和情绪事件做出响应。

{% content-ref url="/pages/0bd691fc4d8a06b0dbafd0f28b11f39be6f57f9a" %}
[事件系统](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/event-system.md)
{% endcontent-ref %}

{% content-ref url="/pages/8c561f7c198c46628ed5818040fdaa9af3397caf" %}
[功能](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features.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:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts/turn-taking-modes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.