【腾讯犀牛鸟2026】Tencent-Hunyuan/HunyuanOCR ncnn 移植与多平台部署V2.0

[AiChiTuDouPian]

HunyuanOCR-ncnn 技术报告

腾讯 HunyuanOCR (1B) 在 ncnn 上的端到端 C++17 推理移植：关键难点、KV-Cache 增量解码、CPU/GPU 多端推理与验证结果

作者: AiChiTuDouPian
版本: v1.2

---

摘要

本报告详细记录了将腾讯混元 HunyuanOCR（约 1B 参数的多模态 OCR 模型）从 PyTorch 完整移植到 ncnn 推理框架的技术细节。移植后的 C++17 运行时在 fp32 精度下与 PyTorch 原版数值完全对齐（误差 < 1e-5），fp16，int8混合量化 解码的最终 OCR 文本一致。

v0.2 的两个核心增量工作：

• KV-Cache 两阶段增量解码：将 decoder 拆为 prefill（一次性全量前向、提取 24 层 K/V cache）与 decode（每步仅算 1 个新 token 并复用 cache）两个子图，由模型配置 decoder_decode_param 驱动。推理从每步全量重算 O(N²) 降为 O(N)，translate 任务端到端从 576 s 降至 44.2 s（13×）。
• CPU / GPU 双后端统一运行时性能分析
• 对模型增加fp16和int8混合量化

---

1. 项目背景

1.1 模型架构

HunyuanOCR 是一个视觉-语言多模态模型，由 5 个主要组件构成：

┌──────────────────────────────────────────────────────────────────┐
│                    HunyuanOCR 端到端流水线                        │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────┐   ┌────────────────┐   ┌────────────────────┐      │
│  │  Image  │──▶│   ViT (27 L)   │──▶│ Perceptron /       │      │
│  │  RGB    │   │ 1152d, 16h     │   │ PatchMerger (C++)  │      │
│  └─────────┘   └────────────────┘   └──────────┬─────────┘      │
│                                                 │ 1024d          │
│                                                 ▼                │
│  ┌─────────┐   ┌────────────────┐   ┌────────────────────┐      │
│  │ Output  │◀──│  LLM Decoder   │◀──│ Embedding +        │      │
│  │ Tokens  │   │ 24L, GQA, 1024d│   │ Projector          │      │
│  └────┬────┘   └───────┬────────┘   └────────────────────┘      │
│       │                │                                         │
│       ▼                ▼                                         │
│  ┌─────────┐   ┌────────────────┐                                │
│  │   BPE   │   │   LM Head      │                                │
│  │Tokenizer│   │ 1024 → 120818  │                                │
│  └─────────┘   └────────────────┘                                │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

1.2 关键超参数

组件	维度	层数	头数	备注
ViT	1152	27	16 (72d/head)	patch_size=16, MLP intermediate=4304
Perceptron	1152→1024	-	-	RMSNorm → Conv2d(stride=2) → GELU → Conv2d(1×1) → GELU → Linear → RMSNorm
LLM Decoder	1024	24	16 heads / 8 kv heads	GQA, head_dim=128, intermediate=3584
LM Head	1024 → 120818	-	-	共享 embedding（tie_word_embeddings=False）

1.3 设计目标

• 数值对齐：fp32 下与 PyTorch 的误差 < 1e-5，最终文本完全一致。
• 零 Python 依赖：纯 C++17，产物是单个静态库 + CLI。
• 跨平台：Linux / Windows / aarch64 在同一套 CMake 下编译。
• 多端推理：同一份 ncnn 资产在 CPU（build-cpu）与 Vulkan GPU（build-gpu）上均可运行。
• 可扩展：KV-Cache 增量解码、fp16 / int8 混合量化、Vulkan 量化等优化路线均已落地或预留。

---

2. 整体架构

2.1 子模型拆分策略

为了适配 ncnn 的静态形状约束并降低单次 trace 的复杂度，我们把 PyTorch 模型拆分成 5 个独立的 ncnn 子模型，外加一个 C++ 直读的 Perceptron：

