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

첫 번째 NPU 모델 실행

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

전체 파이프라인​

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

단계태스크관련 스크립트비고
Step 0환경 점검compiler-0...sh,
runtime-0...sh		SDK 설치 및 NPU 드라이버 확인
Step 1모델 다운로드compiler-1_download_onnx.sh원본 학습 모델(ONNX) 다운로드
Step 2데이터 준비compiler-2_setup_calibration_dataset.sh양자화 최적화용 참조 데이터셋 준비
Step 3경로 설정compiler-3_setup_output_path.sh컴파일 출력물(.dxnn) 저장 경로 설정
Step 4NPU 컴파일compiler-4_model_compile.sh하드웨어 최적화된 .dxnn 바이너리 생성
Step 5NPU 추론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 모델 컴파일 스크립트 가이드 (Step 0~4)​

이 섹션은 Step 0부터 Step 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. 스크립트 상세 가이드​

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

  • 핵심 기능: dx-compiler 환경을 설치하고 간단한 상태 점검을 실행합니다.
  • 스마트 점검: dxcom -v를 사용하여 기존 설치를 확인합니다. 이미 설치되어 있으면 (--force 플래그 없이) 재설치를 건너뜁니다.

[Step 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 사이에 심볼릭 링크를 생성합니다.

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

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

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

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

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

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

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

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

이 섹션은 Step 0(환경 설정)과 Step 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) 환경에서는 GUI 오류를 방지하기 위해 --no-display 플래그가 자동 적용됩니다.
  • 리소스 위임: 스크립트가 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. 스크립트 상세 가이드​

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

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

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

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

[Step 5 준비] runtime-2_setup_assets.sh (리소스 준비) 추론 예제 실행에 필요한 의존성 파일과 샘플 데이터를 준비합니다.

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

[Step 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)을 터미널에 출력합니다.
필수 점검

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

  • 모델이 누락된 경우 추론 중 "File Not Found" 오류가 발생합니다.
  • 전체 end-to-end 과정을 검증하기 위해 런타임 스크립트를 실행하기 전에 3개 모델 모두 컴파일하는 것을 강력히 권장합니다.
Last updated: