Chandra OCR 딥다이브
— ~5B VLM으로 90개 언어와 복잡한 레이아웃을 인식하는 OCR 엔진

1프로젝트 한줄 요약

Chandra는 이미지·PDF를 HTML·Markdown·JSON으로 변환하는 VLM 기반 OCR 엔진으로, 복잡한 표·수식·손글씨·90개 이상의 언어를 레이아웃까지 보존하며 인식합니다.

Chandra 2(2026년 3월 출시)는 9B 파라미터를 ~5B(Qwen3.5)로 줄이면서 olmOCR 정확도는 83.1% → 85.9%로 오히려 높아졌습니다. 처리량도 2배 개선. HuggingFace 월간 165K+ 다운로드. GitHub 스타: 11.1k(2026-06-04 기준).

2왜 주목받는가

경쟁 제품 비교

3기술 스택 전체 지도

모델 (AI/ML)

백엔드 (Python)

4아키텍처 심화 분석

핵심 설계 패턴

① Strategy 패턴 — 추론 백엔드 교체

# 사용자는 method만 바꾸면 됨
manager = InferenceManager(method="vllm")  # 또는 "hf"
result = manager.generate(batch)

vLLM(서버 모드, 높은 처리량)과 HuggingFace(서버 없이 단일 스크립트)가 동일한 generate(batch) 인터페이스를 구현합니다. 같은 모델을 다른 환경에 맞게 서빙하는 실전적 패턴입니다.

② HTML as Intermediate Representation

OCR 결과를 바로 텍스트로 뽑지 않고 HTML을 중간 표현(IR)으로 사용합니다. HTML이 이미 table·div·math 구조를 갖고 있으므로 Markdown이나 JSON으로 변환이 훨씬 쉽습니다. 허용 태그/속성을 제한해 모델 출력의 일관성을 확보합니다.

③ Retry with Escalation — 점진적 온도 상승

vLLM 추론 실패 시 온도를 0.0 → 0.8까지 점진적으로 올립니다. 반복 토큰 패턴(degenerate output)을 감지하면 자동 재시도합니다. LLM 서빙에서 흔한 품질 저하 문제를 우아하게 해결하는 패턴입니다.

④ Pipeline 패턴 — 단계별 독립 모듈

입력(input.py) → 프롬프팅(prompts.py) → 추론(model/) → 후처리(output.py) 각 단계가 독립 모듈로 분리되어 한 단계만 교체하거나 테스트할 수 있습니다.

5디렉토리 구조 해부

6학습 포인트 (기술별)

Vision Language Model (VLM)

VLM이 이미지를 "보고" 텍스트를 생성하는 원리(Vision Encoder → Language Model), 4B 파라미터로 9B를 능가하는 모델 경량화 기법, BF16 추론의 의미와 메모리 절약 효과를 배웁니다.

vLLM 서빙

vLLM이 HuggingFace 대비 빠른 이유(PagedAttention, Continuous Batching), OpenAI 호환 API로 LLM 서빙하는 표준 패턴, ThreadPoolExecutor로 동시 요청 처리를 익힙니다.

# vLLM 클라이언트 OpenAI 호환 호출 패턴
from openai import OpenAI

client = OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1")
response = client.chat.completions.create(
    model="chandra",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img_b64}"}},
            {"type": "text", "text": "OCR this image to HTML"}
        ]
    }],
    temperature=0.0,
    max_tokens=12384
)

Pydantic Settings — 설정 관리 모범 사례

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    MODEL_CHECKPOINT: str = "datalab-to/chandra-ocr-2"
    MAX_OUTPUT_TOKENS: int = 12384
    VLLM_API_BASE: str = "http://localhost:8000/v1"
    IMAGE_DPI: int = 192
    MIN_IMAGE_DIM: int = 1536

    class Config:
        env_file = "local.env"
        extra = "ignore"  # 알 수 없는 env 변수 무시

settings = Settings()  # 모듈 레벨 싱글톤

구조화된 프롬프트 설계

허용 태그/속성을 제한하여 모델 출력 품질을 제어하는 기법, data-bbox로 좌표 정보를 HTML에 내장하는 아이디어, 시맨틱 라벨(Caption·Table·Code-Block) 분류 프롬프트를 배웁니다.

7하드웨어 / 시스템 요구사항

최소 사양 (HuggingFace 백엔드)

권장 사양 (vLLM 프로덕션)

GPU 없이 사용하는 방법: Hosted API(datalab.to), 웹 Playground, HuggingFace에 11개 양자화 버전(GGUF·AWQ) 제공.

8직접 해볼 수 있는 실습 과제

pip install chandra-ocr
chandra my_document.pdf ./output --method vllm
cat ./output/my_document.md

pip install "chandra-ocr[all]"
chandra_app  # 브라우저에서 http://localhost:8501

9관련 기술 심화 학습 로드맵

1주차: OCR 기초와 Chandra 체험

OCR 역사(규칙 기반 → CNN → Transformer → VLM), Tesseract vs EasyOCR vs Chandra 비교 실습, Chandra CLI로 다양한 문서 10개 처리, settings.py 환경변수 커스터마이징

2주차: Vision Language Model 이해

Qwen-VL 논문 읽기(Vision Encoder + LLM 연결 구조), HuggingFace Transformers로 VLM 추론 실습, model/hf.py 코드 라인별 분석, Flash Attention 원리

3주차: vLLM 서빙 마스터

vLLM 공식 문서 정독(PagedAttention·Continuous Batching), model/vllm.py 재시도 로직·온도 에스컬레이션 분석, vLLM 서버 직접 띄우고 벤치마크, 멀티 GPU 설정 실습

4주차: 문서 처리 파이프라인

input.py — pypdfium2 PDF 렌더링 심화, output.py — HTML 파싱·Markdownify 커스터마이징, 자체 문서 처리 파이프라인 설계 및 구현

5주차: 프롬프트 엔지니어링 for OCR

prompts.py 분석(허용 태그/속성 제한 전략), 프롬프트 변형 실험, 자체 도메인 특화 프롬프트 설계(영수증·의료문서 등)

6주차: 프로덕션 배포와 최적화

양자화(GGUF·AWQ) 적용 실습(VRAM 50% 절약), Docker로 Chandra 서비스 컨테이너화, FastAPI + vLLM API 서버 구축, 처리량·에러율·지연시간 모니터링

10핵심 키워드 사전

11참고 링크

• GitHub 레포 (datalab-to/chandra)
• Chandra 2 HuggingFace 모델 카드
• Datalab 공식 사이트 (Hosted API)
• 무료 Playground
• 90개 언어 전체 벤치마크
• vLLM 공식 문서
• Qwen-VL 논문
• Flash Attention 논문
• pypdfium2 문서
• Pydantic Settings 문서
• markdownify