环境设置

DX-AllSuite是用于验证和利用DEEPX设备的集成环境构建工具。本指南解决复杂的依赖关系问题，并在本地主机和Docker容器中提供一致的开发体验。

图. DX-AllSuite支持环境与集成。

安装摘要

[通用] 1. 前提条件：获取源代码并了解虚拟环境管理策略。

[可选] 选择安装路径。

• [路径A] 2. Docker安装：基于容器的隔离安装。
• [路径B] 3. 本地安装：直接在主机OS上安装。

---

前提条件

请先执行以下步骤以确保稳定安装。

仓库克隆与子模块同步

DX-AllSuite是多个独立模块的集合。若子模块缺失，将无法进行编译和运行时执行。请严格按以下命令执行。

A. 克隆仓库（包含子模块）

# 通过HTTPS（推荐）
git clone --recurse-submodules https://github.com/DEEPX-AI/dx-all-suite.git

# 通过SSH
git clone --recurse-submodules git@github.com:DEEPX-AI/dx-all-suite.git

cd dx-all-suite

B. （可选）更新现有仓库 若已克隆仓库但子文件夹为空，必须执行手动初始化。

# 将子模块初始化并更新至最新状态
git submodule update --init --recursive

# 检查子模块状态（前缀无"-"即为成功）
git submodule status

C. （可选）准备Docker环境 若计划使用Docker路径但未安装Docker，请使用提供的自动化脚本。

# 自动安装Docker和Docker Compose
./scripts/install_docker.sh

自动化环境管理

DX-AllSuite自动化Python虚拟环境（venv）的创建以防止软件包冲突。安装脚本自动为每个执行上下文配置优化的独立环境，用户无需手动创建虚拟环境。

• 编译器环境：创建于dx-compiler/venv-dx-compiler
• 运行时环境：创建于dx-runtime/venv-dx-runtime

注意

若安装单个模块（如仅dx-rt），必须激活脚本创建的对应虚拟环境（source .../activate）以避免安装失败。

SDK工作流程指南

DX-AllSuite根据是自带模型还是使用预优化模型，提供两条利用DEEPX NPU的路径。SDK自动管理必要的虚拟环境和依赖项，确保无缝的开发体验。

[路径A] 自定义模型推理路径 转换和部署用户训练模型的标准工作流程。

图. 自定义模型推理。

专为需要将特定模型架构（在PyTorch或TensorFlow等框架中训练）针对DEEPX硬件进行优化的用户设计的路径。

• Step 1（源）：从PyTorch或TensorFlow等主要AI框架获取训练好的模型和源代码。
• Step 2（导出）：将模型导出为DX-COM可识别的标准格式ONNX。 : 提示：设置输入张量大小，使用Opset 11或更高版本以确保与NPU规格的最大兼容性。
• Step 3（DX-COM）：在编译器虚拟环境（venv-dx-compiler）内将ONNX模型转换为NPU优化的.dxnn二进制文件。
• Step 4（DX-RT）：使用运行时虚拟环境（venv-dx-runtime）在目标设备上加载生成的模型并运行推理。
• Step 5（NPU加速）：验证实时AI推理性能并检查最终输出。

[路径B] 预编译模型路径（快速通道） 用于即时硬件验证的"快速通道"。

图. 预构建模型推理。

适合希望使用行业标准模型快速对DEEPX NPU性能进行基准测试或测试硬件集成的用户。

• Step 1（选择）：从DEEPX ModelZoo或示例数据中选择预验证的.dxnn模型。
• Step 2（DX-RT）：在运行时环境（venv-dx-runtime）中无需单独编译即可立即加载所选模型。
• Step 3（NPU加速）：运行硬件加速推理，分析FPS和延迟等关键性能指标。

---

Docker安装

使用Docker可以在无需复杂依赖关系设置的隔离环境中运行DX-AllSuite。

主机系统准备（必须）

由于Docker容器共享主机内核，必须首先在主机系统（PC）上安装驱动程序以识别NPU硬件。

A. NPU驱动程序安装（主机） 首先在主机PC上运行安装脚本。

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

B. 防止服务守护进程（dxrtd）冲突 整个主机和容器中只能运行一个dxrtd实例。在运行容器前停止主机服务。

sudo systemctl stop dxrt.service

Docker镜像构建与容器运行

A. 构建镜像 使用--all选项构建包含编译器、运行时和ModelZoo的集成镜像。

# 构建集成镜像（基于Ubuntu 24.04）
./docker_build.sh --all --ubuntu_version=24.04

# 仅构建特定环境（使用--target）
./docker_build.sh --target=dx-runtime --ubuntu_version=24.04

B. 运行容器 镜像构建完成后运行容器。

./docker_run.sh --all --ubuntu_version=24.04

GUI环境说明

若遇到X11警告或挂载错误（如cannot open display），可能是因为主机OS使用了Wayland会话。请参阅05. FAQ故障排除指南中的Q2. X11会话警告与挂载错误（Wayland问题）。

容器访问与操作指南

A. DX-Compiler环境（模型转换）

DX-Compiler环境用于生成硬件优化的.dxnn二进制文件。

