跳转到主要内容

Running Your First NPU Model

本指南介绍了在完成 DX-AllSuite 安装后，在 DEEPX NPU 上运行实际 AI 模型的实用端到端过程。通过按顺序运行自动化脚本，您可以体验从模型编译到推理成功的整个流水线。

Overall Pipeline​

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

StepTaskRelated ScriptRemark
Step 0Environment Checkcompiler-0...sh,
runtime-0...sh		Verify SDK installation and NPU driver
Step 1Model Downloadcompiler-1_download_onnx.shDownload original trained models (ONNX)
Step 2Data Preparationcompiler-2_setup_calibration_dataset.shPrepare reference dataset for quantization optimization
Step 3Path Configurationcompiler-3_setup_output_path.shConfigure storage path for compiled outputs (.dxnn)
Step 4NPU Compilationcompiler-4_model_compile.shGenerate hardware-optimized .dxnn binaries
Step 5NPU Inferenceruntime-3_run_example_using_dxrt.shExecute the model on NPU and verify results

目录结构
设置完成后 getting-started/ 文件夹配置有指向实际数据源的符号链接，如下所示。

getting-started/
├── calibration_dataset             # dx-compiler/dx_com/calibration_dataset
├── dxnn                            # dx-compiler/dx_com/output
├── forked_dx_app_example        	# Example execution target (forked)
│   ├── bin
│   │   ├── efficientnet_async
│   │   └── yolov5_async
│   │   └── yolov5face_async
│   └── sample
│       └── ILSVRC2012
└── sample_models                	# dx-compiler/dx_com/sample_models
    ├── json
    └── onnx

准备 (Preparation)
在开始之前，请确认环境满足以下标准。

  • 前提条件: DX-AllSuite 的安装已完全完成。
  • 环境选择
    : Local: 在主机操作系统上直接安装了驱动程序和 SDK 的情况。
    : Docker: 在 DEEPX Docker 镜像提供的容器内工作的情况。
    Tip: 在 Docker 环境中，所有脚本都必须在容器内（通过 docker exec）执行。

DX-Compiler: AI Model Compilation Scripts Guide (Steps 0–4)​

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

A. Execution Order​

在 getting-started 目录中，按以下顺序执行脚本。

./getting-started/compiler-0_install_dx-compiler.sh         # Environment Setup
./getting-started/compiler-1_download_onnx.sh               # Model Acquisition
./getting-started/compiler-2_setup_calibration_dataset.sh   # Data Preparation
./getting-started/compiler-3_setup_output_path.sh           # Path Configuration
./getting-started/compiler-4_model_compile.sh               # Final Compilation

B. Common Principles & Tips​

所有编译器脚本采用 智能委托 (Smart Delegation) 设计以保持工作流的一致性。

  • 逻辑委托: 实际处理交给 dx-compiler/example/ 中的原始脚本。
  • 环境自动检测: 脚本自动判断执行环境（主机或 Docker）并配置适当的路径和符号链接。
  • 最终资产: 所有步骤都是生成 NPU 推理必需资产 .dxnn 文件的重要里程碑

C. Detailed Script Guide​

[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 (校准数据设置)
获取参考数据集，用于在模型量化（Quantization）过程中保持精度。

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

[Step 3] compiler-3_setup_output_path.sh (路径设置)

EnvironmentPhysical Path (Actual Storage)Logical Path (Access Point)
Docker${DOCKER_VOLUME_PATH}/dxnngetting-started/dxnn/
Local${DX_AS_PATH}/workspace/dxnngetting-started/dxnn/
Tip

通过这种"逻辑路径"抽象，后续的运行时脚本无论是在服务器上还是在本地 PC 上，都可以始终在同一位置（dxnn/）查找模型。

[Step 4] compiler-4_model_compile.sh (执行模型编译)
结合准备好的模型和数据，生成 NPU 优化二进制文件的最终阶段。

  • 核心操作: 调用 dxcom 引擎，融合以下元素。
    : ONNX (结构) + JSON (配置) + Calibration (精度) = .dxnn (优化二进制文件)
  • 输出: 生成的新 .dxnn 文件保存在 dx-compiler/dx_com/output/ 中，可通过 getting-started/dxnn 链接立即访问和使用。

DX-Runtime: Application Execution (Application Execution Scripts Guide) (Step 0, 5)​

本节介绍以 Step 0 环境构建和 Step 5 推理为中心，将优化模型部署到实际 DEEPX NPU 硬件并执行的过程。

A. Full Execution Order​

在 getting-started/ 目录中，按顺序执行以下脚本。

./getting-started/runtime-0_install_dx-runtime.sh # Set up environment
./getting-started/runtime-1_setup_input_path.sh # Connect model
./getting-started/runtime-2_setup_assets.sh # Prepare resources
./getting-started/runtime-3_run_example_using_dxrt.sh # Run example

B. Common Principles & Tips​

所有运行时脚本基于以下逻辑设计，以实现无缝部署体验。

  • 智能诊断和恢复: 脚本使用 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. Detailed Script Guide​

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

  • 核心功能: 安装运行时库并确认驱动程序运行。
  • 优化: 如果 sanity_check.sh 检测到驱动程序已正确加载，则跳过冗余安装步骤。
  • 省时选项: 如果只想安装软件堆栈而跳过固件更新，请使用 --exclude-fw（当已应用最新固件时很方便）。

[Step 5 准备] runtime-1_setup_input_path.sh (模型路径同步)
同步编译阶段生成的 .dxnn 模型的路径，使运行时引擎可以加载它们。

EnvironmentPhysical Path (Actual Storage)Logical Path (Access Point)
Docker${DOCKER_VOLUME_PATH}/dxnngetting-started/dxnn/
Local${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，测量实际性能，并为以下 3 个主要任务生成可视化输出。

ModelInput DataTaskIterations
YOLOV5S_Face-1face_sample.jpg[1] Face Detection30
YOLOV5S-11.jpg[2] Object Detection300
MobileNetV2-11.jpeg[3] Image Classification300
  • 结果报告: 执行完成后，脚本将平均 FPS（每秒帧数）和 Latency（延迟，ms）输出到终端。
必需检查项

此流水线假定在 Step 1 中准备的 3 个示例模型已在 Step 4 中正常编译。

  • 如果缺少模型，推理期间将发生 "File Not Found" 错误。
  • 强烈建议在运行此运行时脚本之前编译所有 3 个模型，以验证整个端到端过程。
Last updated: