214 lines
5.4 KiB
Markdown
214 lines
5.4 KiB
Markdown
# 🚀 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 기준)
|
|
|
|
```bash
|
|
# 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. 프로젝트 클론 및 환경 설정
|
|
|
|
```bash
|
|
# 프로젝트 클론
|
|
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. 자동 빌드 및 실행
|
|
|
|
```bash
|
|
# 아키텍처 자동 감지하여 빌드
|
|
python3 build_linux.py
|
|
|
|
# 빌드 완료 후 실행
|
|
cd dist/AutoPercenty3_Linux_ARM/
|
|
./start.sh
|
|
```
|
|
|
|
## ⚙️ OCR 백엔드 상세 설정
|
|
|
|
### A. FastDeploy 사용 (권장 - ARM 최적화)
|
|
|
|
```bash
|
|
# FastDeploy CPU 버전 설치
|
|
pip install fastdeploy-cpu==1.0.7
|
|
|
|
# 모델 그대로 사용 (자동 감지)
|
|
# 프로그램 실행시 ARM 감지하여 자동으로 FastDeploy 사용
|
|
```
|
|
|
|
### B. ONNX Runtime 사용 (호환성 최고)
|
|
|
|
```bash
|
|
# 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 등)
|
|
|
|
```bash
|
|
# 환경 변수 최적화 (자동 적용됨)
|
|
export OMP_NUM_THREADS=4
|
|
export OPENBLAS_NUM_THREADS=4
|
|
export MKL_NUM_THREADS=4
|
|
|
|
# 메모리 최적화
|
|
export MALLOC_TRIM_THRESHOLD_=100000
|
|
```
|
|
|
|
### ARM32 (라즈베리 파이 3 등)
|
|
|
|
```bash
|
|
# 메모리 제한 환경
|
|
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 초기화 실패" 오류
|
|
|
|
```bash
|
|
# 해결책: FastDeploy CPU 버전 재설치
|
|
pip uninstall fastdeploy-gpu fastdeploy
|
|
pip install fastdeploy-cpu==1.0.7
|
|
```
|
|
|
|
### Q2: "ONNX Runtime 모델 로드 실패"
|
|
|
|
```bash
|
|
# 해결책: 모델 변환 다시 수행
|
|
python tools/convert_paddle_to_onnx.py \
|
|
--model_dir src/modules/ \
|
|
--output_dir src/modules/ \
|
|
--model_type all
|
|
```
|
|
|
|
### Q3: 메모리 부족 오류
|
|
|
|
```bash
|
|
# 해결책 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: 브라우저 실행 실패
|
|
|
|
```bash
|
|
# 해결책: 시스템 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()` 메서드에 백엔드 추가
|
|
|
|
### 커스텀 모델 사용
|
|
|
|
```python
|
|
# 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** 사용을 권장합니다!
|