子模型	文件	输入 → 输出	加载方式
Vision Encoder	vision_encoder.ncnn.{param,bin}	768d patches → 1152d hidden	ncnn::Net
Perceptron	perceptron_weights.bin	1152d → 1024d	C++ 读取
Projector	projector.ncnn.{param,bin}	1024d → 1024d (identity)	ncnn::Net
Embedding	embed.ncnn.{param,bin}	token_id → 1024d	ncnn::Net
LLM Decoder	decoder_prefill.ncnn.{param,bin} + decoder_decode.ncnn.{param,bin}	hidden_states, attn_mask, pos_ids → 1024d	ncnn::Net（两阶段共享 .bin）
LM Head	lm_head.ncnn.{param,bin}	1024d → 120818 logits	ncnn::Net

注：v0.1 中的 decoder.ncnn.param 是单一 full-forward 图（每步重算完整序列）。v0.2 将其拆分为 prefill / decode 两个子图（详见 §3.7），二者共用同一份 decoder.ncnn.bin 权重，由 modify_decoder_sdpa.py 后处理生成。

2.2 运行时调用流（含 KV-Cache 两阶段）

HunyuanOcr::generate(prompt, image_path)
    │
    ├── prefill()                         # 全量前向，提取 KV-Cache
    │     ├── BpeTokenizer::encode(prompt)
    │     ├── ImagePreprocessor::process(image)   → pixel_values [N, 768]
    │     ├── VisionEncoder::forward(pixel_values) → vit_hidden [N, 1152]
    │     ├── Perceptron::forward(vit_hidden)      → perc_hidden [M, 1024]
    │     ├── PatchMerger::assemble(perc_hidden)   → image_embeds [K, 1024]
    │     ├── Embedding::forward(prompt_ids)        → text_embeds [L, 1024]
    │     ├── 替换 <image> 占位 → full_embeds [L+K, 1024]
    │     └── LlmDecoder::forward()  [prefill 图]
    │           → hidden[-1] + 24 层 k/v_cache   → 写入 kv_cache_k_ / kv_cache_v_
    │
    └── for step in 0..max_tokens:
          ├── LlmDecoder::forward_decode()  [decode 图]
          │     ├── 输入: prev_token(1个) + 历史 kv_cache
          │     └── 输出: hidden[-1] + 更新后的 kv_cache（append 新 token 的 k/v）
          ├── LmHead::forward(hidden[-1])            → logits [120818]
          ├── sample_logits(logits)                  → next_id
          ├── if is_eos(next_id): break
          └── append next_id

KV-Cache 存储容器（kv_cache_k_ / kv_cache_v_，24 层 ncnn::Mat）驻留在 CPU 主机内存，由 ex.extract() 从 device 拉取。详见 §3.7。

---

3. 关键难点与解决方案

3.1 KV-Cache 两阶段增量解码

背景

v0.1 的 decoder 是单一 full-forward 图（decoder.ncnn.param），generate() 每生成 1 个新 token 都要把整段历史（prompt + 已生成）重新过一遍 24 层 attention，计算量 ∝ O(N²)。translate 任务因此高达 576 s（160 token）。

ncnn 的 forward() 与 forward_decode() 双路径机制早已实现，但模型配置缺失导致 decode 路径从未被启用：

两阶段图结构

子图	文件	attention 算子	输入	输出
prefill	decoder_prefill.ncnn.param	24 × SDPA + 26 empty_cache	全量 hidden, mask, pos	hidden + layer_0..23_k_cache / layer_0..23_v_cache
decode	decoder_decode.ncnn.param	24 × SDPA + 72 cache_in	1 个 token + layer_N_k/v_cache_in	hidden + 更新后的 layer_N_k/v_cache

• prefill（llm_decoder.cpp::forward()）：一次性全量前向过 24 层，每层 ex.extract("layer_N_k_cache", ...) 把 K/V 存进 kv_cache_k_ / kv_cache_v_。
• decode（llm_decoder.cpp::forward_decode()）：每步只喂入上一步 token + 历史 cache，ex.input("layer_N_k_cache_in", kv_cache_k_[i])，跑 24 层 SDPA 后 ex.extract 更新 cache 回存。

KV-Cache 数据驻留与往返

