環境設定

DX-AllSuiteはDEEPXデバイスを検証・活用するための統合環境構築ツールです。このガイドは複雑な依存関係の問題を解決し、ローカルホストとDockerコンテナの両方で一貫した開発経験を提供します。

図. DX-AllSuiteサポート環境と統合。

インストール概要

[共通] 1. 前提条件: ソースコードを取得し、仮想環境管理ポリシーを理解します。

[オプション] インストールパスを選択します。

• [ルートA] 2. Dockerインストール: コンテナベースの分離インストール。
• [ルートB] 3. ローカルインストール: ホストOSへの直接インストール。

---

前提条件

安定したインストールのために以下の手順を最初に実行してください。

リポジトリのクローンとサブモジュールの同期

DX-AllSuiteは複数の独立したモジュールの集合体です。サブモジュールが欠落していると、コンパイルとランタイム実行が不可能になります。以下のコマンドを正確に使用してください。

A. リポジトリのクローン（サブモジュールを含む）

# HTTPS経由（推奨）
git clone --recurse-submodules https://github.com/DEEPX-AI/dx-all-suite.git

# SSH経由
git clone --recurse-submodules git@github.com:DEEPX-AI/dx-all-suite.git

cd dx-all-suite

B. （オプション）既存リポジトリの更新 すでにリポジトリをクローンしているがサブフォルダが空の場合、手動初期化を必ず実行する必要があります。

# サブモジュールを最新状態に初期化および更新
git submodule update --init --recursive

# サブモジュールの状態確認（先頭に「-」がなければ成功）
git submodule status

C. （オプション）Docker環境の準備 Dockerルートを使用する予定だがDockerがインストールされていない場合は、提供されている自動化スクリプトを使用してください。

# DockerとDocker Composeの自動インストール
./scripts/install_docker.sh

自動化された環境管理

DX-AllSuiteはパッケージの競合を防ぐためにPython仮想環境（venv）の作成を自動化します。インストールスクリプトが各実行コンテキストに最適化された独立した環境を自動的に設定するため、ユーザーが手動で仮想環境を作成する必要はありません。

• コンパイラー環境: dx-compiler/venv-dx-compilerに作成
• ランタイム環境: dx-runtime/venv-dx-runtimeに作成

注意

個別モジュール（例: dx-rtのみ）をインストールする場合、インストール失敗を防ぐためにスクリプトが作成した対応する仮想環境を必ずアクティベート（source .../activate）する必要があります。

SDKワークフローガイド

DX-AllSuiteは独自のモデルを持ち込むか、事前最適化済みのモデルを使用するかによって、DEEPX NPU活用のための2つのパスを提供します。SDKはシームレスな開発経験のために必要な仮想環境と依存関係を自動的に管理します。

[パスA] カスタムモデル推論パス ユーザーのトレーニング済みモデルを変換してデプロイするための標準ワークフロー。

図. カスタムモデル推論。

PyTorchやTensorFlowなどのフレームワークでトレーニングされた特定のモデルアーキテクチャをDEEPXハードウェア向けに最適化する必要があるユーザー向けに設計されたパスです。

• Step 1（ソース）: PyTorchやTensorFlowなどの主要AIフレームワークでトレーニングされたモデルとソースコードを確保します。
• Step 2（エクスポート）: モデルをDX-COMが認識する標準形式であるONNXにエクスポートします。 : ヒント: 入力テンソルサイズを設定し、NPU仕様との最大互換性のためにOpset 11以上を使用してください。
• Step 3（DX-COM）: コンパイラー仮想環境（venv-dx-compiler）内でONNXモデルをNPU最適化.dxnnバイナリに変換します。
• Step 4（DX-RT）: ランタイム仮想環境（venv-dx-runtime）を使用してターゲットデバイスで生成されたモデルをロードし、推論を実行します。
• Step 5（NPU加速）: リアルタイムAI推論パフォーマンスを検証し、最終出力を検査します。

