updatre readme

README.md

@@ -1,3 +1,126 @@
 ---
 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) 许可。