本文へスキップ

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: ホストOSにドライバと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）プロセスにおいて、精度を維持するための参照用データセットを取得します。

  • 目的: 代表的な画像データセットをダウンロードし、展開します。 これらはモデルを「校正（キャリブレーション）」するために使用され、最適化（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）環境では、GUIエラーを防止するために自動的に --no-display フラグが適用されます。
  • リソースの委譲: スクリプトは 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: