【腾讯犀牛鸟26】HunyuanOCR-ncnn #6809

AInoob3202 · 2026-07-06T12:51:30Z

AInoob3202
Jul 6, 2026

HunYuanOCR-ncnn迁移

repo link

Abstract

本项目围绕 HunyuanOCR 在 ncnn 框架上的迁移与验证展开研究，构建了一套尽可能保持 ncnn-native 的完整部署方案，覆盖动态 smart resize、vision encoder、text embedding、带 KV cache 的 LLM decoder、lm head、tokenizer 以及 C++ 端自回归生成流程。针对 HunyuanOCR 的动态分辨率输入特性，本项目复现了与原始 PyTorch/HuggingFace 流程一致的图像缩放、patch 对齐、动态 position embedding 与 image token 构造机制；针对长序列生成效率，本文在 ncnn decoder 图中实现了 KV cache 的增量推理路径，避免无 cache 解码带来的重复计算。

在精度分析方面，本文建立了从输入到输出的多层级分析体系，包括输入 CHW 像素级一致性检查、bbox 可视化对比、same-input decoder blob replay、logit margin 分析以及多任务 token 级评测。分析表明，少量 1-2 像素级 bbox 偏移主要来自视觉与解码器算子在不同推理框架中的累积数值差异，并在低 margin 坐标 token 上被 argmax 放大。可视化结果表明，该偏移对文本框定位效果无明显可见影响，因此本文未引入坐标后处理补偿或大规模非 ncnn 手写算子替换，而是将其作为生成式 OCR 迁移中的可解释边界现象保留。

本文还构建了覆盖 Spotting、General Parsing、Document Parsing、Table HTML、Formula LaTeX、Information Extraction 和 Translation 等任务的多任务评测流程。在超过 50k token 的迁移一致性评测中，本文统计了各任务的 token 级偏差率，并将差异归因到数字 token、bbox 坐标 token、公式符号、格式标点、结束/续写边界和普通文本内容等类别。结果表明，ncnn版本和PyTorch版本的模型在输出上具有较高一致性。

Experienment

为了更加直观和客观地评估迁移水平，在迁移到 ncnn 后，在数据集 TUL、OCRBench 采样大量样本进行了实验以说明迁移表现和不足，也可以更好地说明PyTorch和ncnn框架的差异。

dense_novel_document_extract_pytorch_ncnn

TUL with bbox

使用TUL数据集进行测试并且提取 bbox，能够实现与 PyTorch 98%文本对齐率。并且表现PyTorch和ncnn都能够对齐实现非常优秀的OCR能力。在实验中发现主要问题是文本输出中的 bbox 没有对齐。ncnn 会在 bbox 上与 PyTorch 输出不一致，而且具体集中在y方向上：左上角的y坐标会略微向上偏移1-3个 value；右下角的y坐标会略微向下偏移1-3个 value；x轴方向上偏差几乎没有。

上图是 ncnn、PyTorch、GT 三个输出的bbox映射回原图的可视化，可以发现即使文本输出有所不同，但是其boxing能力是不受影响的。虽然文本输出不同，但是不影响其多模态能力。

经过对模型全链路的 debug，可以说明 bbox 有1-3个 value 的偏差源于：HunyuanOCR 的坐标不是连续回归值，而是自回归生成的低 margin 坐标 token，ncnn 与 PyTorch 在 vision/decoder 算子累积数值上存在极小差异，最终在坐标 token 的 argmax 处被放大成 1-3 像素偏移。

HunyuanOCR 的 bbox 以文本形式生成，例如：

(88,238),(323,348)

这里的 88、238、323、348 都是 decoder 的离散 token，不是一个连续坐标回归头。只要两个候选坐标 token 的 logit 非常接近，PyTorch 和 ncnn 的微小数值差异就可能改变 argmax。

PyTorch 侧示例的 logit 证据：

