【腾讯犀牛鸟2026】Youtu-VL 模型的 ncnn 移植与跨平台部署

[Edwardssss]

【腾讯犀牛鸟2026】Youtu-VL 模型的 ncnn 移植与跨平台部署

代码仓库：https://github.com/Edwardssss/Youtu-VL-ncnn

模型权重：https://huggingface.co/Edwards129/Youtu-VL-ncnn_llm

原始模型：https://huggingface.co/tencent/Youtu-VL-4B-Instruct

任务目标

issue #6789

将腾讯 tencent/Youtu-VL-4B-Instruct 从 PyTorch 推理链路完整移植到 ncnn 推理框架，实现一个纯 C++、运行时仅依赖 ncnn 与标准库的多模态推理程序。

程序读取一张图片和任意文本 prompt，在纯 C++ 内完成全部工作并输出文本：

1. 读取并预处理图片（bilinear resize → 归一化 → 切 patch）；
2. 用 Llama-3 系 byte-level BPE tokenizer 编码任意文本 prompt；
3. 构造 Youtu-VL 多模态 chat template，将图像 token 注入文本序列；
4. 用 ncnn vision encoder 将图片转换为 image embeddings；
5. 通过 VLPatchMerger 将视觉特征投影到语言模型空间；
6. 用并行 prefill 建立 40 层 MLA decoder 的 KV cache；
7. 用 KV cache 逐 token decode，经 lm_head 与 tokenizer 解码回文本。

完成情况

• ✅ 模型拆解为 5 个模块，按各自特点采用不同导出策略
• ✅ Linux（GCC）与 Windows（MSVC）双平台 CMake 构建
• ✅ 云端 8 项端到端测试全部 PASS
• ✅ 模型权重已上传 Hugging Face

结果展示

纯文本解码

纯文本推理与 Pytorch 参考完全对齐：

输入	ncnn 输出	与 Pytorch 对比
"Hello"	Hello! How can I help you today?	✅ 完全一致
"What is the capital of France?"	The capital of France is Paris.	✅ 完全一致

云端图文测试

在阿里云 ECS（8 vCPU / 61 GB RAM）上串行运行 8 项视觉任务，纯 CPU 推理，全部通过：

#	任务	图片	耗时	结果
1	VQA	1.png (257KB)	12m37s	✅ "There is **1 real dog** in the image..."
2	Grounding	2.jpg (106KB)	3m41s	✅ <box><x_173><y_105><x_227><y_199></box>
3	Detection	3.jpg (277KB)	1h32m	✅ <ref>car</ref><box>... (256 tokens)
4	Semantic Seg	4.jpg (73KB)	~20m	✅ <ref>floor</ref><ref>bed</ref>...
5	Referring Seg	5.jpg (113KB)	~12m	✅ <ins><poly>...
6	Open-Set Seg	6.jpg (292KB)	~18m	✅ <ref>dog</ref><ref>cake</ref>...
7	Depth	7.png (1.7MB)	~16m	✅ <depth>...
8	Pose	8.png (1.9MB)	2h15m	✅ <person><box>...

逐层精度对齐数据

在 fp32 下测得（与 PyTorch 参考逐模块比对）：

环节	指标
L00 KV latent 独立对比	相对误差 2.62e-06
纯文本 decode logit	逐 id 与 Pytorch 一致
图片预处理	989184 元素中 141 个差 1 LSB（与 PIL 定点实现逐位一致）
tokenizer	348/348 token 逐 id 一致
LLM 端到端首 token	top-1 = 2015，与 PyTorch 基准一致

模型导出策略

模块拆解

Youtu-VL 拆为 5 个模块，各自采用最优导出方式：

模块	参数量	导出方式	原因
SigLIP2 Vision Encoder	1.6 GB	pnnx 直接转换	标准 ViT 结构，pnnx 支持良好
Text Embedding	2.9 GB	手动 .param + .bin	283K 词表 torch.jit.trace 会 OOM
VLPatchMerger	132 MB	纯 C++** 实现	ncnn MemoryData extract 版本兼容问题
MLA Decoder (40层)	16.7 GB	手写 ncnn::Layer**	pnnx 不支持 MLA 算子
LM Head	2.9 GB	手动 C++ matmul	ncnn Gemm tile packing 似乎存在导出问题，输出全0

关键导出实践

pnnx 无法稳定转换完整多模态模型： 原始模型包含 Hugging Face remote code、动态 shape、FlashAttention、窗口注意力等复杂结构，直接整体转换会生成 pnnx 无法稳定解析或 ncnn 无法正确执行的图。解决办法是按计算边界拆分子图，动态部分全部使用 C++ runtime。

**不应直接 trace HF 层：**其内部的 dtype 分支与控制流会使 pnnx 解析失败。所以改用纯 nn.Linear 与 RMSNorm 进行重建，从 HF 逐名拷贝权重，并以随机输入自检后放行（视觉层相对误差 2.8e-07，MLA 层 6.8e-08）。

ncnn .bin 导出： 每组权重前必须写入 \x00\x00\x00\x00 flag_struct 标记。

MLA 自定义层实现

架构设计

MLA 继承 ncnn::Layer 实现自定义层。每层持有 12 组权重，实现 decoder layer 的 8 步前向计算：

