Youtu-VL ncnn 移植与多平台部署

[everythingfornothing]

Youtu-VL ncnn 移植与多平台部署

本项目将 Youtu-VL-4B 的完整推理链路从
Python/PyTorch/Transformers 迁移到 ncnn 和 C++，并在 Linux 与 Windows
平台完成编译、运行及最终生成结果回归。

项目链接

• C++ 推理代码： Youtu-VL-ncnn
• ncnn 模型权重： Youtu-VL-4B-Instruct-ncnn

GitHub 仓库包含完整的 C++ 推理运行时、CMake 构建文件、图片
Processor、Chat Template、ByteLevel-BPE Tokenizer、LLM 生成循环，以及
Linux 和 Windows 的构建与运行说明。

Hugging Face 仓库包含运行时所需的 ncnn 模型权重和相关模型资产。由于模型
文件体积较大，权重与源代码分开发布。

在文章的“构建与运行”部分再说明两个仓库如何配合：

构建与运行

1. 克隆 C++ 推理代码：

   https://github.com/everythingfornothing/Youtu-VL-ncnn

2. 下载转换后的 ncnn 模型权重：

   https://huggingface.co/Coderdw/Youtu-VL-4B-Instruct-ncnn

3. 将模型资产放入运行命令指定的模型目录，通过 --model-dir 参数传入，
   然后使用 CMake 编译并运行程序。

摘要

腾讯优图提出 Youtu-VL，旨在以轻量级统一架构缓解传统视觉语言模型的文本偏置，并增强模型对检测、分割、深度估计等细粒度视觉任务的建模能力。Youtu-VL-4B 的官方推理链路依赖 Python、PyTorch、Transformers 以及模型仓库中的自定义代码。这套环境适合研究、调试和快速迭代，但当模型需要被嵌入机器人软件、桌面应用或已有 C++ 系统时，Python 运行时、依赖管理、模型生命周期和跨平台交付都会成为额外负担。本项目的目标，是在保留原模型权重和推理语义的前提下，将完整推理链路迁移为由 ncnn 执行模型计算、C++ 负责动态调度与系统集成 的实现。

迁移并不是把 Python 代码逐行翻译成 C++。我首先通过源码分析将模型拆分为图像处理、SigLIP2 Vision Encoder、VLPatchMerger、多模态 Embedding 融合、Youtu LLM Prefill、KV Cache Decode、Final RMSNorm、LM Head 和 Tokenizer 等部分，再根据每部分的动态性决定哪些计算进入 pnnx/ncnn 图，哪些布局、缓存和控制逻辑保留在 C++。在此基础上，我从结构简单但真实存在的 VLPatchMerger 入手，建立了“源码理解—接口契约—Golden 数据—PyTorch Wrapper—pnnx—Python ncnn—C++ ncnn—数值与功能验收”的通用流程，再逐步推广到更复杂的 Vision、40 层 LLM 和连续自回归生成。

项目中使用 AI 辅助源码理解、候选方案生成、Wrapper 与测试脚手架编写、错误归因和重构建议，但 AI 输出始终被视为待验证假设。每段代码都必须经过真实接口检查、编译运行、Tensor Contract、数值对齐和最终 token 回归。通过这一方式，我将“大模型移植”拆成多个可观察、可回滚、可验收的小问题，并在实际失败中不断修正最初的方法框架。本项目的主要工作如下：

首先，完成了基本的转化要求，模型能够在多平台上完成转化。最终实现能够直接接收图片和 Prompt，由 C++ 完成图片 Processor、Chat Template、ByteLevel-BPE 编解码和生成循环；ncnn 子图与 C++ Bridge 共同完成 27 层 Vision、VLPatchMerger、40 层 Prefill/Decode、KV Cache、Final RMSNorm 和 17 个 LM Head分片。整个运行时不依赖 Python、PyTorch、Transformers、BLAS、MKL 或 OpenBLAS。

其次，利用 AI 构建起了一套 AI 辅助完成的方法。在项目推进过程中，借助 AI 辅助源码理解、候选方案生成以及错误归因，将“大模型移植”有效拆解成了多个可观察、可回滚、可验收的小问题，并在实际落地中持续修正验证框架。

最后，我们的方法在三张真实图片上完成了分层回归：锈蚀易拉罐图片用于中文垃圾分类和 Linux/Windows 跨平台验证，狗与印花毯图片用于英文 VQA，城市道路图片用于目标检测和坐标后处理。主用例覆盖 Linux 32/64/128 token 与 Windows 1/32/64/128 token，两个补充用例各生成 64 token；每个用例都保存了具体输出文本、最终 token ID、Processor Tensor、Top-1/Top-2 和运行报告。借助 Persistent 模式（将 138 个 ncnn 图在 Prefill 前加载一次并复用），与早期重复加载版本相比，Linux 32/64/128 token 的最终端到端耗时分别获得约 8.46×、11.23× 和 15.90× 加速。在 persistent 基线之上，便携 GEMM 与纯 C++ 前端又分别带来了约 1.64×、1.46× 和 1.36× 加速。

1. 项目目标与迁移边界

1.1 迁移目标与系统边界

Youtu-VL-4B 是一个约 4B 参数的视觉语言模型。它的官方运行方式包含以下几层能力：

Python 控制流程
  + Hugging Face Processor / Tokenizer
  + Transformers generate()
  + PyTorch 模型与算子
  + CPU / CUDA 后端

这套包含 Python 和 PyTorch 的技术栈在研发与调试阶段极为高效，但一旦走向嵌入式边缘设备、机器人软件或桌面应用等实际的生产部署，就会面临难以规避的痛点，这也是必须进行推理迁移的核心原因。首先是环境依赖过于沉重，官方链路强依赖 Python 解释器和庞大的深度学习依赖包，在端侧或客户端打包分发整个生态是极不现实的。其次，语言壁垒会导致系统集成割裂，许多成熟的硬件控制或音视频管线均由 C/C++ 构建，如果模型受限于 Python，跨进程或网络通信不仅会增加数据拷贝与延迟，也会大幅提高维护成本。最后是资源调度与生命周期不可控，在资源受限环境中，系统必须对内存分配以及模型权重和 KV Cache 进行精准的显式控制，而 Python 的自动垃圾回收和黑盒调用使得这种细粒度管理变得极为困难。

正是为了解决这些痛点，才有了“推理迁移”的必要性。这并不意味着 PyTorch 或 Transformers 是“多余”的，它们依然在模型训练、研究与快速验证中发挥着不可替代的作用。但在最终的部署阶段，系统不再需要自动微分与复杂的网络构建，只需要稳定的前向计算、轻量的输入处理和自回归生成。

因此，本项目的目标并不是单纯追求“C++ 一定比 Python 快”，而是建立一个轻量、可嵌入、可控制、可验证、可跨平台交付的模型运行时。实际性能由推理引擎、算子、权重格式、线程和硬件共同决定；C++ 的主要价值还包括系统集成和工程可控性。

从部署系统的职责划分看，这次迁移可以进一步概括为：

模型中的稳定数学计算  → pnnx 转换 → ncnn 执行
模型外的动态控制逻辑  → C++ 实现
训练相关能力            → 不进入部署端

原始版本和迁移版本的关系如下：

原始版本
Python
  ├─ Processor / Tokenizer
  ├─ 模型调度与 generate()
  └─ PyTorch 计算图

迁移版本
C++
  ├─ Processor / Tokenizer
  ├─ Vision / LLM 调度
  ├─ KV Cache 与生成循环
  └─ ncnn 计算图

其中：

• pnnx 是从 PyTorch/TorchScript 到 ncnn 的转换工具；
• ncnn 是实际执行权重计算的推理引擎；
• C++ 负责动态 shape、Tensor 布局、图片与文本处理、Cache、循环和跨平台接口。

1.2 模型结构与主要风险

完整推理链路可以简化为：

图片
  ↓
C++ Image Processor
  ↓
SigLIP2 Vision Encoder（27 层）
  ↓
VLPatchMerger
  ↓
image embeddings

Prompt
  ↓
Chat Template + ByteLevel-BPE
  ↓
text embeddings

image embeddings + text embeddings
  ↓
图文融合
  ↓
Youtu LLM（40 层）
  ↓
Final RMSNorm
  ↓
tied LM Head
  ↓
Token / Text

关键模型契约如下：

项目	数值
Vision 层数	27
Vision hidden size	1152
LLM 层数	40
LLM hidden size	2560
Attention heads	32
Q/K 非 RoPE 维度	128
Q/K RoPE 维度	64
Value 维度	128
Vocabulary size	283386
image token ID	128264
EOS token ID	128001
已验证 batch	1
已验证输入形态	单图片 + 单 Prompt

在明确模型结构之后，我与 AI 初步讨论解决方案，并将迁移风险归纳为以下几类，以便进行针对性准备。

模型结构问题：

• Vision 使用动态二维 RoPE、window attention 和 full attention；
• 图片分辨率变化会改变 patch 数、mask 和位置编码；
• LLM 使用自定义 MLA 风格 Attention，而不是最普通的 QKV；
• Prefill 与 Decode 的序列长度和状态不同；
• KV Cache 必须跨 token 保持并增长；
• embedding 与 LM Head 使用 tied weight，词表投影体积很大。

转换工具问题：

• PyTorch 的 [batch, sequence, hidden] 与 ncnn 的 Tensor 布局语义不同；
• pnnx 对 batch 轴上的 reshape、expand、permute 支持有限；
• Slice、Concat 的轴可能在转换后失去原语义；
• 一个模型能够生成 .param/.bin 并不代表数值一定正确。

系统工程问题：

• 4B 模型及其导出中间副本会产生较大内存和磁盘压力；
• 若每个 token 重复加载权重，I/O 会成为主要瓶颈；
• LM Head 权重约 1.35 GiB（FP16），不能粗暴地在单进程中反复复制；
• KV Cache 会随上下文增长，需要稳定的生命周期设计。

跨平台问题：

• Windows 中文命令行和 UTF-8；
• Linux 与 Windows JPEG 解码差异；
• ncnn 静态库、OpenMP、JPEG 和运行 DLL；
• CMake Cache 和二进制不能跨平台复用。

这些问题决定了项目不能以“一次性端到端转换”为起点，而必须先建立一套可重复的验证方法。

2. AI 辅助的工程框架与验证体系

2.1 从资料梳理到可执行框架

开始项目时，我对 C++、PyTorch 推理和模型前向已有初步理解，但对以下内容缺少系统经验：

• pnnx 的实际转换边界；
• ncnn Mat 的布局和动态 shape；
• Vision Transformer 的 window 调度；
• 多模态 embedding 的替换规则；
• MLA Attention 和 KV Cache；
• 大模型转换中的内存与资产管理；
• Windows 下的模型推理交付。

ai使得我们能够快速学习一个新的领域，所以我先建立一个认知闭环：阅读源码获得事实，使用 AI 加快结构化理解，再用实验决定哪些理解可以进入工程。

为把初步认识转化为工程行动，我首先把问题拆成三类，并分别向 AI 提供不同上下文。

第一类：模型是什么。

我向 AI 提供 modeling_youtu_vl.py、modeling_siglip2.py、配置文件和实际 Tensor shape，让它帮助回答：

• 模型由哪些真实模块组成；
• 图片特征在哪里产生；
• 视觉 embedding 如何进入语言模型；
• LLM 的入口、层结构和 LM Head 在哪里；
• 哪些逻辑是 Tensor 计算，哪些是 Python 控制流。

第二类：应该如何迁移。

我让 AI 根据 ncnn/pnnx 的定位，提出候选的分层迁移方案。但我不会直接接受“完整模型一键转换”之类结论，而是要求方案必须包含：

• 模块输入输出；
• Wrapper 边界；
• Golden 数据；
• 失败后的拆分路径；
• C++ 和 ncnn 的职责；
• 每一步的验收标准。

第三类：具体错误如何定位。

当遇到 pnnx 警告、数值离群、段错误或跨平台问题时，我把完整源码片段、输入 shape、版本、日志和已经排除的原因交给 AI，请它生成若干假设和最小实验，而不是只问“这个报错怎么修”。

2.2 问题切割与通用迁移流程

在平常使用ai的过程中，我逐渐形成一个判断：

AI 最适合处理的，不是整个项目，也不是孤立的一行代码，而是具有清晰输入、输出和成功标准的最小工程单元。

例如，下面的任务边界是合适的：

模块：VLPatchMerger
输入：vision_hidden [1152,1152]
输出：image_embeddings [288,2560]
目标：生成只接受 Tensor 的 Wrapper
验收：原模块与 Wrapper 相同；ncnn 与 Wrapper 接近；C++ 与 Python ncnn 一致

相比之下，“帮我把 Youtu-VL 全部迁移到 ncnn”会把 Vision、Tokenizer、KV Cache、动态 shape 和系统构建混在一起；而“帮我写一行 reshape”又缺少足够上下文，无法获得可靠的效率提升。

确定合适的问题粒度后，我将 AI 输出视为以下几类候选资产：

• 源码结构解释；
• Wrapper 或 C++ 类的脚手架；
• Tensor 对比脚本；
• 报错的候选原因；
• 最小复现实验；
• CMake 或平台代码的初稿；
• 文档和报告结构。

但候选资产只有经过下面的流程才能被接受：

AI 建议
  ↓
真实源码字段检查
  ↓
编译 / 运行
  ↓
Shape / dtype / finite 检查
  ↓
数值或 token 对齐
  ↓
回归旧用例
  ↓
进入主分支

这套方式避免了两个常见问题：一是 AI 根据常见模型猜出不存在的接口；二是代码看起来合理，但 Tensor 布局或 Cache 语义已经改变。

经过早期讨论和实验，这些约束最终形成了第一版通用迁移流程：

1. 阅读源码，确认真实计算链
2. 写模块 Contract
3. 冻结输入和 PyTorch Golden
4. 写最小 Tensor Wrapper
5. 原模块与 Wrapper 同源验证
6. pnnx 转换
7. Python ncnn 数值验证
8. C++ ncnn 最小 Runner
9. 串联上下游模块
10. 观察误差传播和最终决策
11. 再做动态输入、性能和跨平台

这不是一个机械模板。进入新模块前，我都会重新判断：

• 新模块相对上一模块增加了什么动态行为；
• 是否存在状态和控制流；
• 是否适合成为一个 ncnn 图；
• 哪些操作更适合放在 C++ Bridge；
• 验收标准是否应该从数值一致升级为 token、Cache 或文本一致。

2.3 Golden、Contract 与五级验收门禁

如果端到端文本错误，可能来自图片 resize、patch 排列、Vision、Merger、图文融合、LLM、KV Cache、LM Head 或 Tokenizer。只比较最终文本无法定位问题，甚至可能因为 greedy token 暂时相同而掩盖某个中间错误。

因此我先建立 PyTorch Golden。根据阶段不同，保存内容包括：

Processor 输入
Vision hidden
image embeddings
text embeddings
fused embeddings
Layer 0 / Layer 20 / Layer 39 hidden
Final Norm
Top-K logits
generated token IDs
KV Cache
最终文本

主回归固定模型 revision、图片、Prompt 和生成参数。最终主用例为：

model revision: 8d30a0e49662a1d628a472b12df264dbcd768753
image: test_data/input_image.jpg
prompt: 这是什么类型的垃圾
do_sample: false
repetition_penalty: 1.0
image grid: [34,50]
prefill length: 450
image token id: 128264
EOS token id: 128001
threads: 8
Vulkan: OFF

在 Golden 基线上，我没有为所有模块使用同一个简单阈值，而是建立了五级验收门禁。

Gate 1：接口正确。

shape
dtype
元素数量
image token 数
Cache 长度

