跳转到主要内容
SDK Version: 2.4.0

运行第一个NPU模型

本指南涵盖完成所有安装后在DEEPX NPU上运行实际AI模型的端到端实践过程。按顺序运行自动化脚本，即可体验从模型编译到成功推理的完整流水线。

完整流水线​

DEEPX NPU模型部署遵循从优化（编译器）到执行（运行时）的结构化6步工作流程（Step 0~5）。

步骤任务相关脚本说明
Step 0环境检查compiler-0...sh,
runtime-0...sh		验证SDK安装和NPU驱动程序
Step 1模型下载compiler-1_download_onnx.sh下载原始训练模型（ONNX）
Step 2数据准备compiler-2_setup_calibration_dataset.sh为量化优化准备参考数据集
Step 3路径设置compiler-3_setup_output_path.sh设置编译输出（.dxnn）的保存路径
Step 4NPU编译compiler-4_model_compile.sh生成硬件优化的.dxnn二进制文件
Step 5NPU推理runtime-3_run_example_using_dxrt.sh在NPU上运行模型并验证结果

目录结构 完成后，getting-started/文件夹将由指向实际数据源的符号链接组成。

getting-started/
├── calibration_dataset             # dx-compiler/dx_com/calibration_dataset
├── dxnn                            # dx-compiler/dx_com/output
├── forked_dx_app_example           # 运行示例目标（已fork）
│   ├── bin
│   │   ├── efficientnet_async
│   │   └── yolov5_async
│   │   └── yolov5face_async
│   └── sample
│       └── ILSVRC2012
└── sample_models                   # dx-compiler/dx_com/sample_models
    ├── json
    └── onnx

前提条件 开始前请确认以下条件已满足：

  • 必要条件：DX-AllSuite安装必须完全完成。
  • 环境选择 : 本地：适用于将驱动程序和SDK直接安装到主机OS的用户。 : Docker：适用于在DEEPX Docker镜像提供的容器内工作的用户。 提示：所有脚本必须在容器内部（通过docker exec）运行。

DX-Compiler：AI模型编译脚本指南（Step 0~4）​

本节通过Step 0至Step 4的顺序工作流程，说明将标准AI模型转换为NPU专用二进制文件（.dxnn）的过程。

A. 执行顺序​

脚本必须在getting-started目录内按以下顺序执行。

./getting-started/compiler-0_install_dx-compiler.sh         # 环境设置
./getting-started/compiler-1_download_onnx.sh               # 获取模型
./getting-started/compiler-2_setup_calibration_dataset.sh   # 准备数据
./getting-started/compiler-3_setup_output_path.sh           # 路径设置
./getting-started/compiler-4_model_compile.sh               # 最终编译

B. 通用原则与提示​

所有编译器脚本遵循"智能委托"设计以保持工作流程一致性。

  • 逻辑委托：实际处理委托给位于dx-compiler/example/的原始脚本。
  • 环境自动检测：脚本自动识别是在主机还是Docker环境中运行，并相应设置路径和符号链接。
  • 最终产出物：所有步骤都是生成.dxnn文件（NPU推理核心产出物）的里程碑。

C. 脚本详细指南​

[Step 0] compiler-0_install_dx-compiler.sh（安装包） 为模型编译器（dxcom）设置环境。

  • 核心功能：安装dx-compiler环境并运行简单状态检查。
  • 智能检查：使用dxcom -v验证现有安装。如果已安装（不带--force标志），则跳过重新安装。

[Step 1] compiler-1_download_onnx.sh（模型下载） 准备用于编译的示例模型文件（.onnx和.json）。

  • 支持模型：YOLOV5S-1, YOLOV5S_Face-1, MobileNetV2-1
  • 映射：在getting-started/sample_models与SDK内部dx-compiler/dx_com/sample_models之间创建符号链接。

[Step 2] compiler-2_setup_calibration_dataset.sh（校准数据设置） 获取用于在模型量化过程中保持精度的参考数据集。

  • 目的：下载并解压有代表性的图像数据集。用于校准模型，确保优化后仍保持高精度。
  • 结果：将本地getting-started/calibration_dataset连接到SDK核心。

[Step 3] compiler-3_setup_output_path.sh（路径设置）