A-1. 容器访问 要在容器内进行操作，必须先登录到运行中容器的Shell。

# 1. 在主机终端执行：进入容器
docker exec -it dx-compiler-24.04 bash 

# 2. 容器内部：切换到工作目录
cd /deepx/dx-compiler/dx_com

路径逻辑注意

/deepx路径是容器内部的绝对路径。此路径在主机机器上不存在。执行命令前请确认终端提示符已变为root@...或user@container_id。

A-2. 编译示例模型 示例模型在安装时预下载到./sample_models/目录。可通过以下两种方法之一进行编译。

• 方法1：批量编译（推荐） 使用提供的脚本自动编译所有示例模型。

../example/3-compile_sample_models.sh

• 方法2：手动编译（CLI） 为进行精细控制，激活虚拟环境并直接使用dxcom工具。

source ../venv-dx-compiler/bin/activate  # 激活venv

dxcom -m sample_models/onnx/YOLOV5S-1.onnx \
      -c sample_models/json/YOLOV5S-1.json \
      -o output/YOLOV5S-1

A-3. 确认结果 成功完成后，优化的.dxnn二进制文件将生成在output/目录（或-o标志指定的路径）中。

• 输出文件：output/YOLOV5S-1.dxnn
• 下一步：将此文件传输到运行时环境在硬件上运行。

B. DX-Runtime环境（NPU推理与流媒体）

DX-Runtime环境专为使用DEEPX NPU硬件运行模型推理并处理高性能视频流而设计。

B-1. 容器访问与状态检查 运行推理前，确认容器能与NPU硬件通信。

# 1. 在主机终端执行：进入容器
docker exec -it dx-runtime-24.04 

# 2. 容器内部：确认NPU硬件识别
dxrt-cli -s

B-2. 运行示例应用程序（dx_app） 此模块为各种视觉任务提供推理演示。

• 工作目录：/deepx/dx-runtime/dx_app

cd /deepx/dx-runtime/dx_app

# 1. 准备资源（下载.dxnn模型和示例图像）
./setup.sh

# 2. 运行演示
./run_demo.sh           # 运行C++演示
./run_demo_python.sh    # 运行Python演示

演示选择

运行时终端将显示可用演示列表（0, 1, 2...）。输入对应编号并按Enter开始。

B-3. 运行流媒体框架（dx_stream） 此模块是针对实时多通道视频流处理优化的基于GStreamer的模块。

• 工作目录：/deepx/dx-runtime/dx_stream

cd /deepx/dx-runtime/dx_stream

# 1. 准备资产（下载流媒体专用模型和视频资产）
./setup.sh

# 2. 运行流媒体演示（C++）
./run_demo.sh

场景选择

在终端中输入显示的场景编号可选择特定流媒体场景。

路径注意事项 区分主机终端和容器终端对于避免"File not found"错误至关重要。

• Docker容器内部：始终使用以/deepx开头的绝对路径（如cd /deepx/dx-runtime/...）。
• 本地主机环境：使用基于当前目录的相对路径（如cd ./dx-runtime/...）。

常见错误

在主机终端输入以/deepx开头的路径将返回No such file or directory错误。移动前请始终确认提示符以root@...或user@container_id开头。

[Docker] 高级故障排除（多运行时容器）

dxrtd守护进程必须在系统内作为单例运行。若要同时运行多个容器，必须修改Entrypoint以防止自动启动。

• 方法1：修改Dockerfile 编辑docker/Dockerfile.dx-runtime文件，禁用默认启动命令并替换为持续等待状态。

# 1. 注释掉现有设置
# ENTRYPOINT [ "/usr/local/bin/dxrtd" ]

# 2. 启用使容器保持运行状态的无限等待设置
ENTRYPOINT ["tail", "-f", "/dev/null"]

• 方法2：修改docker-compose 使用Docker Compose时，可在docker/docker-compose.yml的对应服务部分直接覆盖默认Entrypoint。

services:
  dx-runtime:
    entrypoint: ["/bin/sh", "-c"]
    command: ["sleep infinity"]

手动启动

应用上述设置后NPU将处于等待状态。进入容器后，使用dxrtd &命令手动启动。

[Docker] 安装结果验证（健全性检查）

最终检查安装是否成功完成以及软件和硬件是否正确通信。

A. 硬件识别确认（dxrt-cli）

在容器内部执行以下命令以确认NPU已被识别并正在运行：

dxrt-cli -s

成功检查列表 若输出满足以下三个条件，则表示硬件集成成功：

• [x] 设备识别：显示Device 0: M1（或特定型号）。
• [x] 版本信息：RT Driver version、FW version等显示有效版本号。
• [x] 守护进程状态：无"Other instance of dxrtd is running"等错误消息。

[正常输出示例]

DX-RT v3.2.0
========================================================
* Device 0: M1, Accelerator type
--------------------- Version ---------------------
* RT Driver version : v2.1.0
* FW version :      v2.5.0
-------------------------------------------------------
... (续)

B. 系统一致性确认

此脚本批量检查所有单独模块是否已正确放置在指定路径并准备好运行。

