YOLO onnx 모델 hef로 변환하기. (+라즈베리 파이 적용)

한눈에 보는 파이프라인

PT(학습 가중치) → ONNX → HAR(파서 결과) → Optimize(양자화/보정) → HEF(실행 바이너리)
이 3단계(파싱 → 최적화 → 컴파일) 흐름은 Hailo Dataflow Compiler(DFC)의 표준 빌드 과정입니다.
[참고] MMMSK:Comptuer Vision AI

사용 환경 & 전제 조건

Host(모델 빌드):

OS: Ubuntu 20.04/22.04 x86_64. Windows는 WSL2의 Ubuntu로 지원. 메모리 16GB+(권장 32GB+), Python 3.8/3.9/3.10. RidgeRun Developer Wiki
권장 설치 방식: Hailo가 분기별로 정합성을 맞춰 배포하는 Hailo AI Software Suite(Self‑extractable 또는 Docker). 버전 호환성을 위해 Suite 단위 설치 권장. RidgeRun.ai
본 글 시나리오: Suite 2025‑10 Docker 사용(예: DFC 3.33, HailoRT 4.23.0 조합). RidgeRun.ai

On‑device(실행, 예: Raspberry Pi 5 + Hailo‑8/8L):

sudo apt install hailo-all로 HailoRT/도구 설치 가능(라즈베리파이 측). 실제 실행은 on‑device에서 수행. 런타임(HailoRT)과 Host의 DFC 버전 호환이 중요합니다. 예: RT 4.17 ↔ DFC 3.27, RT 4.18 ↔ DFC 3.28 등. 불일치 시 HEF 파싱 오류가 납니다. Hailo Community

원문 예시 기준: On‑device의 HailoRT 4.23.0, Host는 Docker‑Suite(2025‑10)로 작업합니다.

0) 준비 요약

학습 결과 best_s.pt(YOLOv11-m) 보유.

1) PT → ONNX 내보내기 (Ultralytics)

from ultralytics import YOLO
model = YOLO("./runs/detect/train/weights/best_s.pt")
model.export(format="onnx")   # best_s.onnx 생성

Ultralytics는 export API로 손쉽게 ONNX를 생성합니다(※ YOLO 버전에 따라 문법이 소폭 다를 수 있음). Ultralytics Docs

2) ONNX → HEF (Host의 Docker 컨테이너에서 수행)

2‑1. WSL2 & Docker 준비

Windows라면 WSL2 Ubuntu 22.04 설치(DFC는 네이티브 Windows 미지원, WSL2 경유).
Docker Desktop(+WSL 통합) 설치 후 동작 확인.
Hailo Developer Zone에서 Hailo AI Software Suite – Docker (예: 2025‑10) 패키지 다운로드. RidgeRun.ai

2‑2. Suite Docker 컨테이너 실행

압축 해제 후 제공 스크립트로 컨테이너 진입:

unzip hailo_ai_sw_suite_2025-10_docker.zip
./hailo_ai_sw_suite_docker_run.sh         # 컨테이너 진입
./hailo_ai_sw_suite_docker_run.sh --help  # 도움말

(버전/스크립트 명은 내려받은 파일명에 맞춰 조정) JwAhn_Embedded

버전 정합성 체크: 컨테이너 내부에서 hailo -h로 DFC/HailoRT 버전을 확인해 on‑device와 호환되는지 봅니다. Suite 2025‑10은 드라이버 4.23.0과 매칭됩니다. RidgeRun.ai

2‑3. ONNX 파일을 컨테이너로 복사

Host 셸(컨테이너 밖)에서:

docker cp /home/lim/best_s.onnx \
  hailo_ai_sw_suite_2025-01_container:/local/workspace

스크립트별 공유 경로가 다를 수 있습니다. 원문 예시는 /local/workspace를 사용합니다(일부 배포본은 /local/shared_with_docker). 컨테이너에서 pwd나 ls /local로 확인 가능.

2‑4. Parse: ONNX → HAR 변환

컨테이너 내부에서(작업 디렉터리로 이동 후):

hailomz parse --hw-arch hailo8l --ckpt ./best_s.onnx yolov11m
# 결과: yolov11m.har

yolov11m는 Model Zoo가 아키텍처별 설정을 알고 있는 네트워크 별칭입니다.
이 단계에서 ONNX가 Hailo 내부 표현(HAR)으로 번역됩니다.

2‑5. Optimize: 양자화/보정

hailomz optimize --hw-arch hailo8l --har ./yolov11m.har yolov11m \
  --calib-path ./train/images --classes 1

--calib-path: 보정(통계 수집) 이미지 폴더 또는 TFRecord 경로. (학습 시킬 때 썼던 전처리 완료 된 이미지들을 넣어줌)
권장 수량: 기본 통계 수집은 약 64장으로 충분. 더 진보된 PQ(Post‑Quantization) 알고리즘은 1024장+ 권장.
--classes: 실제 클래스 개수(예시 1).

2‑6. Compile: HAR → HEF 생성

hailomz compile yolov11m --hw-arch hailo8l --har ./yolov11m.har
# 결과: yolov11m.hef

Model Zoo 툴체인(hailomz)은 내부적으로 DFC의 파싱→최적화→컴파일을 포괄합니다(단일 명령으로도 수행 가능). Hailo Community

2‑7. HEF 내용 확인

# HailoRT CLI 권장 명령
hailortcli parse-hef yolov11m.hef

parse‑hef는 입력/출력 형식, 컨텍스트 구조 등 HEF 메타 정보를 출력합니다.

(hailo_virtualenv) hailo@docker-desktop:/local/workspace$ hailo parse-hef yolov11m.hef
[info] No GPU chosen and no suitable GPU found, falling back to CPU.
[info] Current Time: 17:46:17, 10/15/25
[info] CPU: Architecture: x86_64, Model: 13th Gen Intel(R) Core(TM) i9-13980HX, Number Of Cores: 32, Utilization: 0.1%
[info] Memory: Total: 31GB, Available: 29GB
[info] System info: OS: Linux, Kernel: 6.6.87.2-microsoft-standard-WSL2
[info] Hailo DFC Version: 3.33.0
[info] HailoRT Version: 4.23.0
[info] PCIe: No Hailo PCIe device was found
[info] Running `hailo parse-hef yolov11m.hef`
(hailo) Running command 'parse-hef' with 'hailortcli'
Architecture HEF was compiled for: HAILO8L
Network group name: yolov11m, Multi Context - Number of contexts: 6
    Network name: yolov11m/yolov11m
        VStream infos:
            Input  yolov11m/input_layer1 UINT8, NHWC(640x640x3)
            Output yolov11m/yolov8_nms_postprocess FLOAT32, HAILO NMS BY CLASS(number of classes: 1, maximum bounding boxes per class: 100, maximum frame size: 2004)
            Operation:
                Op YOLOV8
                Name: YOLOV8-Post-Process
                Score threshold: 0.200
                IoU threshold: 0.70
                Classes: 1
                Max bboxes per class: 100
                Image height: 640
                Image width: 640

2‑8. HEF를 Host로 복사

Host 셸에서:

docker cp hailo_ai_sw_suite_2025-10_container:/local/workspace/yolov11m.hef \
  /home/lim/

(경로는 환경에 맞게 조정)

3) On‑device에서 실행(요약)

라즈베리파이(또는 대상 장치)에 HEF를 옮긴 뒤 HailoRT CLI로 빠르게 동작 확인:

hailortcli run yolov11m.hef         # 기본 실행
hailortcli run yolov11m.hef --measure-latency  # 지연 측정
hailortcli run yolov11m.hef --measure-power    # 전력 측정(지원 플랫폼)

HailoRT는 HEF를 장치에 로드해 추론을 수행합니다. 빠른 검증에 유용합니다. Macnica

에러 노트 & 베스트 프랙티스

