본문으로 건너뛰기
SDK Version: 2.3.3

첫 번째 NPU 모델 실행하기

이 가이드는 모든 설치를 완료한 후 DEEPX NPU에서 실제 AI 모델을 실행하기 위한 엔드-투-엔드 실무 과정을 다룹니다. 자동화 스크립트를 순서대로 실행하면 모델 컴파일부터 성공적인 추론까지 전체 파이프라인을 경험할 수 있습니다.

전체 파이프라인​

DEEPX NPU 모델 배포는 최적화(컴파일러)에서 실행(런타임)까지 구조화된 6단계 워크플로우(0~5단계)를 따릅니다.

단계태스크관련 스크립트비고
0단계환경 확인compiler-0...sh,
runtime-0...sh		SDK 설치 및 NPU 드라이버 검증
1단계모델 다운로드compiler-1_download_onnx.sh원본 훈련 모델(ONNX) 다운로드
2단계데이터 준비compiler-2_setup_calibration_dataset.sh양자화 최적화를 위한 참조 데이터셋 준비
3단계경로 설정compiler-3_setup_output_path.sh컴파일된 출력(.dxnn)의 저장 경로 설정
4단계NPU 컴파일compiler-4_model_compile.sh하드웨어 최적화된 .dxnn 바이너리 생성
5단계NPU 추론runtime-3_run_example_using_dxrt.shNPU에서 모델 실행 및 결과 검증

디렉토리 구조 완료 후, getting-started/ 폴더는 실제 데이터 소스에 대한 심볼릭 링크로 구성됩니다.

getting-started/
├── calibration_dataset             # dx-compiler/dx_com/calibration_dataset
├── dxnn                            # dx-compiler/dx_com/output
├── forked_dx_app_example        # 예제 실행 대상 (포크됨)
│   ├── bin
│   │   ├── efficientnet_async
│   │   └── yolov5_async
│   │   └── yolov5face_async
│   └── sample
│       └── ILSVRC2012
└── sample_models                # dx-compiler/dx_com/sample_models
    ├── json
    └── onnx

준비 사항 시작하기 전에 환경이 다음 기준을 충족하는지 확인하세요:

  • 전제 조건: DX-AllSuite 설치가 반드시 완전히 완료되어 있어야 합니다.
  • 환경 선택 : 로컬: 드라이버와 SDK를 호스트 OS에 직접 설치한 사용자용. : Docker: DEEPX Docker 이미지가 제공하는 컨테이너 내부에서 작업하는 사용자용. 팁: 모든 스크립트는 반드시 컨테이너 내부(docker exec를 통해)에서 실행해야 합니다.

DX-Compiler: AI 모델 컴파일 스크립트 가이드 (0~4단계)​

이 섹션은 0단계부터 4단계까지 순차적인 워크플로우를 통해 표준 AI 모델을 NPU 전용 바이너리(.dxnn)로 변환하는 과정을 자세히 설명합니다.

A. 실행 순서​

스크립트는 getting-started 디렉토리 내에서 다음 순서로 반드시 실행해야 합니다.

./getting-started/compiler-0_install_dx-compiler.sh         # 환경 설정
./getting-started/compiler-1_download_onnx.sh               # 모델 획득
./getting-started/compiler-2_setup_calibration_dataset.sh   # 데이터 준비
./getting-started/compiler-3_setup_output_path.sh           # 경로 설정
./getting-started/compiler-4_model_compile.sh               # 최종 컴파일

B. 공통 원칙 및 팁​

모든 컴파일러 스크립트는 워크플로우를 일관되게 유지하기 위해 "스마트 위임" 설계를 따릅니다.

  • 로직 위임: 실제 처리는 dx-compiler/example/에 위치한 원본 스크립트에 오프로드됩니다.
  • 자동 환경 감지: 스크립트는 호스트 또는 Docker 환경에서 실행 중인지 자동으로 식별하여 경로 및 심볼릭 링크를 설정합니다.
  • 최종 산출물: 모든 단계는 NPU 추론의 핵심 산출물인 .dxnn 파일을 생성하기 위한 이정표입니다.

