> 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/core-concepts/conversation-flow.md).

# 对话流程

了解语音输入、播放状态、转录事件、动作队列执行、叙事触发器和中断处理。

建立会话后，玩家组件会转发音频或文本输入，Convai 会返回转录文本和角色输出，而聊天机器人组件则播放音频、更新面部和情绪数据，并将动作加入队列。了解哪些部分由事件驱动，以及当前 SDK 中哪些辅助函数可靠，有助于 Blueprint 驱动 UI 和游戏逻辑，而不依赖不受支持的状态假设。

### 播放与辅助状态

`UConvaiChatbotComponent` 提供了多个 `BlueprintPure` 状态和播放辅助函数：

| 函数                        | 蓝图显示名称 | 当前行为                                                                                            |
| ------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `GetIsTalking`            | 是否正在说话 | 返回组件当前的音频播放标志。可用于字幕计时、动画切换和中断按钮。                                                                |
| `GetTalkingTimeElapsed`   | —      | 返回当前音频响应的已播放时长。                                                                                 |
| `GetTalkingTimeRemaining` | —      | 返回估算的剩余播放时长。                                                                                    |
| `IsListening`             | 正在聆听   | 该函数存在于 Blueprint API 中，但目前在 SDK 源码中返回 `false` 。                                                 |
| `IsProcessing`            | 正在思考   | 该函数存在于 Blueprint API 中，但目前在 SDK 源码中返回 `false` 。                                                 |
| `IsInConversation`        | 正在对话   | 组合这些辅助状态。由于 `IsListening` 和 `IsProcessing` 目前都返回 `false`，因此在当前 SDK 中，该状态实际上取决于 `GetIsTalking` 。 |

对于当前版本，请将 `GetIsTalking`、音频播放委托、转录事件和动作事件视为可靠的运行时信号。在 SDK 实现发生变化之前，不要围绕 `IsListening` 或 `IsProcessing` 构建关键 UI 逻辑。

```mermaid
stateDiagram-v2
    Idle --> InputOpen : 玩家取消静音\n(UnmuteStreamingAudio)
    InputOpen --> WaitingForResponse : 玩家静音\n(MuteStreamingAudio)
    WaitingForResponse --> Talking : 收到来自 Convai 的第一帧音频
    Talking --> Idle : 音频播放结束
    Talking --> Idle : 调用了 InterruptSpeech
```

上图展示了概念上的理想流程。它并不与当前 SDK 中的所有辅助函数一一对应。

### 语音输入模式

`UConvaiPlayerComponent` 支持两种模式，用于控制何时将音频转发给 Convai。

#### 按键通话

在按键通话模式下，游戏逻辑会显式开启和关闭音频流。调用 `UnmuteStreamingAudio` ，作用于 `UConvaiPlayerComponent` 当玩家开始说话时，以及 `MuteStreamingAudio` 当玩家停止说话时。玩家组件仅在开放窗口期间转发音频。

在存在环境噪声的训练模拟中使用按住说话功能，例如有机器声、教室环境音或多个用户位于同一地点的场景；在这些场景中，自动语音检测可能会错误地截断轮次。

#### 语音活动检测

调用 `UpdateVadBP(bool EnableVAD)`即可在玩家组件上启用或停用语音活动检测（VAD）。详细的 VAD 阈值位于 `FConvaiVADSettings` 中，该设置属于 Convai 项目设置对象，可通过实用工具设置函数读取或更改。

| 字段                  | 类型      | 默认值    | 说明                                                            |
| ------------------- | ------- | ------ | ------------------------------------------------------------- |
| `bUseServerDefault` | `bool`  | `true` | 当 `true`时，以下所有单字段值都会被忽略，Convai 将应用自己的默认值。设置为 `false` 可覆盖单个字段。 |
| `Confidence`        | `float` | `0.7`  | VAD 模型判断某一帧包含语音的最低概率。提高此值可减少背景噪声造成的误报；如果角色无法检测到轻声说话的人，则可降低此值。 |
| `StartSecs`         | `float` | `0.2`  | 触发“用户开始说话”事件前需要持续说话的秒数。较高的值可以忽略短暂的声音。                         |
| `StopSecs`          | `float` | `2.2`  | 达到 VAD 端点前所需的静音秒数。降低此值可更快检测到轮次结束，但可能会截断说话较慢的用户。               |
| `MinVolume`         | `float` | `0.6`  | 归一化振幅下限，低于该值的音频会被视为静音。提高此值可过滤较轻的背景人声。                         |

VAD 适用于免提或移动场景，在这些场景中，按住说话按钮并不方便。

### 转录文本

转录文本通过 `OnTranscriptionReceivedDelegate`公开；这是 `BlueprintAssignable` 委托，位于 `UConvaiConversationComponent` 上（聊天机器人组件和玩家组件均继承自该组件）。子系统会将用户转录文本转发到玩家会话，并将机器人转录文本转发到聊天机器人会话。

委托参数如下：

| 参数                     | 类型                              | 说明                                                                |
| ---------------------- | ------------------------------- | ----------------------------------------------------------------- |
| `Speaker`              | `UConvaiConversationComponent*` | 广播转录事件的组件。当前的广播位置会传递 `this`.                                      |
| `Listener`             | `UConvaiConversationComponent*` | 存在于委托签名中。当前的广播位置会传递 `nullptr`.                                    |
| `Transcription`        | `FString`                       | 当前语句片段对应的转录文本。                                                    |
| `IsTranscriptionReady` | `bool`                          | 当前转录流程中的就绪标记。机器人转录文本会以 `true`转发；用户转录文本可能会以 `false`到达，随后会以 `true`. |
| `IsFinal`              | `bool`                          | `true` 发送一个空的最终标记，表示这是该语句片段的最后一次更新。                               |

需要用户语句转录文本时，请绑定到玩家组件；需要机器人响应转录文本时，请绑定到聊天机器人组件。对于用户字幕，请显示非空的 `Transcription` 内容，而不要仅根据以下标记来决定是否显示 `IsTranscriptionReady`.

### 文本输入

播放器也可以发送文本，而不是音频。 `UConvaiPlayerComponent::SendText` 接受一个 `UConvaiConversationComponent` 类型的目标参数和一个 `FString`，但当前实现会通过子系统将文本作为 `user_text_message` 发送，不会使用目标参数进行路由。它也不会直接使用提交的文本广播 `OnTranscriptionReceivedDelegate` 。此路径适用于无障碍输入、培训模拟期间由引导人员控制的覆盖操作，以及无需麦克风输入即可注入脚本对话的自动化测试工具。

### 动作队列执行

当 Convai 返回包含角色动作的响应时， `OnActionReceivedEvent_V2` 会触发，并将动作序列添加到 `ActionsQueue`中。如果队列为空，新序列将成为队列内容。如果队列中已有动作，则保留当前的第一个动作，并用新序列替换队列中其余的项目。

Blueprint 中标准的队列驱动执行模式：

1. 在 `OnActionReceivedEvent_V2` 上绑定事件，位置在 `BeginPlay`.
2. 事件触发时，调用 `FetchFirstAction` 以从队列中读取第一个 `FConvaiResultAction` 。
3. 在游戏逻辑中执行该动作（移动到某个位置、播放动画、打开门）。
4. 成功时调用 `HandleActionCompletion(true)` 。插件会向 Convai 报告结果，并准备好获取下一个排队动作（如果有）。
5. 失败时调用 `HandleActionCompletion(false)` 。Convai 会收到通知，并可能生成恢复响应。
6. 如果动作发生无法恢复的失败（例如，目标 Actor 已不存在），请调用 `AbortActionSequence` 以丢弃队列中所有剩余动作。

动作模板中的 `bWaitForBotSpeech` 标志会控制新到达序列中第一个动作的 `StartFirstAction` 调用时机。机器人语音开始或结束、响应不包含机器人音频，或者等待计时器到期时，门控即可解除。之后队列的推进由 `HandleActionCompletion`.

### 中断

`InterruptSpeech` 在 `UConvaiChatbotComponent` 上调用该方法，会通过渐弱音频来停止角色当前的播放，渐弱时长为 `InVoiceFadeOutDuration` 秒。也可以通过组件上的 `InterruptVoiceFadeOutDuration` 属性来设置默认淡出时长。

该类还提供 `Broadcast_InterruptSpeech` 作为 `NetMulticast Reliable` RPC，用于在网络范围内触发中断。 `InterruptSpeech` 本身会在调用它的组件上应用淡出请求。

当聊天机器人正在说话或处理请求时应用中断， `OnInterruptedEvent` 委托会触发。当前实现会广播聊天机器人组件，并将 `nullptr` 作为玩家组件传入。

插件支持渐进淡出而非立即截断，是因为突然停止音频会产生感知伪影。淡出时长让设计人员能够控制中断听起来是自然还是突兀。

### 调用语音和叙事触发器

两个 `BlueprintCallable` 函数可让 Blueprint 在无需玩家输入的情况下驱动角色说话：

