> 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-unreal-engine-plugin/getting-started/configure-conversation-input.md).

# 配置对话输入

在按住说话和免提语音捕获模式之间切换，调整 VAD 设置，并在没有麦克风的情况下向角色发送文本消息。

`UConvaiPlayerComponent` 支持三种输入模式。请查看下面的比较，选择最适合你的交互设计的模式，然后按照该模式的选项卡操作。

### 输入模式比较

|           | 按住说话                                                            | 免提                                                              | 发送文本                      |
| --------- | --------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------- |
| **工作原理**  | 玩家按住按键传输语音。                                                     | 语音活动检测会自动触发。                                                    | 将文本字符串直接发送到聊天机器人。         |
| **适用于**   | 受控输入、游戏交互体验、共享麦克风场景。                                            | 环境 NPC、自助终端安装、始终在线体验。                                           | 辅助功能、文本聊天界面、自动化测试。        |
| **需要麦克风** | 是                                                               | 是                                                               | 否                         |
| **默认值**   | 是 — `启用按住说话` 是 `true` 位于 `BP_ConvaiPlayerComponent` 在 **详情** 面板 | 否 — 禁用 **启用按住说话** 或调用 `UpdateVadBP(true)`                       | 否 — 调用 `SendText()` 按需。   |
| **配置位置**  | **详情** 面板中的 `BP_ConvaiPlayerComponent` 在以下 **Convai** 类别中，或蓝图节点 | 相同 **详情** 面板 — 设置 **启用按住说话** 到 `false`，或者调用 `UpdateVadBP(true)` | Blueprint `SendText()` 节点 |

### 配置你的模式

当 `BP_ConvaiPlayerComponent`，打开 **详情** 面板并展开 **Convai** 类别。 **启用按住说话** 复选框控制默认输入模式：

* **启用按住说话** 选中（`true`）— 按住说话处于活动状态。
* **启用按住说话** 未选中（`false`）— 免提（VAD）模式处于活动状态。

你可以在 **详情** 面板中更改此设置，而无需编辑蓝图图表，或者按照下方各选项卡所述使用蓝图节点在运行时覆盖它。

{% tabs %}
{% tab title="按住说话" %}
按住说话是默认模式。玩家按住按键即可传输语音输入；松开按键则停止传输。

`BP_ConvaiPlayerComponent` 随附按住说话输入，并在其蓝图图表中预接好了默认说话键。要更改按键，请打开玩家 Pawn 蓝图，选择 **BP Convai Player 组件**，并在组件的事件图中编辑输入绑定——或者用你自己的输入动作替换默认绑定。

你还可以设置 **启用按住说话** 到 `true` 在 **详情** 面板中的 **Convai** 类别，以确认按住说话模式已激活。

要手动接线按住说话，请调用：

| 函数                       | 返回                         | 说明                            |
| ------------------------ | -------------------------- | ----------------------------- |
| `UnmuteStreamingAudio()` | `bool` — `true` 如果开始了流式传输。 | 开始将麦克风音频流式传输到当前聊天机器人。按下按键时调用。 |
| `MuteStreamingAudio()`   | `void`                     | 停止音频流式传输。松开按键时调用。             |

将这些连接到玩家 Pawn 蓝图的事件图中的输入动作。

你也可以在不更改模式的情况下切换静音：将 `bMute` 上的属性 `UConvaiPlayerComponent` 到 `true` 其设为静音输入，并将 `false` 其恢复。
{% endtab %}

{% tab title="免提" %}
在免提模式下，角色会持续监听，并在玩家说话时作出响应，无需按键。

禁用 **启用按住说话** 位于 `BP_ConvaiPlayerComponent` 在 **详情** 面板中的 **Convai** 类别，或调用 `UpdateVadBP(true)` 从蓝图中——例如在玩家 Pawn 的 **BeginPlay** 事件中。这需要一个附加的音频处理组件（`ConvaiAudioProcessing`); `BP_ConvaiPlayerComponent` 包含此接线。该调用返回 `false` 如果缺少音频处理组件，则返回。

要返回按住说话，请启用 **启用按住说话** 在 **详情** 面板或调用 `UpdateVadBP(false)`.

无论当前模式如何，你仍然可以通过程序静音输入：将 `bMute` 上的属性 `UConvaiPlayerComponent` 到 `true` 其设为静音输入，并将 `false` 其恢复。
{% endtab %}

{% tab title="发送文本" %}
使用 `SendText()` 设为在不使用任何麦克风输入的情况下向聊天机器人发送文本消息。这对于文本聊天界面、辅助功能或在没有音频硬件的情况下测试角色响应非常有用。

| 参数                 | 类型                             | 说明                                                    |
| ------------------ | ------------------------------ | ----------------------------------------------------- |
| `ChatbotComponent` | `UConvaiConversationComponent` | 为保持 API 兼容性而存在于函数签名中。当前实现通过此玩家组件的活动会话发送，并不会根据该参数进行路由。 |
| `文本`               | `FString`                      | 要发送的文本消息。                                             |

将文本输入控件连接到此函数，并在提交时调用它。调用前请确保玩家组件已与目标角色建立活动会话 `SendText()`.
{% endtab %}
{% endtabs %}

### 微调语音活动检测

免提模式使用语音活动检测（VAD）来判断玩家何时开始和停止说话。默认的 VAD 设置在大多数环境中都适用。如果角色会被背景噪声触发，或漏掉轻声说话，请调整 `FConvaiVADSettings` 结构体。

