책 한 권을 한 번에 베껴 쓰는 OCR: baidu/Unlimited-OCR의 R-SWA 링 버퍼 KV 캐시·DeepEncoder 16배 압축·3B MoE 디코더 심층 해부와 박스 CPU 실측

LLM 디코더를 단 엔드투엔드 OCR은 품질이 좋아진 대신 운영자에게 익숙한 골칫거리를 하나 남겼다. 출력이 길어질수록 KV 캐시가 자라고, 토큰당 지연도 함께 늘어난다는 점이다. 그래서 현장의 문서 파이프라인은 PDF를 페이지 단위로 잘라 for 루프로 돌리고, 페이지마다 모델의 “기억”을 초기화한다. 바이두가 공개한 baidu/Unlimited-OCR은 이 루프를 모델 안으로 끌어들이려는 시도다. DeepSeek-OCR을 베이스로 디코더의 모든 어텐션을 R-SWA(Reference Sliding Window Attention)로 바꿨다. 이미지와 프롬프트(참조 토큰)는 끝까지 전부 보되, 이미 쓴 출력은 최근 128토큰만 본다. 그 결과 디코드 쪽 KV 캐시가 참조 길이 m + 128에서 멈추고, 수십 쪽을 한 번의 forward 패스로 연속 전사할 수 있다는 것이 주장이다.

오늘(2026-10-24) GitHub Trending Python 일간 4위(+75, 11:52 KST 스냅숏)에 다시 올라왔다. 10월 23일 README가 갱신됐고, 이슈 트래커에는 지난주부터 infer.py 품질 개선 PR과 멀티 페이지 구분자 누락 리포트가 이어지고 있다. 이 글은 저장소 README·기술 보고서 PDF·Hugging Face의 trust_remote_code 모델 코드를 직접 읽고 구조와 타협점을 해부한다. 그리고 GPU가 없는 박스(x86_64 VM, 8코어, RAM 15GB)에서 6.67GB 가중치를 실제로 받아 CPU로 돌려 R-SWA 링 버퍼가 정말 KV 캐시를 고정하는지, 링을 끄면 어떻게 되는지, 8쪽 연속 전사가 되는지 측정한 결과를 그대로 적는다.

한눈에 보기: 오늘 기준 스냅숏

무엇을 풀려는가: for 루프 OCR의 진짜 비용

보고서의 문제 설정은 단순하다. 사람은 책을 베낄 때 지금까지 쓴 글 전체를 다시 훑지 않는다. 원본을 보고, 방금 쓴 몇 글자로 “어디까지 썼는지”만 확인한 뒤 다음 글자를 쓴다. 반면 표준 어텐션 디코더는 매 토큰마다 지금까지의 출력 전체를 다시 본다. 페이지 하나에 수천 토큰이 나오는 문서 OCR에서는 이것이 그대로 메모리와 지연 증가로 이어진다. 보고서의 계산으로 1024×1024 기준 약 20~30쪽이면 시각 토큰이 1만 개 수준이고, 시각:텍스트 토큰 비율을 1:10으로 잡으면 출력이 10만 토큰을 넘는다.

아키텍처: 인코더는 그대로, 디코더 어텐션만 바꿨다

구조적으로 Unlimited-OCR은 DeepSeek-OCR의 부분 수정판이다. 보고서에 따르면 DeepSeek-OCR 체크포인트에서 출발해 DeepEncoder는 동결하고 LLM 디코더만 4,000스텝 이어서 학습했다(전역 배치 256, 시퀀스 32K, 8×16 A800, Megatron-LM + DeepEP, 전문가 병렬 4). 학습 데이터는 약 200만 개 문서 OCR 샘플로, 단일:다중 페이지 비율이 9:1이다. 단일 페이지 라벨은 PaddleOCR로 만들었고, 다중 페이지 데이터(약 20만 개, 2~50쪽)는 단일 페이지를 <page> 구분자로 이어 붙여 합성했다.

R-SWA를 코드로 읽기: 링 버퍼 KV 캐시

보고서의 정의는 이렇다. 프리필 길이 L_m(시각 토큰 + 프롬프트)은 한 번의 추론에서 고정이고, 디코드 t번째 토큰이 볼 수 있는 집합은 N(t) = P ∪ D_n(t), 즉 전체 프리필 P와 직전 n개 출력의 합집합이다. 따라서 T개를 생성한 뒤 캐시 크기는 C_R-SWA(T) = L_m + min(n, T) ≤ L_m + n 이고, 표준 MHA의 L_m + T와 대비된다. 흥미로운 건 이게 새 커널이 아니라 캐시 관리 규칙이라는 점이다. Hugging Face에 올라간 modeling_deepseekv2.py의 SlidingWindowLlamaAttention을 보면 구현이 매우 직선적이다.

