환경 설정
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 활용을 위한 두 가지 경로를 제공합니다. 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 인스턴스는 하나만 실행할 수 있습니다. 컨테이너를 실행하기 전에 호스트 서비스를 중지합니다.
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
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/ 디렉토리에 사전 다운로드됩니다. 다음 두 가지 방법 중 하나로 컴파일할 수 있습니다.
- 방법 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] 설치 결과 검증 (Sanity Check)
설치가 성공적으로 완료되었고 소프트웨어와 하드웨어가 올바르게 통신하는지 최종 점검합니다.
A. 하드웨어 인식 확인 (dxrt-cli)
컨테이너 내부에서 다음 명령을 실행하여 NPU가 인식되고 작동 중인지 확인합니다:
dxrt-cli -s
성공 체크리스트 출력이 다음 세 가지 조건을 충족하면 하드웨어 통합이 성공한 것입니다:
- [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
- 웹 서버 실행 (원격/Docker): 웹 서버 스크립트를 실행하고 포트를 지정합니다:
./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를 수행하세요.
[로컬] 설치 검증 (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항)로 돌아가 모든 구성 요소가 올바르게 컴파일되었는지 확인하세요.