生成 step	PyTorch 选择	最高候选 logit	竞争候选	竞争 logit	margin	说明
9	token `21254`，坐标文本 `238`	`19.750`	token `22058`，相邻坐标候选	`19.625`	`0.125`	坐标 token margin 不大
44	token `46918`，坐标文本 `913`	`20.625`	token `48089`	`20.625`	`0.000`	实际出现并列/近并列

这就是 bbox 偏移的直接放大机制：

decoder hidden 产生 1e-5 ~ 1e-4 量级差异
-> lm_head 后候选坐标 logit 顺序发生变化
-> 坐标 token 从 348 变成 346，或从 636 变成 637
-> 映射回原图时表现为小像素偏移

对普通文本 token 来说，margin 往往足够大；对坐标 token、)、,、结束 token 来说，margin 可能小到足以被这些误差改变。

下面是同一输入下，ncnn 与 PyTorch 在 decoder block 内的关键 blob 误差。这里只列出代表性层，单位是 mean absolute error。

block	`q` mean error	`attn_o` mean error	`mlp2` mean error	`ln1` mean error	观察
0	`9.373e-07`	`2.213e-07`	`4.653e-06`	`2.763e-09`	前层误差较小
8	`9.902e-07`	`9.293e-08`	`1.438e-06`	`9.779e-09`	注意力输出仍较稳
23	`9.699e-07`	`1.487e-07`	`8.784e-07`	`2.348e-08`	后层仍有可测误差
24	`1.088e-06`	`1.292e-07`	`2.017e-06`	`2.378e-08`	MLP 分支误差上升
25	`1.046e-06`	`1.498e-07`	`2.874e-06`	`2.357e-08`	MLP 分支继续累积
26	`1.338e-06`	`3.944e-07`	`1.454e-05`	`2.722e-08`	`mlp2` 明显放大，是后续重点

从这张表可以看到：

LayerNorm 本身在该 replay 中不是最大的误差点，ln1 约 1e-08。
q 和 attn_o 有稳定可测差异，量级约 1e-07 ~ 1e-06。
后层 mlp2 的差异更明显，block 26 达到 1.454e-05。

这类误差对文本识别不一定造成影响，但会进入最终 hidden state 和 lm_head。对于 margin 为 0.125、甚至 0.000 的坐标候选，最终 argmax 可能被改变。

OCRBench 7 subtask

在OCRBench的7类子任务上做了评测，总token数超过了50k，整体上，ncnn 推理进程 0 崩溃，说明迁移后的端到端链路具备稳定可运行性；Table HTML 达到 0 token error / 10k tokens，Formula LaTeX 仅 118.03 token errors / 10k tokens，短文本与结构化输出任务表现稳定，长文本也能够和GT对齐，并且性能和PyTorch保持一致。7类子任务主要效果如下：

Formula LaTeX

Table HTML

Document Parsing

Translation

Information Extraction

General Parsing

Spotting

Pipeline

本项目实现了模型主体 ncnn 化率 100%；在KV-Cache、tokenizer、图像预处理、smart resize、自回归生成中仍有必要 C++ 逻辑和少量第三方工具库（如nlohmann/json、stb_image、torch,、transformers、pnnx、PIL主要用于调试、实验、可视化）

阶段	目标	当前实现
1. 模型拆分	将 HunyuanOCR 拆成 ncnn 可执行模块	vision encoder、text embedding、decoder、lm_head 分离
2. PyTorch 导出	生成 TorchScript / pnnx 输入	`community_clean/scripts/export_modules.py`、`trace_export.py`
3. ncnn 转换	生成 `.param/.bin`	vision 动态导出、text 模块转换、decoder KV cache 改图
4. tokenizer	复刻 HunyuanOCR BBPE 和 special tokens	`BpeTokenizer` + `special_tokens.json`
5. smart resize	复刻 HunyuanOCR 动态分辨率机制	`patch_size * spatial_merge_size = 32`，`min/max_pixels` 对齐
6. 图文融合	将 vision output 注入 image token embedding	runtime 中按 image token positions 替换 embedding
7. xD-RoPE	构造 4 轴位置编码	根据 image grid 构造 w/h/t/linear position ids
8. decoder KV cache	避免每步 full decoder	decoder param 有 `cache_k/v` 和 `out_cache_k/v`
9. 生成	greedy decode	C++ runtime 单 token 增量生成

关键机制

smart resize

HunyuanOCR 使用动态分辨率输入。当前 C++ runtime 复现以下规则：

项目	当前实现
patch size	16
spatial merge size	2
尺寸对齐粒度	32
min pixels	已对齐 HF 配置
max pixels	已对齐 HF 配置
position embedding	动态生成并输入 vision 子图

KV cache

decoder 支持：

prefill: prompt + image tokens
decode step: one token + cache_k/cache_v
output: out_cache_k/out_cache_v

这与无 cache baseline 不同，可以避免每一步重复 full decoder。

Comparisons and Limitations

与已有成果的对比

对比对象	主要特点	我们的差异与优势
Tencent/ncnn #6794	将 HunyuanOCR 拆成多个 ncnn 子模型，但 Perceptron / PatchMerger 采用 C++ 直读权重手写前向；KV cache 在当时仍属于后续优化方向。	我们更强调神经网络主体的 ncnn-native 表达，并已经实现 decoder KV cache。这样部署链路更统一，后续接入 ncnn 图优化、Vulkan、FP16 或多平台构建时维护成本更低。
Tencent/ncnn #6800	记录了 HunyuanOCR 端到端 ncnn 迁移中的动态 shape、COW、坐标偏移等关键工程问题，并报告坐标存在 2-6 px 级偏差。	我们吸收其动态 shape 和坐标偏差经验，同时补充了 TUL bbox 可视化、OCRBench 50K token 多任务一致性评测、长文档 `max_new_tokens` 配置对齐，以及 bbox 偏差来源的细粒度归因。
Tencent/ncnn #6808	强调 fixed-grid vision、PIL-compatible preprocessing、KV cache decode 和多平台验证，以 token/text 一致作为重要 gate。	我们更偏向 HunyuanOCR 原始 smart resize 路线和多任务实验分析，重点补充了 bbox 坐标 token、长正文 OCR、prompt 敏感性和生成配置不一致造成的误差边界。

总体而言，本项目不是单纯复现某个已有 demo，而是在完整 C++/ncnn runtime、动态 OCR 任务、KV cache、长文本配置和实验归因方面做了更系统的整理。

局限性

复杂任务对 prompt 高度敏感
文档 Markdown、信息抽取和翻译任务如果 prompt 不一致，输出风格会明显变化。未经 prompt 对齐的 token edit rate 不能直接解释为 ncnn 精度下降。
性能统计口径仍需统一
当前 ncnn 评测多为单图进程级 E2E 时间，包含模型加载；PyTorch 通常统计模型加载后的 generate 时间。二者不能直接作为同口径吞吐对比。
移动端和 Vulkan 仍需系统验证
当前主要验证路径是 CPU FP32。Vulkan、FP16、Android/aarch64 和常驻进程服务模式仍需要单独实验。

Windows/Linux编译教程

1. 准备 ncnn

Linux

git clone https://github.com/Tencent/ncnn.git
cd ncnn
mkdir build && cd build

cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DNCNN_BUILD_TOOLS=ON \
  -DNCNN_BUILD_EXAMPLES=OFF \
  -DNCNN_VULKAN=OFF

cmake --build . -j$(nproc)
cmake --install . --prefix /path/to/ncnn-install

如果需要 Vulkan，将 -DNCNN_VULKAN=OFF 改为 ON，并确保 Vulkan SDK / 驱动可用。

Windows PowerShell + Visual Studio 2022

git clone https://github.com/Tencent/ncnn.git
cd ncnn

cmake -S . -B build -G "Visual Studio 17 2022" -A x64 `
  -DNCNN_BUILD_TOOLS=ON `
  -DNCNN_BUILD_EXAMPLES=OFF `
  -DNCNN_VULKAN=OFF `
  -DCMAKE_INSTALL_PREFIX=C:\ncnn-install

cmake --build build --config Release --parallel
cmake --install build --config Release

如果 PowerShell 中文 prompt 显示异常，可先执行：

chcp 65001

2. 编译 HunyuanOCR-ncnn

Linux

git clone https://github.com/AInoob3202/HunyuanOCR-ncnn.git
cd HunyuanOCR-ncnn

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DNCNN_INSTALL_DIR=/path/to/ncnn-install

cmake --build build -j$(nproc)

生成主程序：

build/hunyuan_ocr_clean_ncnn

Windows PowerShell

git clone https://github.com/AInoob3202/HunyuanOCR-ncnn.git
cd HunyuanOCR-ncnn

cmake -S . -B build -G "Visual Studio 17 2022" -A x64 `
  -DNCNN_INSTALL_DIR=C:\ncnn-install

cmake --build build --config Release --parallel

生成主程序：

build\Release\hunyuan_ocr_clean_ncnn.exe

3. 准备模型目录

运行时模型目录需要包含：

HunyuanOCR_ncnn_clean_model/
├── model.json
├── vocab.json / merges.txt / special_tokens.json
└── models/
    ├── vision_encoder.ncnn.param/bin
    ├── text_embed.ncnn.param/bin
    ├── decoder.ncnn.param/bin
    ├── lm_head.ncnn.param
    └── other runtime assets

模型导出、trace 和 ncnn 转换脚本位于：

community_clean/scripts/

典型流程包括：

python export_modules.py
python verify_modules.py
python trace_export.py
python convert_text_ncnn.py
python prepare_model_dir.py

具体路径需要根据本机 HunyuanOCR 权重位置和 ncnn / pnnx 安装位置设置。

4. 运行示例

Linux

./build/hunyuan_ocr_clean_ncnn \
  --model /path/to/HunyuanOCR_ncnn_clean_model \
  --image /path/to/test.png \
  --prompt "提取图中的文字" \
  --max-new-tokens 1024

Windows PowerShell

chcp 65001

.\build\Release\hunyuan_ocr_clean_ncnn.exe `
  --model C:\path\to\HunyuanOCR_ncnn_clean_model `
  --image C:\path\to\test.png `
  --prompt "提取图中的文字" `
  --max-new-tokens 1024

5. 常用 prompt

提取图中的文字
检测并识别图片中的文字，将文本坐标格式化输出。
识别图片中的公式，用LaTeX格式表示。
把图中的表格解析为HTML。

6. 参数说明

参数	说明
`--model`	ncnn 模型目录
`--image`	输入图片路径
`--prompt`	OCR 任务 prompt
`--max-new-tokens`	最大生成 token 数；长文档建议使用 1024 或 2048

--max-new-tokens 需要与 PyTorch benchmark 保持一致，否则长文本任务会出现“PyTorch 能继续生成、ncnn 提前停止”的伪差异。

Reference

Tencent ncnn: https://github.com/Tencent/ncnn
HunyuanOCR model: https://huggingface.co/tencent/HunyuanOCR
nlohmann/json: https://github.com/nlohmann/json
stb image: https://github.com/nothings/stb
ncnn HunyuanOCR 相关讨论：

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

【腾讯犀牛鸟26】HunyuanOCR-ncnn #6809

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

Uh oh!

【腾讯犀牛鸟26】HunyuanOCR-ncnn #6809

Uh oh!

Uh oh!

AInoob3202 Jul 6, 2026

HunYuanOCR-ncnn迁移

repo link

Abstract

Experienment

TUL with bbox

OCRBench 7 subtask

Formula LaTeX

Table HTML

Document Parsing

Translation

Information Extraction

General Parsing

Spotting

Pipeline

关键机制

smart resize

KV cache

Comparisons and Limitations

与已有成果的对比

局限性

Windows/Linux编译教程

1. 准备 ncnn

Linux

Windows PowerShell + Visual Studio 2022

2. 编译 HunyuanOCR-ncnn

Linux

Windows PowerShell

3. 准备模型目录

4. 运行示例

Linux

Windows PowerShell

5. 常用 prompt

6. 参数说明

Reference

Replies: 0 comments

AInoob3202
Jul 6, 2026