← 返回文档导航

10 · 最终成果说明

本页记录 minivLLM 多模态推理实验在 6 周计划结束时的状态，包括完成度、验证数字、已知限制和后续工作。

1. 项目背景

项目从纯文本推理引擎 minivLLM 起步，增加一条最小可运行的 VLM 推理流水线，目标模型是 Qwen3-VL-4B 或同类开源 VLM。

实验环境：macOS (Apple Silicon, MPS)，transformers 5.8.0，torch 2.11.0，无 NVIDIA GPU / 无 CUDA。引擎代码 minivLLM/ 作为只读基础存在，所有实验代码独立于引擎目录，不修改 minivLLM/ 底层源码。

项目分为 5 个 Wave，每 Wave 约 1 周工作量，覆盖引擎审计、模块修复、paged attention 实现、多模态 pipeline、VLM reference 对照、以及多模态 KV cache 管理。

2. 6 周路线总结

3. 产出与验证数字

3.1 纯文本引擎：HF Parity IDENTICAL

经过 3 轮调试修复了 5 个 Bug：

• B1：Qwen3Attn → Attn 构造参数不兼容（S= / is_decode= 不存在）
• B2：Qwen3FFN.act_fn = None（前向 NoneType not callable）
• B3：head_dim 未通过 DecoderLayer 传给 Attn（推导值 64 vs 实际 128）
• B4：RoPE 实现使用 chunk+cat 方式，非 HF 的 rotate_half 方式
• B5：rope_theta 未传参（默认 10000 vs HF 实际 1,000,000）

3.2 KV Cache：contiguous 与 paged 均对齐

Contiguous KV cache：已接入 minivLLM prefill/decode 路径，4 个 seq_len（1/8/64/512）的 prefill-then-decode vs full-sequence 对比全部通过（atol=1e-5, rtol=1e-4）。

Paged KV cache：correctness-first 实现（BlockManager + BlockTable + PagedKVCache + gather_kv_for_attention），使用 torch.gather 完成逻辑-物理地址映射。与 contiguous KV cache 对齐，logits 通过 torch.allclose。注意：decode 阶段使用 gather fallback，非 CUDA paged_attention kernel；无 CUDA 环境，仅在 CPU/MPS 上验证正确性。

3.3 多模态 KV Cache 管理：策略 A false_hit 实验

实验显示：text-only prefix cache 在多模态推理中不安全。当用户两次请求使用相同文本前缀但不同图像时，仅基于文本 token 的 cache key（策略 A）会错误复用 KV cache，导致模型基于错误的 visual context 解码。

*Case 4 中策略 A/B 的 true_hit 在语义上是错误的（resize 不同导致 visual layout 不匹配），但按 image_bytes 相同被归为 true_hit + 语义警告。

结论：策略 B（text + image_hash）是最小防御线；策略 C（full multimodal metadata）提供完整保护。

3.4 inputs_embeds 路径 + 最小 VLM Demo

inputs_embeds 路径正式接入 minivLLM 引擎：双输入冲突正确拒绝（ValueError），text_parity 测试通过（input_ids 路径 == inputs_embeds = embed_tokens(input_ids) 路径，max|diff|=0.00e+00），HF parity 无回归。

最小 VLM demo（run_minimal_vlm.py）使用随机 tiny-ViT + 随机 linear projector 将图像 embedding 拼接进 LLM，工程路径跑通。重要声明：随机 projector 不保证语义质量。真实 VLM 语义需要真实 vision encoder 权重（HF pretrained）和匹配的 projector。

4. 已知限制

其他已知限制：

• Local VLM demo 使用 random projector：run_minimal_vlm.py 中的 visual-to-text projector 是随机初始化的 nn.Linear，不携带任何预训练语义。真实 VLM 语义需要 HF 预训练权重。
• 无 CUDA / 无 accelerate：当前环境为 macOS + MPS，无 NVIDIA GPU。所有实验在 CPU 或 MPS 上运行。CUDA paged_attention kernel（vLLM/SGLang 生产级）未在本环境实现。
• Paged KV 使用 gather fallback：decode 阶段通过 torch.gather 拼接 KV block，非 GPU-native paged attention kernel。正确性已验证，但性能非优化。
• 无调度器 / 无 batching：minivLLM 无 scheduler、无 request queue、无批量调度。仅单序列推理。
• 显存预算与模型选型为理论值：所有显存数字是 Paper-based 估算（权重 + KV + 激活），未通过 torch.cuda.memory_stats() 在真实 GPU 上校准。
• mm cache 策略为纯 Python 模拟器：3 策略 hash 设计完整、逻辑正确，但未接入真实推理引擎的 KV cache 读/写循环。

5. 后续建议

1. 安装 accelerate 并重试 VLM reference：

   minivLLM/.venv/bin/pip install accelerate

   重新运行 run_qwen_vl_reference.py，验证 3 个 Qwen/SmolVLM 模型能否在 MPS 上加载并前向。
   InternVL3.5-4B 需要额外排查 InternVLChatConfig 的 AutoModelForImageTextToText 注册问题（可能需要特定加载器或更新的 transformers 版本）。
2. 替换 random projector 为 HF pretrained：将 run_minimal_vlm.py 中的随机 nn.Linear 替换为从 HF checkpoint 加载的真实 projector（如 Qwen3-VL 的 visual.merger），使 local VLM demo 具备语义。
3. 将 mm cache 策略接入真实推理循环：将 mm_cache_simulator.py 的 3 策略设计迁移到 minivLLM 引擎的 KV cache 读/写循环，用真实模型前向验证 cache key 命中逻辑。
4. 在 NVIDIA GPU 上重新验证 paged attention 性能：当前 paged KV 在 MPS 上仅验证正确性。在有 CUDA 的 GPU 上运行 compare_contiguous_vs_paged.py，测量 real fragmentation ratio 和 throughput 差异。
5. 实现 scheduler 与 batch 推理：参照 vLLM scheduler 架构，实现 RequestState / Lifecycle / 批量 prefill-then-decode 调度。这一步把当前的 demo 扩展为可服务的执行路径。

6. 产物清单