Mini Pi Guide

Appearance

YOLO AI 이용해서 물체 인식하기 ​

Rockchip NPU(RK3588, RK3568 등)가 탑재된 보드(Orange Pi 5, Radxa Rock 5 등)에서 RKNN-Toolkit-Lite를 사용하여 YOLO를 구동하는 방법을 알아봅시다.

이 과정은 크게 PC에서의 모델 변환과 보드에서의 추론(Inference) 두 단계로 나뉩니다. RKNN-Lite는 오직 '추론'만 담당하므로, 모델 변환은 반드시 PC에서 해야 합니다.

기본 개념 이해 ​

Rockchip NPU를 사용하기 위해서는 일반적인 딥러닝 모델(.pt, .onnx)을 NPU가 이해할 수 있는 포맷(.rknn)으로 변경해야 합니다.

  • PC (x86 리눅스/우분투): rknn-toolkit2 사용. 모델 변환 담당.
  • 보드 (ARM 리눅스): rknn-toolkit-lite2 사용. 실제 실행(Inference) 담당.

주의

최신 칩셋(RK3588/RK3568/RK3566)은 Lite2를 사용하고, 구형 칩셋(RK3399Pro 등)은 Lite를 사용합니다.

여기서는 가장 대중적인 RK3588(Orange Pi 5 등) 기준으로 Lite2를 설명합니다.

준비물 ​

  1. 개발용 PC: Ubuntu 20.04 또는 22.04 권장 (모델 변환용)
  2. 타겟 보드: RK3588/RK356x 기반 보드 (예: Orange Pi 5)
  3. YOLO 모델: YOLOv5 또는 YOLOv8 (ONNX 포맷 권장)

Step 1: PC에서 모델 변환 (PT/ONNX → RKNN) ​

이 단계는 PC에서 수행합니다. 보드에서는 성능 문제로 변환이 불가능하거나 매우 어렵습니다.

  1. RKNN-Toolkit2 설치 (PC) Rockchip의 공식 GitHub에서 툴킷을 다운로드하고 설치합니다. (Docker 사용 권장)

    bash
    git clone https://github.com/ai-rockchip/rknn-toolkit2.git
cd rknn-toolkit2
# doc 폴더의 가이드를 따라 pip install 진행

  2. YOLO 모델 변환 코드 작성 (convert.py)

    rknn.config와 rknn.build를 사용하여 ONNX를 RKNN으로 바꿉니다.

    핵심 설정 (YOLOv5/v8 기준):

    • target_platform: "rk3588"
    • quantize: True (속도를 위해 보통 i8 양자화 사용)

    팁

    초보자라면 직접 변환하기보다 Rockchip Model Zoo에서 이미 변환된 YOLO 데모 모델(yolov5s.rknn 등)을 다운로드하여 보드에서 먼저 돌려보는 것을 강력 추천합니다.

Step 2: 보드 환경 설정 ​

이제 보드(Orange Pi 5 등) 터미널에서의 작업입니다.

  1. 시스템 업데이트 및 필수 라이브러리 설치

    bash
    sudo apt-get update
sudo apt-get install python3-pip python3-dev cmake gcc

  2. RKNN-Toolkit-Lite2 다운로드

    bash
    git clone https://github.com/ai-rockchip/rknn-toolkit-lite2.git

  3. 라이브러리 설치 (pip) 자신의 파이썬 버전(3.8, 3.9, 3.10 등)에 맞는 whl 파일을 찾아 설치합니다.

    bash
    cd rknn-toolkit-lite2/packages
# 예: 파이썬 3.8인 경우
pip3 install rknn_toolkit_lite2-x.x.x-cp38-cp38-linux_aarch64.whl

  4. 설치 확인

    bash
    python3 -c "from rknnlite.api import RKNNLite; print('Success')"

    에러 없이 Success가 뜨면 성공입니다.

Step 3: 파이썬 추론 코드 작성 (실전) ​

보드에서 실행할 inference.py를 작성합니다. YOLO의 경우 전처리(Resize)와 후처리(NMS) 과정이 코드에 포함되어야 합니다.

아래는 RKNNLite 사용법의 핵심 뼈대입니다.

python
import cv2
import numpy as np
from rknnlite.api import RKNNLite

# 1. 설정
RKNN_MODEL = 'yolov5s.rknn' # PC에서 변환해온 파일
IMG_PATH = 'test.jpg'

# 2. RKNNLite 초기화
rknn_lite = RKNNLite()

# 모델 로드
ret = rknn_lite.load_rknn(RKNN_MODEL)
if ret != 0:
    print('Load RKNN model failed')
    exit(ret)

# 런타임 초기화 (NPU 코어 지정)
ret = rknn_lite.init_runtime(core_mask=RKNNLite.NPU_CORE_0)
if ret != 0:
    print('Init runtime failed')
    exit(ret)

# 3. 이미지 전처리 (YOLO 모델 입력 사이즈에 맞게)
# 보통 640x640, RGB 변환이 필요함
src_img = cv2.imread(IMG_PATH)
img = cv2.cvtColor(src_img, cv2.COLOR_BGR2RGB)
img = cv2.resize(img, (640, 640))
img = np.expand_dims(img, 0) # (1, 640, 640, 3) 형태로 변경

# 4. 추론 (Inference)
outputs = rknn_lite.inference(inputs=[img])

# 5. 후처리 (Post-Processing)
# outputs에는 YOLO의 Raw 데이터(박스 좌표, 클래스 점수 등)가 들어있습니다.
# 여기에 NMS(Non-Maximum Suppression) 알고리즘을 적용해야 최종 박스가 나옵니다.
# (후처리 코드는 길기 때문에 rknn_model_zoo의 utils를 주로 import해서 사용합니다)

print("Inference Done. Output shape:", outputs[0].shape)

# 리소스 해제
rknn_lite.release()

추천 학습 루트 (지름길) ​

처음부터 모든 코드를 짜는 것은 매우 어렵습니다. Rockchip에서 제공하는 Model Zoo 예제를 실행해보는 것이 가장 빠릅니다.

  1. 보드에서 rknn_model_zoo를 클론합니다.
    bash
    git clone https://github.com/ai-rockchip/rknn_model_zoo.git
  2. examples/yolov5 폴더로 이동합니다.
  3. 그 안에 있는 python 데모 코드를 실행합니다.
    • 이 예제 코드 안에는 복잡한 전처리/후처리(NMS, 좌표 변환) 로직이 이미 구현되어 있습니다.
    • 이 코드를 분석하여 본인의 프로젝트에 맞게 수정하는 것이 '교과서적'인 학습 방법입니다.