【腾讯犀牛鸟2026】HunyuanOCR ncnn 移植与多平台部署

[Krystal579-max]

HunyuanOCR ncnn 移植与多平台部署 — 技术总结

HunyuanOCR-ncnn 仓库: https://github.com/Krystal579-max/HunyuanOCR-ncnn
关联 Issue: #6787

---

1. 项目概述

本项目完成了 Tencent-Hunyuan/HunyuanOCR（约 1B 参数端到端 OCR VLM）向 ncnn 框架的完整移植，实现了纯 C++ 推理运行时，支持 Linux、Windows、macOS 多平台部署。

HunyuanOCR 是腾讯混元团队开源的端到端多模态 OCR 模型，采用 ViT + LLM 架构，能够直接从图像中识别文字。ncnn 是腾讯开源的高性能神经网络推理框架，专为移动端和边缘设备优化。

项目仓库

• HunyuanOCR-ncnn: https://github.com/Krystal579-max/HunyuanOCR-ncnn
• 原始模型: https://github.com/Tencent-Hunyuan/HunyuanOCR
• 参考项目: https://github.com/nihui/ncnn_llm, https://github.com/pnnx/pnnx

---

2. 模型架构分析

HunyuanOCR 由 5 个核心组件构成：

组件	维度	层数	头数	说明
ViT (视觉编码器)	1152	27	16	patch_size=16，2D-RoPE 位置编码
Perceptron (PatchMerger)	1152→1024	-	-	RMSNorm→Conv2d→GELU→Conv2d→GELU→Linear→RMSNorm
LLM Decoder	1024	24	16Q/8KV (GQA)	head_dim=128
LM Head	1024→120818	-	-	120818 词表
BBPE Tokenizer	-	-	-	Byte-level BPE

关键技术特征

• XD-RoPE (4 轴旋转位置编码)：前 64 维使用 4 轴旋转（t, x, y, z），对应 4 个空间位置索引；后 64 维使用标准 1D RoPE
• YaRN 长上下文缩放：rope_theta=10000, alpha=1000
• GQA (Grouped Query Attention)：16 个 Q 头 + 8 个 KV 头

---

3. 移植策略

3.1 模型拆分

参考 ncnn_llm 项目的 OCR 实现方案，将 HunyuanOCR 拆分为 4 个独立子网络分别导出：

vision.ncnn.{param,bin}      — ViT 视觉编码器
text_embed.ncnn.{param,bin}  — 文本嵌入层
text_decoder.ncnn.{param,bin} — LLM Decoder（24层，含 KV cache）
lm_head.ncnn.{param,bin}     — LM Head 输出层

3.2 pnnx 导出

使用腾讯官方的 pnnx 工具直接从 PyTorch 导出 ncnn 格式，绕过 ONNX 中间步骤：

# Vision Encoder
pnnx.export(vit_wrapper, "vision.pt", inputs=(pixels, grid_thw), fp16=True)

# Text Embedding
pnnx.export(embed_wrapper, "text_embed.pt", inputs=(ids,), fp16=True)

# Text Decoder (24层)
pnnx.export(decoder_wrapper, "text_decoder.pt", inputs=(hs, mask, pos), fp16=True)

# LM Head
pnnx.export(head_wrapper, "lm_head.pt", inputs=(hs,), fp16=True)

3.3 KV Cache 增量解码

导出后通过 add_kvcache.py 修改 SDPA 层参数，启用增量 KV cache：

• SDPA param 7=1（enable_kv_cache）
• 6 输入 → 3 输出（含 past_key/past_value）
• Prefill 一次处理全部输入，后续逐 token 增量解码

---

4. C++ 推理实现

4.1 核心类结构

HunyuanOcrRunner
├── VisionEncoder  (ncnn::Net)  → vision.ncnn
├── TextEmbed      (ncnn::Net)  → text_embed.ncnn
├── TextDecoder    (ncnn::Net)  → text_decoder.ncnn (KV cache)
├── LmHead         (ncnn::Net)  → lm_head.ncnn
├── Perceptron     (C++手工实现) → perceptron_weights.bin
├── BpeTokenizer   (纯C++内联)  → vocab.txt + merges.txt
└── XdRope         (C++手工实现) → 4轴旋转 + YaRN

4.2 推理流程

prefill(image, prompt):
  1. 图像预处理 (smart_resize + normalize)
  2. VisionEncoder::forward() → vit_hidden
  3. Perceptron::forward() → image_embeds
  4. BpeTokenizer::encode(prompt) → token_ids
  5. TextEmbed::forward(token_ids) → text_embeds
  6. 替换 <image> 占位为 image_embeds
  7. 构建 4D 位置编码 + attention mask
  8. TextDecoder::forward() → hidden_states (prefill)
  9. LmHead::forward() → logits
  10. sample → first_token

decode loop:
  1. TextEmbed::forward(last_token) → embed
  2. TextDecoder::forward() → hidden (incremental, KV cache)
  3. LmHead::forward() → logits
  4. sample → next_token
  5. if is_eos: break

4.3 关键难点与解决方案

难点	解决方案
Perceptron 导出失败	pnnx 导出 Conv2d 时 3D 输入解释存在差异，改为 C++ 手工实现所有操作（RMSNorm → Conv2d → GELU → Conv2d 1x1 → GELU → Linear → RMSNorm）
XD-RoPE 4 轴旋转	在 C++ 中实现 apply_xdrope()，预计算 4 轴 cos/sin 缓存表，每个位置独立旋转
ViT 位置嵌入尺寸不匹配	双线性插值将 32×32 的位置嵌入扩展到 40×40
EOS token 语义不一致	将 120007（<｜hy_Assistant｜>）也识别为 EOS
BBPE Tokenizer	约 200 行纯 C++ 实现，零 Python 依赖，支持字节级回退编码

---

5. 构建系统

使用 CMake 构建，支持跨平台编译：

cmake_minimum_required(VERSION 3.10)
project(HunyuanOCR-ncnn)

# 依赖: ncnn (必需), OpenCV (可选)
find_package(ncnn REQUIRED)

# Linux: -O3 -march=native -fopenmp
# Windows: /O2 /arch:AVX2
# macOS: -O3 -march=native

编译命令

# Linux
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

# Windows (MSVC)
mkdir build && cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release

# 交叉编译 (可选)
cmake .. -DCMAKE_TOOLCHAIN_FILE=../toolchains/arm-linux-gnueabihf.cmake

---

6. 精度验证

数值精度

验证项	结果
ViT 27 层逐层 cosine similarity	1.0000
fp32 与 PyTorch 误差	< 1e-5
Greedy 解码 23 token	完全一致
端到端 OCR 输出	完全一致

验证方法

1. 使用相同输入图像和随机种子
2. 对比 PyTorch 原版与 ncnn 版的逐层输出
3. Greedy 解码模式下逐 token 比对
4. 端到端 OCR 文本完全相同

---

7. 性能

平台	后端	配置	耗时
Linux x86_64	CPU	4 线程	~88s (无 KV cache)
Linux x86_64	CPU	4 线程	~15s (KV cache, 预估)
Linux x86_64	Vulkan	GPU	TBD

KV cache 启用后，prefill 一次性处理全部输入，后续逐 token 增量解码，预期提速 5-10x。

---

8. 总结

本项目成功将 HunyuanOCR 从 PyTorch 移植到 ncnn，实现了以下目标：

• 使用 pnnx 将 HunyuanOCR 模型转换到 ncnn
• 参考 ncnn_llm 项目，C++ 实现 LLM 解码，最小化第三方依赖
• 在相同输入下，ncnn 输出的最终文本与 PyTorch 原版一致
• 使用 CMake 构建，确保在 Linux 和 Windows 平台完美编译与运行
• 完成 GitHub Discussion 技术总结文章

后续优化方向

• Vulkan GPU 后端性能测试与优化
• ARM / Android 平台适配
• 模型量化（INT8/INT4）支持
• 向 ncnn_llm 上游提交 Pull Request
• 流式输出支持

---

参考资料

• HunyuanOCR 官方仓库
• ncnn_llm 项目
• pnnx 模型转换工具
• ncnn 推理框架