minivLLM 多模态推理实验工作区

这套文档记录 minivLLM 从纯文本引擎扩展到最小可运行 VLM 的过程，目标是在它上面运行 Qwen3-VL-4B 或同类开源模型。内容包括引擎审计、模块实现、论文笔记和实验日志。

文档目录

章节按实现顺序排列。已完成的页面可以直接打开；标记为占位的页面留给后续 Wave。

01 · 已有引擎审计已发布 minivLLM 文本引擎完整静态审计：模块状态、阻塞 Bug、已实现能力与缺口。
02 · Paged Attention 基础已发布 PagedAttention 原理：块表管理、逻辑-物理映射、碎片率分析，以及 minivLLM 当前 contiguous KV cache 的差距。
03 · ViT 与图像 Patch 编码已发布 Vision Transformer 如何将图像切割为 patch token、patch embedding 与位置编码。
04 · CLIP 与图文对齐已发布 CLIP 对比学习机制：双塔架构、InfoNCE 损失、CLIP 视觉编码器在 VLM 中的角色。
05 · Qwen-VL 多模态输入已发布 Qwen-VL 系列输入格式：特殊 token、visual token 拼接规则、image_grid_thw 与 token 预算。
06 · 多模态 Prefill 与 Decode 已发布多模态 prefill 中 visual token 一次性写入 KV cache，decode 阶段追加文本 token 的差异与显存分析。
07 · 多模态 KV Cache 管理已发布为什么 multimodal-aware cache key 必要：text-only prefix 在不同图像下 KV 不同，需分阶段 cache 策略。
08 · vLLM 多模态推理参考已发布 vLLM 多模态支持：PagedAttention 在 VLM 上的应用、自动前缀缓存、参考实验中的环境阻塞分析。
09 · SGLang 多模态推理参考已发布 SGLang RadixAttention 的多模态扩展、Radix Tree 与文本-视觉分离、受限显存场景下的对比分析。
10 · 最终成果说明已发布 6 周路线、验证数字（HF IDENTICAL / KV 对齐 / mm cache false_hit）、已知限制和后续工作。

学习资料

中文论文笔记存放在 learning/papers/，共 12 篇，范围从 Transformer 到 SGLang RadixAttention。完整论文清单见 learning/papers/00_论文清单.md。

论文清单已发布 12 篇论文/文档列表，含标题、arXiv 链接与阅读目的。
学习笔记 01 · 已有引擎结构 minivLLM 代码组织结构与模块调用关系。
学习笔记 02 · Attention 实现审计 Attn 与 RoPE 的逐行审查。
学习笔记 03 · KV Cache 实现审计 Contiguous KV 与 PagedAttention 的关系分析。
学习笔记 04 · Paged Attention 实现进度 A/B/C/D 四部分进展跟踪。
学习笔记 05 · 多模态输入设计 Multi-modal token pipeline 设计。
学习笔记 06 · Vision Encoder 接入方案图像→visual token→LLM 的完整管线。
学习笔记 08 · 显存预算与模型选型 4 模型显存预算矩阵与降级策略。
学习笔记 09 · vLLM PagedAttention 源码参考 vLLM 类/API 与 minivLLM 对应实现。
学习笔记 10 · SGLang RadixAttention 源码参考 SGLang Radix Tree 结构与显存管理。

周报

Week 1 - 启动审计 minivLLM 文本引擎 / 多模态流水线 / paged attention 审计结论。
Week 2 - Engine Patch + KV Cache HF 对齐、KV cache 接线、最小 PagedKV 实现。
Week 3 - 多模态 Token Pipeline 视觉 encoder 接入方案、inputs_embeds 路径、评测证据。
Week 4 - inputs_embeds 路径 + VLM Demo inputs_embeds 正式接入、VLM reference 矩阵与降级路径。
Week 5 - 多模态 KV Cache（占位） mm KV cache 管理实验（待 Task 11 完成）。
Week 6 - VLM Reference 矩阵 4 模型 reference 对照推理与降级路径验证。