* `ExecuteNarrativeTrigger` （Blueprint 显示名称为 **调用语音**）— 将提供的文本作为动态上下文事件添加，并设置 `EC_RunLLMOption::Always`。Blueprint 节点标记为 **调用语音**；C++ 名称 `ExecuteNarrativeTrigger` 仅在代码中可见。
* `InvokeNarrativeDesignTrigger` （Blueprint 显示名称为 **调用叙事设计触发器**）— 通过聊天机器人组件将指定的叙事设计触发器加入队列或调用它。

{% hint style="info" %}
对于一次性的自由格式提示（其确切措辞可能在运行时变化），请使用 `ExecuteNarrativeTrigger` 。当触发器名称是与叙事设计约定的固定标识时，请使用 `InvokeNarrativeDesignTrigger` 。
{% endhint %}

这两个函数都在 Blueprint API 中公开了 `InGenerateActions` 和 `InReplicateOnNetwork` 参数。在当前实现中， `ExecuteNarrativeTrigger` 通过 `AddContextEvent` 进行调用，不会使用这两个参数。 `InvokeNarrativeDesignTrigger` 使用内部触发器调用路径，并会将会话建立前断开连接时发出的触发器调用加入队列。

### 用法示例

#### 通过按住通话键与角色对话

一种医学培训模拟，学习者通过按住按钮与患者角色交谈。

1. 将 **按下** 事件绑定到交互输入操作，以 **取消静音流式音频** 玩家组件上的此操作会开启音频流。
2. 将 **释放** 事件绑定到 **静音流式音频** 此操作会关闭音频流。
3. 根据输入事件跟踪录音指示器的状态。使用 `GetIsTalking` 和音频播放委托，在角色播放回应时显示字幕或说话指示器。

预期结果：只有在玩家按住按钮时，患者角色才会接收音频。回应播放指示器会跟随 `GetIsTalking` 或播放委托的状态变化。

#### 主持人文本注入

一种培训模拟，主持人可以输入消息，让 AI 角色接收并作出回应，无需使用麦克风。

1. 在编辑器中或运行时构建一个简单的 UI 控件，其中包含文本框和 **发送** 按钮。
2. 将 **发送** 按钮的 **单击时** 事件连接到玩家组件上的 **发送文本** ，并将文本框中的内容作为输入字符串传入。

预期结果：玩家组件会通过子系统将输入的消息作为文本输入发送。如果需要为主持人消息显示本地字幕，请从 UI 状态中显示已提交的文本。

### 故障排查

| 症状                                         | 可能原因                                                                   | 解决方法                                                                                      | 验证                                                         |
| ------------------------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| 输入后角色没有开始说话                                | 会话未连接、音频未发送，或文本消息未提交                                                   | 检查 `GetChatbotConnectionState`，确认玩家组件已初始化，并验证输入事件是否调用了 `MuteStreamingAudio` 或 `SendText`. | `GetIsTalking` 在第一段音频回应播放时变为 `true` 。                      |
| 录音指示器始终不会关闭                                | UI 绑定到了 `IsListening`，而该函数目前返回 `false`                                 | 根据输入的按下/释放事件驱动录音 UI，而不是使用 `IsListening`.                                                  | 这样，指示器就能准确反映按钮状态。                                          |
| 操作已到达 `OnActionReceivedEvent_V2` 但没有执行任何操作 | `FetchFirstAction` 未在事件处理程序中调用，或者 `HandleActionCompletion` 未在每次操作执行后调用 | 在 **获取第一个操作** 事件处理程序中调用 **收到操作** 。执行操作后，务必调用 **处理操作完成** 并传入 `true` 表示成功，或传入 `false` 表示失败。 | 在已获取的操作名称上调用 **打印字符串** 可确认已收到操作。每次调用完成处理后，序列中的下一个操作才会变为可用。 |
| `InterruptSpeech` 没有明显效果                   | 在 `GetIsTalking` 返回 `false` 时调用——此时没有音频正在播放                            | 请先通过 **获取是否正在说话** 进行检查。仅当角色处于说话状态时，才调用 `InterruptSpeech` 。                                | `GetIsTalking` 会在淡出完成后返回 `false` 。                         |

### 相关概念

{% content-ref url="/pages/a8878427b216a80d6b385f1a342c440aa9b398c9" %}
[会话生命周期](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md)
{% endcontent-ref %}

{% content-ref url="/pages/ddcceab71734a05a1e99c8599b42f364e146005e" %}
[事件系统](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/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-unreal-engine-plugin/core-concepts/conversation-flow.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.
