跳转到主要内容
SDK Version: 2.3.3

运行第一个 NPU 模型

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

整体流水线​

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

步骤任务相关脚本备注
步骤 0环境检查compiler-0...sh,
runtime-0...sh		验证 SDK 安装和 NPU 驱动程序
步骤 1模型下载compiler-1_download_onnx.sh下载原始训练模型 (ONNX)
步骤 2数据准备compiler-2_setup_calibration_dataset.sh准备用于量化优化的参考数据集
步骤 3路径配置compiler-3_setup_output_path.sh配置编译输出 (.dxnn) 的存储路径
步骤 4NPU 编译compiler-4_model_compile.sh生成硬件优化的 .dxnn 二进制文件
步骤 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        # 示例执行目标（已分叉）
│   ├── bin
│   │   ├── efficientnet_async
│   │   └── yolov5_async
│   │   └── yolov5face_async
│   └── sample
│       └── ILSVRC2012
└── sample_models                # dx-compiler/dx_com/sample_models
    ├── json
    └── onnx

准备工作 开始前，请确保您的环境满足以下条件：

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

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

本节详细介绍通过从步骤 0 到步骤 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 文件的里程碑，而 .dxnn 是 NPU 推理的必要资产。

C. 详细脚本指南​

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

  • 核心功能：安装 dx-compiler 环境并运行快速健康检查。
  • 智能检查：使用 dxcom -v 探查现有安装。如果已存在，则不会浪费时间进行冗余设置（除非使用 --force 标志）。

[步骤 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 之间创建符号链接。

[步骤 2] compiler-2_setup_calibration_dataset.sh（校准数据设置） 获取参考数据集以在模型量化过程中维持精度。

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

[步骤 3] compiler-3_setup_output_path.sh（路径配置）

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

这个"逻辑路径"抽象允许后续运行时脚本在同一位置 (dxnn/) 查找模型，无论是在服务器还是本地 PC 上运行。

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

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

DX-Runtime：应用程序执行脚本指南（步骤 0、5）​

本章重点介绍步骤 0（环境设置）和步骤 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. 详细脚本指南​

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

  • 关键功能：安装运行时库并验证驱动程序操作。
  • 优化：如果 sanity_check.sh 检测到驱动程序已正确加载，则跳过冗余安装步骤。
  • 省时选项：使用 --exclude-fw 安装软件栈同时跳过固件更新（如果固件已是最新版本，此选项很有用）。

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

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

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

  • 操作：顺序调用 dx_app 和 dx_stream 目录中的 setup.sh 脚本。
  • 注意：此脚本管理各模块内的资源；不会在 forked_dx_app_example 文件夹中创建冗余副本。

[步骤 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）输出到终端。
必要检查

此流水线假设步骤 1 中的所有三个样本模型都在步骤 4 中成功编译。

  • 如果模型缺失，推理期间将遇到"文件未找到"错误。
  • 强烈建议在运行此运行时脚本之前编译所有 3 个模型，以验证整个端到端流程。
Last updated: