Dicklesworthstone/franken_ocr

Pure-Rust, CPU-only OCR engine for Baidu Unlimited-OCR (a DeepSeek-OCR-derived 3B MoE VLM). Five-model zoo, custom int8 kernels, no ML framework, no Python, no GPU.

franken_ocr – Baidu의 Unlimited-OCR 및 관련 모델용 순수 Rust CPU 전용 OCR

무엇인가요 – franken_ocr (이진 파일 focr)는 CPU에서 완전히 작동하는 Rust 라이브러리 + CLI입니다. 수작업으로 이식된 여러 개의 비전-언어 모델을 실행합니다. 기본 모델은 Baidu의 Unlimited-OCR로, 강력한 문서 구문 분석 모델입니다. 추가 모델로는 표 처리(GOT-OCR2), 이미지 설명/VQA(SmolVLM2), 차트 추출(OneChart), 광학 음악 인식(Polyphonic-TrOMR)이 있습니다. Python, CUDA, FFI, GPU는 전혀 필요 없으며, 추론 스택은 단일 메모리 안전한 Rust 이진 파일에 완전히 포함되어 있습니다.

주요 기능

기능	중요성
단일 포터블 이진 파일	macOS(Intel/Apple-Silicon), Linux(x86-64/ARM64), Windows(x86-64/ARM64)용 13–17 MiB 실행 파일. 외부 런타임 없음. CI 러너, 엣지 박스, 임베디드 에이전트에 쉽게 배포 가능.
오프라인 추론	`focr pull`로 모델 아티팩트(기본적으로 `~/.cache/franken_ocr/models`에 저장)를 다운로드한 후, 모든 OCR 작업은 완전히 로컬에서 수행됨. 네트워크 트래픽이 필요 없음.
Rust API	동기적, 블로킹 호출을 지원하는 `OcrEngine`을 제공하여, 비동기나 FFI를 다루지 않고도 Rust 프로그램에 OCR을 직접 통합할 수 있음.
네이티브 PDF 처리	PDF는 순수 Rust 코드로 인프로세스에서 래스터화되며, 페이지 회전을 존중하고 두 페이지 스프레드를 분할할 수 있음.
다중 페이지 및 구조화된 출력	`--multi-page`는 `<PAGE>` 구분자로 구성된 단일 문서를 생성; `--json`은 경계 상자 정보가 포함된 JSON을 반환; `--extract-figures`는 차트/사진을 Markdown과 함께 저장.
모델 저널	`focr models`로 5개의 즉시 실행 가능한 모델 목록을 확인할 수 있음. 각 모델은 맞춤형, 형태 최적화된 커널을 사용하여 일반적인 ML 프레임워크의 오버헤드를 제거.
Int8 가속 커널	수작업으로 작성된 SIMD 커널(AVX-512-VNNI, AVX-VNNI, AVX2, Apple SDOT/SMMLA 등)은 int8 양자화 아티팩트를 스칼라 참조보다 약 3배 빠르게 처리.
결정론적, 에이전트 대응 출력	"로봇 모드"는 NDJSON 이벤트(음악 전용 `staff` 이벤트 포함)를 스트리밍하며 안정적인 종료 코드를 제공하여 자율 에이전트에 적합.
자기 테스트 및 출처 검증	`focr robot selftest`는 int8 커널이 호스트 CPU에서 스칼라 오라클과 비트 단위 동일 결과를 생성함을 검증. 광범위한 릴리스 준비 스크립트와 성능 로그가 리포지토리에 포함됨.
메모리 안전한 Rust	`#![forbid(unsafe_code)]`를 전역적으로 적용(심지어 심층 검토된 SIMD 섬만 예외); 대용량 아티팩트용 옵션 mmap 로딩 지원.

빠른 시작 (README에서)

# 이진 파일 설치 (OS 감지, SHA-256 검증)
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/franken_ocr/main/install.sh | bash
# 기본 Unlimited-OCR 가중치 다운로드 (약 4 GB)
focr pull
# 단일 이미지에서 Markdown으로 OCR
focr ocr page.png
# 구조화된 JSON(경계 상자 포함) 얻기
focr ocr page.png --json -o page.json
# 전용 모델 사용 (예: 표)
focr pull got-ocr2
focr ocr --model got-ocr2.int8.focrq --task tables table.png

모델 캐시 후 모든 명령어는 오프라인에서 작동합니다.

아키텍처 개요

입력 계층 – PNG/JPG, 래스터화된 PDF 페이지, 이미지 배치, 시트음악 스캔을 수신.
모델 라우팅 – --task 플래그 또는 명시적 --model 경로에 따라 적절한 수작업 이식 모델로 디스패치.
런타임 코어 (OcrEngine) – 단일 모델 인스턴스를 보유. 가중치는 한 번만 로드하고, 미세한 SQLite 유사 저장소(fsqlite)를 통해 텔레메트리 기록.
CPU 실행 – 모델별 고정형 Rust 커널; SIMD 디스패치는 최적의 ISA(AVX-512-VNNI, AVX-VNNI, AVX2, x86의 스칼라; ARM에서는 LLVM autovec 또는 Apple SDOT/SMMLA) 선택. Int8 커널은 정확도를 유지하기 위해 대부분의 레이어를 고정밀 BF16로 유지하면서 피드포워드 네트워크를 가속화.
출력 계층 – Markdown, 레이아웃 상자 포함 JSON, MusicXML(OMR용), NDJSON 로봇 이벤트 생성.

프로젝트 건강 및 라이선스

버전 – v0.8.0 (주요 OS/아키텍처 조합용 바이너리 릴리스). 기본 Unlimited-OCR 아티팩트는 v0.7.0 int8 체크포인트에 고정되어 있으며, 20페이지 코퍼스에서 CER 예산 0.193(평균)을 충족하고, 하드 페이지 종료 테스트도 통과.
안전성 – unsafe는 심층 검토된 SIMD 커널 외에는 금지. 코드베이스는 완전한 메모리 안전을 목표로 함.
라이선스 – MIT (LICENSE 참조).
릴리스 증거 – 리포지토리에는 성능 로그, 패리티 게이트 테스트, 퍼즈 코퍼스, 각 릴리스를 인증하는 "가운트렛" 스코어카드를 생성하는 스크립트가 포함됨.

누구에게 적합한가요?

Rust 서비스에 통합하거나 단일 바이너리로 컴파일할 수 있는 가벼운 GPU 없는 OCR 컴포넌트가 필요한 개발자.
Python + CUDA 설치가 현실적이지 않은 CI/자동화 파이프라인.
인터넷 접속 없이 문서 OCR을 수행해야 하는 엣지 또는 오프라인 장치 (예: 노트북, CI 러너, IoT 박스).
구조화된 OCR 출력을 로봇 NDJSON 스트림으로 소비하는 에이전트.
순수 Rust OMR 솔루션을 찾는 음악 기술 애호가.

결론

franken_ocr는 Baidu의 비전-언어 모델의 엄선된 세트를 위한 생산 환경 대응 CPU 전용 OCR 스택을 메모리 안전한 Rust 구현으로 제공합니다. 결정론적 커널, 오프라인 작동, 광범위한 릴리스 준비 도구에 초점을 맞추어, 무거운 Python/CUDA 생태계 없이도 신뢰할 수 있는 OCR이 필요한 모든 사람에게 견고한 선택입니다.