C. 상세 스크립트 가이드​

[0단계] compiler-0_install_dx-compiler.sh (패키지 설치) 모델 컴파일러(dxcom)의 환경을 설정합니다.

  • 핵심 기능: dx-compiler 환경을 설치하고 간단한 상태 확인을 실행합니다.
  • 스마트 확인: dxcom -v를 사용하여 기존 설치 여부를 확인합니다. 이미 설치되어 있으면 (--force 플래그를 사용하지 않는 한) 불필요한 재설정으로 시간을 낭비하지 않습니다.

[1단계] compiler-1_download_onnx.sh (모델 다운로드) 컴파일할 샘플 모델 파일(.onnx 및 .json)을 준비합니다.

  • 지원 모델: YOLOV5S-1, YOLOV5S_Face-1, MobileNetV2-1
  • 매핑: getting-started/sample_models와 SDK 내부의 dx-compiler/dx_com/sample_models 간에 심볼릭 링크를 생성합니다.

[2단계] compiler-2_setup_calibration_dataset.sh (캘리브레이션 데이터 설정) 모델 양자화 과정에서 정확도를 유지하기 위한 참조 데이터셋을 획득합니다.

  • 목적: 대표 이미지 데이터셋을 다운로드하고 압축을 해제합니다. 이를 통해 최적화 후에도 정확도가 높게 유지되도록 모델을 캘리브레이션합니다.
  • 결과: 로컬 getting-started/calibration_dataset을 SDK 코어에 연결합니다.

[3단계] compiler-3_setup_output_path.sh (경로 설정)

환경물리적 경로 (실제 저장소)논리적 경로 (접근 지점)
Docker${DOCKER_VOLUME_PATH}/dxnngetting-started/dxnn/
로컬${DX_AS_PATH}/workspace/dxnngetting-started/dxnn/
팁

이 "논리적 경로" 추상화를 통해 이후 런타임 스크립트가 서버 또는 로컬 PC에서 실행되는지 여부에 관계없이 같은 위치(dxnn/)에서 모델을 찾을 수 있습니다.

[4단계] compiler-4_model_compile.sh (모델 컴파일 실행) 준비된 모델과 데이터를 결합하여 NPU 최적화 바이너리를 생성하는 최종 단계입니다.

  • 핵심 작업: dxcom 엔진을 호출하여 다음 융합을 수행합니다: : ONNX (구조) + JSON (설정) + 캘리브레이션 (정밀도) = .dxnn (최적화된 바이너리)
  • 출력: 새로 생성된 .dxnn 파일은 dx-compiler/dx_com/output/에 저장되고 getting-started/dxnn 링크를 통해 즉시 접근할 수 있습니다.

DX-Runtime: 애플리케이션 실행 스크립트 가이드 (0, 5단계)​

이 장은 0단계(환경 설정)와 5단계(추론)에 초점을 맞추어, 최적화된 모델을 실제 DEEPX NPU 하드웨어에 배포하고 실행합니다.

A. 전체 실행 순서​

안정적인 운용을 위해 getting-started/ 디렉토리 내에서 이 스크립트들을 순차적으로 실행하세요.

./getting-started/runtime-0_install_dx-runtime.sh # 환경 설정
./getting-started/runtime-1_setup_input_path.sh # 모델 연결
./getting-started/runtime-2_setup_assets.sh # 리소스 준비
./getting-started/runtime-3_run_example_using_dxrt.sh # 예제 실행

B. 공통 원칙 및 팁​

