Setting Up Environment

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

DXNN AllSuite

Figure. DX-AllSuite Supported Environments & Integrations.

安装概述

[Common] 1. 准备工作: 获取源代码并了解虚拟环境管理策略。

[Optional] 选择安装路径。

[Route A] 2. Docker 安装: 基于容器的隔离环境。
[Route B] 3. 本地安装: 直接安装到主机操作系统。

Prerequisites

为了稳定安装，请先执行以下步骤。

Repository Cloning and Submodule Synchronization

DX-AllSuite 是多个独立模块的集合体。如果缺少子模块，将无法进行编译或运行时执行。请准确执行以下命令。

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

# Via HTTPS (Recommended)
git clone --recurse-submodules https://github.com/DEEPX-AI/dx-all-suite.git

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

cd dx-all-suite

B. (Optional) 更新现有仓库
如果已经克隆但子文件夹为空，需要手动初始化。

# Initialize and update submodules to the latest state
git submodule update --init --recursive

# Check submodule status (Success if no '-' prefix exists)
git submodule status

C. (Optional) Docker 环境准备
如果计划使用 Docker 但尚未安装，请使用提供的自动化脚本。

# Automatic installation of Docker and Docker Compose
./scripts/install_docker.sh

Automated Environment Management

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

编译器环境: 在 dx-compiler/venv-dx-compiler 中创建
运行时环境: 在 dx-runtime/venv-dx-runtime 中创建

注意

如果单独安装某个模块（例如：仅 dx-rt），为避免安装失败，必须激活脚本创建的相应虚拟环境 (source .../activate)。

SDK Workflow Guide

DX-AllSuite 根据是使用自定义模型还是使用优化模型，提供两种使用 DEEPX NPU 的路径。SDK 会自动管理必要的虚拟环境和依赖关系，以实现无缝的开发体验。

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

DXNN Custom Model

Figure. Custom Model Inference.

此路径专为拥有在 PyTorch 或 TensorFlow 等框架中训练的特定模型架构，并需要为 DEEPX 硬件优化的用户设计。

Step 1 (Source): 从 PyTorch 或 TensorFlow 等主要 AI 框架准备训练好的模型和源代码。
Step 2 (Export): 导出为 ONNX，这是 DX-COM 识别的标准格式。 : Tip: 为了最大限度地提高与 NPU 规范的兼容性，建议固定输入张量大小并使用 Opset 11 或更高版本。
Step 3 (DX-COM): 在编译器虚拟环境 (venv-dx-compiler) 中，将 ONNX 模型转换为针对 NPU 优化的 .dxnn 二进制文件。
Step 4 (DX-RT): 使用运行时虚拟环境 (venv-dx-runtime)，将生成的模型加载到目标设备并执行推理。
Step 5. (NPU Acceleration): 确认实时 AI 推理性能并验证最终输出。

[Path B] 优化模型路径 (Fast Track)
用于快速验证硬件的"快速通道（Fast Track）"。

DXNN Pre-built Model

Figure. Pre-Built Model Inference.

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

Step 1 (Select): 从 DEEPX ModelZoo 或示例数据中选择经过验证的 .dxnn 模型。
Step 2 (DX-RT): 无需单独的编译过程，在运行时环境 (venv-dx-runtime) 中立即加载所选模型。
Step 3 (NPU Acceleration): 执行硬件加速推理并分析 FPS（帧每秒）和延迟(Latency) 等关键性能指标。

Docker Installation

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

Host System Preparation (Critical)

Docker 容器共享主机的内核，因此为了正确识别 NPU 硬件，必须首先在主机系统（PC）端安装驱动程序。

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

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

B. 防止服务守护进程 (dxrtd) 冲突
dxrtd 的实例在整个系统（主机和所有容器）中只能运行一个。在启动容器之前，务必停止主机端的服务。

sudo systemctl stop dxrt.service

Build Docker Image and Run Container

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

# Build integrated image (Based on Ubuntu 24.04)
./docker_build.sh --all --ubuntu_version=24.04

# Build specific environment only (Using --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）。主机操作系统可能正在使用 Wayland 会话。请参阅 05. FAQ Troubleshooting Guide 中的 Q2. X11 Session Warnings & Mount Errors (Wayland Issues)。

Container Access and Task Guide

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

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

A-1. 访问容器
要在容器内工作，首先需要登录到正在运行的容器的 shell。

# 1. Run in Host Terminal: Enter the container
docker exec -it dx-compiler-24.04 bash 

# 2. Inside Container: Navigate to the work directory
cd /deepx/dx-compiler/dx_com

关于路径逻辑的注意事项

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

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

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

../example/3-compile_sample_models.sh

Method 2: 手动编译 (CLI)
如果需要详细控制，激活虚拟环境并直接使用 dxcom 工具。

source ../venv-dx-compiler/bin/activate  # 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. Run from the host terminal: Enter the container
docker exec -it dx-runtime-24.04 

# 2. Inside Container: Verify NPU hardware recognition
dxrt-cli -s

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

工作目录: /deepx/dx-runtime/dx_app

cd /deepx/dx-runtime/dx_app

# 1. Prepare resources (Download .dxnn models and sample images)
./setup.sh

# 2. Run demo 
./run_demo.sh 			# Run C++ based demo
./run_demo_python.sh 		# Run Python demo

选择演示

运行时，将显示可用演示的列表(0, 1, 2...)。输入相应的数字并按 Enter 键开始。

B-3. 运行流式传输框架 (dx_stream)
基于 GStreamer 的模块，针对实时多通道视频流处理进行了优化。

工作目录: /deepx/dx-runtime/dx_stream

cd /deepx/dx-runtime/dx_stream

# 1. Prepare assets (Downloads streaming-specific models and video assets) 
./setup.sh

# 2. Run the streaming demo (C++ based)
./run_demo.sh

选择场景

通过输入终端中显示的场景编号，可以选择特定的流式传输场景。

关于路径的注意事项
为避免"File not found"错误，请明确区分主机端终端和容器端终端。

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

常见错误

如果在主机端终端（Host terminal）中尝试输入以 /deepx 开头的路径，系统将返回 No such file or directory 错误。在移动目录之前，务必确认提示符是否以 root@... 或 user@container_id 开头。

[Docker] Advanced Troubleshooting (Multi-Runtime Containers)

dxrtd 守护进程需要在系统中作为单例（Singleton）运行。也就是说，主机和所有容器加起来同时只能运行一个。如果要同时启动多个容器，需要更改 Entrypoint（入口点），使守护进程不会自动运行。

Method 1: 修改 Dockerfile 编辑 docker/Dockerfile.dx-runtime 文件，禁用默认启动命令，并将其替换为持久空闲状态（待机状态）以保持容器运行。

# 1. Comment out the existing settings
# ENTRYPOINT [ "/usr/local/bin/dxrtd" ]

# 2. Enable infinite wait settings to keep containers running
ENTRYPOINT ["tail", "-f", "/dev/null"]

Method 2: 修改 docker-compose
如果使用 Docker Compose，可以在 docker/docker-compose.yml 中的相应服务部分直接覆盖默认的 Entrypoint。

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

手动启动

应用上述设置后，NPU 将处于待机状态。进入容器后，使用以下命令手动运行 dxrtd &。

[Docker] Verification of Installation Results (Sanity Check)

进行最终确认以验证安装成功完成，软件和硬件可以正确通信。

A. 确认硬件识别 (`dxrt-cli`)

在容器内运行以下命令，确认 NPU 被识别并处于可操作状态。

dxrt-cli -s

成功检查清单
如果输出结果满足以下 3 个条件，则硬件集成成功。

[x] 设备识别 (Device Recognition): 显示 Device 0: M1（或特定型号名称）。
[x] 版本信息 (Version Information): RT Driver version 或 FW version 等显示有效的版本号。
[x] 守护进程状态 (Daemon Status): 没有显示 "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
-------------------------------------------------------
... (Continued)

B. 系统一致性检查 (System Consistency Check)

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

# Check the integrity of the runtime environment
./dx-runtime/scripts/sanity_check.sh

如果所有项目都输出 [OK] 或 PASS，则已准备好开始服务开发。

Local Installation

通过直接在主机操作系统上安装 DX-AllSuite，可以最大限度地发挥硬件性能，确保所有软件模块之间的无缝兼容性。此方法推荐用于生产环境和详细的性能基准测试。

DX-Compiler Installation (DX-COM, DX-TRON)

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

使用方法的差异

CLI 工具 (Command Line Interface): 直接在终端（Bash）中输入 dxcom 命令执行编译。非常适合快速执行或创建自动化 shell 脚本，无需额外编码。
Python 模块 (Library): 在 Python 脚本中通过 import dx_com 调用函数或类。这是将编译器集成到现有 AI 训练或自动化流水线中的推荐方法。

分发方法更改

独立可执行文件的分发已结束支持。本指南介绍了最新的基于 Wheel 的安装工作流，该工作流优化了依赖关系管理和 Python 环境集成。

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 (安装脚本自动检测版本)

安装集成包
提供的 install.sh 脚本一次性处理从 Python 版本检测到包安装的所有内容。

# Run the interactive installation script (recommended)
./dx-compiler/install.sh

C. 验证和使用方法

安装后，激活虚拟环境 (venv-dx-compiler) 并确认设置。

# 1. Activate the Virtual Environment
source ./dx-compiler/venv-dx-compiler/bin/activate

# 2. Verify Installed Version (CLI and Python Modules)
dxcom --version
python3 -c "import dx_com; print(dx_com.__version__)"

# 3. Access Help Documentation
dxcom -h

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

Tip

如果示例数据的自动下载失败，可以使用以下脚本手动获取资源。

./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 Developer Portal 下载专用的 Windows 安装程序。

DX-Runtime Installation (RT, Driver, FW, App, Stream)

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

A. 模块构建和安装

根据需要，可以进行完整安装或指定特定模块以缩短安装时间。

# Option 1: Install all modules (Driver, FW, RT, App, Stream)
./dx-runtime/install.sh --all

# Option 2: Full install excluding firmware
# (Use this if your NPU already has the latest FW version)
./dx-runtime/install.sh --all --exclude-fw

# Option 3: Install a specific module only
./dx-runtime/install.sh --target=<module_name>

B. 固件 (DX-FW) 更新和激活

固件更新是一个非常重要的过程。请准确执行以下步骤以正确初始化硬件逻辑

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

# Method 1. Using the installation script
./dx-runtime/install.sh --target=dx_fw

# Method 2. Manual update using dxrt-cli
dxrt-cli -u ./dx-runtime/dx_fw/m1/X.X.X/mdot2/fw.bin

Step 2. 执行冷启动 (Cold Boot)
强烈建议完全关闭系统，关闭电源后再重新打开。仅在操作系统级别进行"重新启动（Restart）"可能不足以完全初始化硬件。

Step 3. 系统重启
安装和固件写入完成后，务必执行 sudo reboot 以启用已安装的内核驱动程序。

[Local] Installation Verification (Sanity Check)

本地安装完成后，进行最终检查以确认硬件和软件正常通信。

A. 硬件和版本确认

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

dxrt-cli -s

成功检查清单

[x] 设备识别 (Device Recognition): 是否显示 Device 0: M1？
[x] 版本信息 (Version Info): RT Driver、PCIe Driver、FW version 的版本是否显示有效数值（例如: v1.x.x）?
[x] 状态 (Status): 底部是否显示 电压(Voltage)、时钟(Clock)、温度(Temperature) 的实时指标？

B. 系统完整性检查 (System Integrity Check)

运行批处理健全性脚本以确认所有单独模块是否正确放置在指定路径中。

./dx-runtime/scripts/sanity_check.sh

Tip

如果任何项目返回 FAIL 或 Not Found，请重新检查 3-2 节的模块安装步骤，并检查所有组件是否正确编译。

Prerequisites​

Repository Cloning and Submodule Synchronization​

Automated Environment Management​

SDK Workflow Guide​

Docker Installation​

Host System Preparation (Critical)​

Build Docker Image and Run Container​

Container Access and Task Guide​

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

B. DX-Runtime 环境 (NPU 推理和流式传输)​

[Docker] Advanced Troubleshooting (Multi-Runtime Containers)​

[Docker] Verification of Installation Results (Sanity Check)​

A. 确认硬件识别 (dxrt-cli)​

B. 系统一致性检查 (System Consistency Check)​

如果所有项目都输出 [OK] 或 PASS，则已准备好开始服务开发。​

Local Installation​

DX-Compiler Installation (DX-COM, DX-TRON)​

A. 安装前要求​

B. 安装方法​

C. 验证和使用方法​

D. DX-TRON (GUI 可视化工具)​

DX-Runtime Installation (RT, Driver, FW, App, Stream)​

A. 模块构建和安装​

B. 固件 (DX-FW) 更新和激活​

[Local] Installation Verification (Sanity Check)​

A. 硬件和版本确认​

B. 系统完整性检查 (System Integrity Check)​