Offline OCR — 오프라인 이미지 텍스트 추출은(는) 무엇을 하나요?
RapidOCR + PP-OCRv6 기반의 로컬 이미지 텍스트 추출 기능으로, 완전 오프라인 실행됩니다. 중국어 및 영어를 지원하며, 인터넷 연결, API 등록 또는 GPU가 필요하지 않습니다.
사용 시기
- 사용자가 이미지 파일(스크린샷, 사진, 영수증, 스캔본, 문서 이미지, 캡차 등)을 제공하고 그림 속 텍스트를 읽어 달라고 요청할 때
- 영수증 정보 복사, 스크린샷의 코드/텍스트 인식, 표 속 텍스트 추출 등 이미지에서 텍스트 콘텐츠를 추출해야 할 때
- 현재 모델에 멀티모달 기능이 없을 때, '그림 보고 글자 읽기'의 대안으로 사용
- DeepSeek-V4 등 멀티모달 기능이 없는 대형 언어 모델과 함께 사용: 모델의 대화 인터페이스가 이미지를 '볼 수' 없을 때, 이 스킬이 먼저 이미지에서 텍스트를 추출한 후 모델이 이해하고 응답 및 처리하게 합니다.
최초 설치(한 번만 수행)
스크립트 실행에는 별도의 Python 가상 환경이 필요합니다. 이 스킬을 처음 사용할 때는 환경이 준비되었는지 먼저 확인하세요:
# <SKILL_DIR>/.venv 가 없거나 rapidocr를 가져올 수 없는 경우:
python <SKILL_DIR>/scripts/setup.py
# Intel CPU 사용자로 더 높은 성능(약 1.8배)을 원하면 OpenVINO도 함께 설치:
python <SKILL_DIR>/scripts/setup.py --with-openvino
명령어는 Windows/macOS/Linux에서 동일하게 사용 가능하며 bash가 필요하지 않습니다.
python을 찾을 수 없으면 Linux/macOS에서python3로 대체할 수 있습니다.
setup.py는 멱등적이며 여러 번 실행해도 안전합니다. 이미 설치된 경우 건너뜁니다. 제공 기능:
- Python 버전이 3.9 이상인지 확인(부족하면 각 플랫폼별 설치 안내 제공)
<SKILL_DIR>/.venv생성 및rapidocr+onnxruntime(기본) 또는 +openvino(선택) 설치- Intel CPU 감지 시 OpenVINO가 설치되지 않았으면 선택적 1.8배 가속 설치 방법 안내(자동 설치하지 않음)
<SKILL_DIR>은 이 스킬이 위치한 디렉터리를 의미합니다. 모델은 rapidocr 패키지에 내장되어(PP-OCRv6 det/rec 3단계) 추가 다운로드가 필요하지 않습니다.
최초 실행부터 사용 가능까지 전체 과정: python <SKILL_DIR>/scripts/setup.py → 자동 설치 대기(약 1-3분) → 아래 명령어로 이미지 인식 가능.
사용 방법
# 단일 이미지
python <SKILL_DIR>/scripts/ocr.py <이미지_경로>
# 여러 이미지
python <SKILL_DIR>/scripts/ocr.py <이미지1> <이미지2> ...
# 일반 매개변수
--model tiny|small|medium 모델 단계(기본 small)
--engine onnxruntime|openvino 추론 엔진(기본 onnxruntime)
--use_cls 텍스트 줄 방향 분류 활성화(회전/세로 텍스트에 유용, 약간 느림)
--save_vis 시각화 결과를 output/ 디렉터리에 저장
예시:
python <SKILL_DIR>/scripts/ocr.py /path/to/screenshot.png
python <SKILL_DIR>/scripts/ocr.py --model tiny --save_vis /path/to/invoice.jpg
python <SKILL_DIR>/scripts/ocr.py --engine openvino /path/to/photo.png
설명:
ocr.py는 자동으로.venv의 종속성을 사용하여 실행됩니다(Windows에서는.venv\Scripts\python.exe). 인터프리터 경로를 신경 쓸 필요가 없습니다.
출력 형식
스크립트는 stdout에 인식 결과를 다음 형식으로 출력합니다:
===== 파일명.png =====
총 N개의 텍스트 상자 인식:
[1] 인식된 첫 번째 줄 텍스트 (신뢰도: 0.98)
[2] 인식된 두 번째 줄 텍스트 (신뢰도: 0.95)
인식 종료 후 [순서] 뒤의 순수 텍스트 내용을 정리하여 사용자에게 반환하고, 신뢰도가 낮은 경우(예: <0.6) 경고를 함께 전달합니다.
추론 엔진 선택
| 엔진 | 크기 | 특징 |
|---|---|---|
onnxruntime(기본) | 작음 (~52M) | 플랫폼 간 일관성, 깔끔한 설치, 일반적 권장 |
openvino | 큼 (~+123M) | Intel CPU에서만 더 빠름 (약 1.8배); AMD/Apple Silicon에서는 이점 없음 |
모델 단계 선택
| 단계 | det/rec 모델 크기 | 속도 | 정확도 | 적용 시나리오 |
|---|---|---|---|---|
tiny | 1.8M / 4.5M | 가장 빠름 | 낮음 | 단순한 장면, 빠른 미리보기 |
small(기본) | 9.9M / 21M | 균형 | 양호 | 일반적인 장면 |
medium | 62M / 77M | 가장 느림 | 최고 | 복잡하고 흐리거나 밀집된 텍스트 |
이미지가 선명하고 텍스트가 정돈된 경우 우선 small을 사용하고, 인식이 정확하지 않으면 medium으로 업그레이드하세요.
주의 사항
- 이미지가 선명하고 텍스트가 정돈될수록 인식률이 높아집니다. 기울어진 글자, 예술 글꼴, 배경 복잡도는 정확도를 낮출 수 있습니다.
- 방향이 뒤집히거나 세로 텍스트의 경우
--use_cls매개변수를 추가하세요. - 단일 이미지 처리 시간은 약 0.1~1초(CPU)이며, 이미지 크기, 단계, 엔진에 따라 다릅니다.
- Python 3.9+만 필요합니다. Python 환경이 없으면 setup.py가 각 플랫폼별 설치 안내를 제공합니다.