腾讯混元 HunyuanOCR-1.5 把文档解析、文字识别、信息抽取、图文翻译塞进一个 1B 的 VLM，还把推理速度拉高 6 倍。本文带你在本地或 vLLM 上跑通它。
腾讯混元 HunyuanOCR-1.5 把文档解析、文字识别、信息抽取、图文翻译塞进一个 1B 的 VLM，还把推理速度拉高 6 倍。本文带你在本地或 vLLM 上跑通它。
天工超级智能体深度体验：自动盯盘、生成PPT、深度调研，注册即用的云端Agent团队
如果你在做发票识别、表格抽取、古籍扫描、合同解析这类 OCR 任务，大概率已经被传统 OCR 管线的"检测→识别→版面→结构化"四件套折磨过。腾讯混元在 2026-07-07 开源的 HunyuanOCR-1.5（仓库里也叫 HyOCR-1.5）给出了一条更干净的路：把上面所有能力塞进一个 1B 参数的视觉语言模型（VLM），端到端一次出结果，并且通过 speculative decoding 把长文档解码速度拉高约 6.37 倍。
这篇文章带你把官方仓库跑起来，从权重下载到一次批量推理出 Markdown，并覆盖 vLLM 服务、llama.cpp 本地部署两条最常用的路径。所有命令都来自官方 Tencent-Hunyuan/HunyuanOCR 仓库，没有自行编造。
💡 提示：官方明确说明 vLLM (AR / DFlash) 与原生 transformers 三个推理环境互相不兼容，
transformers版本冲突，必须分别建环境。下面路径 A/B/C 任选一条即可，不要混用。
权重托管在 Hugging Face 的 tencent/HunyuanOCR，下载会同时包含 base 模型和 DFlash 的 draft 模型。
pip install -U "huggingface_hub[cli]"
huggingface-cli download tencent/HunyuanOCR \
--local-dir ./HunyuanOCR --exclude "v1.0/*"--exclude "v1.0/*" 是为了避免把上一代 1.0 权重也拉下来，省一份磁盘。
官方在 inference/ 下给出三套互相独立的环境，外加 llama.cpp 的 PC 端方案：
| 路径 | 框架 | DFlash 加速 | 适用场景 |
|---|---|---|---|
A. inference/vllm_0_18_1 | vLLM 0.18.1 | 否 | 最简单，纯 AR 推理 |
B. inference/nightly | vLLM nightly (CUDA 13) | 是 | 长文档/表格/公式，要榨干速度 |
C. inference/transformers | HF transformers 5.13 | — | 对齐/精度检查 |
| D. llama.cpp | GGUF + OpenAI 兼容 server | 可选 | CPU / 笔记本 / 消费级 GPU |
下面以**路径 A（最常用的 vLLM 单卡）**为例完整跑一遍；如果你只关心加速，照着路径 B 的 README 把 serve.sh 换成 serve_dflash.sh 即可。
先按 inference/vllm_0_18_1/requirements.txt 装好依赖，再起一个 OpenAI 兼容的服务端：
MODEL_PATH=./HunyuanOCR GPU=0 PORT=8000 \
bash inference/vllm_0_18_1/serve.sh
# 健康检查
curl -sf http://127.0.0.1:8000/v1/models服务会把模型以 tencent/HunyuanOCR 暴露出来，--max-model-len 默认拉到 131072（128K 上下文，对应训练里的最大配置）。
官方把任务类型锁死成 12 个 --task-type（用 --list-tasks 查全部），避免你随手写 prompt 把模型带偏。采样参数（temperature=0.0、top_p=1.0、repetition_penalty=1.08）和尾部重复早停都已经在客户端里内置好。
python inference/vllm_0_18_1/infer_vllm_client.py \
--image /path/to/document.png \
--task-type doc_parse \
--model tencent/HunyuanOCR \
--port 8000 --max-tokens 32768常用的几个 task-type：doc_parse（整页解析成结构化文本）、text_spotting（纯文字定位识别）、information_extraction（按指令抽字段）、text_image_translation（图文翻译）。一张图出一段 Markdown 或 JSON，看你选哪个任务。
面对一堆扫描件时，用官方的 batch_infer.py，自带多端点并发和断点续跑：
python inference/vllm_0_18_1/batch_infer.py \
--image-dir /path/to/images \
--out-dir /path/to/output \
--ports 8000 \
--task-type doc_parse \
--max-tokens 32768 \
--concurrency 16如果有多张卡，起多个 serve.sh 实例，把端口列表塞给 --ports，吞吐线性扩展。
没有 GPU 也能用。HunyuanOCR-1.5 提供 GGUF 转换后的 checkpoint 和一个 OpenAI 兼容的 llama-server，社区版 llama.cpp 支持 base 模型，DFlash 加速则需要用适配过的 fork（wendadawen/llama.cpp @ dflash-adapt-hunyuanocr-hunyuanstyle）。
最简流程（社区版，无 DFlash）：
# 1. 编译 llama.cpp
git clone https://github.com/ggml-org/llama.cpp.git && cd llama.cpp
cmake -B build -DLLAMA_BUILD_EXAMPLES=ON # NVIDIA GPU 加 -DGGML_CUDA=ON
cmake --build ./build --config Release -j
# 2. 转 GGUF（base + mmproj）
python3 convert_hf_to_gguf.py --outfile ./HunyuanOCR/hyocr-f16.gguf --outtype f16 ./HunyuanOCR
python3 convert_hf_to_gguf.py --outfile ./HunyuanOCR/mmproj-hyocr-f16.gguf --outtype f16 --mmproj
完整的 DFlash 适配版、draft 权重转换、以及 26 张样例图的冒烟测试脚本都在官方 docs/llama_cpp.md 里。
两个核心改动解释了"又快又好"：
docs/benchmark.md。跑完第四步，你应该在标准输出里拿到一段结构化的 Markdown / JSON，表格能保留行列、公式按 LaTeX 输出、多栏排版按阅读顺序还原。要进一步对比精度，可以用官方同期发布的两个开源 benchmark：Chronicles-OCR（中文"七体"古文字感知，arXiv:2605.11960）和 ChartArena（跨语言图表解析，arXiv:2606.01348）。
transformers 版本互不兼容，官方在 inference/README.md 里强调这是"经验证的限制，不是偏好"。建议每个路径单独建一个 env。inference/transformers 为准。LICENSE 全文。scripts/sft_base.sh 是全参 SFT，scripts/sft_dflash.sh 是从头训 DFlash draft，scripts/sft_dflash_finetune.sh 是在已有 draft 上继续微调，具体超参见 docs/training.md。