FAQ 문제 해결 가이드
이 가이드는 DXNN SDK 사용 중 발생하는 일반적인 오류와 증상을 다루고 단계별 해결 방법을 제공합니다.
목차
- Q1. 컨테이너 'Restarting' 오류 (#dxrtd-conflict)
- Q2. X11 세션 경고 및 마운트 오류 (Wayland 문제)
- Q3. 펌웨어 버전 불일치 오류
- Q4. 디바이스 드라이버 업데이트 오류
- Q5. 모델-런타임 버전 호환성 오류
- Q6. 공유 메모리(shm) 부족 오류
Q1. 컨테이너 'Restarting' 오류 (dxrtd 충돌)
docker_run.sh 실행 후 컨테이너 상태가 계속 Restarting으로 표시되어 컨테이너에 진입할 수 없는 경우 발생합니다.
진단 단계
- Step 1. 상태 확인:
docker ps를 실행하고STATUS가Restarting (255)를 반복하는지 확인합니다. - Step 2. 로그 확인:
docker logs <container_name>을 실행하고 "Other instance of dxrtd is running" 메시지를 확인합니다.
# 컨테이너 상태 확인
docker ps
# 출력 예시: STATUS가 'Restarting (255)' 반복
CONTAINER ID IMAGE COMMAND STATUS NAMES
041b9a4933e3 dx-runtime:24.04 "/usr/local/bin/dxrtd" Restarting (255) 4 seconds ago dx-runtime-24.04
# 컨테이너 로그 확인
docker logs dx-runtime-24.04
# 출력: "Other instance of dxrtd is running"
원인
DEEPX Runtime Daemon(dxrtd)은 싱글톤으로 설계되어 있습니다. 전체 시스템(호스트 + 모든 컨테이너)에서 하나의 인스턴스만 실행될 수 있습니다. 호스트에서 dxrtd가 이미 실행 중이면 컨테이너 내부의 데몬이 초기화에 실패하여 크래시 루프가 발생합니다.
해결 방법: 호스트 런타임 서비스(dxrtd) 중지
방법 1: 호스트 서비스 중지 (권장) 컨테이너화된 데몬이 NPU를 제어할 수 있도록 호스트의 서비스를 중지합니다.
# 호스트 서비스 중지
sudo systemctl stop dxrt.service
# 컨테이너 재실행
./docker_run.sh --target=dx-runtime --ubuntu_version=24.04
자세한 내용은 02. 환경 설정의 호스트 시스템 준비 섹션을 참고하세요.
방법 2: 컨테이너 내 자동 실행 방지
호스트 서비스를 반드시 유지해야 한다면 컨테이너 시작 시 데몬(dxrtd)이 자동으로 시작되지 않도록 설정합니다.
자세한 내용은 02. 환경 설정의 Docker 고급 문제 해결 (멀티 런타임 컨테이너) 섹션을 참고하세요.
Q2. X11 세션 경고 및 마운트 오류 (Wayland 문제)
X11 포워딩 인증 실패로 GUI 도구 오류가 발생하거나 컨테이너 시작이 거부되는 경우입니다.
진단 단계
- Q2.1 경고: 시작 시
[WARN] it is recommended to use an X11 session이 표시됩니다. - Q2.2 오류: 시스템 재부팅 또는 로그아웃 후 컨테이너가
error mounting /tmp/.docker.xauth로 실패합니다.
원인
- Q2.1: DX-TRON 등의 GUI 도구는 X11에 최적화되어 있습니다. Wayland 세션은
xauth프로세스를 불안정하게 만들 수 있습니다. - Q2.2: Wayland 세션 종료 시 X 인증 데이터가 삭제되거나 디렉토리 경로가 변경되어 Docker 마운트 포인트가 무효화될 수 있습니다.
해결 방법: 기본 시스템 세션을 X11로 설정
가장 안정적인 해결 방법은 로그인 세션을 X11(Xorg)로 설정하는 것입니다. 이는 Ubuntu/GNOME 환경의 표준 절차입니다.
Step 1. GDM 설정 수정 GDM3 설정 파일을 엽니다.
sudo nano /etc/gdm3/custom.conf
WaylandEnable=false의 주석을 해제하여 로그인 화면이 Xorg를 사용하도록 강제합니다.
# 로그인 화면을 Xorg로 강제
WaylandEnable=false
Step 2. 설정 적용 GDM을 재시작하거나 시스템을 재부팅합니다.
sudo systemctl restart gdm3
# 또는 PC를 단순히 재부팅
Step 3. 리소스 정리 재실행 전에 고아 컨테이너를 제거합니다.
# 기존 컨테이너 정리
docker compose -f docker/docker-compose.yml down --remove-orphans
# 컨테이너 재실행
./docker_run.sh --target=dx-runtime --ubuntu_version=24.04
자세한 내용은 02. 환경 설정의 Docker 설치 섹션을 참고하세요.
Q3. 펌웨어 버전 불일치 오류
NPU 하드웨어의 펌웨어가 필요한 소프트웨어 스택 버전보다 오래되어 애플리케이션이 중단되는 경우 발생합니다.
진단 단계
터미널에서 다음 오류 메시지를 확인합니다.
The current firmware version is X.X.X.
Please update your firmware to version Y.Y.Y or higher.
원인
설치된 DX-RT (런타임) 라이브러리와 NPU에 플래시된 DX-FW (펌웨어) 간의 불일치.
해결 방법: 펌웨어(DX-FW) 업데이트 및 콜드 부팅
방법 1: 통합 설치 스크립트 사용 (권장) 올인원 설정 스크립트를 사용하여 펌웨어를 업데이트합니다.
./dx-runtime/install.sh --target=dx_fw
방법 2: 전용 CLI 도구(dxrt-cli) 사용
특정 바이너리 파일을 지정하여 펌웨어를 수동으로 업데이트합니다.
dxrt-cli -u ./dx-runtime/dx_fw/m1/X.X.X/mdot2/fw.bin
업데이트 후 필수 조치: 콜드 부팅 하드웨어 로직을 완전히 초기화하고 새 펌웨어 버전이 적용되었는지 확인하려면 다음 절차를 따르세요.
옵션 1. [권장] 콜드 부팅
- 방법: 시스템을 완전히 종료하고, 잔류 전원을 소모하기 위해 전원 케이블을 분리한 후 다시 연결하고 전원을 켭니다.
- 이유: NPU의 완전한 하드웨어 수준 리셋을 보장하는 가장 안정적인 방법입니다.
옵션 2. 원격/SSH 환경용
- 물리적 전원 분리가 불가능한 경우(예: 원격 서버실),
sudo reboot명령으로 OS 수준에서 시스템을 재시작합니다. 대부분의 표준 시나리오에서 시스템 재부팅으로 펌웨어를 새로 고치기에 충분합니다.
최종 검증 재부팅 후 다음 명령을 입력하여 펌웨어가 성공적으로 업데이트되었는지 확인합니다.
dxrt-cli -s
자세한 내용은 02. 환경 설정의 펌웨어(DX-FW) 업데이트 및 활성화 섹션을 참고하세요.
Q4. 디바이스 드라이버 업데이트 오류
커널 드라이버 버전이 오래되어 애플리케이션 실행이 중단되는 경우 발생합니다.
진단 단계
터미널에서 다음 오류 메시지를 확인합니다.
The current device driver version is X.X.X.
Please update your device driver to version Y.Y.Y or higher.
원인
설치된 커널 드라이버(dx_rt_npu_linux_driver)가 현재 DX-RT의 최소 요구 사항을 충족하지 않습니다.
해결 방법: 호스트 OS에서 디바이스 드라이버 업데이트
이를 해결하려면 호스트 운영 체제에서 드라이버 모듈을 직접 업데이트해야 합니다.
Step 1. 드라이버 모듈 설치 드라이버를 타겟으로 하는 설치 스크립트를 실행합니다.
./dx-runtime/install.sh --target=dx_rt_npu_linux_driver
Step 2. 시스템 재부팅 드라이버를 Linux 커널에 다시 로드해야 하므로 시스템 재부팅이 필수입니다.
sudo reboot
Step 3. 상태 확인 재부팅 후 업데이트가 성공적으로 완료되었는지 확인합니다.
dxrt-cli -s
Docker 컨테이너는 호스트의 커널을 공유하므로 드라이버 업데이트는 컨테이너 내부가 아닌 호스트 OS에서 수행해야 합니다. 컨테이너 내부에서 드라이버를 업데이트해도 하드웨어 통신 레이어에는 영향을 미치지 않습니다.
자세한 내용은 02. 환경 설정의 모듈 빌드 및 설치 섹션을 참고하세요.
Q5. 모델-런타임 버전 호환성 오류
.dxnn 파일을 생성한 컴파일러 버전과 런타임 라이브러리 버전이 호환되지 않아 애플리케이션이 중단되는 경우 발생합니다.
진단 단계
터미널에서 다음 오류 메시지를 확인합니다.
The model's compiler version(X.X.X) is not compatible in this RT library.
Please downgrade the RT library version to X.X.X or use a model file generated with a compiler version X.X.X or higher.
원인
DX-COM (컴파일러)과 DX-RT (런타임) 간의 버전 불일치 시 발생합니다.
해결 방법: 재컴파일을 통한 버전 동기화
이를 해결하려면 모델과 런타임 환경이 호환되는 버전을 사용하도록 해야 합니다.
방법 1: 모델 재컴파일 (권장)
현재 시스템의 DX-RT 버전과 호환되는 컴파일러 버전으로 .dxnn 파일을 다시 생성합니다. 최적의 성능과 기능 지원을 보장하는 가장 안전한 방법입니다.
방법 2: 런타임 라이브러리 버전 조정 모델 요구 사항에 맞는 버전으로 DX-RT를 재설치합니다.
이 방법을 선택할 경우 NPU 드라이버와 펌웨어의 호환성도 반드시 재확인해야 합니다.
버전 확인 가이드 각 모듈의 정확한 호환 조합을 확인하려면 04. 버전 호환성의 DXNN SDK 버전 호환성 매트릭스를 참고하세요.
Copyright © DEEPX. All rights reserved.
Q6. 공유 메모리(shm) 부족 오류
모델 컴파일 중 DX-COM(DEEPX 컴파일러)의 Docker 기본 /dev/shm 크기가 너무 작을 때 발생합니다.
진단 단계
터미널에서 다음 오류 메시지를 확인합니다.
[ResourceError]: Insufficient shared memory (shm). Increase the available /dev/shm size (e.g. --shm-size for Docker).
원인
Docker 컨테이너에는 기본 64MB의 /dev/shm이 할당됩니다. DX-COM은 모델 컴파일 과정에서 공유 메모리를 사용합니다. 크거나 복잡한 모델을 컴파일할 때 이 기본 한도를 초과할 수 있습니다.
해결 방법: Docker 공유 메모리 크기 늘리기
방법 1: docker run에 --shm-size 사용 (권장)
컨테이너 시작 시 --shm-size 플래그를 전달합니다. 모델 크기에 따라 값을 설정하세요 — 256m이 일반적인 시작점이며, 대형 모델의 경우 1g 이상으로 늘립니다.
docker run --shm-size=256m ...
# 대형 모델의 경우
docker run --shm-size=1g ...
방법 2: docker-compose.yml
Docker Compose(예: docker_run.sh)로 컨테이너를 관리하는 경우 dx-compiler 서비스 정의에 shm_size 필드를 추가합니다.
services:
dx-compiler:
shm_size: '1gb'
256m 값으로 대부분의 경우가 해결됩니다. 더 크거나 일괄 처리되는 모델에서 오류가 지속되면 1g 이상으로 늘리세요.