> 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/troubleshooting/diagnostics-and-log-export.md).

# 诊断和日志导出

当问题未被特定症状的故障排除页面涵盖时，输出日志是主要的诊断信息来源。本页介绍 Convai Unreal Engine 插件使用哪些日志类别、如何控制详细程度、如何从 Blueprint 检查运行时状态，以及如何导出日志以便支持排查。

### Convai 日志类别

该插件声明了以下日志类别。请将这些名称作为输出日志面板中的筛选条件，或在 `DefaultEngine.ini` 中作为详细程度覆盖项使用。

| 类别                           | 涵盖内容                                       | 典型的详细输出                        |
| ---------------------------- | ------------------------------------------ | ------------------------------ |
| `LogConvai`                  | 主要运行时事件：模块启动、设置加载、本地库加载                    | 设置注册、DLL 加载结果、插件初始化错误          |
| `ConvaiConnectionManagerLog` | 托管连接代理的创建与连接设置                             | 会话代理初始化、连接建立失败                 |
| `ConvaiChatbotComponentLog`  | `Convai Chatbot` 组件生命周期、会话事件、响应错误          | 会话打开/关闭、角色数据加载、连接错误字符串         |
| `ConvaiPlayerLog`            | `Convai Player` 组件音频转发、会话关联                | 已入队的音频帧、开始/停止说话事件、组件引用         |
| `ConvaiAudioLog`             | `Convai Audio Capture` 组件：设备打开/关闭、流状态、音频数据 | 设备枚举、流打开结果、帧大小、WAV 解码错误        |
| `ConvaiAudioStreamerLog`     | 角色响应音频播放                                   | WAV 解析和播放失败                    |
| `ConvaiFaceSyncLog`          | `Convai Face Sync` 组件：帧到达、饥饿、模式选择          | 帧缓冲区深度、已解析的 LipSyncMode、饥饿混合事件 |
| `ConvaiSubsystemLog`         | Convai 子系统会话管理和延迟测量                        | 会话状态转换、延迟测量（仅限调试构建）            |
| `ConvaiObjectComponentLog`   | `Convai Object Component` 注册与已跟踪属性诊断       | 对象注册、属性解析、环境元数据变更              |
| `LogConvaiEditorConfig`      | Convai 编辑器窗口配置事件                           | API 密钥写入/读取、配置文件路径、认证状态变更      |
| `LogConvaiEditorNavigation`  | Convai 编辑器窗口导航事件                           | 标签页切换、页面加载事件                   |
| `LogConvaiEditorTheme`       | Convai 编辑器窗口主题事件                           | 样式加载结果、主题应用事件                  |
| `LogConvaiEditorValidation`  | Convai 编辑器窗口验证和 API 密钥检查                   | 密钥格式验证、仪表板连通性测试结果              |

### 日志详细级别

Unreal Engine 使用五个详细级别。更高的详细程度会产生更多输出，但会减慢繁忙日志类别下的编辑器速度。

| 级别            | 显示内容           | 何时使用                |
| ------------- | -------------- | ------------------- |
| `Error`       | 仅显示指示失败的错误     | 生产构建                |
| `Warning`     | 错误和可恢复问题       | 大多数类别的默认级别          |
| `Log`         | 正常运行消息         | 大多数 Convai 类别的默认级别  |
| `Verbose`     | 代码路径和状态变化的详细跟踪 | 用于诊断连接、会话或音频流问题     |
| `VeryVerbose` | 完整的逐帧或逐包跟踪     | 用于诊断音频缓冲区或唇形同步帧时序问题 |

### 在编辑器中筛选输出日志

输出日志面板（**Window > Output Log**）在搜索框中接受类别筛选字符串。

若只显示单一类别的消息，请在输出日志面板顶部的 **Search** 框中输入类别名称。例如，输入 `ConvaiAudioLog` 即可只查看音频捕获消息。

若要一次显示多个类别的消息，请使用输出日志工具栏左侧的 **Filters** 下拉菜单。展开 **Log Categories** ，并仅启用你需要的 Convai 类别。

### 将详细程度从 `DefaultEngine.ini`

将详细程度覆盖项添加到 `Config/DefaultEngine.ini` 以在下次启动编辑器时启用详细输出：

```ini
[Core.Log]
LogConvai=Verbose
ConvaiChatbotComponentLog=Verbose
ConvaiAudioLog=VeryVerbose
ConvaiFaceSyncLog=Verbose
```

调试完成后请删除这些行，以避免生产构建中的日志噪音。

### 从控制台提高详细程度

你可以在不重启编辑器的情况下于运行时更改日志详细程度。打开编辑器内控制台（默认是反引号键）并运行：

```bash
Log ConvaiAudioLog VeryVerbose
```

替换 `ConvaiAudioLog` 配合上表中的任意类别， `VeryVerbose` 与 `Warning`, `Log`, `Verbose`，还是 `VeryVerbose` 按需使用。该更改会立即生效，但仅在当前会话中保留。

### 将日志保存到文件

Unreal Engine 会自动将完整会话日志写入磁盘。默认位置为：

