[犀牛鸟] Tencent-Hunyuan/HunyuanOCR ncnn 移植与多平台部署

[infinity955]

Tencent-Hunyuan/HunyuanOCR ncnn 移植与多平台部署

仓库: https://github.com/infinity955/ncnn_ocr
模型: https://huggingface.co/infinity955/ncnn_ocr

---

背景

项目最初目标是参考 ncnn_llm 的 GLM-OCR 架构，将腾讯 HunYuanOCR（1B 多模态 OCR 模型）移植到 ncnn，用纯 C++ 实现跨平台推理。

过程

开始按照 GLM-OCR 的模式拆模块、写 C++ 推理代码。工作中发现 futz12 已经在 ncnn discussion #6793 发布了完整的 HunYuanOCR 适配教程。按教程重新导出后模型顺利跑通。

补充发现

在复现过程中发现两个教程未覆盖的问题：

1. int(gh)/int(gw) 导致 pnnx 双尺寸崩溃 — VisionPatchMerger.forward 中 int() 将 traced tensor 转为常量，双尺寸时冲突。修复：去掉 int()。

2. ncnn Mat COW 导致 use-after-free — memcpy(row(), ...) 绕过 COW 写入共享数据，Extractor 析构后 crash。修复：修改前 .clone()。

完整流程

以下是从零复现的完整步骤。详细说明见仓库 README_CN.md。

阶段零：获取仓库

git clone https://github.com/infinity955/ncnn_ocr.git
cd ncnn_ocr

阶段一：环境搭建

Python 环境：

pip install torch==2.12.1 numpy pillow
pip install "git+https://github.com/huggingface/transformers@82a06db03535c49aa987719ed0746a76093b1ec4"
pip install pnnx==20260526

包	版本
Python	3.10.18
torch	2.12.1
transformers	4.57.1 (commit 82a06db)
pnnx	20260526

编译 ncnn：

git clone https://github.com/Tencent/ncnn.git
cd ncnn && mkdir build && cd build
cmake .. && make -j       # Windows MSVC: cmake -G "Visual Studio 17 2022" -A x64 ..
cd ../..                  # 回到初始目录

下载 HunYuanOCR 原始模型：

# HuggingFace
huggingface-cli download tencent/HunyuanOCR --local-dir hunyuanocrmodel

# 或 ModelScope（国内）
python -c "from modelscope import snapshot_download; snapshot_download('tencent/HunyuanOCR', local_dir='hunyuanocrmodel')"

阶段二：导出 ncnn 模型

cd ncnn_ocr/scripts

# 1. 导出 TorchScript（scripted，保留动态）
PYTHONUTF8=1 python export_modules.py         # → ts/*.pt

# 2. 精度验证（可选）
PYTHONUTF8=1 python verify_modules.py

# 3. 转为 traced（给 pnnx）
PYTHONUTF8=1 python trace_export.py           # → ts_pnnx/*.pt

# 4. ViT pnnx.export（动态分辨率）
PYTHONUTF8=1 python export_vision_ncnn.py     # → ncnn/vision.ncnn.{param,bin}

# 5. Decoder / Text Embed / LM Head（CLI pnnx + 两组 inputshape）
cd ncnn
pnnx ../ts_pnnx/decoder.pt \
  inputshape=[1,8,1024],[1,1,8,8],[1,8,64],[1,8,64] \
  inputshape2=[1,16,1024],[1,1,16,16],[1,16,64],[1,16,64] \
  fp16=0 optlevel=2
pnnx ../ts_pnnx/text_embed.pt \
  inputshape=[1,8]i64 inputshape2=[1,64]i64 fp16=0 optlevel=2
pnnx ../ts_pnnx/lm_head.pt \
  inputshape=[1,8,1024]f32 inputshape2=[1,64,1024]f32 fp16=0 optlevel=2

# 6. 添加 KV cache
cd ..
PYTHONUTF8=1 python hunyuan_ocr_add_kvcache.py  # 732→733 层, 971→1067 blob

# 7. 生成 tokenizer 文件
PYTHONUTF8=1 python hunyuan_ocr_tokenizer.py   # → vocab.txt (120818 行)

# 8. 复制到仓库目录
cp ncnn/vision.ncnn.{param,bin} ../models/
cp ncnn/text_embed.ncnn.{param,bin} ../models/
cp ncnn/decoder.ncnn.{param,bin} ../models/
cp ncnn/lm_head.ncnn.param ../models/
cp ncnn/pos_embed.bin ../models/
cp vocab.txt ../

四个模块均为 0 自定义层（pnnx.Expression/aten::to 均为 0）。

阶段三：编译 C++

cd ..                          # 回到 ncnn_ocr/ 根目录
mkdir build && cd build
cmake .. -Dncnn_DIR=<ncnn_root>/build/install/lib/cmake/ncnn
make -j
# Windows MSVC: cmake -G "Visual Studio 17 2022" -A x64 .. -DUSE_OPENMP=OFF
cmake --build . --config Release -j

阶段四：运行

./build/hunyuanocr_ncnn --model . --image assets/testimg.jpg
# Windows: .\build\Release\hunyuanocr_ncnn.exe --model . --image assets\testimg.jpg
# 中文乱码: chcp 65001; .\build\Release\hunyuanocr_ncnn.exe --model . --image assets\testimg.jpg

架构

图像 → smart_resize + BICUBIC + BGR→RGB normalize → ViT [1,3,H,W] + pos_embed → image_embeds
提示词 → BBPE → Text Embed → 注入 image_embeds → Decoder (24层,GQA,XD-RoPE,KV cache) → LM Head → 贪心解码

结果

C++ ncnn 端到端跑通，文字输出与 PyTorch HF 一致，任意图片可用。

testimg.jpg:  顺利上岸(231,392),(764,632)LAMAR(446,850),(559,878)05483(934,835),(997,870)

坐标差 2-6 px（size= vs scale_factor+0.1 已知取舍）。

致谢

• futz12/ncnn_llm — GLM-OCR 架构参考
• ncnn discussion #6793 — futz12 的 HunYuanOCR 完整教程
• Tencent/ncnn — 高性能神经网络推理框架