Gate 2：数值稳定。

NaN = 0
Inf = 0
输出范围合理

Gate 3：数值一致。

max_abs_error
mean_abs_error
P99 / P99.9 / P99.99
cosine_similarity

Gate 4：决策一致。

Top-1 / Top-2
Top-K overlap
logit margin

Gate 5：功能一致。

generated token IDs
最终文本
EOS 停止位置
KV Cache 长度与不变性

五级门禁也意味着不能孤立地解释绝对误差。在多层 Transformer 中，少数大幅值通道可能产生较大的最大绝对误差，但绝大多数元素和整体方向仍然一致。最终生成新 token 时，真正关键的是最后一个位置的 hidden、词表 logits 排名和 Top-1/Top-2 margin。

因此，当后续出现 Layer 20 MLP 放大离群误差时，我没有立即回退整个实现，而是继续检查：

• 大误差元素比例；
• 误差集中在哪些 token/channel；
• 是否从某一层突然跳变；
• 最后一个 token 是否受到影响；
• Final Norm 后是否稳定；
• Top-K 和最终 token 是否改变。

为了让这些判断可以复查，每个阶段尽量保存：

• 模型 .param/.bin；
• 输入与输出 NPY；
• 机器可读 JSON；
• PyTorch、pnnx、ncnn 版本；
• 执行参数；
• 构建信息；
• SHA-256。

最终完整模型包包含 339 个必需资产，约 13.43 GiB，并完成全量校验。源码仓库和模型包分离，避免将大权重直接提交到代码仓。

---

3. VLPatchMerger：用最小真实模块建立流程

3.1 切入原因、源码结构与 Contract

我没有先写一个与项目无关的 toy model，也没有直接转换完整 Vision，而是选择 Youtu-VL 中真实存在、结构相对简单的 VLPatchMerger。它同时满足：

• 是真实推理链的一部分；
• 输入输出明确；
• 包含 RMSNorm、reshape、Linear 和 GELU；
• 没有 Attention、Cache 和复杂动态控制；
• 输出直接进入语言模型，具有工程价值。

这使它成为验证“PyTorch → pnnx → ncnn → C++”整条工具链的最小真实闭环。

选定模块后，我先从源码中确认它的真实计算链：

vision_hidden [1152,1152]
  ↓ YoutuRMSNorm
  ↓ view(-1,4608)
  ↓ Linear
  ↓ GELU
  ↓ Linear
image_embeddings [288,2560]

spatial_merge_size=2，因此每四个 Vision token 被合并为一个语言模型视觉 token。源码中的 forward(x, spatial_shapes) 虽然带有 spatial_shapes，但实际计算没有使用它，因此导出 Wrapper 只保留 vision_hidden 一个输入。这一决定不是为了简化而猜测，而是来自对真实源码的检查。

3.2 转换过程、问题处理与结果

AI 帮助生成了 Wrapper 骨架和对比脚本，但我为其定义了明确门禁：

1. 原 model.merger 与 Wrapper 使用同一对象、同一输入；
2. Wrapper 输出必须与原模块相同；
3. pnnx 输出的 ncnn 模型必须在 Python binding 中运行；
4. C++ Runner 必须加载同一 .param/.bin；
5. Python ncnn 与 C++ ncnn 结果必须一致。

最终验证链为：

Original Merger
≈ PyTorch Wrapper
≈ Python ncnn
≈ C++ ncnn

实际转换暴露了两个需要单独定位的问题。第一个问题是输入 shape 写错。

最初使用了 [1152,768]，但 Golden 中的 vision_hidden 是 [1152,1152]，RMSNorm 权重长度也是 1152。通过输入数据和权重维度交叉检查，修正为 [1152,1152]。

这让我形成了一个规则：shape 不依赖记忆或 AI 猜测，而应由真实 Tensor、源码和权重三方确认。

第二个问题是 FP16/FP32 不一致。

最初 Wrapper 为 FP16，而 pnnx 测试输入为 FP32，导致 Linear dtype 不匹配。直接用 FP32 加载完整 4B 模型又带来较大内存压力。最终采用：

完整模型以 FP16 加载
只把当前目标模块转换为 FP32
首轮 pnnx 使用 FP32 基线

这既减少了模型加载压力，也把转换误差与低精度误差分开。

修正上述问题后，最终结果为：

input shape  = [1152,1152]
output shape = [288,2560]

max_abs_error  = 0.0057869
mean_abs_error = 5.13e-05
cosine         = 0.9999999818

原模块与 Wrapper 的最大误差为 0；Python ncnn 与 C++ ncnn 的误差报告一致。

3.3 从最小模块归纳通用规则

完成 Merger 后，我将第一版流程修正为：

1. 每个模块先写 Tensor Contract；
2. Wrapper 必须先与原模块同源验证；
3. 第一轮优先用 FP32 建立转换基线；
4. 大模型采用“整体低精度加载、目标模块局部高精度导出”；
5. Python ncnn 通过后必须补一个最小 C++ Runner；
6. 每阶段保存机器可读误差报告和版本信息。

这一阶段的价值不只是转换了一个小模块，而是建立了后续 Vision 和 LLM 都能够复用的验证框架。

---

4. Vision Encoder：将流程迁移到动态多层结构

4.1 完整模型优先与分层定位

Vision Encoder 不再是一个简单静态模块，它包含：

• 27 层 Transformer；
• 动态二维 RoPE；
• window attention 与 full attention；
• window_index 和反向重排；
• 动态 patch 数；
• 多层误差累计。

真实输入 Contract 为：

pixel_values             [1, patch_count, 768]
pixel_attention_mask     [1, patch_count]
spatial_shapes           [1,2]
vision_hidden            [patch_count,1152]

对于早期样例：

spatial_shapes = [32,36]
patch_count = 1152
pixel_values = [1,1152,768]
vision_hidden = [1152,1152]

针对这些新增特性，我没有默认把 27 层全部拆开，而是采用完整优先、失败后再拆的策略：

先尝试完整 Vision Wrapper
  ├─ 能转换并数值正确 → 直接使用
  └─ 失败或异常 → Embedding / 单个 Block / 前 N 层 / 二分定位

这体现了一个工程原则：拆分是一种诊断工具，不应成为没有必要的复杂度。

4.2 计算图、外部调度与动态图片

第一次导出 Vision Embedding 时，图结构大致是：

Input [1,1152,768]
  ↓ Gemm
  ↓ Reshape
[1152,1152]

pnnx 可以生成模型，但 ncnn 输出出现 NaN 和接近 float32 上限的数值。这不是普通的低精度误差，而是 Tensor 布局被误解的信号。

根据 AI 给出的候选原因，我设计了最小实验：只在 Gemm 前显式去掉固定 batch 维。

pixel_values = pixel_values.view(-1, 768)

转换后图变为：

Input
  ↓ Reshape [1152,768]
  ↓ Gemm
[1152,1152]

数值恢复稳定：

max_abs_error  = 6.44e-06
mean_abs_error = 1.18e-07
cosine         ≈ 1

由此得到的重要经验是：

Shape 表面匹配，不代表 Tensor 轴语义正确。遇到 NaN、极大值或完全错误的 cosine 时，应首先检查 batch、sequence、hidden 的布局，而不是调低阈值或归因于 FP16。

修正 Vision Embedding 的布局后，下一项边界来自动态窗口重排、RoPE 和 mask。它们不适合强行静态化，因此我将每层拆成稳定的权重计算核心：

LayerNorm
→ Q/K/V Linear
→ RoPE 输入
→ MatMul / Softmax / MatMul
→ out_proj
→ residual
→ LayerNorm
→ MLP
→ residual

以下逻辑留在图外：

window_index reorder
reverse window_index
RoPE cos/sin 生成
cu_seqlens / attention mask
动态分段

这不是把所有计算都手写，而是根据 pnnx/ncnn 的能力划分边界：稳定、权重密集的计算进入 ncnn；布局和 shape 相关逻辑由 C++ 管理。