```
<YourProject>/Saved/Logs/<ProjectName>.log
```

每个新的编辑器或游戏会话都会覆盖 `<ProjectName>.log` ，并将上一个会话的日志移动到 `<ProjectName>-backup-<timestamp>.log` ，位于同一文件夹中。

若要查找当前日志文件路径，请在编辑器控制台中运行以下命令：

```bash
Log list
```

提交支持请求时，请附上完整的 `.log` 文件，来自 `Saved/Logs/`。如果日志很大，至少包含从第一个 `LogConvai` 启动消息到第一个错误之间的行。

### 打包构建日志

在打包构建中，日志会写入：

```
<InstallDir>/<ProjectName>/Saved/Logs/<ProjectName>.log
```

在 Windows 上，这位于你解压该包的文件夹内。

在 Android 上，日志会写入设备的外部存储，并可通过以下方式获取：

```bash
adb pull /sdcard/UE4Game/<ProjectName>/<ProjectName>/Saved/Logs/<ProjectName>.log
```

`UE4Game` 是 Unreal Engine 5 在 Android 上保留的旧目录名称。若要从正在运行的 Android 会话中实时流式获取日志，请筛选 Android 系统日志：

```bash
adb logcat -s ConvaiAudioLog:V LogConvai:V ConvaiChatbotComponentLog:V
```

### Convai 编辑器窗口 — 日志导出工具

Convai 编辑器窗口（**Window > Open Convai Editor**）包含一个内置日志导出工具，可将最近的日志和诊断元数据打包成可共享的归档文件。

导出内容包括：

* 最近的项目、引擎和崩溃日志，按默认的 `24` 小时窗口
* 系统和项目元数据
* 网络诊断元数据，包括代理环境值和网络适配器信息
* 来自编辑器收集器的性能元数据
* 一个 `Manifest.json` 文件和 `SystemInfo.json` 元数据文件

该包会写入到：

```
<YourProject>/Saved/ConvaiLogExports/ConvaiLogExport_<timestamp>.zip
```

如需逐步导出流程，请参阅编辑器窗口指南。

{% content-ref url="/pages/79fd9d6c59b3b63b7cf2862389b38dcf2a4493be" %}
[导出诊断日志](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/editor-window/export-diagnostic-logs.md)
{% endcontent-ref %}

### Blueprint 诊断节点和事件

#### 状态读取节点

在 `UConvaiChatbotComponent` 上使用这些可供 Blueprint 调用的节点，可在不读取输出日志的情况下检查运行时会话状态：

| Blueprint 节点 | 返回值         | 用途                 |
| ------------ | ----------- | ------------------ |
| `是否正在对话中`    | `bool`      | 角色是否正在被主动对话、思考或说话？ |
| `是否在思考`      | `bool`      | 角色是否仍在等待或处理响应？     |
| `是否在听`       | `bool`      | 角色当前是否正在接收玩家音频输入？  |
| `是否在说话`      | `bool`      | 角色当前是否正在播放响应？      |
| `获取说话已用时间`   | `float` （秒） | 当前发言轮次已经播放了多久？     |
| `获取说话剩余时间`   | `float` （秒） | 当前发言轮次还剩多少音频？      |

该 `CharacterID`, `CharacterName`，和 `SessionID` 上的属性可被 Blueprint 读取，用于显示已加载的角色身份和会话状态。一个 `UConvaiChatbotComponent` 的 `SessionID` 表示尚未建立活动会话。 `-1` Blueprint 可分配的诊断事件

#### 公开了以下事件，你可以在 Blueprint 或 C++ 中绑定它们，以便在运行时响应会话状态变化：

`UConvaiChatbotComponent` 事件

| 事件                             | 组件               | 触发时机              | 诊断用途                                               |
| ------------------------------ | ---------------- | ----------------- | -------------------------------------------------- |
| **On Failure**                 | `Convai Chatbot` | 任何连接或会话错误         | 捕获失败时刻；随后立即读取 `ConvaiChatbotComponentLog` 以获取错误字符串 |
| **On Character Data Loaded**   | `Convai Chatbot` | 角色元数据加载完成并返回 `成功` | 确认认证成功；检查 `CharacterName` 是否已填充                    |
| **On Interrupted**             | `Convai Chatbot` | 当前发言轮次被打断         | 用于检测意外中断与有意中断                                      |
| **On Interaction ID Received** | `Convai Chatbot` | 每个对话轮次开始时         | 记录 `InteractionID` 以将轮次与 Convai 服务器记录关联起来          |

要在 Blueprint 中绑定事件，请选择相关组件，打开 **详细信息** 面板，找到 **事件** 部分，然后点击 **+** 旁边你想要的事件。生成的节点会出现在 Event Graph 中，并在运行时自动触发。

### 响应延迟日志记录

在调试构建中，插件会记录从玩家停止说话到角色开始播放音频之间的往返延迟。该测量会显示在输出日志中的 `ConvaiSubsystemLog`:

```
ConvaiSubsystemLog: [Latency] Finished Calculating Latency: 483.21 ms
```

仅当插件在启用 `ConvaiDebugMode` 时编译，延迟日志记录才可用。标准 Marketplace 或 Fab 构建中不提供此功能。如果你需要在非调试构建中测量响应延迟，可在 Blueprint 中手动记录时间戳：当玩家停止说话时开始计时，然后在 `On Started Talking` 事件在 `Convai Audio Streamer` 组件上。

### 配置默认值参考

以下默认值来自 `ConvaiUtils.cpp`, `ConvaiDefinitions.h`，以及运行时连接设置。部分值可在 **编辑 > 项目设置 > 插件 > Convai**中配置；其他值则是从插件默认值、配置或命令行覆盖中解析出来的连接参数。

| 设置                              | 默认     | 在哪里更改                      | 备注                             |
| ------------------------------- | ------ | -------------------------- | ------------------------------ |
| `AEC`                           | `1`    | 连接参数                       | 连接设置期间发送的声学回声消除标志              |
| `NoiseSuppression`              | `1`    | 连接参数                       | 连接设置期间发送的噪声抑制标志                |
| `GainControl`                   | `1`    | 连接参数                       | 连接设置期间发送的自动增益控制标志              |
| `HighPassFilter`                | `1`    | 连接参数                       | 连接设置期间发送的高通滤波标志                |
| `VAD`                           | `1`    | 连接参数和 `FConvaiVADSettings` | 启用语音活动检测                       |
| `VADMode`                       | `3`    | 连接参数                       | 默认 VAD 模式                      |
| `FConvaiVADSettings.Confidence` | `0.7`  | **音频设置 \| VAD**            | 当 `bUseServerDefault` 是 `true` |
| `FConvaiVADSettings.StartSecs`  | `0.2`  | **音频设置 \| VAD**            | 语音开始前持续说话的时长                   |
| `FConvaiVADSettings.StopSecs`   | `2.2`  | **音频设置 \| VAD**            | 语音停止前的静音时长                     |
| `FConvaiVADSettings.MinVolume`  | `0.6`  | **音频设置 \| VAD**            | 将输入视为语音的幅度下限                   |
| `ChunkSize`                     | `10`   | 连接参数                       | 连接设置期间发送的音频块大小                 |
| `OutputFPS`                     | `90`   | 连接参数                       | 面部动画输出帧率                       |
| `FramesBufferDuration`          | `0.5`  | 连接参数                       | 唇形同步帧缓冲时长                      |
| `LipSyncTimeOffset`             | `0.02` | 连接参数                       | 由 `Convai Face Sync`           |
| `ClientReadyTimeoutSecs`        | `45.0` | 连接参数                       | 允许给 `bot-ready` 信号的时间          |

### 快速参考

| 工具                                                     | 显示内容                   | 如何访问                                                      |
| ------------------------------------------------------ | ---------------------- | --------------------------------------------------------- |
| 输出日志（`ConvaiAudioLog`)                                 | 音频设备打开/关闭、流错误、WAV 解码失败 | **Window > Output Log**，按类别筛选                             |
| 输出日志（`ConvaiChatbotComponentLog`)                      | 会话启动/停止、连接错误、角色加载结果    | **Window > Output Log**，按类别筛选                             |
| 控制台详细程度命令                                              | 无需重启即可实时更改详细程度         | 反引号控制台： `Log <Category> Verbose`                          |
| `DefaultEngine.ini` 详细程度                               | 跨会话持久化的详细程度            | `[Core.Log]` 部分，位于 `Config/DefaultEngine.ini`             |
| 磁盘上的日志文件                                               | 完整的会话转录，便于共享           | `<YourProject>/Saved/Logs/<ProjectName>.log`              |
| `adb logcat`                                           | Android 设备实时日志流        | `adb logcat -s ConvaiAudioLog:V LogConvai:V`              |
| Convai 编辑器窗口导出                                         | 打包日志归档和诊断元数据           | **Window > Open Convai Editor** → 导出日志控制                  |
| Blueprint 状态节点                                         | 无需读取日志的运行时会话状态         | `是否正在对话中`, `是否在思考`, `SessionID` 在 chatbot 组件上             |
| Blueprint 事件（`On Failure`, `On Character Data Loaded`) | 在运行时响应错误和加载完成          | 通过以下方式在 Blueprint 中绑定： **Details > Events** 在 Chatbot 组件上 |

### 下一步

{% content-ref url="/pages/34f887e298987790d23b0121952c3cb99a98019f" %}
[安装和插件问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/installation-and-plugin-issues.md)
{% endcontent-ref %}

{% content-ref url="/pages/f1b3d71c37ea498f3d6d84fdf60594d3020ae6bf" %}
[连接和 API 密钥问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/connection-and-api-key-issues.md)
{% endcontent-ref %}

{% content-ref url="/pages/162be7d038eafe64dac814c14bb82a2b2ad8b2e3" %}
[音频和麦克风问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/audio-and-microphone-issues.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/troubleshooting/diagnostics-and-log-export.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.