设置环境

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

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

安装概述

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

[选择] 选择安装路径：

• [路径A] 2. Docker 安装：基于容器的隔离安装。
• [路径B] 3. 本地安装：直接安装到主机操作系统。

---

前提条件

为确保稳定安装，请先按照这些步骤操作。

克隆仓库并同步子模块

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] 自定义模型推理路径 用于转换和部署用户训练模型的标准工作流程。

图. 自定义模型推理。

此路径专为拥有在框架中训练的特定模型架构并希望针对 DEEPX 硬件进行优化的用户设计。

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

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

图. 预构建模型推理。

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

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

---

Docker 安装

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

准备主机系统（重要）

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

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 bash

# 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

选择场景

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

路径注意事项 为防止"文件未找到"错误，区分主机终端和容器终端非常重要。

• 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] 验证安装结果（Sanity Check）

最终确认安装成功完成且软件和硬件正确通信。

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 直接安装到主机操作系统可确保最大硬件性能和所有软件模块之间的无缝兼容性。此方法推荐用于生产环境和高级性能基准测试。

• 任务：DX-Compiler 本地安装指南 [链接]

安装 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. 安装方法

支持的环境

• 操作系统：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 安装指南 [链接]

安装 DX-Runtime（RT、驱动程序、FW、App、Stream）

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

A. 构建并安装模块

根据需求，可以执行完整安装或仅安装特定模块。

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

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

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

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

固件更新是一个关键过程。请准确遵循以下步骤以确保硬件逻辑正确初始化。

步骤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

步骤2. 执行冷启动 强烈建议完全关闭系统并断电后重新开机。简单的"重启"可能对硬件初始化不够充分。

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

[本地] 验证安装结果（Sanity Check）

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

A. 验证硬件和版本

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

dxrt-cli -s

成功检查清单

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

B. 系统完整性验证

运行批量 sanity 脚本，确认所有模块都在指定路径中。

./dx-runtime/scripts/sanity_check.sh

提示

如果某项返回 FAIL 或 Not Found，请重新检查模块安装步骤（第3-2节），确认所有组件是否已正确编译。

---