#### 访问 VAD 设置

从 `UConvaiUtils` （无需组件引用——可作为工具函数调用）：

| 函数                            | 类别                 | 说明                                           |
| ----------------------------- | ------------------ | -------------------------------------------- |
| `GetVADSettings()`            | `Convai\|Settings` | 返回当前 `FConvaiVADSettings` 结构体。BlueprintPure。 |
| `SetVADSettings(VADSettings)` | `Convai\|Settings` | 将新的 `FConvaiVADSettings` 应用到 VAD 流水线中。       |

#### VAD 设置字段

| 字段                  | 类型      | 默认值    | 说明                                                         |
| ------------------- | ------- | ------ | ---------------------------------------------------------- |
| `bUseServerDefault` | `bool`  | `true` | 当 `true`，则使用服务器默认的 VAD 参数，其他所有字段都会被忽略。设置为 `false` 以应用本地覆盖。 |
| `置信度`               | `float` | `0.7`  | 语音置信阈值（0.0–1.0）。值越高，角色在开始监听前所需的确定性越高。提高该值可减少背景噪声导致的误触发。    |
| `StartSecs`         | `float` | `0.2`  | 监听器激活前所需的连续语音秒数。提高该值可避免被非常短的声音触发。                          |
| `StopSecs`          | `float` | `2.2`  | 监听器关闭音频流前需要的静音秒数。提高该值可避免对句中停顿的说话者过早截断。                     |
| `MinVolume`         | `float` | `0.6`  | 被视为语音的最低音频级别（0.0–1.0）。提高该值可过滤较轻的环境噪声。                      |

{% hint style="info" %}
设置 `bUseServerDefault` 到 `false` 在赋值任何其他字段之前——否则服务器会忽略所有本地值。你还可以在以下位置统一配置 **编辑 > 项目设置 > 插件 > Convai > 音频设置 | VAD** （自插件版本 4.0.0-beta.20 起可用）。
{% endhint %}

### 录音与状态检查

对于希望在发送前先捕获完整音频片段的工作流——而不是实时流式传输——请使用录音 API：

| 函数                  | 返回            | 说明                              |
| ------------------- | ------------- | ------------------------------- |
| `StartRecording()`  | `void`        | 开始将麦克风音频录制到缓冲区。                 |
| `FinishRecording()` | `USoundWave*` | 停止录制，并将捕获的音频作为 Sound Wave 资源返回。 |

你可以处理或播放返回的 `USoundWave`，或者将其传递给其他蓝图。此路径独立于流式传输流水线，并且不会与活动的聊天机器人会话交互。

如需随时检查流式传输和录制状态：

| 函数                 | 返回     | 说明                      |
| ------------------ | ------ | ----------------------- |
| `GetIsStreaming()` | `bool` | `true` 音频正在流式传输到聊天机器人时。 |
| `GetIsRecording()` | `bool` | `true` 手动录制进行中时。        |

有关内置聊天覆盖层、3D 场景内小组件以及连接自定义转录界面的完整详情，请参阅 [添加聊天 UI](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/add-the-chat-ui.md).

### 故障排查

#### 免提模式会在背景噪声下触发

**症状：** 当没有人在说话时，角色就会开始监听——环境声音、键盘点击声或音乐都可能触发它。

**原因：** VAD `置信度` 或 `MinVolume` 阈值对于当前环境来说太低。

**修复：** 调用 `GetVADSettings()`，将 `bUseServerDefault` 到 `false`，提高 `置信度` （尝试 `0.85`–`0.95`）并提高 `MinVolume` 到高于默认值 `0.6` （尝试 `0.7`–`0.8`），然后使用 `SetVADSettings()`.

**验证：** 在安静环境中进入播放模式，并确认角色不再被环境噪声触发。

#### 免提模式会在玩家说到一半时截断

**症状：** 在玩家仍在说话时，角色就中断了监听——这在说话者思考时常停顿的情况下很常见。

**原因：** `StopSecs` 对于该说话风格来说太短。

**修复：** 调用 `GetVADSettings()`，将 `bUseServerDefault` 到 `false`，增加 `StopSecs` 到高于默认值 `2.2` （尝试 `3.0`–`4.0` 秒），然后使用 `SetVADSettings()`.

**验证：** 以自然的停顿说话，并确认角色会等你说完。

#### 按住说话没有响应

**症状：** 玩家按住按键并说话，但角色始终没有响应。

**原因：** `UnmuteStreamingAudio()` 未连接到按键按下，或者 `bMute` 是 `true` 到玩家组件上的

**修复：** 确认你的输入动作调用 `UnmuteStreamingAudio()` 在按键按下时调用，并在 `MuteStreamingAudio()` 在按键松开时调用。确认 `bMute` 是 `false` 在 **详情** 面板中。

**验证：** 按住按住说话按键，说话，并确认 `GetIsStreaming()` 返回 `true`.

### 下一步

{% content-ref url="/pages/16dba40249f8c38f0e33f50c10a68569851148b6" %}
[添加聊天 UI](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/add-the-chat-ui.md)
{% endcontent-ref %}

{% content-ref url="/pages/1f909841a8dc37e6adc6461224d8b1968155a87c" %}
[验证你的设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/validate-your-setup.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-unreal-engine-plugin/getting-started/configure-conversation-input.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.