# 验证运行时环境完整性
./dx-runtime/scripts/sanity_check.sh

所有项目输出**[OK]或PASS**则表示已准备好开始服务开发。

---

本地安装

将DX-AllSuite直接安装到主机OS上可确保最大硬件性能和所有软件模块之间的无缝兼容性。推荐用于生产环境和高级性能基准测试。

DX-Compiler安装 (DX-COM, DX-TRON)

DX-Compiler（DX-COM）可在支持的Linux发行版上作为CLI工具或Python模块使用。

使用方式差异

• CLI工具（命令行界面）：直接在终端（Bash）输入dxcom命令执行编译。非常适合无需额外编码的快速执行和自动化Shell脚本。
• Python模块（库）：通过Python脚本中的import dx_com调用函数或类。将编译器集成到现有AI训练或自动化管道的首选方法。

分发方式变更

独立分发方式已不再支持。本指南介绍了确保更好依赖管理和Python环境集成的最新基于Wheel的安装工作流程。

A. 安装前要求

安装DX-COM前，必须安装以下系统库以支持核心工具和图形处理。

• libgl1-mesa-glx：图形处理的OpenGL运行时支持
• libglib2.0-0：核心工具库（GNOME/GTK相关）

安装命令

sudo apt-get update
sudo apt-get install -y --no-install-recommends libgl1-mesa-glx libglib2.0-0 make

B. 安装方法

支持环境

• OS：Linux（x86_64）
• Python版本：3.8、3.9、3.10、3.11、3.12、3.13、3.14（安装脚本自动检测版本）

集成包安装 提供的install.sh脚本一次处理所有事项，包括Python版本检测和包安装。

# 运行交互式安装脚本（推荐）
./dx-compiler/install.sh

C. 验证与使用

安装后激活虚拟环境（venv-dx-compiler）以确认配置。

# 1. 激活虚拟环境
source ./dx-compiler/venv-dx-compiler/bin/activate

# 2. 确认安装版本（CLI和Python模块）
dxcom --version
python3 -c "import dx_com; print(dx_com.__version__)"

# 3. 访问帮助文档
dxcom -h

• 示例数据位置：./dx-compiler/dx_com/sample_models/

提示

若自动示例数据下载失败，可使用以下脚本手动获取资产：

• ./dx-compiler/example/1-download_sample_models.sh（模型数据）
• ./dx-compiler/example/2-download_sample_calibration_dataset.sh（校准数据）

D. DX-TRON（GUI可视化工具）

DX-TRON是用于检查模型结构和工作负载分配的可视化分析工具。请根据环境选择运行模式：

• 本地运行（桌面）：在终端输入dxtron或运行以下脚本：

./dx-compiler/run_dxtron_appimage.sh

• Web服务器运行（远程/Docker）：运行Web服务器脚本并指定端口：

./dx-compiler/run_dxtron_web.sh --port=8080

然后在浏览器中访问http://localhost:8080。

• Windows用户：可直接从DEEPX开发者门户下载专用Windows安装程序。

DX-Runtime安装 (RT, Driver, FW, App, Stream)

DX-Runtime栈是控制DEEPX NPU硬件并运行AI应用程序所需的核心软件层。每个组件作为./dx-runtime目录内的子模块进行管理。

A. 模块构建与安装

根据需求选择完整安装或针对特定模块以节省时间。

# 选项1：安装所有模块（驱动程序、固件、RT、App、Stream）
./dx-runtime/install.sh --all

# 选项2：不含固件的完整安装
# （NPU已有最新固件版本时使用）
./dx-runtime/install.sh --all --exclude-fw

# 选项3：仅安装特定模块
./dx-runtime/install.sh --target=<module_name>

B. 固件（DX-FW）更新与激活

固件更新是重要过程。请严格按以下步骤执行以确保硬件逻辑正确初始化。

Step 1. 更新固件 可使用自动化安装脚本或专用CLI工具更新固件。

# 方法1. 使用安装脚本
./dx-runtime/install.sh --target=dx_fw

# 方法2. 使用dxrt-cli手动更新
dxrt-cli -u ./dx-runtime/dx_fw/m1/X.X.X/mdot2/fw.bin

Step 2. 执行冷启动 强烈建议完全关闭系统，断电后重新接通电源并开机。简单的"重启"可能不足以初始化硬件。

Step 3. 系统重启 安装完成后必须执行sudo reboot以激活已安装的内核驱动程序。

[本地] 安装验证（健全性检查）

本地安装完成后，最终检查硬件和软件是否正确通信。

A. 硬件与版本确认

执行以下命令显示系统识别的NPU设备信息。

dxrt-cli -s

成功检查列表

• [x] 设备识别：是否显示Device 0: M1？
• [x] 版本信息：RT Driver、PCIe Driver、FW version是否显示有效编号（如v1.x.x）？
• [x] 状态：底部是否显示电压、时钟、温度的实时指标？

B. 系统完整性确认

运行批量健全性脚本以确认所有模块位于指定路径。

./dx-runtime/scripts/sanity_check.sh

提示

若项目返回FAIL或Not Found，请返回模块安装步骤（3-2节）确认所有组件是否已正确编译。

---