환경 설정
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] 커스텀 모델 추론 경로 사용자 훈련 모델을 변환하고 배포하기 위한 표준 워크플로우입니다.
그림. 커스텀 모델 추론.
이 경로는 프레임워크에서 훈련된 특정 모델 아키텍처를 가지고 있어 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는 호스트와 컨테이너 전체에서 단 하나의 인스턴스만 실행할 수 있습니다. 컨테이너 실행 전에 호스트 서비스를 중지합니다.
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 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
성공 체크리스트 출력이 다음 세 가지 조건을 충족하면 하드웨어 통합이 성공한 것입니다:
- [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
- 웹 서버 실행 (원격/Docker): 웹 서버 스크립트를 실행하고 포트를 지정합니다:
./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절)를 다시 확인하여 모든 구성 요소가 올바르게 컴파일되었는지 확인하세요.