TL;DR

이 리포지토리는 baidu/Unlimited-OCR을 GGUF 형식으로 변환해 텍스트 디코더의 다양한 K-quants와 imatrix 기반 i-quants를 제공하고 공통의 F16 비전 프로젝터(mmproj)를 함께 배포한다. 내부 구성은 SAM-ViT-B+CLIP-L/14 기반의 DeepEncoder와 DeepSeek-V2 MoE 텍스트 디코더를 연결하는 구조로, 비전 프로젝터를 양자화하지 않고 텍스트만 여러 비트폭으로 양자화해 용량과 품질의 트레이드오프를 조절할 수 있다. 사용자는 DeepSeek-OCR을 인식하는 커스텀 llama.cpp PR을 빌드해야 하고, 실전 배포에는 Q4_K_M을 권장하며 결정적 OCR을 위해 --temp 0을 사용해야 한다. 저비트 i-quant들(IQ3_XXS, IQ2_M)은 크기를 크게 줄이는 대신 정확도 손실을 수반하므로 프로덕션에는 Q4_K_M 이상을 권장한다.

핵심 역량

• 다국어 문서에서 텍스트를 인식하고 순서·구조를 보존해 Markdown 형식으로 변환할 수 있다. 입력 이미지를 한 번에 처리해 장문·다중 페이지 문서의 장기적 파싱을 목표로 설계되어 있다. 옵션으로 바운딩 박스를 함께 출력해 시각적 레이아웃을 복원할 수 있다.
• 특정 문자열을 찾아 해당 텍스트의 바운딩 박스를 반환할 수 있다. 프롬프트에 <|grounding|>와 ref 토큰을 조합하면 원하는 필드의 좌표를 얻을 수 있다. 이 기능은 폼 필드나 청구서 번호처럼 위치 기반 추출에 적합하다.
• 도표·차트·다이어그램을 텍스트로 파싱하는 작업을 지원한다. Prompt로 'Parse the figure.' 등을 전달하면 시각적 요소를 텍스트 설명 또는 구조화된 형식으로 추출할 수 있다. 장문 반복이나 루핑이 발생할 때는 repeat-penalty와 temp 조정으로 출력을 제어할 수 있다.

강점

• 다양한 양자화 옵션(Q8_0, Q6_K, Q5_K, Q4_K_M 등)과 i-quant(iq4/iq3/iq2) 구성을 동일한 비전 프로젝터와 함께 제공해 디스크·메모리 제약에 맞춰 선택할 수 있다. 이로 인해 제한된 하드웨어에서도 실용적인 OCR 품질을 유지하면서 실행 환경에 맞춘 트레이드오프를 적용할 수 있다. 레포는 Q4_K_M을 추천 기본값으로 제시해 실무적 균형점을 명시했다.
• 비전 프로젝터를 F16으로 유지함으로써 시각 모듈의 양자화로 인한 OCR 정확도 저하를 방지하고, 모든 텍스트 양자화 버전에서 동일한 비전 투영을 사용해 일관된 시각 성능을 확보한다. 이 설계는 시각 인코더의 민감도를 감안한 실용적인 선택이다.

훈련 방식

baidu/Unlimited-OCR를 기반으로 convert_hf_to_gguf.py로 GGUF 형식으로 변환하고, 텍스트 디코더는 BF16으로 내보낸 뒤 imatrix 기반 중요도 행렬로 K-/i-quant을 생성하여 llama-quantize로 양자화를 수행했다.

알아두면 좋은 것

• 모델은 baidu/Unlimited-OCR의 DeepSeek-OCR 아키텍처를 GGUF로 변환한 것으로, 텍스트 디코더와 비전 프로젝터(mmproj)를 분리해 배포한다.
• 텍스트 모델은 여러 비트폭의 K-quants와 i-quants로 제공되며, 비전 프로젝터는 F16으로 고정되어 있어 시각 모듈의 품질 저하를 방지한다.
• 사용을 위해서는 DeepSeek-OCR을 인식하는 llama.cpp의 PR 빌드가 필요하며, 표준 upstream llama.cpp로는 해당 파일들을 로드할 수 없다.
• 실전 권장 설정은 Q4_K_M을 기본값으로 사용하고 OCR 시에는 --temp 0을 설정해 결정적 출력을 얻는 것이다.

기술적 특징

• 모델은 DeepSeek-OCR 아키텍처를 따라 DeepEncoder( SAM-ViT-B + CLIP-L/14, 1024×1024 입력, 16× 다운샘플)로 이미지를 인코딩하고 선형 프로젝터(mmproj)를 통해 텍스트 디코더에 입력을 전달한다. 비전 파트는 별도의 F16 gguf 파일로 유지되어 텍스트 양자화와 독립적으로 동작한다. 이 분리는 비전 품질을 보호하면서 텍스트 모델의 용량을 다양한 양자화로 줄일 수 있게 한다.
• 텍스트 디코더는 DeepSeek-V2 MoE 구조로 구성되어 12개의 레이어와 hidden 1280 규모, 레이어당 복수 전문가를 라우팅하는 설계로 대용량 표현력을 확보한다. MoE는 입력 토큰마다 일부 전문가만 활성화해 표현 다양성을 늘리는 한편 계산을 통제하는 방식으로 작동한다. 이로 인해 문서 파싱과 같이 다양한 구조적 패턴을 처리하는 능력이 향상된다.
• 양자화는 K-quants와 i-quants라는 두 축으로 제공되며, i-quants는 imatrix(중요도 행렬)를 일반 텍스트 교정셋으로 계산해 비선형·저비트 압축을 달성한다. i-quant의 IQ4_NL 같은 변형은 ARM/edge 장치에서 성능을 내도록 튜닝되어 엣지 환경을 염두에 둔 배포를 가능하게 한다. 양자화 방식 선택은 품질 대 크기 트레이드오프를 직접 제어하게 한다.
• 배포 포맷은 GGUF로 통일되어 llama.cpp 생태계에서 직접 로드가 가능하도록 변환되었으나, DeepSeek-OCR 지원은 아직 upstream에 병합되지 않아 PR 브랜치로 빌드해야 한다. README는 필요한 PR(#17400/24975)을 체크아웃해 llama-mtmd-cli와 llama-server 바이너리를 빌드하는 절차를 명시하고 있다. 사용자는 이 빌드 의존성을 충족해야만 모델과 mmproj를 정상적으로 로드할 수 있다.

차별점

• 비전 프로젝터(mmproj)를 별도의 F16 파일로 분리해 모든 텍스트 양자화 버전과 공유함으로써 비전 모듈의 품질을 보존한다. 이 접근은 텍스트 파트만 경량화하되 시각 입력의 정밀도를 유지하려는 실용적 설계로 작동한다.
• i-quant 변형들은 imatrix(중요도 행렬)를 이용해 동일 비트폭에서 더 작은 용량으로 유사한 품질을 얻도록 설계되어 ARM 및 Apple 같은 엣지 플랫폼에 특화된 옵션을 제공한다. 이로 인해 동일한 모델 계열에서 엣지용과 서버용 배포를 같은 워크플로로 관리할 수 있다.
• DeepSeek-OCR의 DeepEncoder(SAM+CLIP)와 DeepSeek-V2 MoE 디코더 조합을 유지해 문서의 레이아웃·시각적 단서를 적극적으로 활용하는 한편 MoE로 텍스트 표현력을 확장했다. 이 구조는 일반적인 단일 스트림 OCR 모델과 달리 레이아웃 보존과 복잡한 문서 구조 파싱에서 차별화된다.