README.md

---
license: apache-2.0
library_name: ncnn
tags:
  - ocr
  - image-to-text
  - ncnn
  - cpp
  - multimodal
  - vision
  - hunyuan
  - tencent
base_model: tencent/HunyuanOCR
---

# HunyuanOCR-ncnn

腾讯 [HunyuanOCR](https://huggingface.co/tencent/HunyuanOCR) 的 ncnn 推理权重。基于 stock ncnn（上游原版，不做任何代码修改），通过 `add_bin_headers.py` 后处理适配 ncnn 的权重加载格式。

需要配合 C++ 推理框架 [hunyuan-ocr-ncnn](https://github.com/YOUR_USERNAME/HunyuanOCR-ncnn) 使用。

## 模型信息

| 属性 | 值 |
|------|-----|
| 原始模型 | [tencent/HunyuanOCR](https://huggingface.co/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. 下载权重

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

### 2. 编译推理框架

详见 [hunyuan-ocr-ncnn 仓库](https://github.com/YOUR_USERNAME/HunyuanOCR-ncnn) 的 README。简要步骤：

```powershell
# 编译 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

```powershell
.\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](https://huggingface.co/tencent/HunyuanOCR) 模型转换而来。感谢腾讯开源的 OCR 模型和 [ncnn](https://github.com/Tencent/ncnn) 推理框架。

## 许可

权重文件继承原始模型的 [Apache-2.0](https://opensource.org/licenses/Apache-2.0) 许可。