README.md

# Youtu-VL ncnn 模型权重

本仓库提供腾讯 **Youtu-VL** 多模态大模型转换到 **ncnn** 格式的推理权重，需配合自研 C++ 推理引擎（`youtu_engine` + `youtu_vision`）实现端到端图文推理。在相同输入下，ncnn 输出的最终文本与原 PyTorch 实现逐字一致。

## 模型结构

- **LLM 解码器（40 层）**：每层拆为 `decoder_pre`（输入投影 + RoPE 准备）、`decoder_post_o`（注意力输出投影）、`decoder_post_mlp`（RMSNorm + MLP）三个 ncnn 子图。MLA 因果注意力因 pnnx 无法捕获 KV cache，在 C++ 中实现。
- **Vision 编码器（27 层）**：每层拆为 `vision_block_XX_pre/o/mlp`，外加 `vision_embed`（补丁嵌入，WoPos 结构无绝对位置编码）；所有 LayerNorm 在 C++ 端精确实现。
- **共享 / 辅助权重**：`embed.bin`（词嵌入表，与 lm_head 共享）、`norm.bin`（最终 RMSNorm）、merger 系列（VLPatchMerger）、`vision_ln1/ln2/post` 系列。

## 文件清单

| 文件 | 说明 |
|------|------|
| `embed.bin` | 词嵌入表 [VOCAB=283386, HID=2560] |
| `norm.bin` | 最终 RMSNorm 权重 [HID=2560] |
| `decoder_pre_XX.ncnn.{param,bin}` | LLM 第 XX 层 pre 子图（00–39） |
| `decoder_post_o_XX.ncnn.{param,bin}` | LLM 第 XX 层 注意力输出投影（00–39） |
| `decoder_post_mlp_XX.ncnn.{param,bin}` | LLM 第 XX 层 MLP 子图（00–39） |
| `vision_embed.ncnn.{param,bin}` | 视觉补丁嵌入 |
| `vision_block_XX_{pre,o,mlp}.ncnn.{param,bin}` | 视觉第 XX 层（00–26） |
| `vision_ln1_w/b.bin`、`vision_ln2_w/b.bin` | 视觉每层 LayerNorm 权重 |
| `vision_post_w/b.bin` | 视觉后 LayerNorm 权重 |
| `merger_ln_w.bin`、`merger_fc1_w/b.bin`、`merger_fc2_w/b.bin` | VLPatchMerger 权重 |

## 使用方法

将本仓库全部文件作为 `model_dir` 传入 C++ 推理引擎。引擎加载逻辑见 `youtu_engine.cpp` / `youtu_vision.cpp`（随推理引擎仓库提供，本仓库仅含权重）。

图像模式下，按 `pixel.bin` 字节数动态推断视觉 token 数量（不写死），支持不同尺寸输入。

## 精度验证

在 figure1（12×18 视觉网格）端到端验证：vision 输出 cosine 0.9998、visual token 0.9995、logits cosine 0.9978（argmax 一致）、贪心生成 24/24 完全一致。

## 许可

权重源自腾讯 Youtu-VL，请遵守原模型许可证。本仓库仅提供转换后的 ncnn 推理权重，不包含原模型权重或训练代码。