FAQ 故障排除指南
本指南解决使用 DXNN SDK 时遇到的常见错误和症状，并提供逐步解决方案。
目录
- Q1. 容器"Restarting"错误 (#dxrtd-conflict)
- Q2. X11 会话警告 & 挂载错误（Wayland 问题）
- Q3. 固件版本不匹配错误
- Q4. 设备驱动程序更新错误
- Q5. 模型-运行时版本兼容性错误
- Q6. 共享内存 (shm) 不足错误
Q1. 容器"Restarting"错误（dxrtd 冲突）
运行 docker_run.sh 后，容器状态持续显示为 Restarting，导致无法进入容器时发生此问题。
诊断步骤
- 步骤 1. 检查状态：运行
docker ps，检查STATUS是否持续显示Restarting (255)。 - 步骤 2. 检查日志：运行
docker logs <container_name>，检查是否有 "Other instance of dxrtd is running" 消息。
# 检查容器状态
docker ps
# 输出示例：STATUS 持续显示 'Restarting (255)'
CONTAINER ID IMAGE COMMAND STATUS NAMES
041b9a4933e3 dx-runtime:24.04 "/usr/local/bin/dxrtd" Restarting (255) 4 seconds ago dx-runtime-24.04
# 检查容器日志
docker logs dx-runtime-24.04
# 输出: "Other instance of dxrtd is running"
原因
DEEPX 运行时守护进程 (dxrtd) 被设计为单例。整个系统（主机 + 所有容器）中只能运行一个实例。如果 dxrtd 已在主机上运行，容器内的守护进程将无法初始化，导致崩溃循环。
解决方案：停止主机运行时服务 (dxrtd)
方法 1：停止主机服务（推荐） 停止主机上的服务，让容器化守护进程获得 NPU 控制权。
# 停止主机服务
sudo systemctl stop dxrt.service
# 重新运行容器
./docker_run.sh --target=dx-runtime --ubuntu_version=24.04
详情请参考 02. 设置环境中的主机系统准备。
方法 2：防止容器中自动执行
如果必须保持主机服务运行，请配置容器使守护进程 (dxrtd) 在启动时不自动启动。
详情请参考 02. 设置环境中的Docker 高级故障排除。
Q2. X11 会话警告 & 挂载错误（Wayland 问题）
X11 转发认证失败，导致 GUI 工具错误或容器启动被拒绝时发生此问题。
诊断步骤
- Q2.1 警告：启动时出现
[WARN] it is recommended to use an X11 session。 - Q2.2 错误：系统重启或注销后，容器因
error mounting /tmp/.docker.xauth失败。
原因
- Q2.1： DX-TRON 等 GUI 工具针对 X11 进行了优化。Wayland 会话可能导致
xauth进程不稳定。 - Q2.2： 结束 Wayland 会话可能会清除 X 认证数据或更改目录路径，导致 Docker 挂载点失效。
解决方案：将默认系统会话设置为 X11
最可靠的解决方案是将登录会话设置为 X11 (Xorg)。这是 Ubuntu/GNOME 环境的标准程序。
步骤 1. 修改 GDM 配置 打开 GDM3 配置文件。
sudo nano /etc/gdm3/custom.conf
取消注释 WaylandEnable=false 以强制登录界面使用 Xorg。
# 强制登录界面使用 Xorg
WaylandEnable=false
步骤 2. 应用设置 重启 GDM 或重启系统。
sudo systemctl restart gdm3
# 或者直接重启 PC
步骤 3. 资源清理 重新运行前删除孤立容器。
# 清理现有容器
docker compose -f docker/docker-compose.yml down --remove-orphans
# 重新运行容器
./docker_run.sh --target=dx-runtime --ubuntu_version=24.04
详情请参考 02. 设置环境中的 Docker 安装部分。
Q3. 固件版本不匹配错误
NPU 硬件上的固件比所需软件栈版本旧，导致应用程序停止时发生此错误。
诊断步骤
检查终端中的错误消息。
The current firmware version is X.X.X.
Please update your firmware to version Y.Y.Y or higher.
原因
已安装的 DX-RT（运行时）库与刷写到 NPU 上的 DX-FW（固件）之间版本不匹配。
解决方案：更新固件 (DX-FW) 并冷启动
方法 1：使用集成安装脚本（推荐） 使用一体化设置脚本更新固件。
./dx-runtime/install.sh --target=dx_fw
方法 2：使用专用 CLI 工具 (dxrt-cli)
指定特定二进制文件手动更新固件。
dxrt-cli -u ./dx-runtime/dx_fw/m1/X.X.X/mdot2/fw.bin
重要的更新后操作：冷启动 为完全初始化硬件逻辑并确保应用了新固件版本，请按照此程序操作。
选项 1. [推荐] 冷启动
- 方法：完全关闭系统，拔下电源线以耗尽残余电力，然后重新连接并开机。
- 原因：这是保证 NPU 完整硬件级重置的最可靠方法。
选项 2. 远程/SSH 环境
- 如果无法进行物理断电（例如在远程服务器机房），使用
sudo reboot命令在 OS 级别重启系统。在大多数标准场景中，系统重启足以刷新固件。
最终验证 重启后，在终端输入以下命令，验证固件已成功更新。
dxrt-cli -s
详情请参考 02. 设置环境中的固件 (DX-FW) 更新和激活部分。
Q4. 设备驱动程序更新错误
内核驱动程序版本过旧导致应用程序执行中断时发生此问题。
诊断步骤
检查终端中的以下错误消息。
The current device driver version is X.X.X.
Please update your device driver to version Y.Y.Y or higher.
原因
已安装的内核驱动程序 (dx_rt_npu_linux_driver) 不满足当前 DX-RT 的最低要求。
解决方案：在主机 OS 上更新设备驱动程序
要解决此问题，必须直接在主机操作系统上更新驱动程序模块。
步骤 1. 安装驱动程序模块 运行专门针对驱动程序的安装脚本。
./dx-runtime/install.sh --target=dx_rt_npu_linux_driver
步骤 2. 系统重启 由于驱动程序需要重新加载到 Linux 内核中，系统重启是必须的。
sudo reboot
步骤 3. 验证状态 重启后，确认更新成功。
dxrt-cli -s
由于 Docker 容器共享主机内核，驱动程序更新必须在主机 OS 上执行，而不是在容器内部。在容器内更新驱动程序不会影响硬件通信层。
详情请参考 02. 设置环境中的模块构建和安装部分。
Q5. 模型-运行时版本兼容性错误
编译器版本（用于创建 .dxnn 文件）与运行时库版本不兼容导致应用程序停止时发生此错误。
诊断步骤
检查终端中的以下错误消息。
The model's compiler version(X.X.X) is not compatible in this RT library.
Please downgrade the RT library version to X.X.X or use a model file generated with a compiler version X.X.X or higher.
原因
DX-COM（编译器）和 DX-RT（运行时）之间版本不匹配时发生。
解决方案：通过重新编译同步版本
要解决此问题，必须确保模型和运行时环境使用兼容的版本。
方法 1：重新编译模型（推荐）
使用与当前系统 DX-RT 版本兼容的编译器版本重新生成 .dxnn 文件。这是确保最佳性能和功能支持的最安全方法。
方法 2：调整运行时库版本 将 DX-RT 重新安装到符合模型要求的版本。
如果选择此方法，必须同时重新验证 NPU 驱动程序和固件的兼容性。
版本验证指南 要找到每个模块的精确兼容组合，请参考DXNN SDK 组件版本兼容性矩阵。
Copyright © DEEPX. All rights reserved.
Q6. 共享内存 (shm) 不足错误
Docker 默认的 /dev/shm 大小在模型编译期间对 DX-COM（DEEPX 编译器）来说太小时发生此错误。
诊断步骤
检查终端中的以下错误消息。
[ResourceError]: Insufficient shared memory (shm). Increase the available /dev/shm size (e.g. --shm-size for Docker).
原因
Docker 容器分配了默认 /dev/shm 64 MB。DX-COM 在模型编译过程中使用共享内存。编译大型或复杂模型时，可能超过此默认限制。
解决方案：增加 Docker 共享内存大小
方法 1：带 --shm-size 的 docker run（推荐）
启动容器时传递 --shm-size 标志。根据模型大小设置值——256m 是常见的起始值；对于大型模型增加到 1g 或更多。
docker run --shm-size=256m ...
# 对于较大的模型
docker run --shm-size=1g ...
方法 2：docker-compose.yml
如果使用 Docker Compose 管理容器，在 dx-compiler 服务定义中添加 shm_size 字段。
services:
dx-compiler:
shm_size: '1gb'
256m 可解决大多数情况。如果更大或批量处理的模型仍出现错误，请增加到 1g 或更高。