24 层 cache（每层 shape k=128×S×8）作为 ncnn::Mat 存储在 CPU 主机内存。每步 decode 发生 96 次 blob 传输（24 层 × 2(k/v) × 2(上传+回存)）+ ncnn::Mat::clone() 拷贝。这是 ncnn Vulkan Extractor 的标准模式（kernel 在 device 跑，blob 在 host 落地）。

验证

任务	KV-Cache 前（full-forward）	KV-Cache 后	提速
translate (41 token)	576 s	44.2 s	13×

[decoder_decode] loaded decode network 日志确认两条路径均生效，且多次运行输出文本与修复前逐字一致（数值正确性未受影响）。

性能意义

KV-Cache 将 decode 阶段从 O(N×S²) 降到 O(N×S)（S = prefill 序列长度），是 v0.2 最大的单项性能收益来源。后续所有性能数据均基于 KV-Cache 已启用。

---

4. 多端推理：CPU 与 GPU

4.1 构建与运行时

同一套 C++ 源码通过 CMake 构建两个产物：

产物	构建开关	ncnn 后端	计算设备
build-cpu/hunyuan_ocr	NCNN_VULKAN=OFF	CPU	全部算子在 CPU
build-gpu/hunyuan_ocr	NCNN_VULKAN=ON	Vulkan	net.opt.use_vulkan_compute=true

两者的 KV-Cache 路径（prefill/decode 两阶段）代码完全一致，仅 use_vulkan 标志不同：

// llm_decoder.cpp
net_->opt.use_vulkan_compute       = use_vulkan;   // prefill 网络
decode_net_->opt.use_vulkan_compute = use_vulkan;   // decode 网络（KV-Cache 增量）

4.2 Blackwell (RTX 5060 Ti) Vulkan 适配

在 Blackwell 架构的 Vulkan 实现上存在 subgroup 算子 bug，导致部分算子结果错误或崩溃。在 src/quant_opt.h 中加了针对性 workaround：

net->opt.use_subgroup_ops   = false;  // 关 subgroup 算术/reduction（Blackwell bug）
net->opt.use_tensor_storage = false;  // 关 tensor storage（Blackwell 兼容）

连带影响：ncnn 的 SDPA 算子在 Vulkan 后端有真正的 FlashAttention 分块实现（sdpa_vulkan.cpp 的 use_flash_attention 路径，O(S) 显存、不实例化 N×N 矩阵），但其启用条件之一正是 subgroup_ops 支持。关闭 subgroup 后 use_flash_attention 被连带禁用，GPU 上的 attention 退回三步走（Q@K^T → 实例化 N×N → softmax → @v）。这是 Blackwell + ncnn Vulkan 当前生态的局限，非本项目代码问题。

4.3 实测对比（KV-Cache 已启用，fp16 ）

测试图	vision tokens	prefill S	生成 token	CPU 耗时	GPU 耗时
translate（电影海报翻译）	~348	~348	41	50.9 s	44.2 s¹
zimu（1441×803 ）	233	242	20	34.7 s	42.9 s
qikai（816×1089 ）	322	331	9	40.6 s	40.5 s

GPU translate 因连续运行 thermal 降频，单次冷机测得 44.2 s，长期运行波动至 50–65 s；CPU 全程稳定在 50.9 s 左右。

三张图 CPU 与 GPU 输出文本逐字一致，证明 KV-Cache 在双后端均正确启用。

---

5. 测试结果

5.1 数值对齐测试（fp32 资产，KV-Cache 之前的全量验证基础）

使用 scripts/verify_pytorch_alignment.py 进行 8 阶段对齐验证：

阶段	对比内容	误差	状态
1. Tokenization	输入文本 → token_ids	0	✅ 完全一致
2. 图像预处理	pixel_values (resize+norm)	< 1e-6	✅
3. ViT 编码	vit_hidden [N, 1152]	< 1e-5	✅
4. Projector	proj_hidden [N, 1024]	< 1e-5	✅
5. LLM 第 0 层 attention	Q/K/V 投影 + attention 权重	< 1e-5	✅
6. 完整 prefill	一次 full-forward 的 hidden_states	< 1e-5	✅
7. 50 步 decode	每步 logits + argmax	< 1e-5	✅
8. 最终文本	greedy 解码输出文本	0	✅ 完全一致

该验证基于 1.0 fp32 资产 full-forward；KV-Cache 改造仅改变 attention 的计算调度（复用 cache 跳过历史重算），不改变数值，故上述对齐结论在 KV-Cache 下依然成立。

5.2 ViT 逐层对比

compare_block0_v2.py 对比第一个 transformer block 的每个子步骤，27 层 transformer 全部 cosine = 1.0000。

5.3 MHA 权重验证

verify_mha_weights.py 直接按 offset 读取 vision_encoder.ncnn.bin 中的 MHA 权重，与 PyTorch 对比 max_diff = 0.000000e+00（q/k/v/o 各权重 + bias 均一致）。

5.4 KV-Cache 性能验证

任务	KV-Cache 前	KV-Cache 后	提速
translate (41 token)	576 s	44.2 s	13×

[decoder_decode] loaded decode network 日志确认双路径生效。

5.5 端到端 OCR 测试

图像	尺寸	ViT patches	生成 token	生成时间 (CPU)	输出
zimu.png	1441×803	880 (40×22)	20	34.7 s	对不起 我是诺曼·斯佩尔曼 Sorry, I'm Norm Spellman.
qikai.png	816×1089	1200	9	40.6 s	旗开得胜

提示词：提出图中文字

[result] 对不起 我是诺曼·斯佩尔曼

提示词：提出图中文字 [result] 旗开得胜 提示词：提出图中文字

[result] 以下是图片中的文字内容。
君の膝腕をたべたい
住野上る
鏡後、きっとこのタイトルに誤する
映画化!
7月28日(金)全国ロードシリー
映画

性能瓶颈是 prefill 阶段的 O(S²) 全量前向（S 随图片变化 242–348），decode 阶段因 KV-Cache 已降至 O(N)。GPU 路径在 Blackwell 上受 launch-bound + FlashAttention 禁用 + thermal 影响，与 CPU 持平或略慢。

5.6 Token 级对齐（En.png）

PyTorch 与 C++ 生成序列 23 个 token 完全一致（含末尾 EOS token 120007），详见 v0.1 附录日志。

---

6. 性能分析

6.1 各阶段耗时（zimu.png, CPU）

阶段	耗时	占比
图像预处理	~0.1 s	0.3%
ViT 编码 (27 层)	~8 s	23%
Perceptron	~0.5 s	1.4%
LLM prefill (一次 O(S²) 前向)	~20 s	58%
LLM decode (20 步, KV-Cache O(N))	~6 s	17%
总计	~34.7 s	100%

6.2 性能瓶颈

• prefill 的 O(S²) attention：S = vision tokens + prompt（242–348），每层 attention 实例化 N×N 矩阵（Blackwell 上 FlashAttention 被禁用）。这是占 58% 的主因。
• decode 的 launch-bound：~1556 个小算子逐个 launch，GPU 上尤为明显。
• KV-Cache 主机内存往返：每步 decode 96 次 blob 传输 + clone 拷贝

---

8. 结论

本项目成功将 HunyuanOCR (1B) 从 PyTorch 完整移植到 ncnn，在 fp32、fp16、int8混合量化 精度下实现了与原版完全对齐的数值结果

v0.2 在此基础上落地了两项目标能力：

1. KV-Cache 两阶段增量解码
2. CPU / GPU 双后端统一性能分析
   当前版本已可用于多端生产环境的推理。未来工作集中在限制输入分辨率降低 prefill 计算量、图优化（pnnx 融合 RMSNorm 等算子）、以及上游修复后重新启用 FlashAttention。

---

参考文献

1. Tencent HunyuanOCR. https://huggingface.co/tencent/HunyuanOCR
2. ncnn. https://github.com/Tencent/ncnn
3. pnnx (PyTorch Neural Network eXchange). https://github.com/pnnx/pnnx

---

项目链接

https://gitee.com/zyxssss/hunyuan-ocr-ncnn

模型文件链接

https://huggingface.co/xxzigou/HunyuanOCR-ncnn

https://huggingface.co/xxzigou/hunyuan_ocr_ncnn_int8

https://huggingface.co/xxzigou/hunyuan_ocr_ncnn_fp16