计算图边界确定后，转换脚本本身又暴露了内存问题。最初为了取得某个 Vision Layer，我仍使用 AutoModelForCausalLM 加载整个 4B 模型，结果语言模型主体也进入内存。这个问题提醒我：模型转换工具本身也需要资源工程。

改进方案为：

1. 只实例化 Siglip2EncoderLayer；
2. 只读取 vision_config；
3. 使用 safetensors.safe_open 只加载当前层权重；
4. 一次只处理一层；
5. 无权重的 RoPE/window 预处理单独计算。

这样逐层导出不再要求完整 4B 模型常驻内存。

逐层导出和单层对齐完成后，我继续进行 27 层串联测试。串联初期还发现一个 Python binding 生命周期问题：

ncnn.Mat(layer_input.astype(np.float32)).clone()

这里把临时 ndarray 直接传给 ncnn，导致单层结果正确、串联结果异常。改为先创建连续、持久的 NumPy 对象：

layer_input = np.ascontiguousarray(layer_input, dtype=np.float32)

问题消失。这个案例说明，模型边界正确以后，数据所有权和内存连续性同样属于验证范围。

Python 调度通过后，我将同样的过程迁入 C++，形成 Scheduled Vision Runner：

读取 pixel_values / spatial_shapes
→ C++ 生成 window_index / reverse_index
→ ncnn Vision Embedding
→ C++ reorder
→ 27 个 ncnn Vision Block
→ C++ reverse reorder
→ ncnn post_layernorm
→ vision_hidden

C++ scheduled ncnn 与 Python scheduled ncnn 逐元素一致，证明“ncnn 子图 + 外部调度”的架构可以稳定迁移到 C++。

这个 Runner 早期只支持固定 [36,32] grid。我选择在入口明确拒绝不支持的图片，而不是静默使用错误的 RoPE 和 mask；等固定路径充分验证后，再实现动态 Bridge：

• 根据 spatial_shapes 运行时生成 window index；
• 动态生成 Vision RoPE 和 attention mask；
• 修改内存中的 .param 序列长度和 reshape/Gemm 行数；
• 使用 load_param_mem()；
• .bin 权重继续复用。

动态 [34,50] grid 最终能够运行，固定 [36,32] 路径也通过回归。这一演进体现了：

对动态能力，应先通过显式限制保证正确，再逐步放开，而不是一开始把所有不确定性叠加在一起。

4.3 Vision 阶段的方法更新

这一阶段将通用流程进一步修正为：

1. 先尝试完整转换，失败后再拆；
2. pnnx 不擅长的动态控制逻辑不必强行塞入计算图；
3. shape-dependent 与 weight-dependent 逻辑应解耦；
4. 单层通过后必须做多层串联；
5. Python 调度通过后再迁移到 C++；
6. 对暂不支持的输入应主动拒绝，而不是产生不可解释结果。

---

5. 多模态融合、Youtu LLM 与端到端 Runtime

5.1 多模态 Embedding 与接口 Contract

文本 token 首先通过 embedding lookup 得到：

text_embeddings [1,S,2560]

Vision 和 Merger 得到：

image_embeddings [image_token_count,2560]

输入序列中包含同样数量的 image_token_id=128264 占位符。融合就是找到这些位置，并按顺序用视觉向量替换文本向量：

text embeddings
+ image embeddings
→ fused_embeddings [1,S,2560]

融合没有复杂神经网络权重，但并不因此天然正确，它仍可能发生：

• image token 数量不一致；
• token 位置偏移；
• 视觉 token 顺序错误；
• 覆盖普通文本 token；
• batch 或 hidden 维布局错误。

因此我先在 Python 中独立复现 masked_scatter，再迁移到 C++。

因此，融合的成功标准不是简单看整个 Tensor cosine，而是按位置拆分：

• 普通文本位置必须完全不变；
• 图像位置的误差只能来自上游 image_embeddings；
• 融合本身不能新增误差；
• C++ 与 Python 手写融合必须一致。

实际结果：

文本位置 max error = 0
C++ fusion vs Python fusion max error = 0
图像位置误差图与 Vision+Merger 逐元素一致

这一步让我认识到：

“胶水代码”同样需要 Contract 和单元测试，不能因为它没有权重就默认正确。

5.2 Prefill、Decode、KV Cache 与 Final Head

语言模型进一步增加了：

• 40 层 Decoder；
• MLA 风格 Attention；
• Prefill 和 Decode 两种模式；
• 每层独立 KV Cache；
• sequence length 从数百变为 1；
• 动态 position 和 RoPE；
• 283386 词表的巨大 LM Head；
• 误差跨层、跨 token 递归。

因此，Vision 的“模块数值对齐”经验仍然有效，但验收标准必须升级为：

Hidden 数值
+ Cache 结构
+ Top-K
+ Token
+ 连续递推

第一步尝试的完整 Decoder Layer 可以被 TorchScript 和 pnnx 处理，但在运行中暴露出几个问题。

三维输入进入 Gemm。

[1,316,2560]

直接输入时，Q Path 的 ncnn 结果完全错误。去掉固定 batch：

[316,2560]

后数值恢复。

pnnx 的 batch 轴限制。

转换日志出现：

expand tensor along batch index 0 is not supported yet
reshape tensor with batch index 1 is not supported yet
permute across batch dim is not supported yet

KV Path 的 Slice/Concat 语义错误。

pnnx 把本应按最后一维的 concat 转成 axis 0，输出 shape 虽然可能仍可运行，但数学语义已经改变。

因此我没有把“成功生成 param/bin”当作通过，而是把 Layer 0 继续拆分。

为了找到稳定边界，我随后将其拆成最小数学路径并分别验证：

input RMSNorm
Q Path
KV-A Projection
KV-B Path
RoPE
Attention Core
O Projection + Residual
Post RMSNorm
MLP + Residual

这个阶段的目标不是最终性能，而是确定：

• 哪些运算可以可靠交给 pnnx/ncnn；
• 哪些布局操作必须显式控制；
• 哪个检查点开始出现错误。

AI 在这里主要帮助生成 Wrapper 和分段对比脚本；我负责根据源码确认权重拆分等价性，并用真实中间 Tensor 验证。

小模块全部通过后，我没有把所有微型模型直接复制到 40 层，而是将它们重新归纳为“三段 ncnn + C++ Bridge”的工程边界：

Part A ncnn
  input RMSNorm
  Q Projection
  KV Low-rank Projection

C++ Bridge
  reshape / split / permute
  RoPE
  K 扩展与 Q/K/V 拼接
  Q×Kᵀ
  mask / softmax
  Attention×V
  KV Cache

Part B ncnn
  o_proj
  residual

Part C ncnn
  post RMSNorm
  gate/up/down MLP
  residual

这一划分保留了 ncnn 擅长的权重计算，同时把 pnnx 不稳定的布局和状态放在 C++ 中。

Part A 中还遇到 Slice 输出 shape 错误。最终将一个权重矩阵按行等价拆为两个 Linear：

kv_low_proj: 2560 → 512
k_rot_proj:  2560 → 64

从而在图内消除 Slice。这不是改变模型，而是把相同矩阵运算重写成更适合转换器的形式。

Layer 0 三段结构稳定后，我抽象了统一的 DecoderLayerRunner，再按下列顺序扩展：

Layer 0
→ Layer 0-1
→ Layer 0-3
→ Layer 0-7
→ Layer 0-15
→ Layer 0-30
→ Layer 0-39

这种逐级扩大而不是直接跑 40 层的原因是：

• 检查 Runner 是否写死 Layer 0；
• 观察误差增长趋势；
• 在接口错误时降低返工成本；
• 中断后可以从完整层继续；
• 先确认多层 Prefill，再进入更复杂的 Decode。

扩展到 Layer 0-30 时，Layer 20 附近出现了一个有代表性的误差放大案例：

max_abs_error  = 0.1595
mean_abs_error = 0.000626
cosine         = 0.999999967

如果只看最大误差，可能会认为实现已经失效。但进一步统计显示：

P99.99 = 0.0167
error > 0.05：13 / 808960
error > 0.1： 7 / 808960

大误差点极少，主要集中在图像 token 尾部和 <|vision_end|>。分层测试发现最大误差在 Layer 19→20 跳高；层内分段又显示 Attention Bridge 误差很小，主要在 Part C MLP 后被放大。

为了区分“Part C 结构错误”和“前序误差被 MLP 放大”，我使用 PyTorch 参考输入直接运行 Part C ncnn。其最大误差约 0.0414，明显小于累计输入下的 0.1532。因此结论是：

Part C 的结构没有明显错误；前 0-19 层的 FP16/ncnn 误差进入门控 MLP 和残差后，在少数图像相关 token/channel 上被放大。

这个案例体现了我的排查方法：

看分布
→ 找位置
→ 找首次跳变层
→ 层内分段
→ 控制输入做对照
→ 检查最终决策

40 层 Prefill 结束后，hidden 级最大误差达到约 1.184，但 cosine 仍接近 1。此时我没有再用 hidden max error 作为唯一结论，而是继续执行：

Layer 39 hidden
→ Final RMSNorm
→ last token hidden
→ tied LM Head
→ Top-K / argmax

最终：

PyTorch first token = 4356 = "There"
ncnn first token    = 4356 = "There"
Top-10 顺序一致

这证明在当前基线下，中间离群误差没有改变第一个生成决策。

Prefill 正确并不代表生成正确，下一步还需要验证 Decode 和 KV Cache：

当前 token embedding
+ position RoPE
+ 历史 K/V
→ 40 层 Decode
→ 新 K/V
→ 下一 token

我先冻结 PyTorch Decode Golden：

Prefill Cache length = 316
第一个 token = 4356 "There"
Decode position = 316
第二个 token = 516 " are"
Decode Cache length = 317

每层 Cache Contract：

Key   [32,length,192]
Value [32,length,128]

验收不仅比较新 K/V，还检查：

• 历史 Cache 前缀完全不变；
• 新 K/V 只追加在最后一个位置；
• Cache 长度每步加 1；
• position 和 RoPE 正确递增；
• 最终 token 保持一致。

Decode 的实现从 Layer 0 单步逐渐扩展到 40 层连续生成：

Layer 0 单步 Decode
→ 40 层单步 Decode
→ ncnn Prefill 生成 40 层 Cache
→ 使用 ncnn Cache Decode
→ 多 token 连续递推
→ C++ Layer 0 Bridge
→ C++ Layer 0-3
→ C++ Layer 0-39
→ 单进程 C++ generation loop

最终连续生成前缀为：

There are **13 dogs** in the

对应 token 与 Golden 前缀一致。C++ generation loop 中 40 层 Cache 常驻内存，按 token 递增，不再通过 NPY 在每步传递。

生成链末端还需要处理 Final Head 的内存问题。Youtu-VL 没有独立 lm_head.weight，而是复用：

model.embed_tokens.weight [283386,2560]

其 FP16 权重约 1.35 GiB。如果直接在单进程中反复导出完整 LM Head，Torch、TorchScript 和 pnnx 会同时产生多份大型副本。

我将其拆为：

Final RMSNorm
+ 17 个连续 vocabulary shard
→ 拼接完整 logits
→ 全局 argmax

最初较大的 shard 在连续导出时造成系统内存压力。最终采用：

• 更小的 8192-row shard；
• 每个 shard 独立 worker；
• worker 完成即退出；
• 设置内存上限；
• 先做单 shard 压力测试；
• 不在主进程长期持有 safetensors 和 TorchScript 副本。

17 个 shard 覆盖完整词表，8 步连续生成中的 argmax 与参考完全一致。

综合 Prefill、Decode 和 Final Head 的实践，这一阶段补充了以下规则：

1. 复杂图应先验证最小数学路径；
2. 生成 .param/.bin 不是通过，必须检查中间 Tensor；
3. pnnx 不擅长的布局操作应留在 C++ Bridge；
4. Prefill 与 Decode 的接口需要从设计初期同时考虑；
5. 多层模型应按 1、2、4、8、16、全部逐级扩展；
6. 最大误差不是最终判据，token 排名和 margin 更重要；
7. 有状态模型必须检查 Cache 前缀不变性和连续递推；
8. 大权重导出同样需要分片、进程隔离和内存预算。

5.3 C++ 前端与端到端数据流

完成各模块后，我将它们放入同一 C++ 进程：

image path + prompt
  ↓
C++ Image Processor
  ↓
C++ Chat Template + ByteLevel-BPE
  ↓
Vision embedding + 27 Vision blocks
  ↓
VLPatchMerger
  ↓
C++ image-token fusion
  ↓
40-layer Prefill + KV Cache
  ↓
Final Head → first token
  ↓
40-layer Decode loop
  ↓
C++ ByteLevel decode
  ↓
output.txt

模块之间使用内存 Tensor 传递，NPY 只作为可选验收产物，不再作为运行时接口。

端到端串联后的公平比较必须使用相同输入。LLM 接收的是 ncnn Vision 产生的 fused embedding，而旧 LLM Golden 可能来自 PyTorch Vision；两者输入不同，不能直接把最终 hidden 差异归因于 C++ LLM。

因此我建立“同源参考”：

• 使用 C++ 实际输出的 fused embedding；
• 让 Python/TorchScript 和 C++/ncnn 分别从相同 Tensor 继续运行；
• 比较 Layer 0、20、39、last-token hidden 和 first token。

这避免了把上游 Vision 差异错误归因到下游 LLM。

图像侧的 C++ Processor 最终实现：

• JPEG 使用 libjpeg；
• 其他格式使用仓库内 stb_image；
• 按官方规则选择目标尺寸；
• half-pixel / 抗锯齿 resize；
• uint8 舍入、rescale 和 normalize；
• patch_size=16、merge_size=2 patchify；
• pixel_values、mask 和 spatial_shapes。

主回归中，四个整数 Tensor 与官方完全一致；pixel_values 只有极少量一个灰阶量级的差异，最终 token 和文本不变。补充的 VQA 和检测用例又进一步对齐了抗锯齿 resize。

文本侧的 Chat Template 和 Tokenizer 不能采用近似实现，因为任何一个 token 差异都会改变后续生成。最终实现包括：

• ByteLevel-BPE encode；
• merge rank；
• added token 和 special token；
• 中文、英文、中英混合；
• 换行和连续空格；
• token ID 到 UTF-8 文本 decode；
• 跳过 special token。

官方 tokenizer.json 在打包阶段被转换为约 7 MiB 的 tokenizer.bin。Python 只用于一次性打包，不进入推理边界。多组 Prompt 的完整 input_ids 与官方 Processor 一致。

最后，我把 Runtime 的已验证边界明确记录下来：

batch = 1
单图片 + 单 Prompt
动态图片 grid，两个维度可被 merge size 2 整除
CPU Release
Vulkan OFF

尚未验证：

多图片
视频
Batch inference
MSVC
Vulkan

这类边界被明确写入 Contract，而不是以“理论上应该支持”替代实际验收。

---

6. 性能优化与工程交付

6.1 Persistent、性能结果与依赖精简

早期 C++ Runner 在每次子图调用时重新创建和加载 ncnn::Net。每个 Decode token 需要：

40 层 × Part A/B/C = 120 个图
Final RMSNorm + 17 个 LM Head shard = 18 个图
总计 = 138 次模型加载 / token

LLM 和 Head 的逻辑权重读取量约 9.1 GiB/token。128 token 相当于重复读取超过 1 TiB 权重，磁盘成为首要瓶颈。此时 CPU 和内存并没有满，继续增加线程也无法解决问题。

根据上述瓶颈，我实现了 Streaming 与 Persistent 两种模型生命周期：

Streaming：

调用时加载
计算后释放

