TL;DR

경량 end-to-end OCR용 VLM인 HunyuanOCR-1.5는 기존 백본을 유지하면서 DFlash speculative-decoding으로 긴 구조화 출력의 디코딩 병목을 줄이고 GGUF 변환과 llama.cpp를 통해 PC/랩탑 배포 경로를 제공한다. 에이전트 기반의 Agentic Data Flow와 업그레이드된 학습 레시피를 결합하여 저자원 OCR, 고대 문자, 다중 이미지 QA 등 장기 꼬리 능력을 보강하고 사전학습 시 최대 4K 해상도와 128K 컨텍스트를 지원한다. 배포는 vLLM·transformers·llama.cpp의 세 가지 상호 배타적 환경을 제공하여 서버와 로컬 양쪽 시나리오를 커버하지만 vLLM과 native transformers는 동일 환경에서 공존하지 않으므로 환경 분리와 버전 관리를 필요로 한다. 이 저장소는 SFT 및 DFlash 학습 파이프라인과 inferencing 예시를 공개하여 재현과 도메인 적응을 가능하게 한다. 최종적으로 긴 문서·표 중심의 OCR 워크로드에서 추론 지연을 줄이고 데스크톱 환경까지 배포 범위를 확장하는 데 초점을 맞추고 있다.

주요 기능

• DFlash 추론 가속을 적용하여 긴 구조화 출력의 디코딩 지연을 줄인다. 이 방식은 블록-단위 초안 모델이 병렬로 후보 토큰을 생성하고 대상 모델이 단일 검증 패스로 이를 확인하는 구조로 동작한다. 결과적으로 긴 문서나 표에서 순차적 토크나이즈 병목을 완화시키도록 설계되었다.
• PC 사이드 배포를 위해 GGUF 변환과 llama.cpp 호환성을 제공한다. 변환된 체크포인트와 mmproj 파일을 사용하면 CPU 또는 소비자급 GPU 환경에서도 모델을 서빙할 수 있다. HunyuanOCR-1.5는 DFlash가 적용된 llama.cpp 포크를 제공하여 동일한 추정 가속을 데스크톱에서도 활용할 수 있게 했다.
• Agentic Data Flow를 통해 데이터 파이프라인을 에이전트 중심으로 자동화하여 장기적 약점 보강을 목표로 한다. 에이전트는 자료 탐색, 툴 기반 검증, 샘플 정제, 파이프라인 개발에 참여하며 알고리즘 엔지니어와 반복적으로 데이터 요구사항을 생성한다. 이 접근은 저자원 문서, 고대 문자, 다중 이미지 QA 같은 긴 꼬리 능력 강화를 겨냥한다.
• 학습 파이프라인은 토큰 패킹과 대규모 컨텍스트를 지원하여 GPU 활용을 극대화한다. 원문은 packed_max_length=20480 토큰 단위의 시퀀스 패킹을 권장하며 사전학습 Stage-3에서는 4K 해상도와 128K 컨텍스트 창을 확장하여 긴 입력을 처리한다. 이러한 구성은 문서 단위의 긴 텍스트와 고해상도 이미지를 학습 데이터로 직접 다루는 것을 가능하게 한다.

어떻게 동작하는가

HunyuanOCR-1.5는 기존의 경량 VLM 백본을 유지한 채 추론과 데이터 파이프라인을 체계적으로 업그레이드하여 성능을 개선한다. 추론 측면에서는 블록-디퓨전 초안 모델이 병렬로 K개의 후보 토큰을 제안하고 대상 모델이 이를 단일 검증 패스로 확인하는 DFlash speculative-decoding을 채택하여 긴 구조화 출력에서 디코딩 지연을 낮춘다. 배포 측면에서는 Hugging Face 체크포인트를 GGUF로 변환해 llama.cpp 기반의 PC 사이드 서빙을 지원하고, vLLM 및 transformers용 별도 환경을 통해 서버·데스크톱·랩탑 등 다양한 실행 경로를 제공한다.

해결 문제

순차적 autoregressive 디코딩이 긴 문서, 표, 수식과 같은 구조화된 출력에서 주요 병목이 되는 문제를 해결한다. DFlash를 통해 블록 단위 초안 모델과 검증 패스 조합으로 디코딩 지연을 줄여 대량의 토큰을 요구하는 OCR 작업의 추론 시간을 단축한다. 또한 PC·노트북 수준의 자원에서도 실행 가능한 GGUF/llama.cpp 경로를 제공하여 서버 의존도를 낮추고 장비 제약 환경에서도 실용적 배포가 가능하도록 했다.

지금 주목받는 이유

프로젝트는 2026년 7월에 HunyuanOCR-1.5 출시와 함께 DFlash 추론 가속, ECCV·CVPR에 채택된 문서·테이블 관련 연구, 그리고 최신 벤치마크·데이터셋 공개로 주목을 받았다. 모델과 추론 도구를 공개하면서 PC 배포 및 성능 튜닝 관련 실용적 가이드라인을 함께 제시하여 실제 적용 가능성이 높아졌다. 이와 함께 표·고문자 OCR 관련 학회 채택은 기술적 기여가 연구 커뮤니티에서도 인정받았음을 시사한다.

차별점

• DFlash 기반의 추정-검증 워크플로를 도입하여 긴 구조화 출력에서 원본 모델의 출력 분포를 유지하면서 디코딩 지연을 절감한다. 블록-디퓨전 초안이 병렬로 여러 후보를 생성하고 대상 모델이 이를 검증하는 구조는 전통적 순차 토큰 예측과 달리 병목을 감소시킨다. 이 구성은 문서 파싱, 테이블 파싱, 긴 텍스트 생성에서 응답 지연을 크게 낮출 수 있도록 설계되었다.
• PC 사이드 배포를 위한 GGUF 변환과 DFlash 적응 llama.cpp 포크를 함께 제공하여 데스크톱 환경에서도 가속을 활용할 수 있다. 표준 community llama.cpp 빌드와 DFlash-adapted 포크 모두 예시 스크립트와 변환 도구가 포함되어 있다. 이로 인해 클라우드 서버가 아닌 환경에서도 일관된 추론 파이프라인을 유지할 수 있다.
• Agentic Data Flow를 통해 데이터 수집·검증·정제 과정에 에이전트를 깊게 통합하여 장기적 약점 보강을 자동화한다. 에이전트는 자료 검색, 툴 기반 검사, 샘플 클리닝, 파이프라인 개발에 반복적으로 참여하며 생성된 데이터는 Stage-3 사전학습과 후처리 SFT에 반영된다. 이 접근은 고대 문자, 저자원 언어, 멀티이미지 QA 같은 특정 능력을 표적 강화하는 데 초점을 맞춘다.

사용 사례

• 대규모 문서 파싱 파이프라인에서 긴 구조화 텍스트를 빠르게 추출하는 데 사용할 수 있다. DFlash를 통해 테이블과 긴 문단에서의 추론 지연을 줄여 배치 처리량을 높일 수 있으며 batch_infer와 같은 도구로 디렉토리 단위 일괄 처리가 가능하다. 또한 SFT 파이프라인으로 도메인 특화 파인튜닝을 수행하여 특정 문서 형식에 맞춘 정확도 향상을 도모할 수 있다.
• 현장형 PC·랩탑 환경에서 오프라인 OCR 서빙을 구축할 때 유용하다. GGUF로 변환한 체크포인트와 llama.cpp 서버를 통해 소비자급 하드웨어에서도 모델을 호스팅할 수 있으므로 네트워크 연결이 제한된 환경에서 로컬 처리와 개인정보 보호 요구를 충족할 수 있다. DFlash-adapted llama.cpp 포크를 사용하면 동일한 가속 기법을 데스크톱에서도 재현할 수 있다.
• 고문자·저자원 OCR 연구나 평가용 벤치마크 실험에 적합하다. Agentic Data Flow로 타깃 장기 꼬리 사례를 모으고 Stage-3 재학습으로 4K 해상도와 광범위 컨텍스트를 포함한 학습을 수행할 수 있으므로 고대 문자나 희귀 문서 형식에 대한 역량을 확장하는 연구에 활용 가능하다.

시작하기

빠른 시작은 Hugging Face에서 가중치를 내려받고 README의 inference 하위폴더 중 하나를 선택하여 환경을 구성하는 것이다. 예를 들어 vLLM AR 단일 GPU 서버는 inference/vllm_0_18_1의 requirements를 설치한 뒤 MODEL_PATH와 GPU 변수를 설정하고 serve.sh를 실행하여 OpenAI 호환 엔드포인트를 띄운 뒤 HTTP로 이미지를 전송하면 결과를 받을 수 있다. PC 배포를 원하면 GGUF로 체크포인트를 변환한 뒤 llama.cpp를 빌드하여 로컬 서버를 실행하는 절차가 README와 docs/llama_cpp.md에 상세히 제공되어 있다.

요구사항

• 학습 환경은 Python 3.10 이상과 PyTorch 2.1 이상, CUDA 12.1 이상이 권장된다. transformers 4.57+ 및 DeepSpeed 0.14+ 등 특정 라이브러리 버전이 요구되며 flash-attn 같은 일부 패키지는 수동 빌드가 필요하다.
• 추론 환경은 선택한 스택에 따라 상호 비호환성을 가진다. vLLM과 native transformers는 서로 다른 transformers 버전을 요구하므로 동일 환경에서 공존하지 않으며 각 inference 하위폴더는 별도의 requirements.txt를 포함하고 있어 지침을 따라 환경을 분리해야 한다.
• PC 사이드 배포를 위해서는 llama.cpp를 빌드할 수 있는 컴파일 도구와 선택적으로 CUDA를 지원하는 GPU 드라이버가 필요하다. GGUF 변환을 위해 huggingface_hub CLI가 필요하며 변환된 모델의 컨텍스트와 예측 길이에 맞춘 자원(cpu 메모리·GPU 메모리)이 필요하다.

이미지 분석