모든 런타임 스크립트는 원활한 배포 경험을 보장하기 위해 다음 로직으로 설계되어 있습니다.

  • 지능적 진단 및 복구: 스크립트는 sanity_check.sh를 사용하여 NPU 드라이버와 설치 무결성을 자동으로 검증합니다. 환경이 손상된 경우 -f 또는 --force를 사용하여 재초기화합니다.
  • 환경 적응형 로직: 호스트 또는 Docker 환경에 따라 경로가 동적으로 할당됩니다. 헤드리스(TTY) 환경에서는 스크립트가 자동으로 --no-display 플래그를 적용하여 GUI 오류를 방지합니다.
  • 리소스 위임: 스크립트는 dx_app/setup.sh를 트리거하여 forked_dx_app_example 폴더에 필요한 바이너리와 샘플 데이터를 자동으로 채웁니다.
  • 시각적 검증: : CLI 환경: 터미널에서 직접 결과 이미지를 볼 수 있는 fim (fbi improved) 설치 루틴을 포함합니다. : Docker 환경: GUI 출력이 제한되므로 docker cp <container_id>:/path/to/result ./local_path를 사용하여 결과를 가져올 수 있습니다.
전제 조건

이전 컴파일러 단계에서 .dxnn 파일을 성공적으로 생성했어야 합니다. 런타임 엔진은 이 하드웨어 최적화 바이너리 없이는 작동할 수 없습니다.

C. 상세 스크립트 가이드​

[0단계] runtime-0_install_dx-runtime.sh (패키지 설치) DEEPX NPU 제어를 위한 핵심 소프트웨어 스택을 구축합니다.

  • 주요 기능: 런타임 라이브러리를 설치하고 드라이버 작동을 검증합니다.
  • 최적화: sanity_check.sh가 드라이버가 이미 올바르게 로드되어 있음을 감지하면 중복 설치 단계를 건너뜁니다.
  • 시간 절약 옵션: --exclude-fw를 사용하여 펌웨어 업데이트를 건너뛰고 소프트웨어 스택을 설치할 수 있습니다(펌웨어가 이미 최신 상태인 경우 유용).

[5단계 준비] runtime-1_setup_input_path.sh (모델 경로 동기화) 컴파일 단계에서 생성된 .dxnn 모델을 런타임 엔진이 로드할 수 있도록 경로를 동기화합니다.

환경물리적 경로 (실제 저장소)논리적 경로 (접근 지점)
Docker${DOCKER_VOLUME_PATH}/dxnngetting-started/dxnn/
로컬${DX_AS_PATH}/workspace/dxnngetting-started/dxnn/

[5단계 준비] runtime-2_setup_assets.sh (리소스 준비) 추론 예제를 실행하는 데 필요한 종속성 파일과 샘플 데이터를 준비합니다.

  • 작업: dx_app 및 dx_stream 디렉토리 내의 setup.sh 스크립트를 순차적으로 호출합니다.
  • 참고: 이 스크립트는 각 모듈 내에서 리소스를 관리하며, forked_dx_app_example 폴더에 중복 복사본을 생성하지 않습니다.

[5단계] runtime-3_run_example_using_dxrt.sh (예제 실행 및 결과 확인) 이 스크립트는 NPU에 모델을 로드하고, 실제 성능을 측정하며, 세 가지 핵심 태스크에 걸쳐 시각화된 출력을 생성합니다.

모델입력 데이터태스크반복 횟수
YOLOV5S_Face-1face_sample.jpg[1] 얼굴 감지30
YOLOV5S-11.jpg[2] 객체 감지300
MobileNetV2-11.jpeg[3] 이미지 분류300
  • 결과 보고서: 실행이 완료되면 스크립트가 평균 FPS (초당 프레임)와 지연시간 (ms)을 터미널에 출력합니다.
필수 확인 사항

이 파이프라인은 1단계의 세 가지 샘플 모델 모두가 4단계에서 성공적으로 컴파일되었다고 가정합니다.

  • 모델이 없으면 추론 중에 "파일을 찾을 수 없음" 오류가 발생합니다.
  • 전체 엔드-투-엔드 프로세스를 검증하기 위해 이 런타임 스크립트를 실행하기 전에 3개 모델 모두 컴파일하는 것을 강력히 권장합니다.
Last updated: