Tencent-Hunyuan/HunyuanOCR

HunyuanOCR‑1.5 – 가벼운 OCR 전용 시각 언어 모델

무엇인가요

이미지 내 텍스트를 읽을 수 있으며, 문서 구문 분석, 정보 추출, 표 분석, 텍스트-이미지 번역도 수행할 수 있는 엔드투엔드 시각 언어 모델(VLM). 이전의 HunyuanOCR‑1.0을 기반으로 하며, DFlash 사전 추론을 통한 빠른 추론과 llama.cpp를 통한 PC 기반 간편 배포라는 두 가지 주요 업그레이드를 추가했습니다.

핵심 아이디어 및 기능

기능	중요성
DFlash 사전 추론	가벼운 "드래프트" 모델이 병렬로 여러 후보 토큰을 예측하고, 메인 모델이 한 번의 패스로 검증함으로써, 밀도 높은 문서, 표, 수식의 긴 자기회귀 추론 병목을 줄이며 동일한 출력 분포를 유지합니다.
통합 추론 환경	CUDA 13을 기반으로 한 `uv` 기반 환경을 통해 동일한 가중치와 프롬프트로 세 가지 구성(일반 vLLM 자기회귀, DFlash 가속, 네이티브 HuggingFace Transformers)을 실행할 수 있어 벤치마킹이 간편합니다.
llama.cpp를 통한 PC 기반 배포	모델(및 DFlash 드래프트)을 GGUF로 변환하여 CPU, 소비자용 GPU, 노트북 하드웨어에서 OpenAI 호환 `llama-server`로 제공할 수 있습니다.
에이전트 기반 데이터 흐름	모델의 약점을 타겟 데이터 생성 작업(예: 저자원 스크립트, 고대 중국어 문자, 다중 이미지 QA)으로 전환하는 내부 파이프라인. 이 데이터는 다시 트레이닝 레시피에 피드백됩니다.
대규모 컨텍스트 및 해상도	최대 4K 이미지 해상도와 128K 토큰 컨텍스트 창을 지원하여 긴 문서 및 다중 페이지 추론이 가능합니다.
광범위한 벤치마크	CHAOS‑Bench, Chronicles‑OCR, ChartArena, Wild‑OmniDocBench, MMTIT‑Bench 등 커뮤니티 수준의 벤치마크를 리포지토리에 포함하여 환각, 고대 스크립트 OCR, 차트 분석 등을 평가할 수 있습니다.

일반적인 사용 사례

스캔된 문서, 학술 논문, 계약서, 역사적 문헌의 디지털화.
이미지에서 구조화된 정보(표, 양식)를 직접 추출.
다국어 간 OCR 기반 질의 응답 또는 번역 수행.
llama.cpp 경로 덕분에 보통 하드웨어(노트북/CPU)에서도 실행 가능.

시작하기 (개요)

통합 추론 환경 설정 (Python 3.12 및 CUDA 13 필요):

pip install uv
uv venv --python 3.12 && source .venv/bin/activate
uv pip install "vllm>=0.25.1" "flash-attn==2.8.3"

HuggingFace에서 모델 다운로드:

pip install -U "huggingface_hub[cli]"
huggingface-cli download tencent/HunyuanOCR --local-dir ./HunyuanOCR --exclude "v1.0/*"

빠른 서버 실행 (vLLM 자기회귀, 단일 GPU):

MODEL_PATH=./HunyuanOCR GPU=0 PORT=8000 bash inference/vLLM/serve.sh

이미지 전송 (문서 분석 예제):

python inference/vLLM/infer_vllm_client.py \
    --image /path/to/doc.png \
    --task-type doc_parse \
    --model tencent/HunyuanOCR \
    --port 8000 --max-tokens 32768

doc_parse를 --list-tasks로 확인 가능한 12개의 지원 태스크 유형 중 하나로 교체하세요.

선택적 DFlash 가속 – inference/DFlash/serve_DFlash.sh 스크립트 사용. 동일한 클라이언트가 그대로 작동합니다.
PC 기반 배포 – 제공된 convert_hf_to_gguf.py 스크립트로 체크포인트를 GGUF로 변환하고, docs/llama_cpp.md에 설명된 대로 llama.cpp로 제공.

트레이닝 (微조정 또는 확장 원할 경우)

scripts/pack_data.sh 파이프라인으로 원시 OCR JSONL 파일을 긴 시퀀스(최대 20,480 토큰)로 패킹.
베이스 모델에서 교사 기반 미세조정 실행 (scripts/sft_base.sh).
새 DFlash 드래프트를 처음부터 트레이닝 (scripts/sft_dflash.sh) 또는 기존 드래프트를 계속 미세조정 (scripts/sft_dflash_finetune.sh).
모든 스크립트는 표준 NNODES, MASTER_ADDR 등을 통한 멀티노드 분산 트레이닝을 지원하며, PyTorch 2.1+, DeepSpeed, Flash‑Attention에 의존합니다.

문서 및 추가 읽기

docs/training.md – 상세한 하이퍼파라미터 및 분산 설정.
docs/inference/inference.md – 완전한 추론 레시피, 태스크 유형 표, 멀티GPU 가이드.
docs/llama_cpp.md – 소비자 하드웨어에서의 변환 및 제공 절차 단계별 설명.
벤치마크 설명은 benchmarks/CHAOS-Bench 및 링크된 arXiv 논문에 있음.

인용 HunyuanOCR‑1.5를 연구에 사용할 경우, README에 포함된 arXiv 논문(2026)을 인용해 주세요.

위 정보는 리포지토리의 README에서 직접 가져왔으며, 외부 가정은 추가되지 않았습니다.

Tencent-Hunyuan/HunyuanOCR

HunyuanOCR‑1.5 – 가벼운 OCR 전용 시각 언어 모델

관련