1. input_layernorm (RMSNorm)
2. Q 低秩投影: hidden → q_a_proj(1536) → RMSNorm → q_b_proj(32×192)
3. KV 低秩投影: hidden → kv_a_proj(512+64), 拆出 kv_latent 和 k_rot
4. 展开 K/V: kv_latent → RMSNorm → kv_b_proj → k_nope(32×128) + v(32×128)
5. Interleave RoPE: 跨半交错重排后施加旋转
6. Scaled Dot-Product Attention: Q·K^T/√d + mask → softmax → ×V
7. SwiGLU MLP: gate(SiLU) × up → down → 残差
8. 输出: attn_output + kv_latent_out (供下层 KV Cache)

KV Cache 设计

MLA 使用压缩 KV cache：只缓存 kv_latent_out（形状 [total_kv_len, 512]），而非展开后的完整 K/V。每轮推理时从压缩 latent 实时展开出 k_nope、k_rot、v。相比标准 MHA 大幅减少 KV cache 显存占用。

KV Cache 的拼接必须为 chronological（旧→新）。

大权重加载

40 层 decoder 共 16.7GB 权重。采用逐层 fread：每层先读 4 字节长度，再读该长度的 float 数据，每层约 0.42GB，分 40 次加载，避免一次性 mmap 16GB 导致内存不足。

实现难点

1. Interleave RoPE 的双重融合风险

YoutuLLM 的 rope_interleave=True，其 RoPE 在标准 rotate-half 之前多一步反交错重排：

q = q.view(b, h, s, d//2, 2).transpose(4, 3).reshape(b, h, s, d)
q_embed = (q * cos) + (rotate_half(q) * sin)

两个环节都可能被 pnnx 融合成 ncnn 的 RotaryEmbed，而该算子的轴语义与此处的交错布局并不匹配。

解决方案：将反交错与 rotate-half 合并为两个常量矩阵 P 与 PR = P @ R，改写为：

q_rot = (q @ P) * cos + (q @ PR) * sin

2. ncnn 在小尺寸张量上越界

ncnn 的 RMSNorm 与 UnaryOp 在 h 小于 SIMD 打包宽度时越界崩溃，而 decode 的查询长度天然为 1。

解决方案：将 decode 图按查询长度 8 而非 1 导出：runtime 输入 8 份复制的当前 token embedding，仅取输出第 0 行。

3. lm_head Gemm 全零问题

ncnn 的 Gemm_x86::create_pipeline 在处理 [M=1, N=283386, K=2560] 的极端瘦矩阵时，tile packing 产生全零输出。

解决方案：权重以 [vocab, hidden] 非转置方式存储。Embedding 与 lm_head 均不进图，而是以原始二进制存储，runtime 直接查表（embedding）、以 final_norm 后逐行点积取 argmax（lm_head）。

跨平台 BLAS 条件编译

#if defined(__linux__) || defined(__APPLE__) || (defined(_WIN32) && !defined(__ANDROID__))
    // 桌面平台: 使用系统 BLAS
    cblas_sgemm(...);
#else
    // 移动端 (Android/iOS): 回退手写 matmul
    for (...) ...
#endif

调试方法

移植前先运行原始模型，获取 Pytorch 输出参考：输入 token ids、pixel_values、vision 输出、merger 输出、逐层 hidden、prefill logits、greedy token。此后每完成一个模块，都与和参考输出进行逐级比对。

Tokenizer 与图片预处理这类需要逐位复刻的模块，先在 Python 中写出原型并对参考验证通过，再逐行移植。

构建与运行

依赖

• CMake ≥ 3.10
• C++17 编译器（GCC / MSVC / MinGW）
• BLAS 库（Linux: libblas-dev / macOS: Accelerate.framework / Windows: vcpkg openblas）

快速开始

git clone --recursive https://github.com/Edwardssss/Youtu-VL-ncnn
cmake -B build -DNCNN_VULKAN=OFF
cmake --build build -j

# 下载模型权重
# 从 https://huggingface.co/Edwards129/Youtu-VL-ncnn_llm 下载到 ncnn_models/

# 纯文本推理
./build/cpp/youtu_vl_main ncnn_models "Hello"

# 多模态推理
./build/cpp/youtu_vl_main ncnn_models "Describe the image." assets/image.png

Windows 注意事项

• 中文 prompt 经 argv 传入时为系统区域编码，需通过 GetCommandLineW 取 UTF-16 转 UTF-8
• 需 SetConsoleOutputCP(CP_UTF8)，否则输出乱码
• WSL 下编译 ncnn 时构建目录须置于 ext4（如 ~/）而非 NTFS，否则 CMake configure_file 报权限错误
• WSL 默认内存有限，ncnn 的 x86 AVX512 kernel 单个编译单元即占 1~2GB，需按可用内存推算并行度

已知限制

• 上下文窗口固定 512 token：prefill 图与 KV cache 为定长 512 窗口
• 仅覆盖文本输出路径：原模型的密集预测能力（分割可视化、深度图、姿态图）依赖 YoutuDensePrediction 后处理，本移植未覆盖
• 速度优化空间大：当前 CPU 推理每 token ~12-15 秒（40 层全量 MLA 展开），KV cache 重建策略可优化为 O(seq) 而非当前的 O(seq²)