Downloads · 30 days
0
HunyuanOCR-ncnn
xxzigou/HunyuanOCR-ncnn
HunyuanOCR-ncnn is a image-to-text model from xxzigou. Use it when you need a caption or text from an image. It is set up for ncnn. The card lists the license as apache-2.0.
腾讯 HunyuanOCR 的 ncnn 推理权重。基于 stock ncnn（上游原版，不做任何代码修改），通过 addbinheaders.py 后处理适配 ncnn 的权重加载格式。
Access
Public
Updated Jul 22, 2026
Repo size
9.8 GB
Likes
0
Public
Repo makeup
Click a slice to open those files.
.bin4.6 GB · 73%
At a glance
- Task
- Image-to-Text
- Library
- ncnn
- License
- apache-2.0
- Access
- Public
- Created
- Jul 3, 2026
- Updated
- Jul 22, 2026
- SHA
- 680d22d9
Base models
Model card
From the Hugging Face model README
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 格式：
- ONNX 导出：
torch.onnx.export将各子模型导出为 ONNX - pnnx 转换：ONNX → ncnn param/bin（flat 图，避免 torchscript inline 崩溃）
- 权重后处理：
add_bin_headers.py为 type=0 权重添加 4 字节 flag_struct 头，适配 stock ncnn 的ModelBin加载格式 - 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 许可。
- Task
- Image-to-Text
- Library
- ncnn
- License
- apache-2.0
- Created
- Jul 3, 2026
- Updated
- Jul 22, 2026