[Project] Qualcomm Ai Hub에서 YOLOv11-Detection-Quantized 모델 컴파일 해보기

Qualcomm AI Hub 모델 설치 및 사용 가이드

1. Python 패키지 설치

AI Hub 모델 패키지는 pip를 통해 설치할 수 있습니다.

pip install qai_hub_models

• 주의: Snapdragon X Elite 사용자에 한해 Windows에서 64비트 AMDx64 Python만 지원됩니다. Windows ARM64 Python을 사용할 경우 설치가 실패합니다.
• 추가 의존성: 일부 모델(예: YOLOv11)은 추가 의존성을 필요로 합니다. YOLOv11 모델을 설치하려면 아래와 같이 입력합니다.

pip install "qai_hub_models[yolov11-det]"

2. AI Hub 접근 설정

모델 컴파일, 디바이스에서의 프로파일링 등 많은 AI Hub 기능을 사용하려면 Qualcomm® AI Hub에 대한 접근 권한이 필요합니다.

1. Qualcomm® ID 생성: 먼저 Qualcomm® ID를 생성하고, 이를 통해 Qualcomm® AI Hub에 로그인합니다.
2. API 토큰 설정: 아래 명령어로 API 토큰을 설정합니다.

qai-hub configure --api_token API_TOKEN

3. 모델 내보내기 및 실행

AI Hub에서 모델을 컴파일하고 실행할 수 있습니다. 예를 들어, YOLOv11 모델을 컴파일하고 실행하는 과정은 다음과 같습니다.

 

YOLOv11 모델 설치:

pip install "qai_hub_models[yolov11-det]"

 

모델 내보내기 및 실행:

python -m qai_hub_models.models.yolov7.export [--target-runtime ...] [--device ...] [--help]

• 선택한 디바이스 및 런타임을 위한 모델 컴파일
• 모델 양자화 (필요한 경우)
• 실제 디바이스에서 모델 프로파일링
• 디바이스에서 실행하여 모델 출력과 PyTorch 출력을 비교
• 컴파일된 모델을 디스크에 다운로드

⚙️ 참고: 주요 옵션 설명

옵션

--target-runtime	출력할 런타임 형식	--target-runtime tflite
--quantize	양자화 방식 지정 (w8a8 가능)	--quantize w8a8
--precision	float 또는 w8a8 중 하나	--precision float
--batch-size	배치 크기	--batch-size 1
--height	입력 이미지 높이	--height 640
--width	입력 이미지 너비	--width 640
--output-dir	내보낸 모델 저장 경로	--output-dir C:\경로\폴더
--ckpt-name	사용할 체크포인트 이름	--ckpt-name yolov11
--device	디바이스 명시	--device sdxelite (선택)
--chipset	칩셋 명시 (비워도 가능)	--chipset
--device-os	디바이스 OS	--device-os android

4. End-To-End 모델 데모

모델을 실제로 실행하는 데모를 제공하며, 모든 모델은 CLI를 통해 데모를 실행할 수 있습니다. YOLOv11 모델의 예는 아래와 같습니다.

pip install "qai_hub_models[yolov11-det]" python -m qai_hub_models.models.yolov11.demo [--image ...] [--on-device] [--help]

 

데모는 다음과 같은 과정을 포함합니다:

• 모델 입력 데이터를 사람이 이해할 수 있는 형태로 전처리
• 모델 추론 실행
• 모델 출력 데이터를 사람이 이해할 수 있는 형태로 후처리

옵션:

• --on-device: AI Hub에서 실제 디바이스를 사용하여 모델을 실행
• 로컬에서 PyTorch를 통해 실행 가능

5. 샘플 애플리케이션

AI Hub Apps 리포지토리에서 모델을 실행하는 네이티브 애플리케이션을 제공하며, 이는 Pre-processing, Inference, Post-processing을 포함합니다.

• 각 모델은 Python 애플리케이션으로 정의되며, torch와 numpy를 사용하여 모델 추론을 포함한 전체 파이프라인을 작성합니다.
• 애플리케이션은 모델을 쉽게 따라할 수 있도록 최적화되어 있습니다.

from qai_hub_models.models.<model_name> import App

 

https://github.com/quic/ai-hub-models/tree/main/qai_hub_models/models/yolov11_det

ai-hub-models/qai_hub_models/models/yolov11_det at main · quic/ai-hub-models

 

먼저 문서에는 이렇게 간단하게 나와 있지만 과정이 굉장히 어렵다.

우선 아나콘다 가상환경에서 시작하였다. ( Python 3.11.9 )

 