버전 호환(아주 중요!)
HEF 파싱/실행 오류의 다수는 DFC ↔ HailoRT 버전 불일치에서 발생합니다. 예시로 HailoRT 4.17 ↔ DFC 3.27, HailoRT 4.18 ↔ DFC 3.28이 짝을 이룹니다. Suite 단위로 맞추고, on‑device의 HailoRT도 호환 버전으로 정렬하세요. Hailo Community
Docker를 쓰는 이유
호스트에 DFC/Model Zoo/TAPPAS를 개별 설치하면 의존성(예: numpy) 충돌이 잦습니다. Hailo AI Software Suite Docker는 패키지 충돌을 피하고 동일한 환경을 보장합니다. (원문 삽질 기록 + Suite 권장)
WSL2 필요성
DFC는 Windows 네이티브를 지원하지 않고 WSL2의 Ubuntu를 통해 사용합니다(지원 사양에 명시).
보정 데이터(calib)
실제 추론 분포를 잘 반영한 이미지가 좋습니다. 통계 수집은 64장 정도로 시작하고, 정밀 튜닝 시 1024장+도 고려하세요. Hailo Community
Model Zoo 별칭 활용
yolov11m처럼 네트워크 별칭을 쓰면 Model Zoo의 사전 구성(YAML 등)을 이용해 인자 수를 줄일 수 있습니다. GitHub

핵심 명령 모음

# 1) YOLO → ONNX (Host 어디서나)
from ultralytics import YOLO
YOLO("./runs/detect/train/weights/best_s.pt").export(format="onnx")

# 2) 컨테이너 진입 (예: 2025-10)
./hailo_ai_sw_suite_docker_run.sh

# 3) Host→Container 복사(Host 셸)
docker cp /home/lim/best_s.onnx \
  hailo_ai_sw_suite_2025-10_container:/local/workspace

# 4) Parse (컨테이너)
hailomz parse --hw-arch hailo8l --ckpt ./best_s.onnx yolov11m

# 5) Optimize (컨테이너)
hailomz optimize --hw-arch hailo8l --har ./yolov11m.har yolov11m \
  --calib-path ./train/images --classes 1

# 6) Compile (컨테이너)
hailomz compile yolov11m --hw-arch hailo8l --har ./yolov11m.har

# 7) HEF 점검 (컨테이너)
hailortcli parse-hef yolov11m.hef

# 8) Container→Host 복사(Host 셸)
docker cp hailo_ai_sw_suite_2025-10_container:/local/workspace/yolov11m.hef \
  /home/lim/

'AI' 카테고리의 다른 글

hailotracker (0)	2025.10.16
deep-text-recognition-benchmark 모델 ONNX 변환 (0)	2024.12.24
[논문 리뷰] BPE Tokenizer (1)	2024.02.04
KLUE (0)	2024.02.02
[논문 리뷰]attention 매커니즘 (0)	2024.01.31

춤추는 고래의 알고리즘 어드벤처!

YOLO onnx 모델 hef로 변환하기. (+라즈베리 파이 적용)

한눈에 보는 파이프라인

사용 환경 & 전제 조건

0) 준비 요약

1) PT → ONNX 내보내기 (Ultralytics)

2) ONNX → HEF (Host의 Docker 컨테이너에서 수행)

2‑1. WSL2 & Docker 준비

2‑2. Suite Docker 컨테이너 실행

2‑3. ONNX 파일을 컨테이너로 복사

2‑4. Parse: ONNX → HAR 변환

2‑5. Optimize: 양자화/보정

2‑6. Compile: HAR → HEF 생성

2‑7. HEF 내용 확인

2‑8. HEF를 Host로 복사

3) On‑device에서 실행(요약)

에러 노트 & 베스트 프랙티스

핵심 명령 모음

'AI' 카테고리의 다른 글

티스토리툴바

YOLO onnx 모델 hef로 변환하기. (+라즈베리 파이 적용)

한눈에 보는 파이프라인

사용 환경 & 전제 조건

0) 준비 요약

1) PT → ONNX 내보내기 (Ultralytics)

2) ONNX → HEF (Host의 Docker 컨테이너에서 수행)

2‑1. WSL2 & Docker 준비

2‑2. Suite Docker 컨테이너 실행

2‑3. ONNX 파일을 컨테이너로 복사

2‑4. Parse: ONNX → HAR 변환

2‑5. Optimize: 양자화/보정

2‑6. Compile: HAR → HEF 생성

2‑7. HEF 내용 확인

2‑8. HEF를 Host로 복사

3) On‑device에서 실행(요약)

에러 노트 & 베스트 프랙티스

핵심 명령 모음

'AI' 카테고리의 다른 글

관련글

티스토리툴바