[腾讯犀牛鸟26] HunyuanOCR 的 ncnn 移植：pnnx 转换、C++ 解码与 Windows/Linux 验证

[Wi1sonchen]

一个面向Tencent/ncnn#6787 的阶段性实现：使用 pnnx 将 tencent/HunyuanOCR 1.0 拆分转换为 ncnn 模型，并参考ncnn_llm 实现尽量少依赖的 C++ OCR 推理链。

当前版本为 0.1.0-preview.2。完整的图片预处理、视觉编码、视觉特征注入、文本 prefill、KV cache 和逐 token 解码已经在 C++ 中串通；同一份 CMake 工程已在 Windows MinGW x64 和 Ubuntu 24.04/WSL x64 上完成构建与 CPU 推理验证。

现阶段适合作为可构建、可复现和可继续评审的技术预览。两个固定输入已经达到ncnn CPU 与官方 PyTorch BF16 的 generated token 序列和最终文本一致；任意输入上的普遍一致性仍需继续扩大验证范围。

1. 当前完成度

• 使用 pnnx 转换 HunyuanOCR 1.0 的主要计算模块；
• C++ 实现从图片到最终文字的完整推理流程；
• 支持 24 层文本 Decoder 的真实 KV cache 自回归解码；
• 支持 greedy decode，并保留 ncnn_llm 的采样配置接口；
• 从官方配置继承 tokenizer、特殊 token 和完整 EOS 集合；
• 使用 CMake 在 Windows 和 Linux 上构建；
• 推荐运行时采用严格的 121 文件资产合同；
• 两个固定回归输入通过 Windows/Linux CPU 的 token 与文本验收；
• 提供模型清单、依赖锁定、运行时检查、机器可读验收凭据和源码打包脚本。

运行时不依赖 PyTorch、Transformers 或 Python。Python 只用于模型转换、官方参考结果生成和数值验证。

2. 模型拆分与运行结构

为控制峰值内存并便于逐层定位，当前没有把完整 HunyuanOCR 导出成一个大图，而是拆成以下资产：

image
  -> resize / normalize / patch flatten
  -> patch embedding
  -> interpolated position embedding
  -> 27 x vision block
  -> patch merger
  -> vision features
  -> text embedding injection
  -> 24 x text decoder layer + KV cache
  -> LM head
  -> tokenizer decode
  -> final text

推荐的 split eager runtime 共 121 个文件，约 2.24 GB。视觉 block 和文本decoder layer 按顺序加载执行，避免所有子图同时常驻。

3. 关键实现点

3.1 图像预处理与视觉特征

C++ 端实现了与官方 processor 对齐的：

• smart resize；
• bicubic resize；
• RGB 归一化；
• patch 展平；
• 动态二维位置插值；
• 27 层视觉 block；
• patch merger 和图像边界 token 拼接。

视觉输入和注入文本模型前的最终视觉特征保留 BF16 边界。视觉 block 之间使用FP32 residual，避免拆图后重复低精度往返造成额外累计误差。

3.2 文本 Decoder 与 KV cache

24 个 Decoder layer 以独立 ncnn 子图运行。当前 K/V 由子图输出，C++ 将其与历史 cache 拼接后重新输入 attention 图，因此 cache 长度始终与真实 token 数一致，不需要永久屏蔽的占位 K/V。

prefill 与增量解码使用不同形状的 causal mask；生成阶段每次只计算一个新token，并复用 24 层 cache。

3.3 HunyuanOCR 的 RoPE 路径

官方 use_cache=True 的实际 prefill 行为需要特别处理：

• layer 0 在共享 cache 为空时使用 4-axis xdRoPE；
• layer 0 写入 cache 后，layer 1–23 使用普通线性 position RoPE；
• 增量解码阶段四个位置轴使用当前线性位置。

C++ 运行时复刻了这一分支行为。该处理对固定样例的文本 token 一致性非常关键。

3.4 BF16 输出与 token 选择

官方 checkpoint 配置为 BF16。当前实现会在 LM Head 输出后执行FP32 → BF16 → FP32 边界，再进行 greedy token 选择，以匹配官方 logits dtype。

对于量化后合法 EOS 与最高分精确同分的情况，runtime 提供可配置的setting.greedy_eos_tie_break。它只在以下条件同时成立时选择 EOS：

• 确定性 greedy；
• repetition_penalty=1；
• EOS 与已选最高分在 BF16 量化后精确相等。

采样、非单位 repetition penalty 和非平票 logits 不受影响；debug 模式会记录策略是否介入。这个规则用于稳定量化端口的停止行为，不作为任意输入张量等价的证明。

3.5 EOS 与 tokenizer

资产生成器按以下顺序解析并合并 EOS：

generation_config.json -> config.json -> tokenizer

HunyuanOCR 1.0 的运行时 EOS 集合为 [120007, 120020]。C++ 在 callback 前停止，同时在 --debug-tokens 模式下保留结束 token，便于与 Transformers 的generated IDs 逐项比较。

此外，HunyuanOCR 的 byte-level 词表包含字面量 \n、\r 和 \t。当前集成在 ByteDecode 前保留这些 token，使最终文本与 Transformers 的解码结果一致。

4. 固定输入验证

参考模型和环境：

• 模型：tencent/HunyuanOCR 1.0；
• 参考框架：PyTorch 2.7.1+cu128；
• 参考 dtype：torch.bfloat16；
• Transformers：提交 82a06db03535c49aa987719ed0746a76093b1ec4；
• GPU：NVIDIA GeForce RTX 2060；
• ncnn CPU：Windows MinGW x64、Ubuntu 24.04/WSL x64；
• prompt：提取图中的文字。；
• decode：greedy。

固定输入	PyTorch tokens	Windows ncnn CPU	Linux ncnn CPU	最终文本
浏览器界面图	32	32/32	32/32	逐字符一致
中英字幕图	20	20/20	20/20	逐字符一致

字幕样例最终文本：

对不起 我是诺曼·斯佩尔曼 Sorry, I'm Norm. Spellman.

两个样例均在 token 序列中包含最终 EOS，且没有触发 EOS 平票策略。

机器可读凭据：

• validation/acceptance-tools-dark.json
• validation/acceptance-subtitle-eos.json
• validation/platform-builds.json

原始验收图片不随源码包分发，凭据中保留图片 SHA-256、尺寸、prompt、处理参数、生成参数、token 摘要、文本哈希和平台结果。

5. 双平台构建

Linux 示例：

cmake -S . -B build-runtime -G Ninja \
  -DNCNN_SOURCE_DIR="$PWD/third_party/ncnn" \
  -DNCNN_LLM_SOURCE_DIR="$PWD/third_party/ncnn_llm" \
  -DHUNYUANOCR_BUILD_VALIDATION=ON
cmake --build build-runtime -j2

Windows PowerShell 示例：

cmake -S . -B build-windows -G Ninja `
  -DNCNN_SOURCE_DIR="$PWD/third_party/ncnn" `
  -DNCNN_LLM_SOURCE_DIR="$PWD/third_party/ncnn_llm" `
  -DHUNYUANOCR_BUILD_VALIDATION=ON
cmake --build build-windows -j 2

推理示例：

./build-runtime/hunyuanocr_ocr \
  --model /path/to/hunyuanocr-runtime \
  --image /path/to/input.png \
  --prompt '提取图中的文字。' \
  --max-image-side 512 \
  --max-new-tokens 128 \
  --threads 2 \
  --debug-tokens

模型和转换后权重受 Tencent Hunyuan Community License Agreement 约束，因此源码包不包含官方 checkpoint 或约 2.24 GB 的 runtime 权重。仓库提供模型来源说明、文件 manifest 和本地资产生成流程。

6. 当前不足与证据边界

目前可以确认的是两个固定输入在两种 CPU 平台上的 token 与最终文本一致，尚不代表任意图片、任意 prompt 或所有后端都已完全等价。当前主要边界如下：

1. 一张更大尺寸的网页/代码截图仍在第 7 个 generated token 出现非平票分叉。现有证据指向视觉 BF16 kernel 累加顺序和拆图算子边界的组合误差，仍需继续做逐算子定位。
2. Vulkan 路径已能运行，但暂不纳入 token 一致性结论；RTX 2060 上 CPU 仍是当前推荐的精度基线。
3. Windows 和 Linux 构建、推理均来自本地开发环境，尚未替代干净主机和公共 CI 的 portability 验证。
4. 当前验证集规模仍小，需要增加中文、英文、表格、公式、长文档和复杂排版样例，避免对固定输入过拟合。
5. 运行时资产约 2.24 GB，后续仍有量化、内存峰值、加载时间和移动端适配空间。