우선 qai_hub_models와 사용할 모델을 인스톨 한다.

pip install qai_hub_models
pip install "qai_hub_models[yolov11-det]"

 

인스톨 과정에서 첫 오류가 발생했다.

ERROR: Could not install packages due to an OSError: [WinError 206] : 파일 이름이나 확장명이 너무 깁니다

 

Windows에서는 파일 경로가 보통 260자 이하로 제한되는데, 가상환경이며 python 패키지며 Cache 이며 경로가 점점 길어지다 보니 onnx 패키지 내의 어떤 파일 경로가 너무 길어서 발생한 문제이다.

 

▶ 방법:

1. 시작 버튼 → gpedit.msc 입력 → Enter
   (또는 '로컬 그룹 정책 편집기' 실행)
2. 왼쪽 메뉴에서 아래 경로로 이동:
3. 컴퓨터 구성 > 관리 템플릿 > 시스템 > 파일 시스템
4. 오른쪽에서 Win32 긴 경로 사용 더블클릭
5. "사용" 으로 변경 → 확인 → 재부팅

 

 

그 다음 모델을 모바일 장치에서 사용할 예정이기 때문에 export를 해주어야 하는데

python -m qai_hub_models.models.yolov11_det.export

 

이렇게 CLI에 입력하면 

export.py [-h] [--num-calibration-samples NUM_CALIBRATION_SAMPLES] [--target-runtime {precompiled-qnn-onnx,onnx,tflite,qnn}] [--compile-options COMPILE_OPTIONS] [--profile-options PROFILE_OPTIONS] [--ckpt-name CKPT_NAME] [--no-include-postprocessing] [--split-output] [--batch-size BATCH_SIZE] [--height HEIGHT] [--width WIDTH] [--precision {w8a8,float} | --quantize [{w8a8}]] [--device DEVICE | --chipset {}] [--device-os DEVICE_OS] [--skip-compiling] [--skip-profiling] [--skip-inferencing] [--skip-downloading] [--skip-summary] [--output-dir OUTPUT_DIR] export.py: 오류: 인식할 수 없는 인수: { } 이런식으로 오류를 뱉는데 이건 아주 친절한 편이다.

 

정리해 보자면 export를 하려면 다음과 같은 옵션을 넣어 주어야 한다.

옵션 

--target-runtime	출력할 런타임 형식	--target-runtime tflite
--quantize	양자화 방식 지정 (w8a8 가능)	--quantize w8a8
--precision	float 또는 w8a8 중 하나	--precision float
--batch-size	배치 크기	--batch-size 1
--height	입력 이미지 높이	--height 640
--width	입력 이미지 너비	--width 640
--output-dir	내보낸 모델 저장 경로	--output-dir C:\경로\폴더
--ckpt-name	사용할 체크포인트 이름	--ckpt-name yolov11
--device	디바이스 명시	--device sdxelite(선택)
--chipset	칩셋 명시 (비워도 가능)	--chipset
--device-os	디바이스 OS	--device-os android

 

양자화된(w8a8) yolov11_det 모델을 Snapdragon 8 Elite QRD이 장착된 Glaxy s25에서 돌리기 위해 다음과 같이 다시 프롬프트를 작성하였다.

python -m qai_hub_models.models.yolov11_det.export ^
  --target-runtime tflite ^
  --quantize w8a8 ^
  --height 640 ^
  --width 640 ^
  --batch-size 1 ^
  --device "Snapdragon 8 Elite QRD" ^
  --device-os android ^
  --output-dir C:\Users\EliteBook\yolo11_tflite

 

그러면 이번에는 

 

Unable to find a valid API token for Qualcomm® AI Hub. Using results from a previous job run on the same device. To get access to the complete experience, please sign-up for access at https://aihub.qualcomm.com. 

 

이런 오류가 발생하는데 퀄컴 AI 허브에 로그인하여 토큰을 등록 하라는 것

qai-hub configure --api_token 토큰

 

이렇게 토큰을 넣어주면 이번에는

'qai-hub'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다.

 

이런 오류가 발생하는데 pip install을 하였어도 환경 변수가 등록되지 않기 때문에 직접 환경변수에 들어가서 환경 변수를 편집하여 주어야한다.

 

자신이 pip install을 통해 qai-hub가 인스톨된 위치를 확인하고

 

환경 변수 수정 (Windows)

