> 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 诊断节点以及日志文件导出的参考。

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

### Convai 日志类别

该插件声明了以下日志类别。请在 Output Log 面板中或在 `DefaultEngine.ini` 详细程度覆盖中，将这些名称作为过滤词。

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

### 日志详细程度级别

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

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

### 在编辑器中筛选 Output Log

Output Log 面板（**Window > Output Log**）在搜索字段中接受类别过滤字符串。

若只显示单个类别的消息，请在 Output Log 面板顶部的 **搜索** 框中输入类别名称。例如，输入 `ConvaiAudioLog` 即可只查看音频捕获消息。

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

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

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

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

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

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

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

```bash
Log ConvaiAudioLog VeryVerbose
```

替换 `ConvaiAudioLog` 以及上表中的任意类别，并根据需要使用 `非常详细` 并将 `警告`, `日志`, `详细`，或 `非常详细` 。该更改会立即生效，并且仅在当前会话中保留。

### 将日志保存到文件

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 中调用的节点，无需读取 Output Log 即可检查运行时会话状态：

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

该 `CharacterID`, `CharacterName`，以及 `SessionID` 上的属性是 `UConvaiChatbotComponent` 可被 Blueprint 读取，并显示已加载的角色身份和对话会话状态。 `SessionID` 的 `-1` 表示尚未建立任何活动会话。

#### 可在 Blueprint 中分配的诊断事件

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

| 事件             | 组件               | 触发时机              | 诊断用途                                               |
| -------------- | ---------------- | ----------------- | -------------------------------------------------- |
| **失败时**        | `Convai Chatbot` | 任何连接或会话错误         | 捕获失败时刻；随后立即读取 `ConvaiChatbotComponentLog` 以获取错误字符串 |
| **在角色数据加载完成时** | `Convai Chatbot` | 角色元数据加载完成并报告 `成功` | 确认身份验证成功；检查 `CharacterName` 已填充                    |
| **中断时**        | `Convai Chatbot` | 当前语音轮次被提前截断       | 适用于检测意外中断与有意中断                                     |
| **收到交互 ID 时**  | `Convai Chatbot` | 每个对话轮次开始时         | 记录 `InteractionID` 以将各轮次与 Convai 服务器记录相关联          |

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

### 响应延迟日志记录

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

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

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

### 配置默认值参考

以下默认值来自 `ConvaiUtils.cpp`, `ConvaiDefinitions.h`，以及运行时连接设置。某些值可在 **Edit > Project Settings > Plugins > 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` 信号的时间         |

### 快速参考

| 工具                                      | 显示内容                   | 如何访问                                                |
| --------------------------------------- | ---------------------- | --------------------------------------------------- |
| Output Log（`ConvaiAudioLog`)            | 音频设备打开/关闭、流错误、WAV 解码失败 | **Window > Output Log**，按类别过滤                       |
| 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` 在聊天机器人组件上          |
| Blueprint 事件（`失败时`, `在角色数据加载完成时`)       | 在运行时响应错误和加载完成          | 通过以下方式在 Blueprint 中绑定 **Details > Events** 聊天机器人组件上 |

### 下一步

{% 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 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/troubleshooting/diagnostics-and-log-export.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.