Hailo NPU 학습 내용 정리 2

좋습니다. 이번에는 라즈베리파이에서 Hailo API를 사용하는 방법을 단계별로, 아주 쉽게 설명해드릴게요. 여기서 말하는 Hailo API는 HailoRT Python/C++ 라이브러리입니다. 주로 Python을 중심으로 설명하되, 핵심 흐름을 이해하기 쉽게 구성하겠습니다.

---

✅ 1. 기본 개념 정리

💡 Hailo API란?

Hailo API는 라즈베리파이와 Hailo-8 NPU 간의 AI 추론 제어를 위한 인터페이스입니다.
우리가 .hef 모델을 실행시키고, 이미지나 영상을 넣고, 결과를 받아보는 모든 과정을 담당합니다.

---

✅ 2. 사전 준비

📦 설치할 것들:

1. HailoRT SDK (공식 웹사이트에서 제공)
2. Python 3.7+
3. 필수 의존성 패키지

sudo apt update
sudo apt install -y libusb-1.0-0-dev cmake python3-pip
pip3 install numpy opencv-python

---

✅ 3. 기본 구조 이해

Hailo Python API는 크게 세 가지 단계를 거칩니다.

단계	내용	사용 예
1️⃣ 모델 로딩	.hef 파일을 불러옴	HEF("model.hef")
2️⃣ 추론 준비	NPU에 모델 올리고 스트림 설정	VDevice, VStreams 생성
3️⃣ 데이터 입출력	이미지 → 입력, 결과 ← 출력	send(), recv() 사용

---

✅ 4. 기본 코드 예제 (이미지 추론)

🔹 코드 흐름 설명:

# 1. 모듈 임포트
from hailo_platform import HEF, VDevice, InputVStreamParams, OutputVStreamParams
import numpy as np
import cv2

# 2. 모델 불러오기 (.hef 파일)
hef = HEF("yolov5.hef")  # 이미 컴파일된 모델

# 3. Hailo-8 디바이스 초기화
device = VDevice()
network_group = device.create_hef(hef)

# 4. 입출력 스트림 설정
input_vstreams = network_group.create_input_vstream(InputVStreamParams())
output_vstreams = network_group.create_output_vstream(OutputVStreamParams())

# 5. 이미지 불러오기 및 전처리
image = cv2.imread("cat.jpg")
resized = cv2.resize(image, (640, 640)).astype(np.uint8)
input_data = [resized]

# 6. 추론 실행
input_vstreams[0].send(input_data)
results = output_vstreams[0].recv()

# 7. 결과 출력
print("추론 결과:", results)

---

✅ 5. 주요 API 설명

API 이름	역할
HEF(path)	.hef 모델 파일 로드
VDevice()	NPU와 통신하는 가상 디바이스 생성
.create_hef()	모델을 NPU에 올려서 실행 준비
.create_input_vstream()	입력 스트림 설정 (예: 이미지 넣기)
.create_output_vstream()	출력 스트림 설정 (예: 결과 받기)
.send(data)	이미지 데이터 전송
.recv()	추론 결과 수신

---

✅ 6. 라즈베리파이에서 실시간 카메라 추론 예시

cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret:
        continue

    resized = cv2.resize(frame, (640, 640)).astype(np.uint8)
    input_vstreams[0].send([resized])
    results = output_vstreams[0].recv()

    # (예시) 결과가 박스일 경우 시각화
    for box in results:
        x, y, w, h = box['bbox']
        cv2.rectangle(frame, (x, y), (x+w, y+h), (0,255,0), 2)

    cv2.imshow("Hailo Inference", frame)
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

---

✅ 정리: 핵심 흐름 요약

.HEF 모델 로드
    ↓
NPU 디바이스 연결
    ↓
입출력 스트림 구성
    ↓
데이터 전송 (send)
    ↓
추론 결과 수신 (recv)

---

✅ 참고 팁

• .hef 파일은 TappAS에서 ONNX/TFLite 모델을 변환해서 만듭니다.
• Python API는 빠르게 프로토타이핑할 때 좋고,
  성능이 중요하면 C++ API 사용 권장
• HailoRT는 멀티 스트림 처리도 지원 (비동기 가능)

---

Q1: Hailo Python API에서 입력 이미지 전처리는 어떤 방식으로 최적화할 수 있나요?

Q2: 실시간 영상에서 연속 추론 시 버퍼링과 성능 저하를 막는 방법은 무엇인가요?

Q3: 여러 .hef 모델을 동시에 사용하여 멀티 태스크 추론을 수행할 수 있을까요? 가능하다면 구조는 어떻게 구성해야 하나요?

좋습니다. 이번에는 "모델을 올린다"는 개념이 실제로 어떤 의미인지, 그리고 그 모델을 생성하는 전체 과정까지 구체적으로 설명드리겠습니다. 초보자도 쉽게 이해할 수 있도록 추상 개념 → 구체 동작 → 실습 예 순으로 정리합니다.

---