1. 시작 버튼을 클릭하고, "환경 변수"를 검색한 뒤 "시스템 환경 변수 편집"을 선택합니다.
2. 시스템 속성 창에서 "환경 변수(N)..." 버튼을 클릭합니다.
3. 사용자 변수 또는 시스템 변수 목록에서 Path를 찾아 선택한 후 편집을 클릭합니다.
4. 새로 만들기 버튼을 클릭한 뒤, 위에서 찾은 경로를 입력 필자는 다음 주소였음C:\Users\Users\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.11_qbz5n2kfra8p0\LocalCache\local-packages\Python311\Scripts를 입력합니다.
5. 확인을 눌러 모든 창을 닫습니다.

그렇게 다시 토큰을 넣어주면 이번에는

UnicodeDecodeError: 'cp949' codec can't decode byte 0xf0 in position 19: illegal multibyte sequence

 

인코딩 문제가 발생한다. 우리가 import한 qai_hub_models\utils\asset_loaders.py에서 발생한 문제인데, 필자의 컴퓨터에서만 이런 현상이 발생하는지 모르겠지만 파일 인코딩 문제 때문에 발생한 것이라고 한다.

 

UnicodeDecodeError: 'cp949' codec can't decode byte 메시지는 Python이 파일을 열 때, 해당 파일을 cp949 (한국어 윈도우 기본 인코딩)로 읽으려 했는데, 파일이 다른 인코딩으로 되어 있어 발생한 문제이다.

 

오류가 발생한  ai_hub_models\utils\asset_loaders.py에 find_replace_in_repo 함수를 찾아서 인코딩 방식을 명시하여 직접 수정하였다.

 

그렇게 수정후 다시 커맨드를 입력하면 

<module>
    from .head import OBB, Classify, Detect, Pose, RTDETRDecoder, Segment, WorldDetect, v10Detect
ImportError: cannot import name 'OBB' from 'ultralytics.nn.modules.head' (C:\Users\EliteBook\.qaihm\models\yolov11_det\v1\ultralytics_ultralytics_git\ultralytics\nn\modules\head.py)

 

이런 오류가 발생한다.

 

ultralytics\nn\modules\head.py에 OBB라는 함수가 없다는 오류인데 확인을 해보니 head.py가 비어있었다.

 

확인해보니 qai_hub 라이브러리랑 Utralytics 라이브러리가 충돌이 나는것 같아서 퀄컴 yolov11 깃허브에 있는 requirements.txt를 모두 인스톨 했는데 그래도 계속 head.py가 비어있어서 직접 Ultralytics  git hub에 있는 head.py를 복사하여 가져왔다.  

 

https://github.com/ultralytics/ultralytics/blob/main/ultralytics/nn/modules/head.py

ultralytics/ultralytics/nn/modules/head.py at main · ultralytics/ultralytics

 

여기서 또 ultralytics/nn/modules/head.py만 가져오니 Residual와 SAVPE은 모듈이 없어서 import 에러가 발생하니

from .block import DFL, BNContrastiveHead, ContrastiveHead, Proto, Residual, SwiGLUFFN, SAVPE 

=>

from .block import DFL, BNContrastiveHead, ContrastiveHead, Proto, SwiGLUFFN

 

다음과 같이 수정

 

그리고 양자화 옵션을 택하였기 때문에 YOLOv11 모델을 export 할 때, 양자화(quantization)용 calibration 데이터를 자동으로 COCO에서 다운로드 받으려고 하는데 fiftyone이라는 데이터셋 관리 툴이 없어서 오류가 발생하니 다음 라인 추가

pip install fiftyone==1.0.1

 

 

성공!

 

단계

1️⃣ 모델 선택	yolov11_det 모델 선택
2️⃣ 변환 옵션 설정	--target-runtime tflite, --quantize w8a8 등으로 설정
3️⃣ 모델 양자화 준비	모델 파일 업로드됨 (tmp5cwi_1lo.pt)
4️⃣ Calibration 필요	양자화 품질 향상을 위해 COCO 2017 데이터셋에서 이미지 5000장 자동 다운로드
5️⃣ Qualcomm AI Hub에서 Job 실행	모델 컴파일, 프로파일링, 추론 전부 자동 실행됨
6️⃣ 모델 최종 생성	yolov11_det.tflite 생성 완료 (약 2.8MB)
7️⃣ 성능 결과 확인	모델은 스냅드래곤 8 Elite QRD 장비에서 추론 1.1ms, 메모리 26MB 사용
8️⃣ 정확도 비교	로컬 vs. 디바이스 결과 비교: PSNR 37.02~37.7 → 양자화 정확도 매우 우수

 

그렇게 YOLOv11 객체 탐지 모델을 → TFLite로 양자화(8-bit 정밀도)해서 → 스냅드래곤 기기에서 동작 가능하게 최적화하여 보았다.