优点是常驻内存低，适合调试和内存受限环境；缺点是重复读取权重。

Persistent：

Prefill 前加载 138 个 ncnn::Net
后续只创建 Extractor
权重全程复用
KV Cache 独立增长

验收约束：

resident_models  = 138
model_load_count = 138

model_load_count 不得随生成长度增加。Persistent 模式实测最大 RSS 约 24 GiB，因此完整回归要求至少 32 GiB RAM，推荐 64 GiB。这说明项目已经形成 C++ 端侧/边缘部署路径，但当前 4B persistent 配置尚不是低内存手机方案。

模型生命周期稳定后，我继续移除临时 BLAS/MKL 依赖。迁移中期的 Attention Bridge 使用 cblas_sgemm；为了让最终构建更便携，我实现了 portable_gemm.hpp：

FP32 row-major Q × Kᵀ
FP32 row-major Attention × V
OpenMP 按行并行
每个点积按 K 递增顺序累加

固定累加顺序有助于跨平台确定性。最终 CMake 删除 BLAS 查找，二进制不存在 BLAS、MKL、OpenBLAS 或 cblas 符号依赖。

上述优化对应的 Linux persistent 最终结果如下：

Tokens	前一版 persistent	最终版	加速
32	176.88 s	108.16 s	1.64×
64	203.60 s	139.74 s	1.46×
128	268.49 s	198.04 s	1.36×

更早的 streaming 版本 32/64/128 token 分别约为 914.62/1569.16/3149.09 秒，因此主要性能修复来自权重生命周期，而不是简单增加计算线程。

6.2 CMake、测试、模型资产与开源边界

最终工程使用 CMake 管理：

• ncnn 通过 ncnn_DIR 查找；
• OpenMP、JPEG 显式配置；
• Release 构建；
• 测试可开关；
• 模型资产不进入源码仓；
• Linux 和 Windows 使用独立 build 目录；
• 不复用跨平台 CMake Cache 和二进制。

构建完成后的验证分为单元、接口、数值和端到端四个层次。单元测试包括：

• portable GEMM；
• Tokenizer；
• persistent module 生命周期。

接口测试包括：

• CLI usage；
• Processor Tensor；
• Merger 重复调用。

数值回归包括：

• 关键中间 Tensor；
• Top-1/Top-2；
• Cache；
• token ID。

端到端测试包括：

• 1/32/64/128 token；
• 最终文本；
• EOS；
• RSS 和 swap；
• 模型加载次数。

与源码构建配套的完整运行模型包含：

• Vision embedding；
• 27 个 Vision block；
• Vision post norm；
• Merger；
• 40×3 个 LLM 子图；
• Final RMSNorm；
• 17 个 LM Head shard；
• embedding、RoPE 常量和 tokenizer。

总计 339 个资产、约 13.43 GiB。模型包与源码分离，并通过 manifest 和 SHA-256 检查。

在开源关系上，项目参考了 ncnn_llm 的运行时组织、KV Cache 生命周期、Tokenizer 集成和模型持久化思路，但当前 Youtu-VL 代码为独立实现，并未直接包含 ncnn_llm 源文件。

正式公开发布前仍需要：

• 固定实际参考 commit；
• 列出设计参考点；
• 审查是否复制过代码；
• 完善第三方许可证说明。

这部分体现了我对技术来源和开源合规边界的重视。

---

7. 跨平台验收与具体结果

结果展示不再只使用“PASS”或“文本一致”作为结论，而是按照输入图片、Prompt、Processor Contract、具体输出和系统指标逐项记录。主回归图片、英文 VQA 图片和目标检测图片分别覆盖中文生成、计数推理、结构化坐标输出三类能力。

7.1 Linux 平台验收

Linux 测试运行在 AutoDL Ubuntu 22.04 环境，硬件为 12 vCPU Intel Xeon Platinum 8352V @ 2.10 GHz、62 GB 内存和 30 GB 系统盘；软件环境为 GNU 11.4.0、CMake 3.22.1、ncnn 20260526、OpenMP 4.5 和 libjpeg.so.8。构建采用 CPU Release、Vulkan OFF、8 threads 和 persistent 权重模式，最终二进制不链接 BLAS、MKL 或 OpenBLAS。

构建和轻量测试不是形式化的“跑通检查”，而是分别约束构建边界、命令行边界、数值内核和模型生命周期：

测试	选择该测试的目的	通过标准	结果
CMake configure/build	检查公开源码能否只通过 CMake 完成配置和编译，并确认没有隐式引入 BLAS、MKL 或 OpenBLAS	Release 构建完成，目标文件依赖符合设计边界	PASS
youtu_vl_cli_usage	检查图片、Prompt、生成长度等参数的解析，以及参数缺失时的失败路径	合法参数进入推理，非法参数返回明确错误	PASS
youtu_vl_portable_gemm	检查替代第三方 BLAS 的 C++ GEMM 在不同 shape 下是否满足参考数值	与冻结参考输出在规定容差内一致	PASS
CTest	将上述基础能力纳入可重复执行的构建后回归	预定用例全部通过	2/2 PASS
Merger persistent	检查 ncnn 图是否只加载一次并能被多次调用，排除重复运行中的状态污染	load=1, run=2，两次输出 bit-exact	PASS

Linux 端到端主回归使用 test_data/input_image.jpg。图片分辨率为 800×533，内容是大量堆叠且严重锈蚀的饮料罐和金属罐；Prompt 为：

这是什么类型的垃圾

测试目的。 这个用例被选为主回归，不只是因为图片内容容易观察，而是因为它能够同时覆盖中文 Prompt 的 UTF-8 输入、Chat Template、ByteLevel-BPE 编解码，以及图片经过 Vision、VLPatchMerger、Prefill、Decode 和 LM Head 后生成中文 Markdown 文本的完整链路。相同输入还会在 Windows 上复用，从而把“模型理解是否正确”和“操作系统、编译器、JPEG 解码器及命令行编码是否改变结果”分离开。通过标准被固定为：Processor Contract 中五个 Tensor 满足预定精度，指定长度的 generated IDs 全序列一致，解码文本逐字节一致，persistent 模式下模型加载数保持为 138，KV Cache 长度与输入和生成长度相符。

C++ Processor 将图片调整为 800×544，得到 [34,50] 的视觉网格和 1700 个 patch；Chat Template 与 Tokenizer 生成 450 个输入 token。与冻结 PyTorch Processor 对比时，五个输入 Tensor 的结果为：

Tensor	Shape / dtype	不同元素	最大绝对误差
input_ids	[1,450] / int64	0	0
attention_mask	[1,450] / int64	0	0
pixel_attention_mask	[1,1700] / int32	0	0
spatial_shapes	[1,2] / int64	0	0
pixel_values	[1,1700,768] / float32	319 / 1,305,600	0.00784314424

这里的 319 个差异只占全部像素通道值的约 0.0244%，最大幅度对应一个很小的图像量化舍入差异。为了观察它是否会沿 27 层 Vision 和 40 层 LLM 放大，我分别生成 32、64 和 128 token。32 token 用于较短 Decode 的端到端冒烟回归；64 token 用于观察中等长度下 KV Cache 增长和逐 token 误差累积；128 token 则进一步覆盖长 Decode、候选 token 低 margin 与资源增长。以下是 PyTorch 与 Linux ncnn 均得到的具体文本。

32-token 输出：

这是**金属类可回收垃圾**，具体为**废弃的易拉罐（铝罐或铁罐）**。

从图片中可以看到：

64-token 输出：

这是**金属类可回收垃圾**，具体为**废弃的易拉罐（铝罐或铁罐）**。

从图片中可以看到：

- 大量罐体堆积，表面严重锈蚀，说明是长期废弃的金属容器；
- 多数罐口朝上，部分罐身

128-token 输出：

这是**金属类可回收垃圾**，具体为**废弃的易拉罐（铝罐或铁罐）**。

从图片中可以看到：