[パスB] 事前コンパイル済みモデルパス（ファストトラック） 即時ハードウェア検証のための「ファストトラック」。

図. 事前ビルド済みモデル推論。

業界標準モデルを使用してDEEPX NPUのパフォーマンスを迅速にベンチマークするか、ハードウェア統合をテストしたいユーザーに理想的なパスです。

• Step 1（選択）: DEEPX ModelZooまたはサンプルデータから事前検証済みの.dxnnモデルを選択します。
• Step 2（DX-RT）: 別途コンパイルなしでランタイム環境（venv-dx-runtime）で選択したモデルを即時ロードします。
• Step 3（NPU加速）: ハードウェア加速推論を実行し、FPSやレイテンシなどの主要パフォーマンス指標を分析します。

---

Dockerインストール

Dockerを使用すると、複雑な依存関係のセットアップなしに分離された環境でDX-AllSuiteを実行できます。

ホストシステムの準備（必須）

DockerコンテナはホストカーネルをNPUハードウェア認識のために共有するため、まずホストシステム（PC）にドライバーをインストールする必要があります。

A. NPUドライバーインストール（ホスト） まずホストPCでインストールスクリプトを実行します。

./dx-runtime/install.sh --target=dx_rt_npu_linux_driver

B. サービスデーモン（dxrtd）の競合防止 ホストとコンテナ全体でdxrtdインスタンスは1つだけ実行できます。コンテナを実行する前にホストサービスを停止します。

sudo systemctl stop dxrt.service

Dockerイメージのビルドとコンテナ実行

A. イメージビルド --allオプションを使用するとコンパイラー、ランタイム、ModelZooを含む統合イメージをビルドします。

# 統合イメージのビルド（Ubuntu 24.04ベース）
./docker_build.sh --all --ubuntu_version=24.04

# 特定環境のみのビルド（--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トラブルシューティングガイドの**Q2. X11セッション警告とマウントエラー（Wayland問題）**を参照してください。

コンテナアクセスと作業ガイド

A. DX-Compiler環境（モデル変換）

DX-Compiler環境はハードウェア最適化された.dxnnバイナリを生成するために使用されます。

A-1. コンテナアクセス コンテナ内で作業を行うには、実行中のコンテナのシェルに必ず最初にログインする必要があります。

# 1. ホストターミナルで実行: コンテナに入る
docker exec -it dx-compiler-24.04 bash 

# 2. コンテナ内部: 作業ディレクトリへ移動
cd /deepx/dx-compiler/dx_com

パスロジックの注意

/deepxパスはコンテナ内部の絶対パスです。このパスはホストマシンには存在しません。コマンドを実行する前にターミナルのプロンプトがroot@...またはuser@container_idに変わっているか確認してください。

A-2. サンプルモデルのコンパイル サンプルモデルはインストール時に./sample_models/ディレクトリに事前ダウンロードされます。以下の2つの方法のいずれかでコンパイルできます。

• 方法1: 一括コンパイル（推奨） 提供されているスクリプトを使用してすべてのサンプルモデルを自動的にコンパイルします。

../example/3-compile_sample_models.sh

• 方法2: 手動コンパイル（CLI） 細かい制御のために仮想環境をアクティベートしてdxcomツールを直接使用します。

source ../venv-dx-compiler/bin/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. ホストターミナルで実行: コンテナに入る
docker exec -it dx-runtime-24.04 

# 2. コンテナ内部: NPUハードウェア認識の確認
dxrt-cli -s

B-2. サンプルアプリケーションの実行（dx_app） このモジュールはさまざまなビジョンタスクの推論デモを提供します。

• 作業ディレクトリ: /deepx/dx-runtime/dx_app

cd /deepx/dx-runtime/dx_app

# 1. リソース準備（.dxnnモデルとサンプル画像のダウンロード）
./setup.sh

# 2. デモ実行
./run_demo.sh           # C++ベースのデモ実行
./run_demo_python.sh    # Pythonデモ実行

デモの選択

実行時にターミナルに利用可能なデモの一覧（0, 1, 2...）が表示されます。該当番号を入力してEnterを押して開始します。

