HunyuanOCR-ncnn

腾讯 HunyuanOCR 的 ncnn 推理权重。基于 stock ncnn（上游原版，不做任何代码修改），通过 add_bin_headers.py 后处理适配 ncnn 的权重加载格式。

需要配合 C++ 推理框架 hunyuan-ocr-ncnn 使用。

模型信息

属性	值
原始模型	tencent/HunyuanOCR（~1B 参数）
架构	HunYuanVL（ViT + LLM 多模态）
视觉编码器	27 层 ViT，hidden=1152，16 heads，patch_size=16
PatchMerger	RMSNorm → Conv2d(stride=2) → GELU → Conv2d(1x1) → GELU → Linear → RMSNorm
LLM Decoder	24 层 GQA，hidden=1024，16 heads / 8 kv heads，head_dim=128，intermediate=3584
LM Head	1024 → 120818（词嵌入权重共享）
位置编码	XD-RoPE（4 轴 mRoPE，sections=[16,16,16,16]）+ 64 维标准 1D RoPE
Tokenizer	SentencePiece BPE（ByteLevel，120818 词表）
最大位置	32768 tokens
数据类型	float32（未做 fp16 量化）

文件说明

文件	大小	说明
model.json	~1 KB	运行时配置（层数、维度、文件映射）
vision_encoder.ncnn.param	~25 KB	ViT 网络结构
vision_encoder.ncnn.bin	~1.7 GB	ViT 权重（已添加 flag_struct 头）
decoder.ncnn.param	~85 KB	LLM 网络结构（已移除 Cast 层）
decoder.ncnn.bin	~1.6 GB	LLM 权重（已添加 flag_struct 头）
embed.ncnn.param	~165 B	词嵌入结构
embed.ncnn.bin	~472 MB	词嵌入权重（120818 x 1024）
lm_head.ncnn.param	~179 B	LM head 结构
lm_head.ncnn.bin	~472 MB	LM head 权重
projector.ncnn.param	~178 B	投影层结构
projector.ncnn.bin	~4 MB	投影层权重
perceptron_weights.bin	~117 MB	PatchMerger 权重（C++ 直读）
pos_embed_32x32.bin	~5 MB	ViT 位置嵌入（32x32 网格）
image_begin.bin	4 KB	图像开始标记嵌入
image_end.bin	4 KB	图像结束标记嵌入
image_newline.bin	4 KB	图像换行标记嵌入
vocab.txt	~1.6 MB	Tokenizer 词表（120818 tokens）
merges.txt	~1.6 MB	BPE 合并规则（119758 条）

总计：约 4.5 GB

转换流程

原始 PyTorch 模型经过以下步骤转换为 ncnn 格式：

1. ONNX 导出：torch.onnx.export 将各子模型导出为 ONNX
2. pnnx 转换：ONNX → ncnn param/bin（flat 图，避免 torchscript inline 崩溃）
3. 权重后处理：add_bin_headers.py 为 type=0 权重添加 4 字节 flag_struct 头，适配 stock ncnn 的 ModelBin 加载格式
4. Param 修补：删除 decoder 中 fp16 导出产生的 Cast 层（stock ncnn 的 Cast 层会丢失 batch 维度）

所有处理步骤均在推理框架仓库的 tools/ 和 export/ 目录下。

使用方法

1. 下载权重

pip install huggingface_hub
huggingface-cli download xxzigou/HunyuanOCR-ncnn --local-dir assets/hunyuan_ocr_ncnn

2. 编译推理框架

详见 hunyuan-ocr-ncnn 仓库 的 README。简要步骤：

# 编译 stock ncnn
cd ncnn
cmake -B build -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release -DNCNN_AVX=OFF -DNCNN_OPENMP=ON
cmake --build build --config Release -j8
cmake --install build --config Release

# 编译推理框架
cd hunyuan-ocr-ncnn
cmake -B build -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release -Dncnn_DIR=C:/ncnn/build/install/lib/cmake/ncnn -DNCNN_SRC_DIR=C:/ncnn
cmake --build build --config Release -j8

3. 运行 OCR

.\build\hunyuan_ocr.exe --model assets/hunyuan_ocr_ncnn --image document.png --threads 4 --stream

性能参考

配置	生成速度
CPU 4 线程，full-forward（无 KV cache）	~6 s/tok

当前 decoder 为 full-forward 模式（每步重算完整序列），无 KV cache。长序列性能随序列长度二次增长。

已知限制

• 无 KV cache，长序列生成较慢
• float32 推理，未做量化（int8/fp16）
• AVX 关闭以保证数值正确性
• 静态序列长度 512（超出需重新导出）

致谢

本权重基于腾讯 HunyuanOCR 模型转换而来。感谢腾讯开源的 OCR 模型和 ncnn 推理框架。

许可

权重文件继承原始模型的 Apache-2.0 许可。