보고서가 내세운 숫자, 그리고 읽는 법

읽을 때 주의할 점이 세 가지다. 첫째, v1.6에서 1위라고는 하지만 2위(Qianfan-OCR 93.90)와 차이는 0.02포인트이고 Text Edit·Table TEDS는 오히려 뒤진다. “동급 최상위권”이 정확한 표현이다. 둘째, v1.5에서 베이스 대비 +6.22포인트는 R-SWA만의 효과로 단정하기 어렵다. 같은 실험에서 200만 개 문서 특화 데이터로 추가 학습을 했기 때문에, 어텐션 변경과 데이터 효과가 섞여 있다(보고서도 “R-SWA may allow…”라고 조심스럽게 쓴다). 셋째, 장문 성능(표 3)은 사내 테스트셋이라 재현이 어렵다.

표 4는 R-SWA의 핵심 효과를 가장 깨끗하게 보여 준다. 출력이 짧으면 차이가 없고, 길어질수록 베이스는 떨어지는데 Unlimited-OCR은 7,800 TPS대에서 평평하다. OmniDocBench 실측 처리량은 512 동시성에서 5,580 vs 4,951 TPS(+12.7%)로 보고됐다. 문서 길이가 짧은 벤치마크에선 이득도 작다는 뜻이다. 보고서 스스로 밝힌 한계도 분명하다. 32K 컨텍스트 안에서 프리필이 쌓이면 결국 막힌다. 보고서 초록도 “표준 최대 길이 32K에서 수십 쪽”이라고 쓴다. 그래서 ‘진짜 무제한’은 아니며, 128K 학습과 “프리필 KV 풀에서 필요한 페이지를 꺼내 오는” 방식이 향후 과제로 적혀 있다.

저장소 구조: 코드는 얇고, 무게는 HF와 서빙 엔진에 있다

즉 “저장소를 클론해서 테스트를 돌린다”는 개념이 거의 없다. 학습 코드나 단위 테스트는 공개되지 않았고(CONTRIBUTING은 단위 테스트를 요구하지만 저장소에 테스트 디렉터리가 없다), 모델 코드는 Hugging Face 쪽 trust_remote_code로 배포된다. 도입 검토는 HF 리비전 고정 + 원격 코드 리뷰가 사실상 코드 리뷰다.

설치와 실행: 세 갈래

1) Transformers (가장 단순, CUDA 전제)

pip install torch==2.10.0 torchvision==0.25.0 transformers==4.57.1 \
  einops==0.8.2 addict easydict pymupdf==1.27.2.2 Pillow matplotlib psutil

python - <<'EOF'
import torch
from transformers import AutoModel, AutoTokenizer
name = "baidu/Unlimited-OCR"
tok = AutoTokenizer.from_pretrained(name, trust_remote_code=True)
model = AutoModel.from_pretrained(name, trust_remote_code=True,
        use_safetensors=True, torch_dtype=torch.bfloat16).eval().cuda()
# 단일 페이지: gundam(base_size=1024, image_size=640, crop) 또는 base(1024, no crop)
model.infer(tok, prompt="<image>document parsing.", image_file="page.png",
            output_path="out", base_size=1024, image_size=640, crop_mode=True,
            max_length=32768, no_repeat_ngram_size=35, ngram_window=128, save_results=True)
# 멀티 페이지/PDF: base(1024)만, n-gram 창 1024
model.infer_multi(tok, prompt="<image>Multi page parsing.",
            image_files=["p1.png", "p2.png", "p3.png"], output_path="out",
            image_size=1024, max_length=32768, no_repeat_ngram_size=35,
            ngram_window=1024, save_results=True)
EOF

2) vLLM (전용 이미지)

docker run --rm --gpus all --network host --ipc host \
  vllm/vllm-openai:unlimited-ocr \
  baidu/Unlimited-OCR --trust-remote-code \
  --logits_processors vllm.model_executor.models.unlimited_ocr:NGramPerReqLogitsProcessor \
  --no-enable-prefix-caching --mm-processor-cache-gb 0
# 요청 시: skip_special_tokens=False,
#   vllm_xargs={"ngram_size": 35, "window_size": 128}  (멀티 페이지는 1024)