B-3. ストリーミングフレームワークの実行（dx_stream） このモジュールはリアルタイムマルチチャンネルビデオストリーム処理に最適化されたGStreamerベースのモジュールです。

• 作業ディレクトリ: /deepx/dx-runtime/dx_stream

cd /deepx/dx-runtime/dx_stream

# 1. アセット準備（ストリーミング専用モデルとビデオアセットのダウンロード）
./setup.sh

# 2. ストリーミングデモの実行（C++ベース）
./run_demo.sh

シナリオの選択

ターミナルに表示されたシナリオ番号を入力して特定のストリーミングシナリオを選択できます。

パスの注意事項 「File not found」エラーを防ぐには、ホストターミナルとコンテナターミナルを区別することが重要です。

• Dockerコンテナ内部: 常に/deepxで始まる絶対パスを使用（例: cd /deepx/dx-runtime/...）。
• ローカルホスト環境: 現在のディレクトリを基準とした相対パスを使用（例: cd ./dx-runtime/...）。

一般的なエラー

ホストターミナルで/deepxで始まるパスを入力するとNo such file or directoryエラーが返されます。移動前にプロンプトがroot@...またはuser@container_idで始まることを常に確認してください。

[Docker] 高度なトラブルシューティング（マルチランタイムコンテナ）

dxrtdデーモンはシステム内でシングルトンとして必ず実行される必要があります。複数のコンテナを同時に実行するには、自動起動を防ぐためにEntrypointを必ず修正する必要があります。

• 方法1: Dockerfileの修正 docker/Dockerfile.dx-runtimeファイルを編集してデフォルトの起動コマンドを無効化し、継続的な待機状態に置き換えます。

# 1. 既存設定をコメントアウト
# ENTRYPOINT [ "/usr/local/bin/dxrtd" ]

# 2. コンテナを実行状態に保つ無限待機設定を有効化
ENTRYPOINT ["tail", "-f", "/dev/null"]

• 方法2: docker-composeの修正 Docker Composeを使用する場合、docker/docker-compose.ymlの対応するサービスセクションでデフォルトのEntrypointを直接上書きできます。

services:
  dx-runtime:
    entrypoint: ["/bin/sh", "-c"]
    command: ["sleep infinity"]

手動起動

上記の設定を適用するとNPUが待機状態になります。コンテナに入った後、dxrtd &コマンドで手動で実行してください。

[Docker] インストール結果の検証（サニティチェック）

インストールが正常に完了し、ソフトウェアとハードウェアが正しく通信しているか最終確認します。

A. ハードウェア認識の確認（dxrt-cli）

コンテナ内部で以下のコマンドを実行してNPUが認識され動作中であることを確認します:

dxrt-cli -s

成功チェックリスト 出力が以下の3つの条件を満たしていれば、ハードウェア統合が成功しています:

• [x] デバイス認識: Device 0: M1（または特定のモデル）が表示される。
• [x] バージョン情報: RT Driver version、FW versionなどに有効なバージョン番号が表示される。
• [x] デーモン状態: 「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
-------------------------------------------------------
... (続く)

B. システム一貫性の確認

このスクリプトはすべての個別モジュールが指定されたパスに正しく配置されて実行準備が整っているか一括確認します。

# ランタイム環境の整合性確認
./dx-runtime/scripts/sanity_check.sh

すべての項目に**[OK]またはPASS**が出力されれば、サービス開発を開始する準備ができています。

---

ローカルインストール

ホストOSにDX-AllSuiteを直接インストールすると、最大のハードウェアパフォーマンスとすべてのソフトウェアモジュール間のシームレスな互換性が保証されます。本番環境と高度なパフォーマンスベンチマークに推奨される方法です。

DX-Compilerインストール (DX-COM, DX-TRON)

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

使用方式の違い

• CLIツール（コマンドラインインターフェイス）: ターミナル（Bash）でdxcomコマンドを直接入力してコンパイルを実行。追加のコーディングなしで迅速な実行と自動化されたシェルスクリプトに最適です。
• Pythonモジュール（ライブラリ）: 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、3.13、3.14（インストールスクリプトが自動的にバージョンを検出）

統合パッケージインストール 提供されているinstall.shスクリプトがPythonバージョン検出とパッケージインストールを含めてすべてを一度に処理します。

# インタラクティブインストールスクリプトの実行（推奨）
./dx-compiler/install.sh

C. 確認と使用

インストール後に仮想環境（venv-dx-compiler）をアクティベートして設定を確認します。

# 1. 仮想環境のアクティベート
source ./dx-compiler/venv-dx-compiler/bin/activate

# 2. インストールバージョンの確認（CLIとPythonモジュール）
dxcom --version
python3 -c "import dx_com; print(dx_com.__version__)"

# 3. ヘルプドキュメントへのアクセス
dxcom -h

• サンプルデータの場所: ./dx-compiler/dx_com/sample_models/

ヒント

自動サンプルデータのダウンロードが失敗した場合、以下のスクリプトで手動でアセットを取得できます:

• ./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開発者ポータルから専用のWindowsインストーラーを直接ダウンロードできます。

DX-Runtimeインストール (RT, Driver, FW, App, Stream)

DX-RuntimeスタックはDEEPX NPUハードウェアを制御してAIアプリケーションを実行するために必要なコアソフトウェアレイヤーです。各コンポーネントは./dx-runtimeディレクトリ内のサブモジュールとして管理されています。

A. モジュールのビルドとインストール

要件に応じて完全インストールまたは特定モジュールをターゲットにして時間を節約できます。

# オプション1: すべてのモジュールをインストール（ドライバー、FW、RT、App、Stream）
./dx-runtime/install.sh --all

# オプション2: ファームウェアを除く完全インストール
# （NPUにすでに最新FWバージョンがある場合に使用）
./dx-runtime/install.sh --all --exclude-fw

# オプション3: 特定モジュールのみインストール
./dx-runtime/install.sh --target=<module_name>

B. ファームウェア（DX-FW）の更新とアクティベーション

ファームウェアの更新は重要なプロセスです。ハードウェアロジックが正しく初期化されるよう以下の手順を正確に実行してください。

Step 1. ファームウェアの更新 自動化されたインストールスクリプトまたは専用CLIツールを使用してファームウェアを更新できます。

# 方法1. インストールスクリプトの使用
./dx-runtime/install.sh --target=dx_fw

# 方法2. dxrt-cliを使用した手動更新
dxrt-cli -u ./dx-runtime/dx_fw/m1/X.X.X/mdot2/fw.bin

Step 2. コールドブートの実施 システムを完全にシャットダウンし、電源をオフにしてから再度オンにすることを強く推奨します。単純な「再起動」はハードウェアの初期化に十分でない場合があります。

Step 3. システムの再起動 インストール完了後、インストールされたカーネルドライバーをアクティベートするために必ずsudo rebootを実行してください。

[ローカル] インストール検証（サニティチェック）

ローカルインストールが完了したら、ハードウェアとソフトウェアが正しく通信しているか最終確認します。

A. ハードウェアとバージョンの確認

以下のコマンドを実行してシステムで認識されたNPUデバイス情報を表示します。

dxrt-cli -s

成功チェックリスト

• [x] デバイス認識: Device 0: M1が表示されるか？
• [x] バージョン情報: RT Driver、PCIe Driver、FW versionに有効な番号（例: v1.x.x）が表示されるか？
• [x] 状態: 下部に電圧、クロック、温度のリアルタイム指標が表示されるか？

B. システム整合性の確認

一括サニティスクリプトを実行してすべてのモジュールが指定されたパスに配置されているか確認します。

./dx-runtime/scripts/sanity_check.sh

ヒント

項目がFAILまたはNot Foundを返した場合、モジュールインストール手順（3-2項）に戻ってすべてのコンポーネントが正しくコンパイルされているか確認してください。

---