环境物理路径（实际存储）逻辑路径（访问点）
Docker${DOCKER_VOLUME_PATH}/dxnngetting-started/dxnn/
本地${DX_AS_PATH}/workspace/dxnngetting-started/dxnn/
提示

通过此"逻辑路径"抽象，后续运行时脚本无论在服务器还是本地PC上运行，都能从同一位置（dxnn/）找到模型。

[Step 4] compiler-4_model_compile.sh（执行模型编译） 将准备好的模型和数据结合生成NPU优化二进制文件的最终步骤。

  • 核心操作：调用dxcom引擎执行以下融合： : ONNX（结构）+ JSON（配置）+ 校准（精度）= .dxnn（优化二进制文件）
  • 输出：生成的.dxnn文件存储在dx-compiler/dx_com/output/中，可通过getting-started/dxnn链接立即访问。

DX-Runtime：应用程序执行脚本指南（Step 0, 5）​

本节重点介绍Step 0（环境设置）和Step 5（推理），在实际DEEPX NPU硬件上部署和运行优化后的模型。

A. 完整执行顺序​

为确保稳定运行，请在getting-started/目录内按顺序执行。

./getting-started/runtime-0_install_dx-runtime.sh # 环境设置
./getting-started/runtime-1_setup_input_path.sh # 连接模型
./getting-started/runtime-2_setup_assets.sh # 准备资源
./getting-started/runtime-3_run_example_using_dxrt.sh # 运行示例

B. 通用原则与提示​

所有运行时脚本均按以下逻辑设计，以提供流畅的部署体验。

  • 智能诊断与恢复：脚本使用sanity_check.sh自动验证NPU驱动程序和安装完整性。如果环境损坏，使用-f或--force重新初始化。
  • 环境适应逻辑：根据主机或Docker环境动态分配路径。在无头（TTY）环境中自动应用--no-display标志以防止GUI错误。
  • 资源委托：脚本运行dx_app/setup.sh，自动将所需的二进制文件和示例数据填充到forked_dx_app_example文件夹中。
  • 可视化验证： : CLI环境：包含安装fim（fbi improved）的例程，可在终端直接查看结果图像。 : Docker环境：由于GUI输出受限，可使用docker cp <container_id>:/path/to/result ./local_path提取结果。
前提条件

必须已从之前的编译器阶段成功生成.dxnn文件。运行时引擎没有此硬件优化二进制文件无法工作。

C. 脚本详细指南​

[Step 0] runtime-0_install_dx-runtime.sh（安装包） 构建用于DEEPX NPU控制的核心软件栈。

  • 主要功能：安装运行时库并验证驱动程序运行。
  • 优化：如果sanity_check.sh检测到驱动程序已正确加载，则跳过重复安装步骤。
  • 节时选项：使用--exclude-fw跳过固件更新，仅安装软件栈（当固件已是最新时有用）。

[Step 5准备] runtime-1_setup_input_path.sh（模型路径同步） 同步路径，使运行时引擎能够加载编译阶段生成的.dxnn模型。

环境物理路径（实际存储）逻辑路径（访问点）
Docker${DOCKER_VOLUME_PATH}/dxnngetting-started/dxnn/
本地${DX_AS_PATH}/workspace/dxnngetting-started/dxnn/

[Step 5准备] runtime-2_setup_assets.sh（准备资源） 准备运行推理示例所需的依赖文件和示例数据。

  • 操作：依次调用dx_app和dx_stream目录内的setup.sh脚本。
  • 注意：该脚本在各模块内管理资源，不在forked_dx_app_example文件夹中创建重复副本。

[Step 5] runtime-3_run_example_using_dxrt.sh（运行示例并查看结果） 该脚本将模型加载到NPU上，测量实际性能，并为三个核心任务生成可视化输出。

模型输入数据任务迭代次数
YOLOV5S_Face-1face_sample.jpg[1] 人脸检测30
YOLOV5S-11.jpg[2] 目标检测300
MobileNetV2-11.jpeg[3] 图像分类300
  • 结果报告：执行完成后，脚本在终端输出平均FPS（每秒帧数）和延迟（ms）。
必要检查

此流水线假设Step 1中的三个示例模型均在Step 4中成功编译。

  • 如果模型缺失，推理过程中会出现"File Not Found"错误。
  • 强烈建议在运行运行时脚本前编译全部3个模型，以验证完整的端到端过程。
Last updated: