---
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}
}
```