- 大量罐体堆积，表面严重锈蚀，说明是长期废弃的金属容器；
- 多数罐口朝上，部分罐身印有品牌或文字残留（如“Budweiser”等），表明它们曾用于盛装饮料；
- 材质多为铝或铁（铝罐较轻、易拉环，铁罐较重、易生锈）；
- 虽然外观锈蚀，但金属本身仍具有

三个输出都是达到指定 token 上限后停止，因此 64-token 和 128-token 文本以未完成句子结尾，reached_eos=false。验收比较的是同一生成参数下的完整 token 序列，而不是对被截断文本做人工补全。

对应的 Token、耗时与资源结果如下：

生成长度	该长度的测试目的	PyTorch ↔ ncnn token	文本	Top-2 诊断	Vision	Prefill	Decode	总耗时	RSS
32	短 Decode 冒烟回归	32/32，差异 0	上述文本逐字节一致	32/32	36.517 s	23.638 s	28.316 s	108.155 s	23.76 GiB
64	中等长度 KV Cache 与误差累积	64/64，差异 0	上述文本逐字节一致	64/64	38.346 s	25.705 s	55.894 s	139.737 s	23.89 GiB
128	长 Decode、低 margin 候选和资源增长	128/128，差异 0	上述文本逐字节一致	127/128，1 个零 margin 排序边界	36.726 s	24.323 s	117.366 s	198.044 s	24.06 GiB

128-token 回归中，Top-1/Top-2 在一个位置出现完全同分后的候选顺序差异；实际选择的生成 token 仍为参考 token，完整 128 个 generated IDs 没有差异。三次运行的 resident_models 与 model_load_count 都是 138，final cache length 分别为 481、513 和 577，退出码为 0，swap 为 0。

为了避免主回归只覆盖一种语言、一种图片格式和一种输出形式，我又在 Linux 上增加了英文 VQA 和物体检测。三张图片的分工和通过标准如下：

图片	原始尺寸与内容	Prompt	选择该用例的目的	通过标准
test_data/input_image.jpg	800×533，大量锈蚀饮料罐	这是什么类型的垃圾	验证中文输入与输出、完整多模态长序列，并以同一输入隔离 Linux/Windows 平台差异	Processor Contract 满足阈值；32/64/128 generated IDs 和文本一致；模型加载数与 Cache 正确
assets/1.png	493×547，1 只真实白色小狗，背景毯子上有 12 个狗脸印花	How many dogs in the image?	验证英文 Prompt 与英文解码、PNG 输入、视觉计数，以及不同尺寸图片产生的动态 grid	Processor 5/5 exact；64 个 generated IDs、Top-1/Top-2 和文本一致
assets/3.jpg	1920×1440，城市道路、卡车、多辆汽车、交通灯、停车计时器和鸟	Detect all objects in the provided image.	验证高分辨率 JPEG、视觉密集场景、结构化检测文本、坐标 token 和原图坐标反变换	Processor 5/5 exact；64 个 generated IDs 和文本一致；32 个坐标 token 后处理与 PyTorch 一致

两个补充用例共同使用 max_image_patches=1700、max_new_tokens=64、greedy decode、persistent、CPU 8 threads 和 Vulkan OFF。VQA 得到 1152 patches、[36,32] grid 和 316 个输入 token；检测图得到 1656 patches、[36,46] grid 和 443 个输入 token。经过抗锯齿 resize 对齐后，两张图片的五个 Processor Tensor 均为 5/5 exact。

英文 VQA 图片包含 1 只真实白色小狗和背景毯子上的 12 个狗脸印花。

这个用例用于把语言路径和视觉任务同时换出主回归的覆盖范围：Prompt 与回答均为英文，可以检查 ByteLevel-BPE 对英文、数字和 Markdown 标点的编解码；输入是 PNG，可以覆盖不同于主回归 JPEG 的图像读取路径；问题要求区分真实狗和印花狗脸，可以检查视觉计数和跨区域信息聚合；[36,32] grid 还可以验证 Vision RoPE、mask 与 window 调度不是为 [34,50] 写死。它的通过条件不是只得到数字“13”，而是 Processor 五个 Tensor、64 个 generated IDs、Top-1/Top-2 候选顺序和完整英文文本全部与 PyTorch 参考一致。

PyTorch 与 ncnn 均生成 64 个 token，具体输出为：

There are **13 dogs** in the image.

Here’s the breakdown:

- **1 real dog** standing in front of the blanket.
- **12 printed dog faces** on the white blanket behind it — arranged in 3 rows of 4.

So, total = 1 (real)

该输出在第 64 个 token 后截断，因而最后停在 1 (real)。比较结果为 generated IDs 64/64、Top-1 IDs 64/64、Top-2 IDs 64/64、最终文本逐字节一致；Top-1 和 Top-2 logit 最大绝对差分别为 0.125 和 0.15625，没有 raw tie。ncnn CPU 的端到端耗时为 103.722783 s，其中模型加载 18.945001 s、Vision 22.582406 s、Prefill 14.444231 s、Decode 47.601659 s，final cache length 为 379。这个用例还验证了动态图片网格确实由运行时生成，而不是只适配主回归的固定 shape。

物体检测用例使用包含卡车、汽车、交通灯、停车计时器和鸟的城市道路图片。

这个用例用于验证普通问答之外的结构化生成能力。高分辨率、多目标道路图像会产生 [36,46] grid，用于覆盖另一种动态图片 shape；输出中的 <ref>、<box> 和坐标 token 用于检查特殊 token 解码、坐标约束和从 Processor 尺度回到 1920×1440 原图尺度的后处理；密集场景中的低 margin 坐标候选还可以检验浮点误差是否真正改变贪心决策。这个测试评估的是 ncnn 对同一 PyTorch 推理语义的复现，而不是用单张图片计算 mAP。通过标准是 Processor 5/5 exact、64 个最终 generated IDs 与文本一致，并且 32 个坐标 token 的反缩放结果与参考一致；Top-1/Top-2 的平局顺序仅作为诊断信息，最终 token 不分叉才属于生成通过。

PyTorch 与 ncnn 的 64-token 最终输出为：

<ref>truck</ref><box><x_0><y_0><x_449><y_1032></box><ref>car</ref><box><x_1560><y_445><x_1920><y_680></box><box><x_1122><y_440><x_1471><y_625></box><box><x_863><y_665><x_1915><y_1418></box><box><x_1878><y_538><x_1920><y_665></box><box><x_240><y_538><x_386><y_670></box><ref>traffic light</ref><box><x_1250><y_2><x_1294><y_48></box><box><x_412><y_175><x_446><y_255></box><ref>parking meter</ref><box>

把结构化文本展开后，模型给出了 1 个 truck box、5 个 car box 和 2 个 traffic-light box，并开始生成 parking-meter box；由于达到 64-token 上限，最后一个 box 没有生成完。上述坐标已经从 Processor 缩放坐标反变换到 1920×1440 原图坐标。

最终比较结果为 generated IDs 64/64、文本逐字节一致、Processor 5/5 exact。Top-1/Top-2 诊断各为 63/64，唯一差异来自一个 raw-logit 完全平局位置；Top-1 和 Top-2 logit 最大绝对差均为 0.078125，最终生成 token 没有分叉。运行时对 32 个坐标 token 执行了后处理，ncnn CPU 总耗时为 140.451401 s，其中模型加载 19.444072 s、Vision 37.767491 s、Prefill 23.583362 s、Decode 59.459924 s，final cache length 为 506。

该用例首次运行时暴露了坐标基准、抗锯齿 resize、低 margin 坐标 token 和临时 RoPE/mask NPY 四类问题。最终实现只对展示文本中的坐标 token 做反缩放，自回归反馈仍使用 raw token；同时在 C++ 中动态生成 Vision RoPE 和 mask。由此，结果验证从“模型算子一致”扩展到了输入几何、生成决策和后处理语义一致。

7.2 Windows 平台验收

