AutoPercenty3/docs/ARM_PORTING_GUIDE.md

🚀 ARM 아키텍처 포팅 가이드

AutoPercenty3를 ARM 아키텍처 (Raspberry Pi, ARM 서버 등)에서 실행하는 방법

📋 지원 현황

구분	x86_64	ARM64	ARM32	상태
기본 GUI (PySide6)	✅	✅	✅	완전 지원
브라우저 자동화 (Playwright)	✅	✅	⚠️	대부분 지원
이미지 처리 (OpenCV)	✅	✅	✅	완전 지원
OCR - PaddleOCR (기본)	✅	⚠️	❌	성능 저하
OCR - FastDeploy	✅	✅	⚠️	ARM 최적화
OCR - ONNX Runtime	✅	✅	✅	권장 방식

🔧 설치 방법

1. 시스템 준비 (Ubuntu/Debian 기준)

# Python 3.11 설치
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev

# 빌드 도구 설치
sudo apt install build-essential pkg-config git

# GUI 의존성 (PySide6용)
sudo apt install qt6-base-dev libgl1-mesa-glx

# 브라우저 설치
sudo apt install chromium-browser

# ARM 최적화 라이브러리
sudo apt install libblas3 liblapack3 libopenblas-dev

2. 프로젝트 클론 및 환경 설정

# 프로젝트 클론
git clone [your-repo] AutoPercenty3_ARM
cd AutoPercenty3_ARM

# Python 가상환경 생성
python3.11 -m venv venv_arm
source venv_arm/bin/activate

# ARM용 의존성 설치
pip install -r requirements_arm.txt

3. 자동 빌드 및 실행

# 아키텍처 자동 감지하여 빌드
python3 build_linux.py

# 빌드 완료 후 실행
cd dist/AutoPercenty3_Linux_ARM/
./start.sh

⚙️ OCR 백엔드 상세 설정

A. FastDeploy 사용 (권장 - ARM 최적화)

# FastDeploy CPU 버전 설치
pip install fastdeploy-cpu==1.0.7

# 모델 그대로 사용 (자동 감지)
# 프로그램 실행시 ARM 감지하여 자동으로 FastDeploy 사용

B. ONNX Runtime 사용 (호환성 최고)

# 1. 모델 변환 (x86 시스템에서 수행)
python tools/convert_paddle_to_onnx.py \
    --model_dir src/modules/ \
    --output_dir src/modules/onnx_models/ \
    --model_type all

# 2. ONNX 모델을 ARM 시스템으로 복사
# src/modules/PP_Models/ 디렉토리에 model.onnx 파일들 배치

# 3. 자동 실행 (ONNX Runtime 백엔드 자동 선택)

C. 백엔드 우선순위

프로그램이 ARM을 감지하면 다음 순서로 OCR 백엔드를 시도합니다:

1. FastDeploy (최고 성능) → 설치된 경우 우선 사용
2. ONNX Runtime (최고 호환성) → FastDeploy 실패시 사용
3. PaddleOCR (폴백) → 다른 백엔드 모두 실패시 사용

🎯 성능 최적화

ARM64 (Raspberry Pi 4, Apple M1 등)

# 환경 변수 최적화 (자동 적용됨)
export OMP_NUM_THREADS=4
export OPENBLAS_NUM_THREADS=4
export MKL_NUM_THREADS=4

# 메모리 최적화
export MALLOC_TRIM_THRESHOLD_=100000

ARM32 (라즈베리 파이 3 등)

# 메모리 제한 환경
export OMP_NUM_THREADS=2
export OPENBLAS_NUM_THREADS=2

# 스왑 메모리 활성화 권장
sudo swapon /swapfile

📊 성능 비교

Raspberry Pi 4 (ARM64, 8GB) 기준

OCR 백엔드	초기화 시간	추론 속도	메모리 사용량
FastDeploy	~3초	0.8초/이미지	~800MB
ONNX Runtime	~2초	1.2초/이미지	~600MB
PaddleOCR	~8초	3.5초/이미지	~1.2GB

🔍 문제 해결

Q1: "FastDeploy 초기화 실패" 오류

# 해결책: FastDeploy CPU 버전 재설치
pip uninstall fastdeploy-gpu fastdeploy
pip install fastdeploy-cpu==1.0.7

Q2: "ONNX Runtime 모델 로드 실패"

# 해결책: 모델 변환 다시 수행
python tools/convert_paddle_to_onnx.py \
    --model_dir src/modules/ \
    --output_dir src/modules/ \
    --model_type all

Q3: 메모리 부족 오류

# 해결책 1: 스왑 메모리 증가
sudo fallocate -l 2G /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 해결책 2: 브라우저 메모리 제한
export CHROME_FLAGS="--memory-pressure-off --max_old_space_size=512"

Q4: 브라우저 실행 실패

# 해결책: 시스템 Chromium 설치 확인
sudo apt install chromium-browser

# 또는 권한 문제 해결
sudo chmod +x /usr/bin/chromium-browser

🚀 개발자용 고급 설정

새로운 OCR 백엔드 추가

1. src/modules/ocr_backends/ 디렉토리에 새 백엔드 클래스 생성
2. PaddleOCR과 동일한 ocr(img, det=True, rec=True, cls=True) 인터페이스 구현
3. src/modules/ocr_module.py의 _initialize_arm_ocr() 메서드에 백엔드 추가

커스텀 모델 사용

# src/modules/ocr_backends/custom_ocr.py
class CustomOCR:
    def ocr(self, img, det=True, rec=True, cls=True):
        # 커스텀 OCR 로직 구현
        results = []
        # ...
        return results  # PaddleOCR 형식: [[bbox, (text, confidence)], ...]

📈 로드맵

• OpenVINO 백엔드 추가 (Intel ARM 최적화)
• TensorRT 백엔드 추가 (NVIDIA Jetson 지원)
• Core ML 백엔드 추가 (Apple Silicon 최적화)
• 모델 양자화 지원 (INT8 추론으로 속도 향상)

🤝 기여하기

ARM 관련 개선사항이나 새로운 백엔드를 추가하고 싶으시면:

1. 이슈 등록 후 논의
2. 포크하여 개발
3. 테스트 결과와 함께 PR 제출

---

💡 팁: ARM 환경에서 최적의 성능을 위해서는 FastDeploy 사용을 권장합니다!