【2026腾讯犀牛鸟】Penguin-VL ncnn 移植与多平台部署

[AiChiTuDouPian]

Penguin-VL → ncnn 转换与端到端推理 技术报告

目标：将 tencent/Penguin-VL（基于 Qwen3 的视觉语言模型，VLM）转换为 ncnn 格式，实现自包含 C++ 端到端推理（图像 + 文字 → 文本），在相同输入下输出须与 PyTorch 原版一致；CMake 跨平台构建（Windows + Linux）。

---

1. 项目概述

项	内容
源模型	tencent/Penguin-VL（Qwen3 底座 VLM）
推理框架	ncnn（参考 nihui/ncnn_llm 的 LLM 解码范式）
导出工具	pnnx（PyTorch → ncnn 参数/权重）
形态	单条命令 penguin_vl_run.exe --model . --image x.png --prompt "..." 直接出文本，无 Python 胶水、无中间文件
一致性要求	相同输入下 ncnn 数值与 PyTorch 真值一致（vision encoder cosine ≥ 0.99）

---

2. 模型架构与 ncnn 映射

2.1 结构参数

• 视觉编码器 ViT：hidden=1024，28 层
• 语言模型 Qwen3：hidden=1024，28 层，16 注意力头 / 8 KV 头（GQA），head_dim=128，vocab=151936，tie_word_embeddings（词嵌入与 lm_head 共享），RoPE θ=1e6，RMSNorm eps=1e-6
• 视觉投影器：2 层 MLP（1024 → 2048 → 1024）

2.2 关键 token id

• <image> = 151669；<|image_pad|> = 151655；<|vision_start|> = 151652；<|vision_end|> = 151653

2.3 图像与视觉 RoPE

• num_patches = 495（= 9×55）；pixel_values shape = [N, 588]（588 = 14×42）
• 真实模型 merge_size = 1（PyTorch 官方不合并）
• 视觉 RoPE：2D mRoPE，head_dim=128 按 [64, 64] 切两段，第 063 维用 h 流 cos/sin、第 64127 维用 w 流 cos/sin；base=1e6；merge_size=1 退化为行优先位置

2.4

• Mat 二进制布局：offset = x + y*w + z*w*h（w 最内层）；numpy 正确视图为 [h, w]（2D）或 [c, h, w]（3D）。保存 bin 时 save_bin 须把 C-order 数组与显式头 (w, h, c) 配对。
• Slice / Concat 轴语义反转：axis=0→切 c 维、axis=1→切 h 维、axis=2→切 w 维。视觉 RoPE 用 Slice 1=2（沿 w=head_dim=128 切 [64,64]）、Concat 0=2（沿 w 拼）。
• 权重存储布局：MatMul 的 MemoryData 以 [h=in, w=out] 即 Wᵀ 形式存储。
• splitncnn_4 / splitncnn_5 是广播（非切片）：cos/sin 单份 (128, 1, N) 即可。

---

3. 导出与工程实现

1. pnnx 将原始 PyTorch 模型导出为 ncnn 参数/权重。
2. 手写修正脚本（export/export_vision.py 等）处理：
   • GQA 展开：k/v 权重 [1024,1024]（8 KV 头）展开为 [2048,1024]（16 头），wk.reshape(NKV,HD,HID).repeat_interleave(2,0).reshape(NH*HD,HID)。
   • RoPE 轴与 h/w 交错、权重 Wᵀ 布局对齐。
3. C++ 运行时（cpp/）实现：BPE 分词器 + 图像预处理 + ncnn 推理 + 贪婪解码，参考 HunyuanOCR 的自包含形态。

模型资产位于 assets/penguin_vl/：

• decoder.ncnn.{param,bin}、embed.ncnn.{param,bin}、lm_head.ncnn.{param,bin}
• vision_embed_patch.ncnn.*、vision_encoder.ncnn.*、vision_projector.ncnn.*
• vocab.txt、merges.txt、model.json

---

4. 关键问题与修复

4.1 自回归生成退化成 '!'(id 0)

• 现象：prefill 与 decoder/lm_head 数值均正确（top1 与 PyTorch 第二 token 一致），但自回归每一步都选 id 0 输出 !。
• 根因：<|image|> 不在 vocab.txt（<|image_pad|> 在），AddAdditionalSpecialToken("<|image|>") 把它追加成 index 151936，使 vocab_size = 151937 > logits 实际维数 total = 151936，llm_select_next_token 因 vocab_size > total 早退 return 0。
• 修复：在 llm_select_next_token 把 vocab_size 钳制到 total（vocab_size = (cfg.vocab_size>0 && <=total) ? cfg.vocab_size : total）。
• 验证：纯文本生成「我是一个人工智能助手，能够帮助您完成各种任务和解决问题。」与 PyTorch PY_IDS 逐 token 一致。

4.2 vision encoder NaN

• 现象：ncnn vision_encoder 在 L2 残差突然全 NaN；而 L0(max 685)/L1(max 1283) 有限。
• 误判纠正：曾怀疑是 fp16 溢出；实测该 bin 为 fp32（首 4 字节非 fp16 魔数，精确大小 1,996,750,848 = 309 个权重 blob 按 param 顺序连续存放）。
• 真因：历史某次坏补丁用错 fp32 偏移，把 181/309 个权重 blob 写成 NaN（共 946 个散点，每 blob 2~22 个）。Layer 2 的 k_proj 只是最先暴露的一处，整份 bin 都不可信。
• 修复：export/rewrite_vision_bin.py 整体从 safetensors 重生成 vision_encoder.ncnn.bin（fp32，k/v 做 GQA 8→16 头展开），不依赖旧损坏数据。所有 309 个 blob 与 safetensors cos=1.0（自校）。旧损坏 bin → vision_encoder.ncnn.bin.corrupted_bak。
• 关键解析修复（修复脚本中踩过的坑）：
  • MatMul 行格式 MatMul name bc tc b1 b2 top → 权重输入在 t[4], t[5]（此前误用 t[3], t[4]）；
  • MemoryData blob 号在 t[4]；RMSNorm 的 dim 在 t[6]（此前误用 t[5]）。
  • 每层的 7 个 MatMul 顺序为 (idx//7, TYPES[idx%7])，RMSNorm 顺序为 [input, q_norm, k_norm, post] × 28 + final。
• 验证（见第 5 节）：encoder 输出与 PyTorch cos=0.999965，nan=0。

---

5. PyTorch 一致性验证

本项目对所有可比对环节都做了 ncnn 输出 vs PyTorch 原版真值 的一致性验证，层次从"单个权重 blob"逐级上升到"端到端生成 token"。验证遵循"能精确 Match 就不止步于 cos≈1"的原则：文本生成要求 token 级逐位一致，张量要求 cosine ≥ 0.99 且 nan = 0。

5.1 验证方法论

• 权威参考实现：export/reference_vision.py 提供与 PyTorch 原模型逐算子对齐的参考函数（rmsnorm / rotate_half / vision_rope / attention / decoder_layer / vision_forward），作为所有数值比对真值来源；LLM 部分以 PyTorch verify_greedy.py 的 PY_IDS 真值序列为准。
• 比对指标：
  • cos(x, y) = Σ(x·y) / (‖x‖·‖y‖ + 1e-12)（向量夹角余弦，衡量方向一致性）
  • nan_count（NaN 计数，修复前为整图 NaN，修复后须为 0）
  • max_abs = max|x − y|（绝对误差幅值，用于评估 fp32 累积漂移）
• 比对层次：权重 blob → 单层中间量 → 子模块输出 → 整体输出 → 端到端 token，逐层收敛定位问题。

5.2 权重层一致性（safetensors ↔ ncnn bin）

修复脚本 export/rewrite_vision_bin.py 在写出每个 blob 时即做 self-check，确保与 safetensors 完全一致：

检查项	结果
309/309 权重 blob（196 MatMul + 113 RMSNorm）vs safetensors	cos = 1.0（全部）
layer-0 q_proj 权重（ncnn Wᵀ 布局）vs safetensors q_proj.weight	cos = 1.0
layer-0 k_proj 权重（含 GQA 8→16 头展开，Wᵀ 布局）vs safetensors 展开后	cos = 1.0
vision_projector.ncnn.bin 4 blob vs safetensors	干净，cos = 1.0，无需重生成

这一步同时确认了两个关键约定：ncnn MatMul 权重以 [h=in, w=out] = Wᵀ 形式存储；k/v 权重须经 repeat_interleave 做 GQA 头数展开（8 KV 头 → 16 Q 头）。

5.3 纯文本 decoder 一致性

纯文本路径不依赖视觉，验证 C++ 解码器正确性。

• 比对方法：C++ 贪婪生成输出 token 序列 vs PyTorch verify_greedy.py 的 PY_IDS。
• 结果：生成文本「我是一个人工智能助手，能够帮助您完成各种任务和解决问题。」与 PyTorch 逐 token 完全一致（exact match，非近似）。

5.4 视觉编码器逐层一致性（layer-by-layer）

为定位 4.2 的 NaN 根因，做了逐层中间量比对，确认每层图计算与 PyTorch 一致：

检查项	方法 / 脚本	结果
Layer 0 全部中间量	verify_layer0.py：复算 rmsnorm/rotate_half/SDPA 等	q_proj / q_norm / q_rope / k_rope / sdpa / o_proj / L0 残差 全部 cos = 1.0
Layer 1 残差	同上流程复算 L1	cos = 1.0（证明 L0/L1 图计算完全正确，残差 685→1283 放大是模型真实行为）
28 层残差链（PyTorch 真值）	compare_layers.py：用 reference_vision.decoder_layer 跑全链，打印每层 max/min/nan	全程有限（L0=685 → L18=3481 → L19 突跳 104924 → L27=4,927,556，无 NaN）→ 证明图在 L2 的 NaN 是图自身 bug，非模型行为
Layer N 通用比对	verify_layerN.py：先复算 layer N−1 输出再比 layer N 中间量	用于定位 layer 2 的 k_proj（blob 241）已含 990 个 NaN → 锁定权重损坏根因

5.5 视觉编码器整体输出一致性

• 方法：compare_enc.py 将 ncnn vision_encoder 的 out0 与 PyTorch vision_forward（28 层 + final norm，merge 之前）逐元素比对。
• 结果：cos = 0.999965，max_abs = 0.034，nan = 0。
• 解读：cos 略低于 1.0 来自 28 层 fp32 注意力累积漂移（量级 10⁶ 量级残差对 0.034 绝对误差），符合 fp32 端到端精度预期，远优于目标阈值 0.99。

5.6 全视觉链路一致性（encoder + merge + projector）

• 方法：verify_full_vision.py 比对 ncnn 整条视觉链路输出与 PyTorch 参考 features_ref.npy（encoder 输出经位置 merge 再经 2 层 MLP projector 后的特征）。
• 结果：cos = 0.999980，nan = 0 → 视觉特征送入 LLM 前的最后一环也与原版一致。

5.7 端到端图文一致性（C++ 自包含推理 vs 真值语义）

测试图	输入	模型输出	结论
英文文字图	"Compressed and interpretable light-weight model ready for edge deployment."	精确 OCR 出原文	恢复文字识别能力，证明视觉特征质量足够高

5.8 一致性验证汇总

检查项	方法	结果
权重一致性	309/309 blob vs safetensors	cos = 1.0
纯文本 decoder	C++ 贪婪 vs PyTorch PY_IDS	逐 token 精确一致
视觉编码器逐层	L0/L1 中间量 vs PyTorch	cos = 1.0
视觉编码器输出	ncnn out0 vs PyTorch 28 层 + final norm	cos = 0.999965
全视觉链路	encoder + merge + projector vs features_ref.npy	cos = 0.999980
projector 权重	vision_projector.ncnn.bin 4 blob vs safetensors	cos = 1.0，无需重生成
端到端·图像描述	使用下面的测试图	准确描述
端到端·OCR	英文文字图	**精确 OCR **

---

提示词：请描述这张图片
output：这张图片是一段文字，内容如下：
"Compressed and interpretable light-weight model ready for edge deployment."
这段文字描述了一个轻量级、可解释的模型，已经压缩好，准备用于边缘部署。

提示词：请描述这张图片
output：这张图片展示了一个紧张的场景，看起来像是电影或电视剧中的一个片段。画面中，一个穿着深色衣服的男子正与另一个坐在椅子上的男子进行对话。坐在椅子上的男子穿着浅色T恤，表情严肃，似乎在认真倾听或回应对方。背景中可以看到其他几个人，他们似乎在观看或参与这个对话。整个场景的光线较暗，给人一种紧张和严肃的氛围。图片下方有文字：“对不起，我是诺曼·斯佩尔曼”，这表明对话的主角之一是诺曼·斯佩尔曼，而坐在椅子上的男子可能是他的对手或对手方。

6. 模型发布（Hugging Face）和代码仓库

• 模型仓库：https://huggingface.co/xxzigou/plugin-VL-ncnn
• 代码仓库：https://github.com/AiChiTuDouPian/plugin-VL-ncnn
• 上传内容：仅运行必需的 15 个文件 / 约 6.3GB
  • 6 组 *.ncnn.{param,bin}（decoder / embed / lm_head / vision_embed_patch / vision_encoder / vision_projector）
  • vocab.txt、merges.txt、model.json、README.md

7. 结论与后续

• vision encoder NaN 已彻底修复（从 safetensors 整体重生成，309 blob 全 cos=1.0），并通过 5.2–5.7 全层次的 PyTorch 一致性验证：纯文本 decoder 逐 token 精确一致，视觉编码器输出 cos = 0.999965、全视觉链路 cos = 0.999980、端到端图文推理视觉接地、OCR 可用。
• 模型权重已打包并发布至 Hugging Face Hub（仅含运行必需文件，约 6.3GB）。