Penguin-VL-2B ncnn porting

[lvy010]

• Github：https://github.com/lvy010/penguin-vl-ncnn
• Huggingface：https://huggingface.co/lvy010/penguin-vl-2b-ncnn

1.Penguin-VL-2B

一个视觉-语言多模态模型，由视觉塔 + LLM 解码器构成，端到端流水线如下：

Image(RGB) -> PatchEmbed(14x14) -> ViT Encoder(1024d, 2D-RoPE) -> Projector(->2048d)
                                                                        |
                                                                image_embeds
                                                                        v
Output Tokens <- LM Head(2048->151675) <- LLM Decoder(28L, GQA) <- Embedding + <image> 替换(2048d)
      ^
   BBPE Tokenizer

参数

组件	维度	层数	头数	备注
ViT Encoder	1024	-	head_dim=128	patch_size=14, 2D-RoPE, rope_theta=1e6
Projector	1024 -> 2048	-	-	对齐 LLM 隐藏维
LLM Decoder	2048	28	16 heads / 8 kv heads	GQA, head_dim=128, intermediate=6144
LM Head	2048 -> 151675	-	-	tie_word_embeddings（权重与 embedding 共享）

• rope_theta = 1000000，无 rope_scaling，rms_norm_eps = 1e-6
• 分词器：字节级 BPE（bbpe），特殊 token 含 <|im_start|>、<|im_end|>、<image>、<think>、</think>

目标

• 数值对齐：fp32 下逐子图对齐，最终 greedy 文本与 PyTorch 逐 token 一致。
• 零 Python 依赖：纯 C++，产物是运行时库 + CLI。
• 自包含：单个模型目录（6 个 ncnn 子图 + 分词器 + model.json）即可推理。

---

2. 架构

2.1 子模型拆分策略

为适配 ncnn 的静态形状约束并降低单次 trace 的复杂度，将 PyTorch 模型拆成 6 个独立 ncnn 子图：

子模型	文件	输入 -> 输出
Patch Embed	vision_patch_embed.ncnn.{param,bin}	图像 patch -> 1024d
Vision Encoder	vision_encoder.ncnn.{param,bin}	1024d -> 1024d hidden
Projector	vision_projector.ncnn.{param,bin}	1024d -> 2048d
Embedding	embed.ncnn.{param,bin}	token_id -> 2048d
LLM Decoder	decoder_nocache.ncnn.{param,bin}	hidden, mask, cos, sin -> 2048d
LM Head	lm_head.ncnn.{param,bin}	2048d -> 151675 logits

2.2 运行时调用流

PenguinVL::chat(prompt, image_path)
  |
  |-- 视觉分支
  |     |-- load_image + preprocess          -> pixel_values
  |     |-- PatchEmbed -> VisionEncoder -> Projector -> image_embeds [N, 2048]
  |
  |-- build_prompt(chat 模板 + <image> 占位 + <think> 块)
  |-- Embedding(token_ids) -> text_embeds，并把 <image> 位置替换为 image_embeds
  |
  |-- for step in 0..max_new_tokens:              # 无 cache：每步重跑整段序列
        |-- make_causal_mask(n) + generate_rope_embed_cache_full(n)
        |-- Decoder(running, mask, cos, sin)      -> hidden [2048, n]
        |-- LmHead(hidden[-1])                    -> logits [151675]
        |-- argmax / sample                       -> next_id
        |-- if next_id == eos: break
        |-- 把 next_id 的 embedding 追加到 running

---

3. LLM 解码器的图转换

与跨平台一致性

1 — KV-cache 解码器无法转换。 把 KV-cache 作为图输入、并 unsqueeze(0) 加 batch 维的写法，使 pnnx 在 pass_level0 内联 RMSNorm 时崩溃（0xC0000409），即便转换成功，ncnn 运行时也在 prefill 阶段堆损坏。根因是该模式在 28 层 Qwen3 大图下触发深层结构不兼容。

• 方案：放弃 KV-cache，改用无 cache 解码器每步重跑整段序列——O(n^2) 但可靠、自包含，与已验证的 batch=1 视觉编码器同款注意力风格。

2 — pnnx 把序列长度写死。 导出后 .param 里 Reshape 将 trace 时的 seq=8 固化（0=8 1=8 / 2=8），变长输入即元素数不匹配 → 乱码或崩溃。

• 方案：向 pnnx 追加第二组不同 seq 的 inputshape2，令其自动把不一致维标记为动态（2=-1）。

3 — 动态形状引入不可加载算子。 GQA 的 repeat_kv 用 expand(...).reshape(...)，动态下被降级成 ncnn 不支持的 pnnx.Expression / Tensor.expand。

• 方案：改用静态平铺 repeat(1,1,rep,1,1)（映射到 ncnn Tile），reshape 仅保留单一 -1 推断维，并把 q/k/v/cos 统一改为 view(-1, ...)，彻底消除动态表达式。

4 — 因果 mask 被降级成双 -1 Reshape。 逐子图对齐锁定问题在解码器后，.param 中出现 Reshape ... 0=-1 1=-1 2=1：scores(4D)+mask(2D) 的广播被降级为带两个待推断维的 Reshape，ncnn 无法求解，表现为「连贯却错误」的输出。

• 方案：导出后自动把该 Reshape 改写为保持原维的 0=0 1=0 2=1，C++ 侧只喂 2D 因果 mask 由图内部广播

5 — Windows argv 的 GBK 编码。 embed/decoder/lm_head/RoPE 全部验证正确后仍输出错误，打印 token id 发现中文被拆成字节 token（「请用」= GBK 字节 C7 EB D3 C3）。根因是 Windows ANSI argv 为 GBK/936，中文在进入 UTF-8 分词器前已损坏。

• 方案：入口处用 CommandLineToArgvW + WideCharToMultiByte(CP_UTF8, ...) 重建 UTF-8 argv，并 SetConsoleOutputCP(CP_UTF8)；修复后 token id 与 HF 逐 id 一致，文本与 PyTorch 逐字一致。

---

4.编译与运行

# 1. 编译 ncnn
git clone https://github.com/Tencent/ncnn.git && cd ncnn
cmake -B build -DCMAKE_BUILD_TYPE=Release -DNCNN_VULKAN=OFF
cmake --build build -j
cmake --install build --prefix build/install

# 2. 编译本项目
cd penguin-vl-ncnn
cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH=$PWD/../ncnn/build/install
cmake --build build --config Release

# 3. 导出子图
python tools/export_decoder_kvcache.py --model ./Penguin-VL-2B --out ./penguin-vl-2b-ncnn \
    --seq 8 --no-cache --name decoder_nocache

# 4. 运行文本推理
./build/Release/penguinvl --model ./penguin-vl-2b-ncnn \
    --prompt "请用一句话介绍你自己" --threads 8 --max-new-tokens 30

# 5. 运行图像推理
./build/Release/penguinvl --model ./penguin-vl-2b-ncnn \
    --image ./assets/test.jpg --prompt "请描述这张图片" --threads 8 --max-new-tokens 40