Add HunyuanOCR-1.5 (target at root, DFlash under dflash/, archive 1.0 under v1.0/) (#30)

- Add HunyuanOCR-1.5 (target at root, DFlash under dflash/, archive 1.0 under v1.0/) (7f4662d542acd852b2c71b6b12937d3a541ef585)
- Remove old HunyuanOCR-1.0 shards/index from root (archived under v1.0/) (84129bb47d0b5b937da960d8c121da40d6aa10ac)

README.md

@@ -1,236 +1,228 @@
 ---
 license: other
+license_name: tencent-hunyuan-community
+license_link: https://huggingface.co/tencent/HunyuanOCR/blob/main/LICENSE
 language:
 - multilingual
-pipeline_tag: image-text-to-text
-library_name: transformers
-base_model:
-- tencent/HunyuanOCR
+- en
+- zh
 tags:
 - ocr
-- hunyuan
-- vision-language
-- image-to-text
-- 1B
-- end-to-end
+- vision-language-model
+- document-parsing
+- text-spotting
+- information-extraction
+- text-image-translation
+pipeline_tag: image-text-to-text
+library_name: transformers
 ---
 
-<p align="center">
- <img src="https://github.com/Tencent-Hunyuan/HunyuanOCR/blob/main/assets/hyocr-head-img.png?raw=true" width="80%"/> <br>
-</p>
+# HunyuanOCR-1.5 &nbsp;·&nbsp; Preview
 
+<div align="center">
 
-<p align="center">
-<a href="https://hunyuan.tencent.com/chat/HunyuanDefault?modelId=HY-OCR-1.0&mid=308&from=vision-zh"><b>🎯 Demo</b></a> |
-<a href="https://huggingface.co/tencent/HunyuanOCR"><b>📥 Model Download</b></a> |
-<a href="https://arxiv.org/abs/2511.19575"><b>📄 Technical Report</b></a> |
-<a href="https://github.com/Tencent-Hunyuan/HunyuanOCR"><b>🌟 Github</b></a>
-</p>
+**Towards Efficient and Effective E2E OCR**
 
-<h2>
-<p align="center">
-  <a href="https://arxiv.org/abs/2511.19575">HunyuanOCR</a>
-</p>
-</h2>
+</div>
 
+> 📝 **Note.** This is a **preview release** of HunyuanOCR-1.5 weights.
+> The **technical report and official weights are coming very soon**; the
+> checkpoint, file layout and interface here may still evolve before the final
+> release. Training / inference toolkit and full documentation live in the
+> GitHub repo (branch **`develop`**):
+> <https://github.com/Tencent-Hunyuan/HunyuanOCR>.
+
+---
 
 ## 📖 Introduction
-**HunyuanOCR** stands as a leading end-to-end OCR expert VLM powered by Hunyuan's native multimodal architecture. With a remarkably lightweight 1B parameter design, it has achieved multiple state-of-the-art benchmarks across the industry. The model demonstrates mastery in **complex multilingual document parsing** while excelling in practical applications including **text spotting, open-field information extraction, video subtitle extraction, and photo translation**.
 
+**HunyuanOCR-1.5** is a lightweight, end-to-end OCR-specialized vision-language
+model. It targets a broad range of text-centric visual tasks and unifies
+**document parsing, text spotting, information extraction, and text-image
+translation** within a single end-to-end VLM.
+
+Building upon the validated lightweight architecture of **HunyuanOCR-1.0**,
+HunyuanOCR-1.5 does *not* redesign the backbone. Instead, it performs a
+systematic upgrade around two goals — **making the model faster and better**:
+
+- ⚡ **Faster — DFlash inference acceleration.**
+  A lightweight block-diffusion draft model drafts multiple candidate tokens in
+  parallel, verified by the target model in a single pass, significantly
+  reducing decoding latency of long structured OCR outputs (dense documents,
+  tables, formulas) while **preserving the target model's output distribution**.
+  Draft weights: [`tencent/HunyuanOCR/dflash`](https://huggingface.co/tencent/HunyuanOCR/tree/main/dflash).
+
+- 💻 **PC-side deployment via llama.cpp.**
+  Beyond server-grade vLLM, HunyuanOCR-1.5 also supports **CPU / consumer-GPU /
+  laptop** deployment via [`llama.cpp`](https://github.com/ggml-org/llama.cpp)
+  with an OpenAI-compatible `llama-server`. A DFlash-adapted `llama.cpp` fork is
+  also provided so the same speculative-decoding acceleration is available on
+  PC.
+
+- 🧠 **Better — Agentic Data Flow + upgraded training recipe.**
+  An agent-driven data-construction system (**Agentic Data Flow**) translates
+  model weaknesses into executable data requirements, targeting long-tail
+  capabilities such as **low-resource OCR, ancient-script OCR, and multi-image
+  text-centric QA**. Pretraining Stage-3 is re-planned with **4K resolution** and
+  a **128K context window**; post-training refines SFT data and further explores
+  RL across different OCR tasks.
+
+Together, HunyuanOCR-1.5 achieves both faster inference and broader OCR
+capability coverage while retaining the deployment advantages of a lightweight
+end-to-end model.
+
+---
+
+## ⚙️ Environment
 
-## 🚀 Quick Start with Transformers
+- Python 3.10+
+- PyTorch 2.1+ (CUDA 12.1+)
+- **transformers** (ships `HunYuanVLForConditionalGeneration` + `AutoProcessor` for the HunyuanOCR-1.5 series)
+- **vLLM nightly** — for serving and DFlash speculative decoding
+
+### transformers
+
+```bash
+pip install transformers torch pillow accelerate
+# for FlashAttention:
+pip install flash-attn --no-build-isolation
+```
+
+### vLLM serving
+
+We use a dedicated venv for inference to keep vLLM nightly isolated:
 
-### Installation
 ```bash
-pip install git+https://github.com/huggingface/transformers@82a06db03535c49aa987719ed0746a76093b1ec4
+uv pip install -U vllm \
+    --torch-backend=cu130 \
+    --extra-index-url https://wheels.vllm.ai/nightly
+uv pip install runai-model-streamer
 ```
-> **Note**: We will merge it into the Transformers main branch later.
 
-### Model Inference
+> 💡 On CUDA 12.x, replace `--torch-backend=cu130` with the matching tag
+> (e.g. `cu121`, `cu124`).
+---
+
+## 🚀 Quick start
+
+### A. HuggingFace transformers
 
 ```python
-from transformers import AutoProcessor
-from transformers import HunYuanVLForConditionalGeneration
-from PIL import Image
 import torch
+from transformers import AutoProcessor, HunYuanVLForConditionalGeneration
 
-def clean_repeated_substrings(text):
-    """Clean repeated substrings in text"""
-    n = len(text)
-    if n<8000:
-        return text
-    for length in range(2, n // 10 + 1):
-        candidate = text[-length:] 
-        count = 0
-        i = n - length
-        
-        while i >= 0 and text[i:i + length] == candidate:
-            count += 1
-            i -= length
-
-        if count >= 10:
-            return text[:n - length * (count - 1)]  
-
-    return text
-
-model_name_or_path = "tencent/HunyuanOCR"
-processor = AutoProcessor.from_pretrained(model_name_or_path, use_fast=False)
-img_path = "path/to/your/image.jpg"
-image_inputs = Image.open(img_path)
-messages1 = [
-    {"role": "system", "content": ""},
-    {
-        "role": "user",
-        "content": [
-            {"type": "image", "image": img_path},
-            {"type": "text", "text": (
-                "检测并识别图片中的文字，将文本坐标格式化输出。"
-            )},
-        ],
-    }
-]
-messages = [messages1]
-texts = [
-    processor.apply_chat_template(msg, tokenize=False, add_generation_prompt=True)
-    for msg in messages
-]
-inputs = processor(
-    text=texts,
-    images=image_inputs,
-    padding=True,
-    return_tensors="pt",
-)
+MODEL_ID = "tencent/HunyuanOCR"
+
+processor = AutoProcessor.from_pretrained(MODEL_ID, trust_remote_code=True)
 model = HunYuanVLForConditionalGeneration.from_pretrained(
-    model_name_or_path,
-    attn_implementation="eager",
-    dtype=torch.bfloat16,
-    device_map="auto"
+    MODEL_ID, torch_dtype=torch.bfloat16, device_map="auto",
+    trust_remote_code=True,
+).eval()
+
+prompt = (
+    "提取文档图片中正文的所有信息用markdown格式表示，其中页眉、页脚部分忽略，"
+    "表格用html格式表达，文档中公式用latex格式表示，按照阅读顺序组织进行解析。"
 )
-with torch.no_grad():
-    device = next(model.parameters()).device
-    inputs = inputs.to(device)
-    generated_ids = model.generate(**inputs, max_new_tokens=16384, do_sample=False)
-if "input_ids" in inputs:
-    input_ids = inputs.input_ids
-else:
-    print("inputs: # fallback", inputs)
-    input_ids = inputs.inputs
-generated_ids_trimmed = [
-    out_ids[len(in_ids):] for in_ids, out_ids in zip(input_ids, generated_ids)
-]
-output_texts = clean_repeated_substrings(processor.batch_decode(
-    generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
-))
-print(output_texts)
-```
 
+messages = [{
+    "role": "user",
+    "content": [
+        {"type": "image", "image": "/path/to/document.png"},
+        {"type": "text",  "text":  prompt},
+    ],
+}]
 
-## 🚀 Quick Start with vLLM
+inputs = processor.apply_chat_template(
+    messages, add_generation_prompt=True, tokenize=True,
+    return_dict=True, return_tensors="pt",
+).to(model.device)
 
-Checkout [vLLM HunyuanOCR Usage Guide](https://docs.vllm.ai/projects/recipes/en/latest/Tencent-Hunyuan/HunyuanOCR.html).
+with torch.inference_mode():
+    out = model.generate(**inputs, max_new_tokens=8000, do_sample=False)
 
-### Installation
+gen = out[:, inputs["input_ids"].shape[1]:]
+print(processor.batch_decode(gen, skip_special_tokens=True)[0])
+```
+
+Or use the ready-made single-image script from the repo:
 
 ```bash
-uv venv hunyuanocr
-source hunyuanocr/bin/activate
+git clone -b develop https://github.com/Tencent-Hunyuan/HunyuanOCR.git
+cd HunyuanOCR
 
-uv pip install -U vllm --pre --extra-index-url https://wheels.vllm.ai/nightly
+python inference/infer_base.py \
+    --model tencent/HunyuanOCR \
+    --image /path/to/document.png \
+    --max-new-tokens 8000
 ```
 
-Note: We suggest to install [cuda-compat-12-9](https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/):
+### B. vLLM
+
 ```bash
-sudo dpkg -i cuda-compat-12-9_575.57.08-0ubuntu1_amd64.deb
-echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.9/compat:$LD_LIBRARY_PATH' >> ~/.bashrc
-source ~/.bashrc
-# verify cuda-compat-12-9
-ls /usr/local/cuda-12.9/compat
+# Autoregressive baseline
+MODEL_PATH=tencent/HunyuanOCR \
+GPU=0 PORT=8000 GPU_MEM_UTIL=0.9 \
+bash inference/serve_ar.sh
+
+# DFlash speculative decoding
+# The draft lives under the `dflash/` subfolder of tencent/HunyuanOCR;
+# download it into a flat local dir first (HF subfolder loading is
+# unsupported by vLLM's speculative-config):
+#   python -c "from huggingface_hub import snapshot_download; import shutil, os; \
+#   d=snapshot_download('tencent/HunyuanOCR', allow_patterns=['dflash/*']); \
+#   shutil.copytree(os.path.join(d,'dflash'), './hunyuanocr_dflash', dirs_exist_ok=True)"
+MODEL_PATH=tencent/HunyuanOCR \
+DFLASH_PATH=./hunyuanocr_dflash \
+GPU=0 PORT=8001 GPU_MEM_UTIL=0.9 NUM_SPEC_TOKENS=15 \
+bash inference/serve_dflash.sh
 ```
 
-### Model Deploy
+Send one image with the shipped client (streaming + tail-repetition early-stop,
+matches internal bench sampling params):
+
 ```bash
-vllm serve tencent/HunyuanOCR \
-    --no-enable-prefix-caching \
-    --mm-processor-cache-gb 0 \
-    --gpu-memory-utilization 0.2
+python inference/infer_vllm_client.py \
+    --host 127.0.0.1 --port 8000 \
+    --model tencent/HunyuanOCR \
+    --image /path/to/document.png
 ```
 
-### Model Inference
-```python
-from vllm import LLM, SamplingParams
-from PIL import Image
-from transformers import AutoProcessor
-
-def clean_repeated_substrings(text):
-    """Clean repeated substrings in text"""
-    n = len(text)
-    if n<8000:
-        return text
-    for length in range(2, n // 10 + 1):
-        candidate = text[-length:] 
-        count = 0
-        i = n - length
-        
-        while i >= 0 and text[i:i + length] == candidate:
-            count += 1
-            i -= length
-
-        if count >= 10:
-            return text[:n - length * (count - 1)]  
-
-    return text
-
-model_path = "tencent/HunyuanOCR"
-llm = LLM(model=model_path, trust_remote_code=True)
-processor = AutoProcessor.from_pretrained(model_path)
-sampling_params = SamplingParams(temperature=0, max_tokens=16384)
-
-img_path = "/path/to/image.jpg"
-img = Image.open(img_path)
-messages = [
-    {"role": "system", "content": ""},
-    {"role": "user", "content": [
-        {"type": "image", "image": img_path},
-        {"type": "text", "text": "检测并识别图片中的文字，将文本坐标格式化输出。"}
-    ]}
-]
-prompt = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
-inputs = {"prompt": prompt, "multi_modal_data": {"image": [img]}}
-output = llm.generate([inputs], sampling_params)[0]
-print(clean_repeated_substrings(output.outputs[0].text))
+### C. PC-side deployment via llama.cpp
+
+See `docs/llama_cpp.md` in the GitHub repo for GGUF conversion, community
+`llama-server` launch, and the DFlash-adapted fork.
+
+---
+
+## 🎯 Default OCR prompt
+
+```
+提取文档图片中正文的所有信息用markdown格式表示，其中页眉、页脚部分忽略，
+表格用html格式表达，文档中公式用latex格式表示，按照阅读顺序组织进行解析。
 ```
 
-## 💬 Application-oriented Prompts
+The model also handles text spotting, information extraction, and text-image
+translation — pass a task-specific instruction as the text prompt.
 
-| Task | Prompt |
-|------|---------|
-| **Spotting** | 检测并识别图片中的文字，将文本坐标格式化输出。 |
-| **Document Parsing** | • 识别图片中的公式，用LaTeX格式表示。<br><br>• 把图中的表格解析为HTML。<br><br>• 解析图中的图表，对于流程图使用Mermaid格式表示，其他图表使用Markdown格式表示。<br><br>• 提取文档图片中正文的所有信息用markdown格式表示，其中页眉、页脚部分忽略，表格用html格式表达，文档中公式用latex格式表示，按照阅读顺序组织进行解析。|
-| **General Parsing** | • 提取图中的文字。|
-| **Information Extraction** | • 输出Key的值。<br><br>• 提取图片中的: ['key1','key2', ...] 的字段内容，并按照JSON格式返回。<br><br>• 提取图中的字幕 |
-| **Translation** | 先提取文字，再将文字内容翻译为英文。若是文档，则其中页眉、页脚忽略。公式用latex格式表示，表格用html格式表示。 |
+---
 
-## 🤝 Join Our Community
+## 🔗 Related repositories
 
-<div align="center">
+- **GitHub — training & inference toolkit** (branch `develop`):
+  <https://github.com/Tencent-Hunyuan/HunyuanOCR>
+- **DFlash draft weights** (required for speculative-decoding acceleration):
+  [`tencent/HunyuanOCR/dflash`](https://huggingface.co/tencent/HunyuanOCR/tree/main/dflash)
+- **HunyuanOCR-1.0** (previous generation, archived under `v1.0/`):
+  [`tencent/HunyuanOCR/v1.0`](https://huggingface.co/tencent/HunyuanOCR/tree/main/v1.0)
 
-| Wechat Discussion Group | Discord Group |
-| :---: | :---: |
-| <img src="https://github.com/Tencent-Hunyuan/HunyuanOCR/blob/main/assets/qrcode_for_hunyuanocr_wechat.jpg?raw=true" width="150"> | [Join HunyuanOCR Discord](https://discord.gg/XeD3p2MRDk) |
+---
 
-</div>
+## 📜 License
 
-## 📚 Citation
-```
-@misc{hunyuanvisionteam2025hunyuanocrtechnicalreport,
-      title={HunyuanOCR Technical Report}, 
-      author={Hunyuan Vision Team and Pengyuan Lyu and Xingyu Wan and Gengluo Li and Shangpin Peng and Weinong Wang and Liang Wu and Huawen Shen and Yu Zhou and Canhui Tang and Qi Yang and Qiming Peng and Bin Luo and Hower Yang and Xinsong Zhang and Jinnian Zhang and Houwen Peng and Hongming Yang and Senhao Xie and Longsha Zhou and Ge Pei and Binghong Wu and Kan Wu and Jieneng Yang and Bochao Wang and Kai Liu and Jianchen Zhu and Jie Jiang and Linus and Han Hu and Chengquan Zhang},
-      year={2025},
-      journal={arXiv preprint arXiv:2511.19575},
-      url={https://arxiv.org/abs/2511.19575}, 
-}
-```
+HunyuanOCR-1.5 is released under the same license as HunyuanOCR 1.0 — the
+**Tencent Hunyuan Community License Agreement**.
+
+> ⚠️ **Preview notice.** This checkpoint is a preview snapshot. The technical
+> report and official model release will follow shortly; interfaces and weights
+> may be updated before the final release.
 
-## 🙏 Acknowledgements
-We would like to thank [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR), [MinerU](https://github.com/opendatalab/MinerU), [MonkeyOCR](https://github.com/Yuliang-Liu/MonkeyOCR), [DeepSeek-OCR](https://github.com/deepseek-ai/DeepSeek-OCR), [dots.ocr](https://github.com/rednote-hilab/dots.ocr) for their valuable models and ideas.
-We also appreciate the benchmarks: [OminiDocBench](https://github.com/opendatalab/OmniDocBench), [OCRBench](https://github.com/Yuliang-Liu/MultimodalOCR/tree/main/OCRBench), [DoTA](https://github.com/liangyupu/DIMTDA).

chat_template.jinja

@@ -0,0 +1 @@
+{% if messages[0]['role'] == 'system' %}{% set loop_messages = messages[1:] %}{% if messages[0]['content'] is string %}{% set system_message = messages[0]['content'] %}{% else %}{% set system_message = messages[0]['content']['text'] %}{% endif %}<｜hy_begin▁of▁sentence｜>{{ system_message }}<｜hy_place▁holder▁no▁3｜>{% else %}{% set loop_messages = messages %}<｜hy_begin▁of▁sentence｜>{% endif %}{% for message in loop_messages %}{% if message['role'] == 'user' %}{% if message['content'] is string %}{{ message['content'] }}{% else %}{% for content in message['content'] %}{% if content['type'] == 'image' or 'image' in content or 'image_url' in content %}<｜hy_place▁holder▁no▁100｜><｜hy_place▁holder▁no▁102｜><｜hy_place▁holder▁no▁101｜>{% elif 'text' in content %}{{ content['text'] }}{% endif %}{% endfor %}{% endif %}<｜hy_User｜>{% elif message['role'] == 'assistant' %}{{ message['content'] }}<｜hy_Assistant｜>{% endif %}{% endfor %}

config.json

@@ -6,18 +6,19 @@
   "attention_dropout": 0.0,
   "attention_head_dim": 128,
   "bos_token_id": 120000,
+  "dtype": "bfloat16",
   "eod_token_id": 120020,
   "eos_token_id": 120020,
   "head_dim": 128,
   "hidden_act": "silu",
   "hidden_size": 1024,
-  "image_start_token_id": 120118,
   "image_end_token_id": 120119,
-  "image_token_id": 120120,
   "image_newline_token_id": 120121,
+  "image_start_token_id": 120118,
+  "image_token_id": 120120,
   "initializer_range": 0.02,
   "intermediate_size": 3584,
-  "max_position_embeddings": 32768,
+  "max_position_embeddings": 131072,
   "mlp_bias": false,
   "model_type": "hunyuan_vl",
   "norm_type": "rms",
@@ -27,7 +28,7 @@
   "num_key_value_heads": 8,
   "org_vocab_size": 120818,
   "pad_id": 120002,
-  "pad_token_id": -1,
+  "pad_token_id": 120002,
   "pretraining_tp": 1,
   "rms_norm_eps": 1e-05,
   "rope_scaling": {
@@ -48,33 +49,142 @@
   "rope_theta": 10000.0,
   "routed_scaling_factor": 1.0,
   "sep_token_id": 0,
+  "text_config": {
+    "_name_or_path": "/jizhicfs/shangppeng/save_models/hunyuan/HYOCR_1_5/std_hf/HYOCR_v1_5_SFT/0625_sft_stage2_step300",
+    "add_classification_head": false,
+    "architectures": [
+      "HunYuanVLForConditionalGeneration"
+    ],
+    "attention_bias": false,
+    "attention_dropout": 0.0,
+    "attention_head_dim": 128,
+    "bos_token_id": 120000,
+    "class_num": 0,
+    "dense_list": [
+      1024,
+      0
+    ],
+    "dtype": "bfloat16",
+    "eod_token_id": 120020,
+    "eos_token_id": 120007,
+    "expert_hidden_dim": null,
+    "first_k_dense_replace": 0,
+    "group_limited_greedy": false,
+    "head_dim": 128,
+    "hidden_act": "silu",
+    "hidden_size": 1024,
+    "image_newline_token_id": 120121,
+    "initializer_range": 0.02,
+    "intermediate_size": 3584,
+    "kv_lora_rank": 512,
+    "mask_init_id": 13,
+    "max_position_embeddings": 131072,
+    "mlp_bias": false,
+    "model_type": "hunyuan_vl_text",
+    "moe_drop_tokens": false,
+    "moe_intermediate_size": null,
+    "moe_layer_num_skipped": 0,
+    "moe_random_routing_dropped_token": false,
+    "moe_topk": 1,
+    "mtp_loss_factor": 0.1,
+    "mtp_no_bias": true,
+    "n_group": null,
+    "norm_topk_prob": true,
+    "norm_type": "rms",
+    "num_attention_heads": 16,
+    "num_experts": 1,
+    "num_experts_per_tok": 1,
+    "num_hidden_layers": 24,
+    "num_key_value_heads": 8,
+    "num_nextn_predict_layers": 1,
+    "num_predictor_layers": 0,
+    "num_shared_expert": 1,
+    "num_shared_experts": 1,
+    "org_vocab_size": 120818,
+    "pad_id": 120002,
+    "pad_token_id": 120002,
+    "pool_type": "last",
+    "pretraining_tp": 1,
+    "q_lora_rank": 1536,
+    "qk_nope_head_dim": 128,
+    "qk_norm": false,
+    "qk_rope_head_dim": 64,
+    "rms_norm_eps": 1e-05,
+    "rope_scaling": {
+      "alpha": 1000.0,
+      "beta_fast": 32,
+      "beta_slow": 1,
+      "factor": 1.0,
+      "mscale": 1.0,
+      "mscale_all_dim": 1.0,
+      "type": "xdrope",
+      "xdrope_section": [
+        16,
+        16,
+        16,
+        16
+      ]
+    },
+    "rope_theta": 10000.0,
+    "routed_scaling_factor": 1.0,
+    "sep_token_id": 0,
+    "text_end_id": 8,
+    "text_start_id": 7,
+    "tie_word_embeddings": true,
+    "topk_group": null,
+    "use_cache": true,
+    "use_cla": false,
+    "use_mixed_mlp_moe": false,
+    "use_mla": false,
+    "use_qk_norm": true,
+    "use_rotary_pos_emb": true,
+    "v_head_dim": 128,
+    "vision_full_attention": false,
+    "vocab_size": 120818
+  },
   "text_end_id": 8,
   "text_start_id": 7,
-  "tie_word_embeddings": true,
-  "dtype": "bfloat16",
-  "transformers_version": "4.49.0",
+  "transformers_version": "4.57.1",
   "use_cache": true,
-  "use_qk_norm": true,
   "use_cla": false,
+  "use_qk_norm": true,
+  "video_end_token_id": 120123,
+  "video_start_token_id": 120122,
   "vision_config": {
     "add_patchemb_bias": true,
+    "anyres_vit_max_image_size": 2048,
     "attention_dropout": 0.0,
     "cat_extra_token": 1,
+    "dtype": "bfloat16",
     "hidden_act": "gelu",
     "hidden_dropout": 0.0,
     "hidden_size": 1152,
-    "img_max_token_num": 4096,
+    "img_max_token_num": 16384,
     "intermediate_size": 4304,
     "interpolate_mode": "bilinear",
+    "learnable_mlp_pooling_size": 0,
     "max_image_size": 2048,
-    "max_vit_seq_len": 16384,
+    "max_vit_seq_len": 65536,
+    "min_image_size": 512,
+    "model_type": "hunyuan_vl",
     "num_attention_heads": 16,
     "num_channels": 3,
     "num_hidden_layers": 27,
+    "num_key_value_heads": 16,
     "out_hidden_size": 1024,
     "patch_size": 16,
+    "perceive_post_norm": true,
+    "perceive_pre_norm": true,
+    "remove_prenorm": true,
+    "resize_resolution": 2048,
     "rms_norm_eps": 1e-05,
-    "spatial_merge_size": 2
+    "spatial_merge_size": 2,
+    "spatial_patch_size": 1,
+    "temporal_patch_size": 1,
+    "text_hidden_size": 1024,
+    "video_max_image_size": 768,
+    "video_min_image_size": 256,
+    "vision_full_attention": false
   },
   "vocab_size": 120818
 }

dflash/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

dflash/README.md

@@ -0,0 +1,172 @@
+---
+license: other
+license_name: tencent-hunyuan-community
+license_link: https://huggingface.co/tencent/HunyuanOCR/blob/main/LICENSE
+tags:
+- ocr
+- speculative-decoding
+- draft-model
+- dflash
+- block-diffusion
+- vision-language-model
+base_model: tencent/HunyuanOCR
+library_name: transformers
+---
+
+# HunyuanOCR-1.5 · DFlash Draft  ·  Preview
+
+<div align="center">
+
+**Speculative-decoding draft for [`tencent/HunyuanOCR`](https://huggingface.co/tencent/HunyuanOCR)**
+
+</div>
+
+
+> ⚠️ **This model is not usable standalone.** It is a *draft model* used only
+> for **speculative decoding** together with the target model
+> [`tencent/HunyuanOCR`](https://huggingface.co/tencent/HunyuanOCR).
+
+---
+
+## 📖 What is DFlash?
+
+End-to-end OCR is often accompanied by long autoregressive decoding — the major
+bottleneck for dense documents, tables, formulas, and other long structured
+outputs.
+
+HunyuanOCR-1.5 adopts a speculative-decoding framework based on **DFlash**:
+
+- A lightweight **block-diffusion** draft model (this repo) proposes multiple
+  candidate tokens **in parallel**.
+- The target model
+  ([`tencent/HunyuanOCR`](https://huggingface.co/tencent/HunyuanOCR))
+  verifies them in a **single forward pass**.
+- Accepted tokens are committed as-is, so the **output distribution of the
+  target model is preserved** — DFlash is a lossless acceleration.
+
+The result is significantly reduced decoding latency for long structured OCR
+outputs, without sacrificing accuracy.
+
+Architecture: 5-layer Qwen3-style block-diffusion draft, predicting 16 masked tokens in a single block. The draft is bound to
+target-layer indices `[1, 8, 15, 22]` of the 24-layer HunyuanOCR-1.5 base.
+
+---
+
+## ⚙️ Environment
+
+- Python 3.10+
+- PyTorch 2.1+ (CUDA 12.1+)
+- **transformers**
+- **vLLM nightly** — required for real speculative-decoding speedup at
+  deployment time. DFlash support is included in the nightly wheel; no separate
+  patch is needed.
+
+```bash
+uv pip install -U vllm \
+    --torch-backend=cu130 \
+    --extra-index-url https://wheels.vllm.ai/nightly
+uv pip install runai-model-streamer
+```
+
+> 💡 On CUDA 12.x, replace `--torch-backend=cu130` with the matching tag
+> (e.g. `cu121`, `cu124`).
+---
+
+## 🚀 How to use
+
+### A. transformers — draft-load check
+
+Use the shipped script from the GitHub repo. It loads the draft, runs it
+alongside the target for one image, and verifies that the AR reference matches:
+
+```bash
+git clone -b develop https://github.com/Tencent-Hunyuan/HunyuanOCR.git
+cd HunyuanOCR
+
+python inference/infer_dflash.py \
+    --model        tencent/HunyuanOCR \
+    --dflash-model ./hunyuanocr_dflash \
+    --image        /path/to/document.png \
+    --num-spec-tokens 15
+```
+
+> ℹ️ `infer_dflash.py` only verifies that the DFlash draft loads and
+> produces a matching AR reference on a single image. **Real
+> speculative-decoding acceleration is only realized under vLLM**, see below.
+
+> ⬇️ **Preparing the draft directory.** The DFlash draft lives under the
+> `dflash/` subfolder of `tencent/HunyuanOCR`. Because vLLM's
+> `--speculative-config` and `trust_remote_code` custom-code loading do not
+> support HF subfolders, download that subfolder into a **flat local
+> directory** first and point the draft path at it:
+>
+> ```bash
+> python -c "from huggingface_hub import snapshot_download; import shutil, os; \
+> d=snapshot_download('tencent/HunyuanOCR', allow_patterns=['dflash/*']); \
+> shutil.copytree(os.path.join(d,'dflash'), './hunyuanocr_dflash', dirs_exist_ok=True)"
+> ```
+>
+> Then use `./hunyuanocr_dflash` as the draft path in the commands below.
+
+### B. vLLM speculative decoding
+
+```bash
+MODEL_PATH=tencent/HunyuanOCR \
+DFLASH_PATH=./hunyuanocr_dflash \
+GPU=0 PORT=8001 GPU_MEM_UTIL=0.9 \
+NUM_SPEC_TOKENS=15 \
+bash inference/serve_dflash.sh
+```
+
+Under the hood the launch script passes:
+
+```
+--speculative-config '{"method":"dflash","model":"./hunyuanocr_dflash","num_speculative_tokens":15}'
+```
+
+to the vLLM entrypoint. Send an OpenAI-compatible request with the shipped
+single-image client:
+
+```bash
+python inference/infer_vllm_client.py \
+    --host 127.0.0.1 --port 8001 \
+    --model tencent/HunyuanOCR \
+    --image /path/to/document.png
+```
+
+### C. llama.cpp (PC-side)
+
+A DFlash-adapted `llama.cpp` fork is provided for CPU / consumer-GPU / laptop
+speculative decoding. See `docs/llama_cpp.md` in the GitHub repo for the full
+guide (GGUF conversion of both target + draft, `llama-server` launch, and a
+smoke-test client).
+
+---
+
+## 📦 Files in this repo
+
+| file | purpose |
+|---|---|
+| `model.safetensors` | draft weights (float32) |
+| `config.json` | draft config; sets `auto_map` to `dflash.DFlashDraftModel` |
+| `dflash.py` | `DFlashDraftModel` implementation (loaded via `trust_remote_code=True`) |
+| `chat_template.jinja`, `tokenizer.json`, `tokenizer_config.json`, `processor_config.json` | tokenizer / processor, kept in sync with the target model |
+
+---
+
+## 🔗 Related repositories
+
+- **Target model** (required):
+  [`tencent/HunyuanOCR`](https://huggingface.co/tencent/HunyuanOCR)
+- **GitHub — training & inference toolkit** (branch `develop`):
+  <https://github.com/Tencent-Hunyuan/HunyuanOCR>
+- **HunyuanOCR-1.0** (previous generation, archived under `v1.0/`):
+  [`tencent/HunyuanOCR/v1.0`](https://huggingface.co/tencent/HunyuanOCR/tree/main/v1.0)
+
+---
+
+## 📜 License
+
+HunyuanOCR-1.5 (including the DFlash draft) is released under the same license
+as HunyuanOCR 1.0 — the **Tencent Hunyuan Community License Agreement**.
+

dflash/chat_template.jinja

@@ -0,0 +1 @@
+{% if messages[0]['role'] == 'system' %}{% set loop_messages = messages[1:] %}{% if messages[0]['content'] is string %}{% set system_message = messages[0]['content'] %}{% else %}{% set system_message = messages[0]['content']['text'] %}{% endif %}<｜hy_begin▁of▁sentence｜>{{ system_message }}<｜hy_place▁holder▁no▁3｜>{% else %}{% set loop_messages = messages %}<｜hy_begin▁of▁sentence｜>{% endif %}{% for message in loop_messages %}{% if message['role'] == 'user' %}{% if message['content'] is string %}{{ message['content'] }}{% else %}{% for content in message['content'] %}{% if content['type'] == 'image' or 'image' in content or 'image_url' in content %}<｜hy_place▁holder▁no▁100｜><｜hy_place▁holder▁no▁102｜><｜hy_place▁holder▁no▁101｜>{% elif 'text' in content %}{{ content['text'] }}{% endif %}{% endfor %}{% endif %}<｜hy_User｜>{% elif message['role'] == 'assistant' %}{{ message['content'] }}<｜hy_Assistant｜>{% endif %}{% endfor %}

dflash/config.json

@@ -0,0 +1,51 @@
+{
+  "architectures": [
+    "DFlashDraftModel"
+  ],
+  "attention_bias": false,
+  "attention_dropout": 0.0,
+  "auto_map": {
+    "AutoModel": "dflash.DFlashDraftModel"
+  },
+  "block_size": 16,
+  "dflash_config": {
+    "mask_token_id": 120817,
+    "target_layer_ids": [
+      1,
+      8,
+      15,
+      22
+    ]
+  },
+  "dtype": "float32",
+  "eos_token_id": 120007,
+  "head_dim": 128,
+  "hidden_act": "silu",
+  "hidden_size": 1024,
+  "initializer_range": 0.02,
+  "intermediate_size": 3584,
+  "layer_types": [
+    "full_attention",
+    "full_attention",
+    "full_attention",
+    "full_attention",
+    "full_attention"
+  ],
+  "max_position_embeddings": 131072,
+  "max_window_layers": 5,
+  "model_type": "qwen3",
+  "num_attention_heads": 16,
+  "num_hidden_layers": 5,
+  "num_key_value_heads": 8,
+  "num_target_layers": 24,
+  "pad_token_id": 120002,
+  "rms_norm_eps": 1e-05,
+  "rope_scaling": null,
+  "rope_theta": 10000.0,
+  "sliding_window": null,
+  "tie_word_embeddings": true,
+  "transformers_version": "4.57.1",
+  "use_cache": true,
+  "use_sliding_window": false,
+  "vocab_size": 120818
+}

dflash/dflash.py

@@ -0,0 +1,188 @@
+from typing import Optional, Callable
+from typing_extensions import Unpack, Tuple
+import torch
+from torch import nn
+from transformers.models.qwen3.modeling_qwen3 import (
+    Qwen3RMSNorm,
+    Qwen3RotaryEmbedding,
+    Qwen3Config,
+    Qwen3PreTrainedModel,
+    Qwen3MLP,
+    GradientCheckpointingLayer,
+    FlashAttentionKwargs,
+    rotate_half,
+    eager_attention_forward,
+    ALL_ATTENTION_FUNCTIONS,
+)
+from transformers.modeling_outputs import CausalLMOutputWithPast
+from transformers.cache_utils import Cache
+
+def apply_rotary_pos_emb(q, k, cos, sin, position_ids=None, unsqueeze_dim=1):
+    cos = cos.unsqueeze(unsqueeze_dim)
+    sin = sin.unsqueeze(unsqueeze_dim)
+    q_len = q.size(-2)
+    q_embed = (q * cos[..., -q_len:, :]) + (rotate_half(q) * sin[..., -q_len:, :])
+    k_embed = (k * cos) + (rotate_half(k) * sin)
+    return q_embed, k_embed
+
+class Qwen3DFlashAttention(nn.Module):
+    """Multi-headed attention from 'Attention Is All You Need' paper"""
+
+    def __init__(self, config: Qwen3Config, layer_idx: int):
+        super().__init__()
+        self.config = config
+        self.layer_idx = layer_idx
+        self.head_dim = getattr(config, "head_dim", config.hidden_size // config.num_attention_heads)
+        self.num_key_value_groups = config.num_attention_heads // config.num_key_value_heads
+        self.scaling = self.head_dim**-0.5
+        self.attention_dropout = config.attention_dropout
+        self.is_causal = False  
+        self.q_proj = nn.Linear(
+            config.hidden_size, config.num_attention_heads * self.head_dim, bias=config.attention_bias
+        )
+        self.k_proj = nn.Linear(
+            config.hidden_size, config.num_key_value_heads * self.head_dim, bias=config.attention_bias
+        )
+        self.v_proj = nn.Linear(
+            config.hidden_size, config.num_key_value_heads * self.head_dim, bias=config.attention_bias
+        )
+        self.o_proj = nn.Linear(
+            config.num_attention_heads * self.head_dim, config.hidden_size, bias=config.attention_bias
+        )
+        self.q_norm = Qwen3RMSNorm(self.head_dim, eps=config.rms_norm_eps)
+        self.k_norm = Qwen3RMSNorm(self.head_dim, eps=config.rms_norm_eps)
+        self.sliding_window = config.sliding_window if config.layer_types[layer_idx] == "sliding_attention" else None
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        target_hidden: torch.Tensor,
+        position_embeddings: tuple[torch.Tensor, torch.Tensor],
+        attention_mask: Optional[torch.Tensor],
+        past_key_values: Optional[Cache] = None,
+        cache_position: Optional[torch.LongTensor] = None,
+        **kwargs: Unpack[FlashAttentionKwargs],
+    ) -> tuple[torch.Tensor, Optional[torch.Tensor]]:
+        bsz, q_len = hidden_states.shape[:-1]
+        ctx_len = target_hidden.shape[1]
+        q = self.q_proj(hidden_states)
+        q = q.view(bsz, q_len, -1, self.head_dim)
+        q = self.q_norm(q).transpose(1, 2)
+        k_ctx = self.k_proj(target_hidden)
+        k_noise = self.k_proj(hidden_states)
+        v_ctx = self.v_proj(target_hidden)
+        v_noise = self.v_proj(hidden_states)
+        k = torch.cat([k_ctx, k_noise], dim=1).view(bsz, ctx_len + q_len, -1, self.head_dim)
+        v = torch.cat([v_ctx, v_noise], dim=1).view(bsz, ctx_len + q_len, -1, self.head_dim)
+        k = self.k_norm(k).transpose(1, 2)
+        v = v.transpose(1, 2)
+        cos, sin = position_embeddings
+        q, k = apply_rotary_pos_emb(q, k, cos, sin)
+        if past_key_values is not None:
+            cache_kwargs = {"sin": sin, "cos": cos, "cache_position": cache_position}
+            k, v = past_key_values.update(k, v, self.layer_idx, cache_kwargs)
+        attn_fn: Callable = eager_attention_forward
+        if self.config._attn_implementation != "eager":
+            attn_fn = ALL_ATTENTION_FUNCTIONS[self.config._attn_implementation]
+        attn_output, attn_weights = attn_fn(
+            self,
+            q,
+            k,
+            v,
+            attention_mask,
+            dropout=0.0 if not self.training else self.attention_dropout,
+            scaling=self.scaling,
+            sliding_window=self.sliding_window,
+            **kwargs,
+        )
+        attn_output = attn_output.reshape(bsz, q_len, -1)
+        attn_output = self.o_proj(attn_output)
+        return attn_output, attn_weights
+
+class Qwen3DFlashDecoderLayer(GradientCheckpointingLayer):
+    def __init__(self, config: Qwen3Config, layer_idx: int):
+        super().__init__()
+        self.hidden_size = config.hidden_size
+        self.self_attn = Qwen3DFlashAttention(config=config, layer_idx=layer_idx)
+        self.mlp = Qwen3MLP(config)
+        self.input_layernorm = Qwen3RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+        self.post_attention_layernorm = Qwen3RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+
+    def forward(
+        self,
+        target_hidden: Optional[torch.Tensor] = None,
+        hidden_states: Optional[torch.Tensor] = None,
+        attention_mask: Optional[torch.Tensor] = None,
+        position_ids: Optional[torch.LongTensor] = None,
+        past_key_value: Optional[Cache] = None,
+        output_attentions: Optional[bool] = False,
+        use_cache: Optional[bool] = False,
+        cache_position: Optional[torch.LongTensor] = None,
+        position_embeddings: Optional[Tuple[torch.Tensor, torch.Tensor]] = None,  # necessary, but kept here for BC
+        **kwargs: Unpack[FlashAttentionKwargs],
+    ) -> Tuple[torch.FloatTensor, Optional[Tuple[torch.FloatTensor, torch.FloatTensor]]]:
+        residual = hidden_states
+        hidden_states = self.input_layernorm(hidden_states)
+        hidden_states = self.self_attn(
+            hidden_states=hidden_states,
+            target_hidden=target_hidden,
+            attention_mask=attention_mask,
+            position_ids=position_ids,
+            past_key_values=past_key_value,
+            output_attentions=output_attentions,
+            use_cache=use_cache,
+            cache_position=cache_position,
+            position_embeddings=position_embeddings,
+            **kwargs,
+        )[0]
+        hidden_states = residual + hidden_states
+        residual = hidden_states
+        hidden_states = self.post_attention_layernorm(hidden_states)
+        hidden_states = self.mlp(hidden_states)
+        hidden_states = residual + hidden_states
+        return hidden_states
+
+class DFlashDraftModel(Qwen3PreTrainedModel):
+    config_class = Qwen3Config
+    _no_split_modules = ["Qwen3DFlashDecoderLayer"]
+
+    def __init__(self, config) -> None:
+        super().__init__(config)
+        self.config = config
+        self.layers = nn.ModuleList(
+            [Qwen3DFlashDecoderLayer(config, layer_idx) for layer_idx in range(config.num_hidden_layers)]
+        )
+        self.target_layer_ids = self.config.dflash_config.get("target_layer_ids", None)
+        self.norm = Qwen3RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+        self.rotary_emb = Qwen3RotaryEmbedding(config)
+        self.fc = nn.Linear(len(self.target_layer_ids) * config.hidden_size, config.hidden_size, bias=False)
+        self.hidden_norm = Qwen3RMSNorm(config.hidden_size, eps=config.rms_norm_eps)
+        self.block_size = config.block_size
+        self.mask_token_id = self.config.dflash_config.get("mask_token_id", None)
+        self.post_init()
+
+    def forward(
+        self,
+        position_ids: torch.LongTensor,
+        attention_mask: Optional[torch.Tensor] = None,
+        noise_embedding: Optional[torch.Tensor] = None,
+        target_hidden: Optional[torch.Tensor] = None,
+        past_key_values: Optional[Cache] = None,
+        use_cache: bool = False,
+        **kwargs,
+    ) -> CausalLMOutputWithPast:
+        hidden_states = noise_embedding
+        target_hidden = self.hidden_norm(self.fc(target_hidden))
+        position_embeddings = self.rotary_emb(hidden_states, position_ids)
+        for layer in self.layers:
+            hidden_states = layer(
+                hidden_states=hidden_states,
+                target_hidden=target_hidden,
+                attention_mask=attention_mask,
+                position_ids=position_ids,
+                past_key_value=past_key_values,
+                use_cache=use_cache,
+                position_embeddings=position_embeddings,
+                **kwargs,
+            )
+        return self.norm(hidden_states)

dflash/model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9b189f2c0d2b0251d697c19790c2a9b5416da5fc2981edfaab9673ac76b5d513
+size 362867640

dflash/processor_config.json

@@ -0,0 +1,65 @@
+{
+  "image_processor": {
+    "do_convert_rgb": true,
+    "do_normalize": true,
+    "do_rescale": true,
+    "do_resize": true,
+    "image_mean": [
+      0.48145466,
+      0.4578275,
+      0.40821073
+    ],
+    "image_processor_type": "HunYuanVLImageProcessor",
+    "image_std": [
+      0.26862954,
+      0.26130258,
+      0.27577711
+    ],
+    "max_pixels": 16777216,
+    "merge_size": 2,
+    "min_pixels": 262144,
+    "patch_size": 16,
+    "resample": 1,
+    "rescale_factor": 0.00392156862745098,
+    "size": {
+      "longest_edge": 16777216,
+      "shortest_edge": 262144
+    },
+    "temporal_patch_size": 1
+  },
+  "processor_class": "HunYuanVLProcessor",
+  "video_processor": {
+    "data_format": "channels_first",
+    "default_to_square": true,
+    "do_convert_rgb": true,
+    "do_normalize": true,
+    "do_rescale": true,
+    "do_resize": true,
+    "do_sample_frames": false,
+    "image_mean": [
+      0.48145466,
+      0.4578275,
+      0.40821073
+    ],
+    "image_std": [
+      0.26862954,
+      0.26130258,
+      0.27577711
+    ],
+    "max_frames": 768,
+    "max_pixels": 4194304,
+    "merge_size": 2,
+    "min_frames": 4,
+    "min_pixels": 262144,
+    "patch_size": 16,
+    "resample": 3,
+    "rescale_factor": 0.00392156862745098,
+    "return_metadata": false,
+    "size": {
+      "longest_edge": 4194304,
+      "shortest_edge": 262144
+    },
+    "temporal_patch_size": 1,
+    "video_processor_type": "HunYuanVLVideoProcessor"
+  }
+}

dflash/tokenizer_config.json

@@ -0,0 +1,26 @@
+{
+  "backend": "tokenizers",
+  "bos_token": "<｜hy_begin▁of▁sentence｜>",
+  "clean_up_tokenization_spaces": true,
+  "eos_token": "<｜hy_Assistant｜>",
+  "image_end_token": "<｜hy_place▁holder▁no▁101｜>",
+  "image_start_token": "<｜hy_place▁holder▁no▁100｜>",
+  "image_token": "<｜hy_place▁holder▁no▁102｜>",
+  "is_local": true,
+  "local_files_only": false,
+  "model_max_length": 1000000000000000019884624838656,
+  "model_specific_special_tokens": {
+    "image_end_token": "<｜hy_place▁holder▁no▁101｜>",
+    "image_start_token": "<｜hy_place▁holder▁no▁100｜>",
+    "image_token": "<｜hy_place▁holder▁no▁102｜>",
+    "video_end_token": "<｜hy_place▁holder▁no▁105｜>",
+    "video_start_token": "<｜hy_place▁holder▁no▁104｜>",
+    "video_token": "<｜hy_place▁holder▁no▁665｜>"
+  },
+  "pad_token": "<｜hy_▁pad▁｜>",
+  "processor_class": "HunYuanVLProcessor",
+  "tokenizer_class": "TokenizersBackend",
+  "video_end_token": "<｜hy_place▁holder▁no▁105｜>",
+  "video_start_token": "<｜hy_place▁holder▁no▁104｜>",
+  "video_token": "<｜hy_place▁holder▁no▁665｜>"
+}

generation_config.json

@@ -1,13 +1,7 @@
 {
+  "_from_model_config": true,
   "bos_token_id": 120000,
+  "eos_token_id": 120020,
   "pad_token_id": 120002,
-  "do_sample": true,
-  "eos_token_id": [
-    120007,
-    120020
-  ],
-  "repetition_penalty": 1.03,
-  "top_k": 1,
-  "top_p": 1.0,
-  "temperature":0.0
+  "transformers_version": "4.57.1"
 }

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:632a1e082c4dd5a3284cf1ffcdba2fdaa06f435762c58c2f34aff0f3bd6c0249
+size 2239932512

preprocessor_config.json

@@ -1,20 +1,29 @@
 {
-  "min_pixels": 262144,
-  "max_pixels": 4194304,
-  "patch_size": 16,
-  "resample": 1,
-  "temporal_patch_size": 1,
-  "merge_size": 2,
+  "do_convert_rgb": true,
+  "do_normalize": true,
+  "do_rescale": true,
+  "do_resize": true,
   "image_mean": [
     0.48145466,
     0.4578275,
     0.40821073
   ],
+  "image_processor_type": "HunYuanVLImageProcessor",
   "image_std": [
     0.26862954,
     0.26130258,
     0.27577711
   ],
-  "image_processor_type": "HunYuanVLImageProcessor",
-  "processor_class": "HunYuanVLProcessor"
+  "max_pixels": 16777216,
+  "merge_size": 2,
+  "min_pixels": 262144,
+  "patch_size": 16,
+  "processor_class": "HunYuanVLProcessor",
+  "resample": 1,
+  "rescale_factor": 0.00392156862745098,
+  "size": {
+    "longest_edge": 4194304,
+    "shortest_edge": 262144
+  },
+  "temporal_patch_size": 1
 }

special_tokens_map.json

@@ -1,5 +1,29 @@
 {
-  "bos_token": "<｜hy_begin▁of▁sentence｜>",
-  "eos_token": "<｜hy_place▁holder▁no▁2｜>",
-  "pad_token": "<｜hy_▁pad▁｜>"
+  "bos_token": {
+    "content": "<｜hy_begin▁of▁sentence｜>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "eos_token": {
+    "content": "<｜hy_Assistant｜>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "image_end_token": "<｜hy_place▁holder▁no▁101｜>",
+  "image_start_token": "<｜hy_place▁holder▁no▁100｜>",
+  "image_token": "<｜hy_place▁holder▁no▁102｜>",
+  "pad_token": {
+    "content": "<｜hy_▁pad▁｜>",
+    "lstrip": false,
+    "normalized": false,
+    "rstrip": false,
+    "single_word": false
+  },
+  "video_end_token": "<｜hy_place▁holder▁no▁105｜>",
+  "video_start_token": "<｜hy_place▁holder▁no▁104｜>",
+  "video_token": "<｜hy_place▁holder▁no▁665｜>"
 }

tokenizer_config.json

@@ -6548,15 +6548,22 @@
   "bos_token": "<｜hy_begin▁of▁sentence｜>",
   "clean_up_tokenization_spaces": true,
   "eos_token": "<｜hy_Assistant｜>",
-  "model_max_length": 1000000000000000019884624838656,
-  "pad_token": "<｜hy_▁pad▁｜>",
   "extra_special_tokens": {
-    "image_token": "<｜hy_place▁holder▁no▁102｜>",
-    "image_start_token": "<｜hy_place▁holder▁no▁100｜>",
     "image_end_token": "<｜hy_place▁holder▁no▁101｜>",
+    "image_start_token": "<｜hy_place▁holder▁no▁100｜>",
+    "image_token": "<｜hy_place▁holder▁no▁102｜>",
+    "video_end_token": "<｜hy_place▁holder▁no▁105｜>",
     "video_start_token": "<｜hy_place▁holder▁no▁104｜>",
-    "video_end_token": "<｜hy_place▁holder▁no▁105｜>"
+    "video_token": "<｜hy_place▁holder▁no▁665｜>"
   },
+  "image_end_token": "<｜hy_place▁holder▁no▁101｜>",
+  "image_start_token": "<｜hy_place▁holder▁no▁100｜>",
+  "image_token": "<｜hy_place▁holder▁no▁102｜>",
+  "model_max_length": 1000000000000000019884624838656,
+  "pad_token": "<｜hy_▁pad▁｜>",
+  "processor_class": "HunYuanVLProcessor",
   "tokenizer_class": "PreTrainedTokenizerFast",
-  "chat_template": "{% if messages[0]['role'] == 'system' %}{% set loop_messages = messages[1:] %}{% if messages[0]['content'] is string %}{% set system_message = messages[0]['content'] %}{% else %}{% set system_message = messages[0]['content']['text'] %}{% endif %}<｜hy_begin▁of▁sentence｜>{{ system_message }}<｜hy_place▁holder▁no▁3｜>{% else %}{% set loop_messages = messages %}<｜hy_begin▁of▁sentence｜>{% endif %}{% for message in loop_messages %}{% if message['role'] == 'user' %}{% if message['content'] is string %}{{ message['content'] }}{% else %}{% for content in message['content'] %}{% if content['type'] == 'image' or 'image' in content or 'image_url' in content %}<｜hy_place▁holder▁no▁100｜><｜hy_place▁holder▁no▁102｜><｜hy_place▁holder▁no▁101｜>{% elif 'text' in content %}{{ content['text'] }}{% endif %}{% endfor %}{% endif %}<｜hy_User｜>{% elif message['role'] == 'assistant' %}{{ message['content'] }}<｜hy_Assistant｜>{% endif %}{% endfor %}"
+  "video_end_token": "<｜hy_place▁holder▁no▁105｜>",
+  "video_start_token": "<｜hy_place▁holder▁no▁104｜>",
+  "video_token": "<｜hy_place▁holder▁no▁665｜>"
 }

v1.0/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

v1.0/LICENSE

@@ -0,0 +1,78 @@
+TENCENT HUNYUAN COMMUNITY LICENSE AGREEMENT
+Tencent HunyuanOCR Release Date: November 25, 2025
+THIS LICENSE AGREEMENT DOES NOT APPLY IN THE EUROPEAN UNION, UNITED KINGDOM AND SOUTH KOREA AND IS EXPRESSLY LIMITED TO THE TERRITORY, AS DEFINED BELOW.
+By clicking to agree or by using, reproducing, modifying, distributing, performing or displaying any portion or element of the Tencent Hunyuan Works, including via any Hosted Service, You will be deemed to have recognized and accepted the content of this Agreement, which is effective immediately.
+1.	DEFINITIONS.
+a.	“Acceptable Use Policy” shall mean the policy made available by Tencent as set forth in the Exhibit A.
+b.	“Agreement” shall mean the terms and conditions for use, reproduction, distribution, modification, performance and displaying of Tencent Hunyuan Works or any portion or element thereof set forth herein.
+c.	“Documentation” shall mean the specifications, manuals and documentation for Tencent Hunyuan made publicly available by Tencent.
+d.	“Hosted Service” shall mean a hosted service offered via an application programming interface (API), web access, or any other electronic or remote means.
+e.	“Licensee,” “You” or “Your” shall mean a natural person or legal entity exercising the rights granted by this Agreement and/or using the Tencent Hunyuan Works for any purpose and in any field of use.
+f.	“Materials” shall mean, collectively, Tencent’s proprietary Tencent Hunyuan and Documentation (and any portion thereof) as made available by Tencent under this Agreement.
+g.	“Model Derivatives” shall mean all: (i) modifications to Tencent Hunyuan or any Model Derivative of Tencent Hunyuan; (ii) works based on Tencent Hunyuan or any Model Derivative of Tencent Hunyuan; or (iii) any other machine learning model which is created by transfer of patterns of the weights, parameters, operations, or Output of Tencent Hunyuan or any Model Derivative of Tencent Hunyuan, to that model in order to cause that model to perform similarly to Tencent Hunyuan or a Model Derivative of Tencent Hunyuan, including distillation methods, methods that use intermediate data representations, or methods based on the generation of synthetic data Outputs by Tencent Hunyuan or a Model Derivative of Tencent Hunyuan for training that model. For clarity, Outputs by themselves are not deemed Model Derivatives.
+h.	“Output” shall mean the information and/or content output of Tencent Hunyuan or a Model Derivative that results from operating or otherwise using Tencent Hunyuan or a Model Derivative, including via a Hosted Service.
+i.	“Tencent,” “We” or “Us” shall mean the applicable entity or entities in the Tencent corporate family that own(s) intellectual property or other rights embodied in or utilized by the Materials.
+j.	“Tencent Hunyuan” shall mean the large language models, text/image/video/audio/3D generation models, and multimodal large language models and their software and algorithms, including trained model weights, parameters (including optimizer states), machine-learning model code, inference-enabling code, training-enabling code, fine-tuning enabling code and other elements of the foregoing made publicly available by Us, including, without limitation to, Tencent HunyuanOCR released at [https://huggingface.co/tencent/HunyuanOCR].
+k.	“Tencent Hunyuan Works” shall mean: (i) the Materials; (ii) Model Derivatives; and (iii) all derivative works thereof.
+l.	“Territory” shall mean the worldwide territory, excluding the territory of the European Union, United Kingdom and South Korea. 
+m.	“Third Party” or “Third Parties” shall mean individuals or legal entities that are not under common control with Us or You.
+n.	“including” shall mean including but not limited to.
+2.	GRANT OF RIGHTS.
+We grant You, for the Territory only, a non-exclusive, non-transferable and royalty-free limited license under Tencent’s intellectual property or other rights owned by Us embodied in or utilized by the Materials to use, reproduce, distribute, create derivative works of (including Model Derivatives), and make modifications to the Materials, only in accordance with the terms of this Agreement and the Acceptable Use Policy, and You must not violate (or encourage or permit anyone else to violate) any term of this Agreement or the Acceptable Use Policy.
+3.	DISTRIBUTION.
+You may, subject to Your compliance with this Agreement, distribute or make available to Third Parties the Tencent Hunyuan Works, exclusively in the Territory, provided that You meet all of the following conditions:
+a.	You must provide all such Third Party recipients of the Tencent Hunyuan Works or products or services using them a copy of this Agreement;
+b.	You must cause any modified files to carry prominent notices stating that You changed the files;
+c.	You are encouraged to: (i) publish at least one technology introduction blogpost or one public statement expressing Your experience of using the Tencent Hunyuan Works; and (ii) mark the products or services developed by using the Tencent Hunyuan Works to indicate that the product/service is “Powered by Tencent Hunyuan”; and
+d.	All distributions to Third Parties (other than through a Hosted Service) must be accompanied by a “Notice” text file that contains the following notice: “Tencent Hunyuan is licensed under the Tencent Hunyuan Community License Agreement, Copyright © 2025 Tencent. All Rights Reserved. The trademark rights of “Tencent Hunyuan” are owned by Tencent or its affiliate.”
+e.	In the event that You use, integrate, implement, or otherwise deploy the Tencent Hunyuan Works, in whole or in part, to provide, enable, or support any service, product, or functionality to third parties, You shall clearly, accurately, and prominently disclose to all end users the full legal name and entity of the actual provider of such service, product, or functionality. You shall expressly and conspicuously state that Tencent is not affiliated with, associated with, sponsoring, or endorsing any such service, product, or functionality. You shall not use or display any name, logo, trademark, trade name, or other indicia of Tencent in any manner that could be construed as, or be likely to create, confusion, deception, or a false impression regarding any relationship, affiliation, sponsorship, or endorsement by Tencent.
+You may add Your own copyright statement to Your modifications and, except as set forth in this Section and in Section 5, may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Model Derivatives as a whole, provided Your use, reproduction, modification, distribution, performance and display of the work otherwise complies with the terms and conditions of this Agreement (including as regards the Territory). If You receive Tencent Hunyuan Works from a Licensee as part of an integrated end user product, then this Section 3 of this Agreement will not apply to You.
+4.	ADDITIONAL COMMERCIAL TERMS.
+If, on the Tencent Hunyuan version release date, the monthly active users of all products or services made available by or for Licensee is greater than 100 million monthly active users in the preceding calendar month, You must request a license from Tencent, which Tencent may grant to You in its sole discretion, and You are not authorized to exercise any of the rights under this Agreement unless or until Tencent otherwise expressly grants You such rights.
+5.	RULES OF USE.
+a.	Your use of the Tencent Hunyuan Works must comply with applicable laws and regulations (including trade compliance laws and regulations) and adhere to the Acceptable Use Policy for the Tencent Hunyuan Works, which is hereby incorporated by reference into this Agreement. You must include the use restrictions referenced in these Sections 5(a) and 5(b) as an enforceable provision in any agreement (e.g., license agreement, terms of use, etc.) governing the use and/or distribution of Tencent Hunyuan Works and You must provide notice to subsequent users to whom You distribute that Tencent Hunyuan Works are subject to the use restrictions in these Sections 5(a) and 5(b).
+b.	You must not use the Tencent Hunyuan Works or any Output or results of the Tencent Hunyuan Works to improve any other AI model (other than Tencent Hunyuan or Model Derivatives thereof).
+c.	You must not use, reproduce, modify, distribute, or display the Tencent Hunyuan Works, Output or results of the Tencent Hunyuan Works outside the Territory. Any such use outside the Territory is unlicensed and unauthorized under this Agreement.
+6.	INTELLECTUAL PROPERTY.
+a.	Subject to Tencent’s ownership of Tencent Hunyuan Works made by or for Tencent and intellectual property rights therein, conditioned upon Your compliance with the terms and conditions of this Agreement, as between You and Tencent, You will be the owner of any derivative works and modifications of the Materials and any Model Derivatives that are made by or for You.
+b.	No trademark licenses are granted under this Agreement, and in connection with the Tencent Hunyuan Works, Licensee may not use any name or mark owned by or associated with Tencent or any of its affiliates, except as required for reasonable and customary use in describing and distributing the Tencent Hunyuan Works. Tencent hereby grants You a license to use “Tencent Hunyuan” (the “Mark”) in the Territory solely as required to comply with the provisions of Section 3(c), provided that You comply with any applicable laws related to trademark protection. All goodwill arising out of Your use of the Mark will inure to the benefit of Tencent.
+c.	If You commence a lawsuit or other proceedings (including a cross-claim or counterclaim in a lawsuit) against Us or any person or entity alleging that the Materials or any Output, or any portion of any of the foregoing, infringe any intellectual property or other right owned or licensable by You, then all licenses granted to You under this Agreement shall terminate as of the date such lawsuit or other proceeding is filed. You will defend, indemnify and hold harmless Us from and against any claim by any Third Party arising out of or related to Your or the Third Party’s use or distribution of the Tencent Hunyuan Works.
+d.	Tencent claims no rights in Outputs You generate. You and Your users are solely responsible for Outputs and their subsequent uses.
+7.	DISCLAIMERS OF WARRANTY AND LIMITATIONS OF LIABILITY.
+a.	We are not obligated to support, update, provide training for, or develop any further version of the Tencent Hunyuan Works or to grant any license thereto.
+b.	UNLESS AND ONLY TO THE EXTENT REQUIRED BY APPLICABLE LAW, THE TENCENT HUNYUAN WORKS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED “AS IS” WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES OF ANY KIND INCLUDING ANY WARRANTIES OF TITLE, MERCHANTABILITY, NONINFRINGEMENT, COURSE OF DEALING, USAGE OF TRADE, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING, REPRODUCING, MODIFYING, PERFORMING, DISPLAYING OR DISTRIBUTING ANY OF THE TENCENT HUNYUAN WORKS OR OUTPUTS AND ASSUME ANY AND ALL RISKS ASSOCIATED WITH YOUR OR A THIRD PARTY’S USE OR DISTRIBUTION OF ANY OF THE TENCENT HUNYUAN WORKS OR OUTPUTS AND YOUR EXERCISE OF RIGHTS AND PERMISSIONS UNDER THIS AGREEMENT.
+c.	TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL TENCENT OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, FOR ANY DAMAGES, INCLUDING ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, EXEMPLARY, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR LOST PROFITS OF ANY KIND ARISING FROM THIS AGREEMENT OR RELATED TO ANY OF THE TENCENT HUNYUAN WORKS OR OUTPUTS, EVEN IF TENCENT OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+8.	SURVIVAL AND TERMINATION.
+a.	The term of this Agreement shall commence upon Your acceptance of this Agreement or access to the Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein.
+b.	We may terminate this Agreement if You breach any of the terms or conditions of this Agreement. Upon termination of this Agreement, You must promptly delete and cease use of the Tencent Hunyuan Works. Sections 6(a), 6(c), 7 and 9 shall survive the termination of this Agreement.
+9.	GOVERNING LAW AND JURISDICTION.
+a.	This Agreement and any dispute arising out of or relating to it will be governed by the laws of the Hong Kong Special Administrative Region of the People’s Republic of China, without regard to conflict of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement.
+b.	Exclusive jurisdiction and venue for any dispute arising out of or relating to this Agreement will be a court of competent jurisdiction in the Hong Kong Special Administrative Region of the People’s Republic of China, and Tencent and Licensee consent to the exclusive jurisdiction of such court with respect to any such dispute.
+ 
+EXHIBIT A
+ACCEPTABLE USE POLICY
+
+Tencent reserves the right to update this Acceptable Use Policy from time to time.
+Last modified: November 5, 2024
+
+Tencent endeavors to promote safe and fair use of its tools and features, including Tencent Hunyuan. You agree not to use Tencent Hunyuan or Model Derivatives:
+1.	Outside the Territory;
+2.	In any way that violates any applicable national, federal, state, local, international or any other law or regulation;
+3.	To harm Yourself or others;
+4.	To repurpose or distribute output from Tencent Hunyuan or any Model Derivatives to harm Yourself or others; 
+5.	To override or circumvent the safety guardrails and safeguards We have put in place;
+6.	For the purpose of exploiting, harming or attempting to exploit or harm minors in any way;
+7.	To generate or disseminate verifiably false information and/or content with the purpose of harming others or influencing elections;
+8.	To generate or facilitate false online engagement, including fake reviews and other means of fake online engagement;
+9.	To intentionally defame, disparage or otherwise harass others;
+10.	To generate and/or disseminate malware (including ransomware) or any other content to be used for the purpose of harming electronic systems;
+11.	To generate or disseminate personal identifiable information with the purpose of harming others;
+12.	To generate or disseminate information (including images, code, posts, articles), and place the information in any public context (including –through the use of bot generated tweets), without expressly and conspicuously identifying that the information and/or content is machine generated;
+13.	To impersonate another individual without consent, authorization, or legal right;
+14.	To make high-stakes automated decisions in domains that affect an individual’s safety, rights or wellbeing (e.g., law enforcement, migration, medicine/health, management of critical infrastructure, safety components of products, essential services, credit, employment, housing, education, social scoring, or insurance);
+15.	In a manner that violates or disrespects the social ethics and moral standards of other countries or regions;
+16.	To perform, facilitate, threaten, incite, plan, promote or encourage violent extremism or terrorism;
+17.	For any use intended to discriminate against or harm individuals or groups based on protected characteristics or categories, online or offline social behavior or known or predicted personal or personality characteristics;
+18.	To intentionally exploit any of the vulnerabilities of a specific group of persons based on their age, social, physical or mental characteristics, in order to materially distort the behavior of a person pertaining to that group in a manner that causes or is likely to cause that person or another person physical or psychological harm;
+19.	For military purposes;
+20.	To engage in the unauthorized or unlicensed practice of any profession including, but not limited to, financial, legal, medical/health, or other professional practices.

v1.0/README.md

@@ -0,0 +1,236 @@
+---
+license: other
+language:
+- multilingual
+pipeline_tag: image-text-to-text
+library_name: transformers
+base_model:
+- tencent/HunyuanOCR
+tags:
+- ocr
+- hunyuan
+- vision-language
+- image-to-text
+- 1B
+- end-to-end
+---
+
+<p align="center">
+ <img src="https://github.com/Tencent-Hunyuan/HunyuanOCR/blob/main/assets/hyocr-head-img.png?raw=true" width="80%"/> <br>
+</p>
+
+
+<p align="center">
+<a href="https://hunyuan.tencent.com/chat/HunyuanDefault?modelId=HY-OCR-1.0&mid=308&from=vision-zh"><b>🎯 Demo</b></a> |
+<a href="https://huggingface.co/tencent/HunyuanOCR"><b>📥 Model Download</b></a> |
+<a href="https://arxiv.org/abs/2511.19575"><b>📄 Technical Report</b></a> |
+<a href="https://github.com/Tencent-Hunyuan/HunyuanOCR"><b>🌟 Github</b></a>
+</p>
+
+<h2>
+<p align="center">
+  <a href="https://arxiv.org/abs/2511.19575">HunyuanOCR</a>
+</p>
+</h2>
+
+
+## 📖 Introduction
+**HunyuanOCR** stands as a leading end-to-end OCR expert VLM powered by Hunyuan's native multimodal architecture. With a remarkably lightweight 1B parameter design, it has achieved multiple state-of-the-art benchmarks across the industry. The model demonstrates mastery in **complex multilingual document parsing** while excelling in practical applications including **text spotting, open-field information extraction, video subtitle extraction, and photo translation**.
+
+
+## 🚀 Quick Start with Transformers
+
+### Installation
+```bash
+pip install git+https://github.com/huggingface/transformers@82a06db03535c49aa987719ed0746a76093b1ec4
+```
+> **Note**: We will merge it into the Transformers main branch later.
+
+### Model Inference
+
+```python
+from transformers import AutoProcessor
+from transformers import HunYuanVLForConditionalGeneration
+from PIL import Image
+import torch
+
+def clean_repeated_substrings(text):
+    """Clean repeated substrings in text"""
+    n = len(text)
+    if n<8000:
+        return text
+    for length in range(2, n // 10 + 1):
+        candidate = text[-length:] 
+        count = 0
+        i = n - length
+        
+        while i >= 0 and text[i:i + length] == candidate:
+            count += 1
+            i -= length
+
+        if count >= 10:
+            return text[:n - length * (count - 1)]  
+
+    return text
+
+model_name_or_path = "tencent/HunyuanOCR"
+processor = AutoProcessor.from_pretrained(model_name_or_path, use_fast=False)
+img_path = "path/to/your/image.jpg"
+image_inputs = Image.open(img_path)
+messages1 = [
+    {"role": "system", "content": ""},
+    {
+        "role": "user",
+        "content": [
+            {"type": "image", "image": img_path},
+            {"type": "text", "text": (
+                "检测并识别图片中的文字，将文本坐标格式化输出。"
+            )},
+        ],
+    }
+]
+messages = [messages1]
+texts = [
+    processor.apply_chat_template(msg, tokenize=False, add_generation_prompt=True)
+    for msg in messages
+]
+inputs = processor(
+    text=texts,
+    images=image_inputs,
+    padding=True,
+    return_tensors="pt",
+)
+model = HunYuanVLForConditionalGeneration.from_pretrained(
+    model_name_or_path,
+    attn_implementation="eager",
+    dtype=torch.bfloat16,
+    device_map="auto"
+)
+with torch.no_grad():
+    device = next(model.parameters()).device
+    inputs = inputs.to(device)
+    generated_ids = model.generate(**inputs, max_new_tokens=16384, do_sample=False)
+if "input_ids" in inputs:
+    input_ids = inputs.input_ids
+else:
+    print("inputs: # fallback", inputs)
+    input_ids = inputs.inputs
+generated_ids_trimmed = [
+    out_ids[len(in_ids):] for in_ids, out_ids in zip(input_ids, generated_ids)
+]
+output_texts = clean_repeated_substrings(processor.batch_decode(
+    generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
+))
+print(output_texts)
+```
+
+
+## 🚀 Quick Start with vLLM
+
+Checkout [vLLM HunyuanOCR Usage Guide](https://docs.vllm.ai/projects/recipes/en/latest/Tencent-Hunyuan/HunyuanOCR.html).
+
+### Installation
+
+```bash
+uv venv hunyuanocr
+source hunyuanocr/bin/activate
+
+uv pip install -U vllm --pre --extra-index-url https://wheels.vllm.ai/nightly
+```
+
+Note: We suggest to install [cuda-compat-12-9](https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/):
+```bash
+sudo dpkg -i cuda-compat-12-9_575.57.08-0ubuntu1_amd64.deb
+echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.9/compat:$LD_LIBRARY_PATH' >> ~/.bashrc
+source ~/.bashrc
+# verify cuda-compat-12-9
+ls /usr/local/cuda-12.9/compat
+```
+
+### Model Deploy
+```bash
+vllm serve tencent/HunyuanOCR \
+    --no-enable-prefix-caching \
+    --mm-processor-cache-gb 0 \
+    --gpu-memory-utilization 0.2
+```
+
+### Model Inference
+```python
+from vllm import LLM, SamplingParams
+from PIL import Image
+from transformers import AutoProcessor
+
+def clean_repeated_substrings(text):
+    """Clean repeated substrings in text"""
+    n = len(text)
+    if n<8000:
+        return text
+    for length in range(2, n // 10 + 1):
+        candidate = text[-length:] 
+        count = 0
+        i = n - length
+        
+        while i >= 0 and text[i:i + length] == candidate:
+            count += 1
+            i -= length
+
+        if count >= 10:
+            return text[:n - length * (count - 1)]  
+
+    return text
+
+model_path = "tencent/HunyuanOCR"
+llm = LLM(model=model_path, trust_remote_code=True)
+processor = AutoProcessor.from_pretrained(model_path)
+sampling_params = SamplingParams(temperature=0, max_tokens=16384)
+
+img_path = "/path/to/image.jpg"
+img = Image.open(img_path)
+messages = [
+    {"role": "system", "content": ""},
+    {"role": "user", "content": [
+        {"type": "image", "image": img_path},
+        {"type": "text", "text": "检测并识别图片中的文字，将文本坐标格式化输出。"}
+    ]}
+]
+prompt = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = {"prompt": prompt, "multi_modal_data": {"image": [img]}}
+output = llm.generate([inputs], sampling_params)[0]
+print(clean_repeated_substrings(output.outputs[0].text))
+```
+
+## 💬 Application-oriented Prompts
+
+| Task | Prompt |
+|------|---------|
+| **Spotting** | 检测并识别图片中的文字，将文本坐标格式化输出。 |
+| **Document Parsing** | • 识别图片中的公式，用LaTeX格式表示。<br><br>• 把图中的表格解析为HTML。<br><br>• 解析图中的图表，对于流程图使用Mermaid格式表示，其他图表使用Markdown格式表示。<br><br>• 提取文档图片中正文的所有信息用markdown格式表示，其中页眉、页脚部分忽略，表格用html格式表达，文档中公式用latex格式表示，按照阅读顺序组织进行解析。|
+| **General Parsing** | • 提取图中的文字。|
+| **Information Extraction** | • 输出Key的值。<br><br>• 提取图片中的: ['key1','key2', ...] 的字段内容，并按照JSON格式返回。<br><br>• 提取图中的字幕 |
+| **Translation** | 先提取文字，再将文字内容翻译为英文。若是文档，则其中页眉、页脚忽略。公式用latex格式表示，表格用html格式表示。 |
+
+## 🤝 Join Our Community
+
+<div align="center">
+
+| Wechat Discussion Group | Discord Group |
+| :---: | :---: |
+| <img src="https://github.com/Tencent-Hunyuan/HunyuanOCR/blob/main/assets/qrcode_for_hunyuanocr_wechat.jpg?raw=true" width="150"> | [Join HunyuanOCR Discord](https://discord.gg/XeD3p2MRDk) |
+
+</div>
+
+## 📚 Citation
+```
+@misc{hunyuanvisionteam2025hunyuanocrtechnicalreport,
+      title={HunyuanOCR Technical Report}, 
+      author={Hunyuan Vision Team and Pengyuan Lyu and Xingyu Wan and Gengluo Li and Shangpin Peng and Weinong Wang and Liang Wu and Huawen Shen and Yu Zhou and Canhui Tang and Qi Yang and Qiming Peng and Bin Luo and Hower Yang and Xinsong Zhang and Jinnian Zhang and Houwen Peng and Hongming Yang and Senhao Xie and Longsha Zhou and Ge Pei and Binghong Wu and Kan Wu and Jieneng Yang and Bochao Wang and Kai Liu and Jianchen Zhu and Jie Jiang and Linus and Han Hu and Chengquan Zhang},
+      year={2025},
+      journal={arXiv preprint arXiv:2511.19575},
+      url={https://arxiv.org/abs/2511.19575}, 
+}
+```
+
+## 🙏 Acknowledgements
+We would like to thank [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR), [MinerU](https://github.com/opendatalab/MinerU), [MonkeyOCR](https://github.com/Yuliang-Liu/MonkeyOCR), [DeepSeek-OCR](https://github.com/deepseek-ai/DeepSeek-OCR), [dots.ocr](https://github.com/rednote-hilab/dots.ocr) for their valuable models and ideas.
+We also appreciate the benchmarks: [OminiDocBench](https://github.com/opendatalab/OmniDocBench), [OCRBench](https://github.com/Yuliang-Liu/MultimodalOCR/tree/main/OCRBench), [DoTA](https://github.com/liangyupu/DIMTDA).

v1.0/config.json

@@ -0,0 +1,80 @@
+{
+  "architectures": [
+    "HunYuanVLForConditionalGeneration"
+  ],
+  "attention_bias": false,
+  "attention_dropout": 0.0,
+  "attention_head_dim": 128,
+  "bos_token_id": 120000,
+  "eod_token_id": 120020,
+  "eos_token_id": 120020,
+  "head_dim": 128,
+  "hidden_act": "silu",
+  "hidden_size": 1024,
+  "image_start_token_id": 120118,
+  "image_end_token_id": 120119,
+  "image_token_id": 120120,
+  "image_newline_token_id": 120121,
+  "initializer_range": 0.02,
+  "intermediate_size": 3584,
+  "max_position_embeddings": 32768,
+  "mlp_bias": false,
+  "model_type": "hunyuan_vl",
+  "norm_type": "rms",
+  "num_attention_heads": 16,
+  "num_experts": 1,
+  "num_hidden_layers": 24,
+  "num_key_value_heads": 8,
+  "org_vocab_size": 120818,
+  "pad_id": 120002,
+  "pad_token_id": -1,
+  "pretraining_tp": 1,
+  "rms_norm_eps": 1e-05,
+  "rope_scaling": {
+    "alpha": 1000.0,
+    "beta_fast": 32,
+    "beta_slow": 1,
+    "factor": 1.0,
+    "mscale": 1.0,
+    "mscale_all_dim": 1.0,
+    "type": "xdrope",
+    "xdrope_section": [
+      16,
+      16,
+      16,
+      16
+    ]
+  },
+  "rope_theta": 10000.0,
+  "routed_scaling_factor": 1.0,
+  "sep_token_id": 0,
+  "text_end_id": 8,
+  "text_start_id": 7,
+  "tie_word_embeddings": true,
+  "dtype": "bfloat16",
+  "transformers_version": "4.49.0",
+  "use_cache": true,
+  "use_qk_norm": true,
+  "use_cla": false,
+  "vision_config": {
+    "add_patchemb_bias": true,
+    "attention_dropout": 0.0,
+    "cat_extra_token": 1,
+    "hidden_act": "gelu",
+    "hidden_dropout": 0.0,
+    "hidden_size": 1152,
+    "img_max_token_num": 4096,
+    "intermediate_size": 4304,
+    "interpolate_mode": "bilinear",
+    "max_image_size": 2048,
+    "max_vit_seq_len": 16384,
+    "num_attention_heads": 16,
+    "num_channels": 3,
+    "num_hidden_layers": 27,
+    "out_hidden_size": 1024,
+    "patch_size": 16,
+    "rms_norm_eps": 1e-05,
+    "spatial_merge_size": 2
+  },
+  "vocab_size": 120818
+}

v1.0/generation_config.json

@@ -0,0 +1,13 @@
+{
+  "bos_token_id": 120000,
+  "pad_token_id": 120002,
+  "do_sample": true,
+  "eos_token_id": [
+    120007,
+    120020
+  ],
+  "repetition_penalty": 1.03,
+  "top_k": 1,
+  "top_p": 1.0,
+  "temperature":0.0
+}

v1.0/preprocessor_config.json

@@ -0,0 +1,20 @@
+{
+  "min_pixels": 262144,
+  "max_pixels": 4194304,
+  "patch_size": 16,
+  "resample": 1,
+  "temporal_patch_size": 1,
+  "merge_size": 2,
+  "image_mean": [
+    0.48145466,
+    0.4578275,
+    0.40821073
+  ],
+  "image_std": [
+    0.26862954,
+    0.26130258,
+    0.27577711
+  ],
+  "image_processor_type": "HunYuanVLImageProcessor",
+  "processor_class": "HunYuanVLProcessor"
+}

v1.0/special_tokens_map.json

@@ -0,0 +1,5 @@
+{
+  "bos_token": "<｜hy_begin▁of▁sentence｜>",
+  "eos_token": "<｜hy_place▁holder▁no▁2｜>",
+  "pad_token": "<｜hy_▁pad▁｜>"
+}

video_preprocessor_config.json

@@ -0,0 +1,43 @@
+{
+  "crop_size": null,
+  "data_format": "channels_first",
+  "default_to_square": true,
+  "device": null,
+  "do_center_crop": null,
+  "do_convert_rgb": true,
+  "do_normalize": true,
+  "do_rescale": true,
+  "do_resize": true,
+  "do_sample_frames": false,
+  "fps": null,
+  "image_mean": [
+    0.48145466,
+    0.4578275,
+    0.40821073
+  ],
+  "image_std": [
+    0.26862954,
+    0.26130258,
+    0.27577711
+  ],
+  "input_data_format": null,
+  "max_frames": 768,
+  "max_pixels": 4194304,
+  "merge_size": 2,
+  "min_frames": 4,
+  "min_pixels": 262144,
+  "num_frames": null,
+  "pad_size": null,
+  "patch_size": 16,
+  "processor_class": "HunYuanVLProcessor",
+  "resample": 3,
+  "rescale_factor": 0.00392156862745098,
+  "return_metadata": false,
+  "size": {
+    "longest_edge": 4194304,
+    "shortest_edge": 262144
+  },
+  "temporal_patch_size": 1,
+  "video_metadata": null,
+  "video_processor_type": "HunYuanVLVideoProcessor"
+}