環境設定

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] カスタムモデル推論パス ユーザーがトレーニングしたモデルを変換・デプロイするための標準ワークフローです。

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

このパスは、フレームワークでトレーニングされた特定のモデルアーキテクチャを持ち、DEEPXハードウェア向けに最適化したいユーザーのために設計されています。

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

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

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

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

• ステップ1（選択）: DEEPX ModelZooまたはサンプルデータから事前検証済みの.dxnnモデルを選択します。
• ステップ2（DX-RT）: 別途コンパイルせずに、ランタイム環境（venv-dx-runtime）で選択したモデルをすぐにロードします。
• ステップ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 bash

# 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

シナリオの選択

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

パスに関する注意事項 「ファイルが見つからない」エラーを防ぐために、ホストターミナルとコンテナターミナルを区別することが重要です。

• 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] インストール結果の検証（Sanity Check）

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

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**が出力されれば、サービス開発を開始する準備ができています。

---

ローカルインストール

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

• 作業: DX-Compilerローカルインストールガイド [リンク]

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インストールガイド [リンク]

DX-Runtimeのインストール（RT、ドライバー、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）の更新とアクティベーション

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

ステップ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

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

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

[ローカル] インストール結果の検証（Sanity Check）

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

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

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

dxrt-cli -s

成功チェックリスト

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

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

すべてのモジュールが指定されたパスにあるか確認する一括Sanityスクリプトを実行します。

./dx-runtime/scripts/sanity_check.sh

ヒント

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

---