Add ncnn model card and usage guide

README.md

@@ -1,5 +1,199 @@
 ---
+language:
+- zh
+- en
 license: other
 license_name: youtu-vl
 license_link: LICENSE
+library_name: ncnn
+pipeline_tag: image-text-to-text
+base_model: tencent/Youtu-VL-4B-Instruct
+tags:
+- ncnn
+- pnnx
+- cpp
+- vision-language
+- multimodal
+- image-text-to-text
 ---
+
+# Youtu-VL-4B-Instruct-ncnn
+
+这是
+[`tencent/Youtu-VL-4B-Instruct`](https://huggingface.co/tencent/Youtu-VL-4B-Instruct)
+的 pnnx/ncnn 部署版本，面向不依赖 Python、PyTorch 和 Transformers 的
+C++ CPU 推理。
+
+本仓库只发布转换后的 ncnn 模型资产。模型需要与专用
+`Youtu-VL-ncnn` C++ 运行时配套使用，不能直接通过
+`AutoModel.from_pretrained()`、Hugging Face Inference API 或标准
+Transformers Pipeline 加载。
+
+## 项目来源
+
+| 项目 | 来源 |
+| --- | --- |
+| 原始模型 | [tencent/Youtu-VL-4B-Instruct](https://huggingface.co/tencent/Youtu-VL-4B-Instruct) |
+| 官方代码 | [TencentCloudADP/youtu-vl](https://github.com/TencentCloudADP/youtu-vl) |
+| 技术报告 | [Youtu-VL: Unleashing Visual Potential via Unified Vision-Language Supervision](https://arxiv.org/abs/2601.19798) |
+| 推理框架 | [Tencent/ncnn](https://github.com/Tencent/ncnn) |
+| 模型转换工具 | [pnnx](https://github.com/pnnx/pnnx) |
+| C++ 运行时 | `Youtu-VL-ncnn`，源码通过独立 GitHub 仓库发布 |
+
+Youtu-VL 是腾讯优图实验室发布的视觉语言模型，基于 Youtu-LLM，并使用
+Vision-Language Unified Autoregressive Supervision。原模型同时覆盖通用
+视觉问答、多模态理解以及目标检测、视觉定位等视觉中心任务。
+
+本项目没有重新训练 Youtu-VL，也不改变原模型的所有权。项目工作集中在部署
+链路迁移：使用 pnnx 将模型计算转换为 ncnn 图，并以 C++ 实现图片
+Processor、Chat Template、ByteLevel-BPE、KV Cache、Prefill/Decode 调度
+和最终文本解码。
+
+## 转换后的运行结构
+
+```text
+image + prompt
+  -> C++ image decode / resize / normalize / patchify
+  -> C++ Chat Template + ByteLevel-BPE
+  -> ncnn 27-layer Vision
+  -> ncnn VLPatchMerger
+  -> image/text token fusion
+  -> ncnn 40-layer LLM Prefill
+  -> KV-cache Decode
+  -> Final RMSNorm + 17 LM-head shards
+  -> C++ coordinate postprocess + UTF-8 text
+```
+
+模型按照实际运行边界拆分为多个 ncnn 子图。线性层、归一化、激活和投影由
+ncnn 执行；动态图像网格、Vision RoPE/mask、图文 token 融合、KV Cache
+及生成循环由 C++ 调度。
+
+推理运行时不依赖 Python、PyTorch、Transformers、BLAS、MKL 或 OpenBLAS。
+
+## 文件说明
+
+| 文件 | 说明 |
+| --- | --- |
+| `youtu-vl-ncnn-model.tar.gz` | 完整 ncnn 模型压缩包 |
+| `MODEL_PACKAGE_SHA256.txt` | 压缩包 SHA-256 |
+| `LICENSE` | Youtu-VL License |
+
+压缩包解开后生成 `model/`：
+
+```text
+model/
+├── artifacts/
+│   ├── vision_embedding/
+│   ├── vision_layer0_masked_core/ ... vision_layer26_masked_core/
+│   ├── vision_post_layernorm/
+│   ├── llm_layer0_three_part/ ... llm_layer39_three_part/
+│   ├── llm_final_head_ncnn/
+│   ├── text_embedding/
+│   └── llm_rope_inv_freq.npy
+├── models/
+│   └── youtu_merger.ncnn.{param,bin}
+├── tokenizer/
+│   └── tokenizer.bin
+└── checksums.sha256
+```
+
+完整模型包含 339 个运行资产，解压后约 13.43 GiB。
+
+## 下载、校验与解压
+
+安装 Hugging Face CLI：
+
+```bash
+python3 -m pip install -U huggingface_hub
+```
+
+下载模型包：
+
+```bash
+hf download Coderdw/Youtu-VL-4B-Instruct-ncnn \
+  youtu-vl-ncnn-model.tar.gz MODEL_PACKAGE_SHA256.txt \
+  --local-dir model-download
+```
+
+校验并解压：
+
+```bash
+cd model-download
+sha256sum -c MODEL_PACKAGE_SHA256.txt
+tar -xzf youtu-vl-ncnn-model.tar.gz
+(cd model && sha256sum -c checksums.sha256)
+```
+
+当前模型包 SHA-256：
+
+```text
+BAF79D8507B89AFDDC70EC151605A41A7616F03A9ACA3983B804FBE52302C4AA  youtu-vl-ncnn-model.tar.gz
+```
+
+## C++ 推理
+
+在 `Youtu-VL-ncnn` 源码根目录完成 CMake 构建后运行：
+
+```bash
+./build/youtu_vl_ncnn \
+  --model-root /path/to/model-download/model \
+  --image /path/to/image.jpg \
+  --prompt "Describe this image." \
+  --output-dir out/run \
+  --max-new-tokens 128 \
+  --weight-mode persistent \
+  --threads 8
+```
+
+`persistent` 模式会在 Prefill 前加载 138 个 ncnn 图，并在生成阶段持续复用。
+该模式实测最大 RSS 约 24 GiB，建议至少准备 32 GiB 内存，推荐 64 GiB。
+
+## 验证结果
+
+验证条件为单图片、单 Prompt、batch size 1、greedy decode、CPU Release、
+8 threads 和 Vulkan OFF。
+
+| 验证范围 | 结果 |
+| --- | --- |
+| Linux 32/64/128 token | 最终 token ID 与 PyTorch 参考逐元素一致，文本一致 |
+| Windows 1/32/64/128 token | 最终 token ID 与 PyTorch 参考逐元素一致，文本一致 |
+| 英文 VQA、物体检测 | 64-token 用例均通过 |
+| Persistent 生命周期 | `resident_models=138`，`model_load_count=138` |
+| Python/Transformers 运行时依赖 | 无 |
+| BLAS/MKL/OpenBLAS/Vulkan 依赖 | 无 |
+
+Linux Persistent 最终版相对重复加载基线，在 32/64/128 token 下的总耗时
+分别获得约 1.64×、1.46× 和 1.36× 加速。
+
+## 使用范围与限制
+
+- 当前验证范围是单张图片和单个文本 Prompt，batch size 为 1。
+- 当前发布版本以 CPU Release、Vulkan OFF 为验收配置。
+- 多图片、视频、批量推理和服务端并发不在当前验证范围内。
+- 模型输出可能继承原始模型的知识偏差、幻觉和安全限制。
+- 本模型包是部署格式转换，不应被描述为新的训练模型或新的基础模型。
+
+## License
+
+模型、转换权重及使用行为遵循仓库中的
+[Youtu-VL License](LICENSE)。使用前请同时阅读原始模型仓库的许可证与
+使用限制。
+
+本项目使用 ncnn，并通过 pnnx 完成模型图转换；相关组件分别遵循其自身的
+开源许可证。本仓库与腾讯优图实验室不存在官方隶属或背书关系。
+
+## Citation
+
+使用本模型时，请引用原始 Youtu-VL 工作：
+
+```bibtex
+@article{youtu-vl,
+  title={Youtu-VL: Unleashing Visual Potential via Unified Vision-Language Supervision},
+  author={Tencent Youtu Lab},
+  year={2026},
+  eprint={2601.19798},
+  archivePrefix={arXiv},
+  primaryClass={cs.CV},
+  url={https://arxiv.org/abs/2601.19798}
+}
+```