> 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、自助服务终端装置和始终开启的体验。                                                 | 适用于无障碍功能、文本聊天界面和自动化测试。    |
| **需要麦克风** | 是                                                                            | 是                                                                           | 否                         |
| **默认值**   | 是 — `Enable Push to Talk` 在 `true` 中 `BP_ConvaiPlayerComponent` 的 **细节** 面板中 | 否 — 禁用 **Enable Push to Talk** 或调用 `UpdateVadBP(true)`                      | 否 — 根据需要调用 `SendText()` 。 |
| **配置位置**  | **细节** 面板中的 `BP_ConvaiPlayerComponent` 下的 **Convai** 类别，或使用蓝图节点              | 同上 **细节** 面板 — 将 **Enable Push to Talk** 设为 `false`，或调用 `UpdateVadBP(true)` | 蓝图 `SendText()` 节点        |

### 配置输入模式

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

* **启用按住说话** 已选中（`true`）— 按住说话模式已启用。
* **启用按住说话** 未选中（`false`）— 免提（VAD）模式已启用。

你可以在 **细节** 面板中更改此设置，无需编辑蓝图图表；也可以按照下方各个选项卡中的说明，使用蓝图节点在运行时覆盖此设置。

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

`BP_ConvaiPlayerComponent` 蓝图中已预先接入按住说话输入和默认说话按键。要更改按键，请打开玩家 Pawn 蓝图，选择 **BP Convai Player Component**，然后在组件的事件图表中编辑输入绑定，或将默认绑定替换为自定义输入操作。

你也可以将 **启用按住说话** 设置为 `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 兼容性，该参数保留在函数签名中。当前实现通过此玩家组件的活动会话发送消息，不会根据此参数进行路由。 |
| `Text`             | `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` 以应用本地覆盖值。 |
| `Confidence`        | `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` 后，再设置任何其他字段；否则服务器会忽略所有本地值。你也可以在项目范围内配置 VAD 默认值，路径如下： **编辑 > 项目设置 > 插件 > Convai > 音频设置 | VAD** （插件版本 4.0.0-beta.20 起可用）。
{% endhint %}

### 录音与状态检查

如果你希望先录制完整的音频片段，再发送，而不是实时流式传输，请使用录音 API：

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

你可以处理或播放返回的 `USoundWave`，也可以将其传递给其他蓝图。此流程与流式传输管线相互独立，不会与当前活动的聊天机器人会话交互。

随时检查流式传输和录音状态：

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

有关内置聊天叠加层、3D 游戏内小组件以及连接自定义转录文本 UI 的完整说明，请参阅 [添加聊天 UI](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/add-the-chat-ui.md).

### 故障排查

#### 免提模式会被背景噪音触发

**症状：** 没人说话时，角色却开始监听——环境音、键盘敲击声或音乐都会触发它。

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

**解决方法：** 调用 `GetVADSettings()`，将 `bUseServerDefault` 设为 `false`，提高 `Confidence` （可尝试 `0.85`–`0.95`），并将 `MinVolume` 调高至默认值 `0.6` （可尝试 `0.7`–`0.8`以上），然后调用 `SetVADSettings()`.

**验证：** 在安静的环境中进入 Play 模式，确认角色不再被环境噪音触发。

#### 免提模式会在玩家说到一半时停止监听

**症状：** 玩家还在说话时，角色就停止监听——说话时经常停顿思考的人尤其容易遇到这种情况。

**原因：** `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](https://docs.convai.com/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" %}
[验证你的设置](https://docs.convai.com/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.