✅ 1. “모델을 올린다”는 의미는?

✔ 개념적으로는:

“훈련된 AI 모델을 NPU 칩 내부로 로드해서 추론 가능한 상태로 만드는 것”

쉽게 말해,

• 우리가 만든 또는 사전 학습된 AI 모델을
• .hef라는 Hailo 전용 실행 포맷으로 변환한 뒤
• 이를 Hailo NPU 내부 메모리(SRAM)로 올려 실행 대기 상태로 만드는 과정입니다.

이걸 Hailo API에서는 아래처럼 실행하죠:

hef = HEF("model.hef")
device = VDevice()
network_group = device.create_hef(hef)  # 👉 바로 여기서 “올리는” 동작 수행

---

✅ 2. 모델 생성 전체 흐름

모델을 "올리기" 위해선 먼저 모델을 만들어야 합니다. Hailo에서는 기존 AI 프레임워크에서 만든 모델 → 최적화 → 컴파일이라는 3단계를 거칩니다.

---

🎯 전체 순서 요약:

[ Step 1 ] 모델 학습 (PyTorch, TensorFlow 등)
      ↓
[ Step 2 ] ONNX 또는 TFLite로 변환
      ↓
[ Step 3 ] TappAS로 .hef 생성 (컴파일)
      ↓
[ Step 4 ] Hailo-8 NPU에 로딩 (HailoRT)

---

✅ 3. 단계별 자세한 설명

---

🔹 Step 1: AI 모델 준비

대표적인 프레임워크:

• PyTorch: YOLOv5, ResNet, FaceNet 등
• TensorFlow / Keras: MobileNet, SSD 등

예시:

import torch
model = torch.hub.load('ultralytics/yolov5', 'yolov5s')
torch.onnx.export(model, dummy_input, "yolov5.onnx")

---

🔹 Step 2: ONNX 또는 TFLite로 변환

• Hailo TappAS는 ONNX 또는 TensorFlow Lite 모델을 입력으로 받습니다.
• 이 단계에서는 학습한 모델을 표준화된 파일 형식으로 저장합니다.

변환 예시:

# PyTorch → ONNX
python export.py --weights yolov5s.pt --img 640 --include onnx

---

🔹 Step 3: TappAS로 .hef 파일 생성 (Hailo Executable Format)

이 단계가 핵심입니다. .onnx → .hef로 컴파일하면서
양자화 (INT8), 하드웨어 매핑, 메모리 최적화 등이 함께 수행됩니다.

hailo model-compile yolov5.onnx \
  --hardware-target HAILO-8 \
  --output yolov5.hef

• .hef는 Hailo 전용 실행 포맷입니다.
• 이 안에 추론 그래프 정보, 레이어 매핑 정보, 양자화 데이터가 모두 들어 있습니다.

---

🔹 Step 4: HailoRT로 로딩 (NPU에 모델 올리기)

이제 라즈베리파이 또는 x86 시스템에서 .hef 파일을 로딩합니다:

hef = HEF("yolov5.hef")
device = VDevice()
network_group = device.create_hef(hef)  # ← 이 시점에 모델이 NPU에 “올라감”

이제부터는:

• send()로 입력 보내고
• recv()로 결과를 받을 수 있습니다.

---

✅ 그림으로 정리

┌────────────┐
│ PyTorch/TensorFlow │ ← 학습 & 저장 (.onnx, .tflite)
└────────────┘
       ↓
┌────────────┐
│ TappAS Compiler │ ← 최적화, 양자화 → .hef 생성
└────────────┘
       ↓
┌────────────┐
│ HailoRT SDK │ ← .hef 로딩 → NPU 메모리로 “모델 업로드”
└────────────┘
       ↓
▶ 실시간 추론 (send/recv)

---

✅ 추가 팁: 양자화란?

• Hailo는 고속 처리를 위해 모델을 INT8로 양자화합니다.
• 이를 통해 속도는 높이고 전력은 낮추며, 정확도 손실은 아주 미세합니다 (1~2% 미만).
• TappAS가 자동으로 양자화를 수행합니다 (Calibration 데이터셋 선택 가능).

---

✅ 요약

항목	설명
“모델을 올린다”	.hef 모델을 NPU 내부로 로드해서 실행 준비 상태로 만드는 것
모델 생성 방식	학습 → 변환(ONNX) → 컴파일(.hef) → 로딩
핵심 도구	PyTorch/TensorFlow, ONNX, TappAS, HailoRT
실행 파일	.hef (Hailo Executable Format)

---

Q1: 모델을 양자화할 때 정확도를 최대한 유지하려면 어떤 전략을 사용할 수 있나요?

Q2: .hef 파일 하나에 여러 네트워크를 포함시켜 멀티 모델 추론이 가능할까요?

Q3: 직접 만든 모델이 아닌 오픈소스 사전학습 모델을 Hailo에서 쓸 때 주의할 점은 무엇인가요?

