> 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 Player` 组件音频转发、会话关联                | 音频帧入队、Start/Stop Talking 事件、组件引用 |
| `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` | 完整跟踪每帧或每个数据包  | 诊断音频缓冲区或口型同步帧计时问题  |

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

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

若要仅显示单个类别的消息，请在输出日志面板顶部的 **搜索** 框中输入类别名称。例如，输入 `ConvaiAudioLog` 即可只查看音频采集消息。

若要同时显示多个类别的消息，请使用输出日志工具栏左侧的 **筛选器** 下拉菜单。展开 **日志类别** 并仅启用所需的 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 编辑器窗口（**窗口 > 打开 Convai 编辑器**）内置了日志导出工具，可将近期日志和诊断元数据打包成可共享的归档文件。

导出内容包括：

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

打包文件写入以下位置：

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

有关分步导出流程，请参阅编辑器窗口指南。

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

### 蓝图诊断节点和事件

#### 状态读取节点

在以下对象上使用这些可由蓝图调用的节点： `UConvaiChatbotComponent` 无需查看输出日志，即可在运行时检查会话状态：

| 蓝图节点                         | 返回          | 适用场景               |
| ---------------------------- | ----------- | ------------------ |
| `Is In Conversation`         | `bool`      | 角色当前是否正在被交谈、思考或说话？ |
| `Is Thinking`                | `bool`      | 角色是否仍在等待或处理响应？     |
| `Is Listening`               | `bool`      | 角色当前是否正在接收玩家的音频输入？ |
| `Is Talking`                 | `bool`      | 角色当前是否正在播放响应？      |
| `Get Talking Time Elapsed`   | `float` （秒） | 当前语音轮次已播放多久？       |
| `Get Talking Time Remaining` | `float` （秒） | 当前语音轮次还剩多少音频？      |

CharacterID `CharacterName`, `和`、 `SessionID` 上的属性 `UConvaiChatbotComponent` 可在蓝图中读取，用于显示已加载的角色身份和对话会话状态。值为 `SessionID` 的 `-1` 表示尚未建立活动会话。

#### 可在蓝图中绑定的诊断事件

`UConvaiChatbotComponent` 提供以下事件，你可以在蓝图或 C++ 中绑定，以便在运行时响应会话状态变化：

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

要在蓝图中绑定事件，请选择相应组件，打开 **“详情”** 面板，找到 **“事件”** 部分，然后点击所需事件旁边的 **+** 。生成的节点会显示在事件图表中，并在运行时自动触发。

### 响应延迟日志记录

在调试版本中，插件会记录往返延迟，即从玩家停止说话到角色开始播放音频所经过的时间。此测量结果会显示在输出日志中的 `ConvaiSubsystemLog`:

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

仅当插件在编译时启用了 `ConvaiDebugMode` ，才会记录延迟。标准的 Marketplace 或 Fab 版本不提供此功能。如果需要在非调试版本中测量响应延迟，请在蓝图中手动记录时间戳：玩家停止说话时启动计时器，然后在 `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 解码失败 | **窗口 > 输出日志**，按类别筛选                                 |
| 输出日志（`ConvaiChatbotComponentLog`) | 会话开始/停止、连接错误、角色加载结果    | **窗口 > 输出日志**，按类别筛选                                 |
| 控制台详细程度命令                         | 无需重启即可实时更改详细程度         | 反引号控制台： `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 编辑器窗口导出                    | 打包的日志存档和诊断元数据          | **窗口 > 打开 Convai 编辑器** → 导出日志控件                     |
| 蓝图状态节点                            | 无需读取日志即可查看运行时会话状态      | `Is In Conversation`, `正在思考`, `SessionID` 在聊天机器人组件上 |
| 蓝图事件（`发生故障时`, `角色数据加载完成时`)        | 在运行时响应错误和加载完成事件        | 通过以下方式在蓝图中绑定： **“细节”>“事件”** 在聊天机器人组件上               |

### 后续步骤

{% content-ref url="/pages/34f887e298987790d23b0121952c3cb99a98019f" %}
[安装和插件问题](https://docs.convai.com/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 密钥问题](https://docs.convai.com/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" %}
[音频和麦克风问题](https://docs.convai.com/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.