3) SGLang (저장소 동봉 휠 + 배치 스크립트)

uv venv --python 3.12 && source .venv/bin/activate
uv pip install wheel/sglang-0.0.0.dev11416+g92e8bb79e-py3-none-any.whl
uv pip install kernels==0.11.7 pymupdf==1.27.2.2
python infer.py --pdf ./document.pdf --output_dir ./outputs \
  --concurrency 8 --image_mode gundam --gpu 0

박스 실측: GPU 없이 CPU로 정말 돌려 봤다

공식 경로는 모두 CUDA 전제다. infer()와 infer_multi() 안에 .cuda() 호출과 torch.autocast("cuda")가 하드코딩돼 있어(이슈 #81도 같은 지적) 그대로는 CPU에서 즉시 실패한다. 박스에서는 코드를 고치지 않고 torch.Tensor.cuda를 항등 함수로 바꾸는 한 줄 몽키패치로 우회했다(autocast는 CUDA가 없으니 경고 후 비활성). 환경은 Python 3.12 가상환경, torch 2.10.0+cpu · transformers 4.57.1, BF16 가중치, attn_implementation="eager"(= 링 버퍼 어텐션 클래스), 8스레드다. 입력은 정답을 아는 합성 문서(1240×1754, 제목·문단·3×3 표)를 PIL로 만들어 썼다. 가중치 다운로드(6.67GB)는 약 3분, 모델 로드는 1~2초(페이지 캐시 적중)였다.

import torch
torch.Tensor.cuda = lambda self, *a, **k: self      # CPU 박스용 우회
model = AutoModel.from_pretrained(MD, trust_remote_code=True, use_safetensors=True,
        torch_dtype=torch.bfloat16, attn_implementation="eager").eval()
# 링을 끈 대조군: 같은 가중치에서 sliding_window를 None으로
model.config.sliding_window_size = None; model.config.sliding_window = None
# forward hook으로 스텝별 시간과 0번 층 KV 길이를 기록

가장 분명한 결과는 KV 캐시 길이다. R-SWA 실행은 모든 경우 정확히 프리필 + 128에서 멈췄다(277→405, 824→952, 2,189→2,317). 같은 가중치에서 링을 끄면 프리필 + 생성 토큰 수만큼 자랐다(277→489, 824→1,392). 서로 다른 8쪽 문서는 프리필 2,189토큰(페이지당 약 273토큰 × 8 + 텍스트)으로 시작해 1,034토큰을 생성하는 동안 캐시가 2,317에서 고정됐고, 페이지 구분자 <PAGE> 7개(8쪽 사이 7곳)가 모두 정상으로 나왔으며 정답 대비 정규화 편집거리는 0.0011였다. 3쪽 R-SWA 출력에서는 “becomes”를 “becoming”으로 쓴 단어 오류가 하나 있었다.

비교: 어디에 놓이는 도구인가

이슈 #100의 외부 R&D 리포트가 현실적인 기준점을 준다. T4 GPU에서 단일 페이지 세 건을 비교했더니 Unlimited-OCR은 어려운 스캔에서 문자 정확도 79.36% → 99.54%로 크게 앞섰지만, 페이지당 시간은 Tesseract보다 8~19배 느렸다. 정확도가 돈이 되는 문서(계약·논문·재무제표)라면 투자할 만하고, “대충 검색만 되면 되는” 경량 인입 파이프라인이라면 과하다.

타협점과 주의 사항

평가 방법: 우리 문서로 이렇게 재 보자

누가 도입하면 좋은가

정리

Unlimited-OCR의 핵심은 거창한 새 커널이 아니라 “참조는 끝까지, 출력은 128토큰만”이라는 캐시 규칙 하나다. 박스에서 CPU로 돌려 보니 그 규칙은 코드에서 정확히 지켜졌다. 캐시는 프리필 + 128에서 멈췄고, 서로 다른 8쪽 문서를 한 번에 전사해 페이지 구분자까지 맞췄다. 반면 같은 페이지가 반복되면 위치를 잃었고, 한국어는 오탈자가 눈에 띄었으며, 처리량 이득은 GPU와 긴 출력에서만 의미 있게 드러나는 성질이다. 벤치마크 1위라는 숫자보다 “for 루프를 모델 안으로 옮길 수 있는가”라는 질문을 자기 문서로 검증하는 데 쓰기 좋은 저장소다. MIT 라이선스에 3B·활성 0.5B라는 크기도 실험 비용을 낮춰 준다.