Windows 测试运行在阿里云 ecs.r7.2xlarge：Windows Server 2022 Datacenter 64-bit English、8 vCPU（4 个物理核心，每核心 2 线程）和 64 GB 内存。编译环境为 GCC 16.1.0 UCRT64、CMake 4.4.0、Ninja 1.13.2、ncnn 20260526 静态库、OpenMP 5.2 和 libjpeg-turbo 3.2.0。这一结果代表 MinGW/UCRT64，不代表 MSVC 已验证。

Windows 构建测试刻意覆盖了与 Linux 不同的编译器、运行库和动态库边界：

测试	选择该测试的目的	通过标准	结果
ncnn Windows static build	检查 ncnn 能否在 MinGW/UCRT64 下以静态库方式构建	ncnn 静态库可被下游 CMake 工程使用	PASS
Youtu-VL-ncnn build	检查项目源码、CMake 路径和条件编译是否可迁移到 Windows	全部目标完成编译和链接	PASS
youtu_vl_ncnn.exe	检查最终交付程序能否在真实 Windows 运行库环境中启动	依赖齐全并进入推理入口	PASS
test_portable_gemm.exe	检查同一无 BLAS 数值内核跨编译器后的行为	与冻结参考输出在规定容差内一致	PASS
test_persistent_module.exe	检查 persistent 对象在 Windows 下的加载、复用和析构	一次加载、多次执行，重复输出一致	PASS
CTest	检查 Windows 的自动化回归入口，而非只手工运行 .exe	预定用例全部通过	3/3 PASS

首次运行时，main(char**) 把中文 Prompt 读取为 ?????????，输入长度从 450 变为 448。修复后入口使用 GetCommandLineW、CommandLineToArgvW 和 WideCharToMultiByte(CP_UTF8)，同一个 Prompt 恢复为 450 token。该修复的验收不是“终端看起来能显示中文”，而是 input_ids、生成 token 和输出文本同时恢复到参考结果。

Windows 使用与 Linux 完全相同的易拉罐图片和 Prompt 进行具体输出与跨平台对比。1-token 回归输出为：

这是

测试目的。 Windows 没有另选一张图片，因为这一轮要控制语义输入不变，专门隔离平台变量。它验证 MinGW/UCRT64 编译结果、Windows JPEG 解码、CRLF、DLL 依赖，以及 Win32 UTF-16 参数转 UTF-8 后是否仍能复现 Linux 生成。新增的 1-token 用例把检查范围集中在模型加载、Vision、Prefill 和第一次贪心决策上，便于在完整长序列失败前快速判断前半条链路；32、64 和 128 token 则验证平台差异不会随 Decode 和 KV Cache 增长演变为 token 分叉。通过标准是四种长度的 generated IDs 与参考逐位置一致，文本在统一换行后 UTF-8 字节一致，Final Cache 等于 450 个输入 token 加上继续生成所需的历史长度。

32、64 和 128-token 的具体输出分别与 Linux 主回归列出的三个代码块相同；比较时先统一 Windows CRLF 与 Linux LF，再检查 UTF-8 字节和 generated IDs。量化结果如下：

生成长度	Windows generated IDs	与 Linux 的具体文本关系	Final Cache	总耗时
1	1/1，差异 0，首 token ID 102140	输出“这是”	450	81.308 s
32	32/32，差异 0	等于 7.1 的 32-token 文本	481	122.079 s
64	64/64，差异 0	等于 7.1 的 64-token 文本	513	166.306 s
128	128/128，差异 0	等于 7.1 的 128-token 文本	577	261.057 s

因此，跨平台结论并不是两个程序都输出了“易拉罐”这一关键词，而是每个生成位置的 token ID 均一致，解码后的完整 Markdown 标点、换行、中文内容和截断位置也一致。

跨平台回归还需要解释 JPEG 差异、候选平局与发布依赖。Windows libjpeg-turbo 与 Linux libjpeg 的解码路径不同。Windows 与 Linux C++ 前端对比时，pixel_values 有 21,377 / 1,305,600 个元素不同，最大绝对误差为 0.0235294104；Windows 与官方冻结 Processor 相比则只有 1 个 float 不同，最大误差为 0.0078431368，其余四个 Processor Tensor exact。

128-token 的第 69 个诊断位置出现 Top-1/Top-2 margin 为 0 的排序差异，实际生成 token 为 110313，与 PyTorch 和 Linux 参考相同。这个结果说明，跨系统浮点差异必须同时观察候选 margin 和最终决策，不能把一个平局下的 Top-2 顺序变化直接写成生成错误。

ncnn 在 Windows 中静态链接；发布的 MinGW/UCRT64 可执行文件需要将 libgcc_s_seh-1.dll、libstdc++-6.dll、libgomp-1.dll、libjpeg-8.dll 和 libwinpthread-1.dll 放在 .exe 同目录。

---

8. 工程经验与 AI 协作方法

8.1 工程迁移方法沉淀

真正的迁移至少包含：

计算图
Tensor 布局
动态调度
缓存状态
输入处理
输出后处理
模型生命周期
跨平台构建

仅仅得到 .param/.bin 并不能证明迁移完成。

其中，Shape 正确并不代表数据语义正确。Vision Embedding 和 LLM Q Path 都出现过“输出 shape 正确或可运行，但数值完全错误”的情况。对三维 Tensor、batch=1、head 维和 concat 轴，必须建立显式 Contract。

中间误差也必须结合最终决策解释。隐藏状态最大误差可以随着层数增大，但真正的生成判断需要结合：

• 误差分布；
• 最后一个 token hidden；
• Final Norm；
• Top-K；
• margin；
• 最终 token 和文本。

这比设一个固定 max_error 阈值更符合实际模型行为。

在职责划分上，动态控制与权重计算应解耦。将 reshape、permute、RoPE、mask、KV Cache 和生成循环放在 C++，将 Linear、Norm、MLP 和投影放在 ncnn，使系统既能绕过转换器限制，也能支持动态图片和 Decode。

实现顺序上，应先保证可观察，再追求性能。最初很多子图、NPY 和独立进程会降低性能，但它们提供了定位能力。只有在正确性稳定后，才将模块收敛为三段图、C++ Runner、单进程 Cache 和 persistent 权重。

性能瓶颈同样需要证据，而不是直觉。早期速度极慢的根因不是“CPU 太差”，而是每 token 重复加载 138 个模型。通过分段计时、模型加载计数和磁盘行为，才确定 persistent 是首要优化方向。

8.2 AI 的有效边界与可复用协作流程

在本项目中，AI 最有效的用途包括：

• 快速梳理陌生源码；
• 把模型 forward 转成模块表和数据流；
• 生成 Wrapper 与测试脚手架；
• 根据完整报错提出可证伪假设；
• 辅助设计误差分解实验；
• 生成 CMake、Win32 UTF-8 和报告初稿；
• 帮助把一次性解决方案抽象为通用 Runner。

但以下内容必须由工程人员控制，不能交由 AI 替代：

• 哪个模块是正确边界；
• 哪个指标代表通过；
• 哪些实验能够排除某个原因；
• 是否接受浮点差异；
• 是否需要回滚；
• 平台和依赖边界如何表述；
• 开源参考与许可证关系。

将两者结合后，可以得到一个可复用的 AI 协作流程：

给 AI 真实源码和完整上下文
→ 要求它列出假设而非单一答案
→ 将建议缩成一个最小实验
→ 先写 Contract 和通过标准
→ 执行并保存结果
→ 用证据接受或否定
→ 把新规则写回项目方法

例如，面对 Layer 20 的误差，不要要求 AI“修复精度”，而是让它帮助设计分层、分段和控制输入实验。最终我们发现 Part C 不是结构错误，避免了无意义地重写整个 LLM。

高质量使用 AI 的关键，不是让它生成更多代码，而是让每次生成都发生在边界明确、可测试、可回滚的工程单元中。

AI 提高了探索速度，但项目可信度来自 Golden、Contract、编译、数值、token、文本和跨平台回归。