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

# 配置对话输入

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

### 输入模式比较

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

### 配置你的模式

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

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

你可以在……中更改此项 **详细信息** 面板中无需编辑 Blueprint 图，就能更改此项，或者按照下方每个选项卡所述，使用 Blueprint 节点在运行时覆盖它。

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

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

你也可以设置 **启用按住说话** 到 `true` 在 **详细信息** 面板下的 **Convai** 类别，以确认按住说话模式已启用。

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

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

在玩家 Pawn 的 Blueprint 事件图中，将这些与你的输入动作连接起来。

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

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

禁用 **启用按住说话** 在 `BP_ConvaiPlayerComponent` 在 **详细信息** 面板下的 **Convai** 类别，或者调用 `UpdateVadBP(true)` 在 Blueprint 中——例如在玩家 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 设置

使用以下可从……调用的 Blueprint 函数 `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 默认值 **Edit > Project Settings > Plugins > Convai > Audio Settings | VAD** （从插件版本 4.0.0-beta.20 起可用）。
{% endhint %}

### 录制和状态检查

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

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

你可以处理或播放返回的 `USoundWave`，或者将其传递给其他 Blueprint。此路径与流式传输管线是分开的，并且不会与当前聊天机器人会话交互。

若要随时检查流式传输和录制状态：

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

有关内置聊天覆盖层、3D 场景内小部件以及连接自定义转录 UI 的完整详情，请参阅 [添加聊天 UI](/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](/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 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-unreal-engine-plugin/getting-started/configure-conversation-input.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.