README.md

---
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 模型资产版本。

本仓库只发布转换后的 ncnn 权重和参数文件，不包含 C++ 源码、可执行文件、
CMake 工程或模型转换脚本。模型需要与独立发布的 `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) |
| 技术总结 | [从 PyTorch 到 ncnn/C++：Youtu-VL-4B 的端侧迁移与 AI 辅助工程方法](https://github.com/Tencent/ncnn/discussions/6871) |
| 推理框架 | [Tencent/ncnn](https://github.com/Tencent/ncnn) |
| 模型转换工具 | [pnnx](https://github.com/pnnx/pnnx) |
| C++ 代码与运行说明 | [everythingfornothing/Youtu-VL-ncnn](https://github.com/everythingfornothing/Youtu-VL-ncnn) |

Youtu-VL 是腾讯优图实验室发布的视觉语言模型，基于 Youtu-LLM，并使用
Vision-Language Unified Autoregressive Supervision。原模型同时覆盖通用
视觉问答、多模态理解以及目标检测、视觉定位等视觉中心任务。

本项目没有重新训练 Youtu-VL，也不改变原模型的所有权。仓库中的资产由
pnnx 转换并按照 ncnn 运行边界拆分，供配套运行时加载。

## 转换内容

```text
27-layer Vision
VLPatchMerger
40-layer LLM Prefill/Decode
Final RMSNorm
17 LM-head shards
Text embedding and RoPE constants
ByteLevel-BPE tokenizer.bin
```

模型按照实际运行边界拆分为多个 ncnn 子图。本仓库只负责分发这些转换资产，
运行时实现、构建方法和命令行接口请查看
[`everythingfornothing/Youtu-VL-ncnn`](https://github.com/everythingfornothing/Youtu-VL-ncnn)。

## 文件说明

| 文件 | 说明 |
| --- | --- |
| `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)
```

下载完成后，请按照
[`everythingfornothing/Youtu-VL-ncnn`](https://github.com/everythingfornothing/Youtu-VL-ncnn)
中的构建与运行说明加载解压后的 `model/` 目录。

当前模型包 SHA-256：

```text
BAF79D8507B89AFDDC70EC151605A41A7616F03A9ACA3983B804FBE52302C4AA  youtu-vl-ncnn-model.tar.gz
```

## 验证结果

这些权重曾与配套 `Youtu-VL-ncnn` 运行时联合验证。验证条件为单图片、
单 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` |
| 配套 C++ 运行时的 Python/Transformers 依赖 | 无 |
| 配套 C++ 运行时的 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}
}
```