跳转到主要内容
SDK Version: 2.4.0

FAQ故障排除指南

本指南处理使用DXNN SDK过程中遇到的常见错误和症状，并提供分步解决方案。

目录

  • Q1. 容器"Restarting"错误（dxrtd冲突）
  • Q2. X11会话警告与挂载错误（Wayland问题）
  • Q3. 固件版本不匹配错误
  • Q4. 设备驱动程序更新错误
  • Q5. 模型-运行时版本兼容性错误
  • Q6. 共享内存（shm）不足错误

Q1. 容器"Restarting"错误（dxrtd冲突）​

运行docker_run.sh后，容器状态反复显示Restarting，无法进入容器时发生。

诊断步骤​

  • Step 1. 检查状态：运行docker ps，确认STATUS是否反复出现Restarting (255)。
  • Step 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 Runtime Daemon（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环境的标准操作步骤。

Step 1. 修改GDM配置 打开GDM3配置文件。

sudo nano /etc/gdm3/custom.conf

取消WaylandEnable=false的注释，强制登录界面使用Xorg。

# 强制登录界面使用Xorg
WaylandEnable=false

Step 2. 应用配置 重启GDM或重启系统。

sudo systemctl restart gdm3
# 或直接重启电脑

Step 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上更新设备驱动程序​

解决此问题需要在主机操作系统上直接更新驱动程序模块。

Step 1. 安装驱动程序模块 运行以驱动程序为目标的安装脚本。

./dx-runtime/install.sh --target=dx_rt_npu_linux_driver

Step 2. 系统重启 需要系统重启以将驱动程序重新加载到Linux内核。

sudo reboot

Step 3. 确认状态 重启后，确认更新已成功完成。

dxrt-cli -s
Docker用户注意

由于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驱动程序和固件的兼容性。

版本确认指南 要确认各模块的精确兼容组合，请参阅04. 版本兼容性中的DXNN SDK版本兼容性矩阵。

Copyright © DEEPX. All rights reserved.

Q6. 共享内存（shm）不足错误​

模型编译过程中DX-COM（DEEPX编译器）的Docker默认/dev/shm大小过小时发生。

诊断步骤​

在终端确认以下错误消息。

[ResourceError]: Insufficient shared memory (shm). Increase the available /dev/shm size (e.g. --shm-size for Docker).

原因​

Docker容器默认分配64MB的/dev/shm。DX-COM在模型编译过程中使用共享内存。编译大型或复杂模型时可能超出此默认上限。

解决方案：增加Docker共享内存大小​

方法1：在docker run中使用--shm-size（推荐） 启动容器时传入--shm-size标志。根据模型大小设置值 — 256m是常见起点，大型模型可增加到1g或更大。

docker run --shm-size=256m ...
# 大型模型
docker run --shm-size=1g ...

方法2：docker-compose.yml 若通过Docker Compose（如docker_run.sh）管理容器，在dx-compiler服务定义中添加shm_size字段。

services:
  dx-compiler:
    shm_size: '1gb'
选择合适的大小

256m值可解决大多数情况。若大型或批处理模型仍持续报错，请增加到1g或更大。

Last updated: