本文へスキップ

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. ローカルインストール: ホストOSへの直接インストール。

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 を使用する予定で、まだ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を活用するための2つのパス（経路）を提供します。 SDKは、シームレスな開発体験を実現するために、必要な仮想環境や依存関係を自動的に管理します。

[Path A] カスタムモデル推論パス
ユーザーが学習させた独自のモデルを変換し、デプロイするための標準的なワークフローです。

DXNN Custom Model

Figure. Custom Model Inference.

このパスは、PyTorchやTensorFlowなどのフレームワークで学習させた特定のモデルアーキテクチャを持ち、それをDEEPXハードウェア用に最適化する必要があるユーザー向けに設計されています。

  • Step 1 (Source): PyTorchやTensorFlowなどの主要なAIフレームワークから、学習済みモデルとソースコードを準備します。
  • Step 2 (Export): DX-COMが認識する標準形式であるONNXにエクスポートします。 : 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 のインスタンスは、ホストと全コンテナを通じてシステム全体で1つしか実行できません。 コンテナを起動する前に、必ずホスト側のサービスを停止してください。

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）が発生した場合。 ホストOSが 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. コンテナへのアクセス
コンテナ内で作業を行うには、まず実行中のコンテナのシェルにログインする必要があります。

# 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/ ディレクトリに事前ダウンロードされています。 以下の2つの方法でコンパイル可能です。

  • 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) として動作する必要があります。 つまり、ホストおよびすべてのコンテナを合わせて、同時に1つしか実行できません。 複数のコンテナを同時に起動したい場合は、デーモンが自動実行されないように 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をホストOSに直接インストールすることで、ハードウェア性能を最大限に引き出し、すべてのソフトウェアモジュール間のシームレスな互換性を確保できます。 この方法は、本番環境および詳細なパフォーマンスベンチマークに推奨されます。

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

DX-Compiler(DX-COM)は、サポートされているLinuxディストリビューション上で、CLIツールまたはPythonモジュールとして使用できます。

使用方法の違い

  • CLI ツール (Command Line Interface): ターミナル（Bash）で直接 dxcom コマンドを入力してコンパイルを実行します。 追加のコーディングなしで、迅速な実行や自動シェルスクリプトを作成するのに最適です。
  • Python モジュール (Library): Pythonスクリプト内で import dx_com を介して関数やクラスを呼び出します。 既存のAIトレーニングや自動化パイプラインにコンパイラを統合する場合に推奨される方法です。
配布方法の変更

スタンドアロン実行ファイルの配布はサポートを終了しました。 このガイドでは、依存関係の管理とPython環境の統合を最適化する最新の Wheelベースのインストールワークフロー について説明します。

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) の実行
システムを完全にシャットダウンし、電源をオフにしてから再度オンにすることを強く推奨します。 単なるOSレベルの「再起動（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 のモジュールインストール手順を再度確認し、すべてのコンポーネントが正しくコンパイルされているかチェックしてください。

Last updated: