[犀牛鸟 2026 #6787] HunyuanOCR ncnn 移植：C++ 端到端，Linux/Windows 双平台部署

[LiamFan16-mikasa]

【腾讯犀牛鸟2026】HunyuanOCR-ncnn：HunyuanOCR v1.0 的 ncnn C++ 移植与双平台验证

面向 issue #6787。

项目仓库：LiamFan16-mikasa/HunyuanOCR-ncnn

一、任务要求与完成情况

任务要求	完成情况
用 pnnx 将 HunyuanOCR v1.0 转换为 ncnn	视觉塔、LLM prefill（24 层）、LLM decode 双图（dqkv/dattn）全部导出为 ncnn
纯 C++、最小依赖实现完整推理	C++17，应用层仅依赖 ncnn；预处理、tokenizer、rope、position、KV cache 全部自实现
相同输入下 ncnn(fp32) 与 PyTorch(fp32) 输出一致	固定测试图上 99/99 token 逐 id 完全一致，自然遇 EOS 停，复现路径零参考数据依赖
CMake 覆盖至少两个平台	Linux（gcc）、Windows（MinGW-w64 gcc）均构建通过，且带模型推理结果一致
发布技术总结与仓库地址	本文及上方仓库链接

二、核心亮点

• 端到端 99/99 逐 token 位级复现，复现路径零依赖参考数据；Linux/Windows 双平台输出一致
• 实测反推出 XDRoPE 有效 base ≈ 1.11588e7（由 alpha 缩放决定，非 config 表面的 rope_theta），且四轴中仅 position/height 两轴真正生效
• QK-Norm 施加顺序与 Qwen3 相反（rope 之后、写 KV cache 之前）——照搬 Qwen3 结构不会报错，只会静默拉低精度
• 定位并修复两处此前无文档记录的 pnnx→ncnn 坑：optlevel=0 稳定崩溃、inplace 层直连输入运行时崩溃
• tokenizer、KV cache、rope、position 全部手写零依赖 C++（含手搓 Unicode 分类表替代 \p{} 正则）

三、结果展示

阶段	验收	结果
视觉链路 → ncnn	274 行 cos ≥ 0.9999	min 0.99994
LLM prefill 24 层	逐层 cos ≥ 0.9999	最差 0.99999999
LLM decode 24 层	逐层 cos ≥ 0.9999	最差 0.99999998
C++ 端到端	逐 token == PyTorch	99/99
双平台	Linux/Windows 一致	一致

四、实现流程

1. 建 fp32。dump 全套中间量（输入、视觉逐层、LLM 逐层 hidden、rope、
   KV cache、逐 token logits）。复跑两次逐位相同（确定性），故此后任何 ncnn 侧不一致
   责任 100% 在 ncnn 侧。参考必须 fp32——bf16 参考会在长程 greedy 出现精度域边界翻转的假分叉。
2. 视觉链路整体导出为一张图。输入直接是整幅 (3,512,512) 图像，位置编码预插值成常量塞进图，输出 (274,1024)。
3. LLM prefill 逐层导出，每层接口 (x, cos, sin, mask)，额外输出 K/V 供 runtime 填 cache。
   rope 的 cos/sin 作为图输入喂入，不在 ncnn 里算 XDRoPE。
4. LLM decode 拆两图：dqkv（出 q/k/v，k 已 rope+QK-Norm）+ dattn（吃完整定长窗口
   cache + mask 出 hidden），cache 写入放在两图之间的 runtime。
5. C++ runtime：fp16 共享词表查表做 embedding + lm_head argmax；自写 rope、position_ids、
   RMSNorm、preprocess；零依赖 byte-level BPE tokenizer。

五、实现难点

1. XDRoPE 有效 base ≈ 1.11588e7（base = rope_theta · alpha^(d/(d-2))，非 config 表面值）。
2. QK-Norm 在 rope 之后（与 Qwen3 相反），cache 存归一化后的 K。
3. XDRoPE 四轴实际仅两轴生效：mrope_section=[16,16,16,16] 但 inv_freq 在 j≥32
   已近零，width/image_index 两轴近似恒等；C++ 仍完整实现四轴 gather 保证逐位一致。
4. image span 布局 1 + h×(w+1) + 1：274 行 = 首尾各 1 行文本式位置 + 16×17 网格
   （17 = 16 列 + 1 换行列）。
5. pnnx optlevel=0 稳定崩溃（跳过 pass_level3/4/5 却仍进 pass_ncnn，两平台稳定复现，
   最小复现仅需 Conv2d+reshape）；optlevel=1 另有独立崩溃；只有默认 optlevel=2 可用。
6. 防融合改写：rotate-half rope 会被融成 RotaryEmbed → 改用 ±1 置换阵 matmul；
   repeat_interleave 被静默丢弃（无报错、结果错、FLOPS=0 信号）→ 改 expand+reshape；
   -inf mask 加载不了 → 改有限值外部输入。
7. param 后处理两件必做：重名层去重（如两个 splitncnn_0）；inplace 层（RMSNorm 等）
   直连网络输入会运行时崩溃，与形状无关 → 为其插 Split 隔离层。
8. decode 小 h 崩溃：q_len=1 触发 ncnn RMSNorm 越界 → 按 q_len=8 导出，运行时取第 0 行。
9. 3D permute 结果直接作网络输出会崩 → decode 图输出一律 2D。
10. ncnn::Mat(data) 只借引用不拷贝 → 输入缓冲区生命周期须覆盖整个 extract。

六、构建与复现

仓库不含模型权重，需自行从官方渠道下载 HunyuanOCR v1.0；ncnn 以 submodule 形式拉取源码构建（CPU-only，关 vulkan/tools）。转换（PyTorch → ncnn）、C++ 构建（Linux gcc / Windows MinGW-w64）、运行、逐级对齐验证的完整命令见仓库 README。

七、当前边界

• prefill 图按测试图序列长度导出，换分辨率/长度需重导。
• 图像预处理只实现目标尺寸路径，通用 LANCZOS 缩放待补。
• tokenizer 已对 OCR 固定 prompt 逐 id 对齐，通用性（中英混合样本）待补。

八、参考链接

HunyuanOCR ·
HunyuanOCR Hugging Face model ·
ncnn ·
pnnx ·
HunyuanOCR-ncnn（本项目仓库）