좋습니다. 이번에는 직접 만든 모델이 아닌, 오픈소스 사전학습(pre-trained) 모델을 Hailo NPU에서 사용하는 방법을 예제 중심으로 단계별로 자세히 설명드리겠습니다.

---

✅ 1. 오픈소스 사전학습 모델이란?

사전학습 모델은 이미 대규모 데이터셋으로 학습된 모델로, 바로 가져다 쓰거나, 약간 수정(fine-tuning)해서 사용할 수 있는 모델입니다.

🔹 대표적인 사전학습 모델 예시

모델	용도	프레임워크	Hailo 호환
YOLOv5	객체 탐지	PyTorch → ONNX	✅
MobileNetV2	이미지 분류	TensorFlow / TFLite	✅
EfficientDet	객체 탐지	TensorFlow	✅
ResNet50	이미지 분류	ONNX	✅
DeepLabv3+	이미지 세그멘테이션	TensorFlow	✅

Hailo는 ONNX, TFLite, TensorFlow SavedModel 형식의 모델을 TappAS로 컴파일할 수 있습니다.

---

✅ 2. Hailo에서 사전학습 모델 사용하는 전체 흐름

🔁 요약된 4단계 흐름

1. 사전학습 모델 다운로드
2. 호환 가능한 포맷으로 변환 (ONNX or TFLite)
3. TappAS로 .hef 생성
4. HailoRT로 추론 실행

---

✅ 3. 단계별 설명 및 예제

---

✅ Step 1: 사전학습 모델 다운로드

예시: YOLOv5s

git clone https://github.com/ultralytics/yolov5
cd yolov5
pip install -r requirements.txt

# 사전학습된 모델 다운로드
python export.py --weights yolov5s.pt --include onnx --img 640

결과: yolov5s.onnx 생성

---

✅ Step 2: TappAS로 .hef 생성

TappAS를 사용해 .onnx → .hef로 변환합니다.
이 과정에서 양자화 (INT8) 및 하드웨어 최적화가 이루어집니다.

hailo model-compile yolov5s.onnx \
  --output yolov5s.hef \
  --hardware-target HAILO-8 \
  --calibration hailo_calib.yaml

TIP: hailo_calib.yaml에는 양자화를 위한 샘플 이미지 폴더 경로를 명시합니다.

예시 내용:

calibration:
  type: image
  path: ./calib_images/
  preprocessing:
    resize: [640, 640]

---

✅ Step 3: 라즈베리파이로 .hef 파일 복사

scp yolov5s.hef pi@raspberrypi.local:/home/pi/

---

✅ Step 4: HailoRT Python 코드로 실행

from hailo_platform import HEF, VDevice, InputVStreamParams, OutputVStreamParams
import cv2, numpy as np

hef = HEF("yolov5s.hef")
device = VDevice()
ng = device.create_hef(hef)
inputs = ng.create_input_vstream(InputVStreamParams())
outputs = ng.create_output_vstream(OutputVStreamParams())

img = cv2.imread("test.jpg")
img_resized = cv2.resize(img, (640, 640)).astype(np.uint8)
inputs[0].send([img_resized])
result = outputs[0].recv()

print("추론 결과:", result)

---

✅ 4. 모델 포맷별 주의사항

포맷	주의사항
ONNX	동적 입력 크기 사용하지 말 것 (fixed input shape 필요)
TFLite	Quantized 모델 추천 (INT8)
TensorFlow SavedModel	불필요한 서브그래프 제거 필요
PyTorch	반드시 export.py 등으로 ONNX 변환 후 사용

---

✅ 5. 이미 준비된 Hailo Model Zoo 활용 (추천)

Hailo는 이미 최적화된 사전학습 모델을 직접 제공합니다.

• Hailo Model Zoo GitHub
• YOLOv5, SSD-MobileNet, ResNet50 등 지원
• .hef, .onnx, .yaml, 추론 예제 코드까지 포함

git clone https://github.com/hailo-ai/hailo_model_zoo
cd hailo_model_zoo
python hailomz.py download --model-name yolov5s

→ 이미 준비된 .hef 모델, Python 코드, 설정 파일이 포함됨

---

✅ 요약 정리

단계	설명
1. 모델 선택	PyTorch, TensorFlow 등 오픈소스 사전학습 모델 사용
2. 변환	ONNX, TFLite 등으로 변환 (고정 입력 사이즈)
3. 컴파일	TappAS로 .hef 생성 (양자화 포함)
4. 실행	HailoRT Python API로 추론 수행

---

Q1: 사전학습 모델의 ONNX 구조가 복잡하거나 커질 경우, Hailo 컴파일 시 어떤 최적화 전략을 적용할 수 있을까요?

Q2: Hailo Model Zoo에서 제공되는 모델을 직접 재학습하거나 수정할 수 있는 방법은 무엇인가요?

Q3: 사전학습 모델을 사용할 때 양자화 정확도 저하를 줄이기 위한 Calibration 데이터셋 구성 전략은 어떻게 설계하는 게 좋을까요?