1. 文件职责
model/model_minimind.py
MiniMind 语言模型：配置、RMSNorm、RoPE、Attention、FFN、MoE、Transformer block、CausalLM 和 generate。
model/model_vlm.py
VLM 扩展：VLMConfig、MMVisionProjector、SigLIP2 加载、图像预处理、视觉 embedding 注入、forward 和 generate 多返回兼容。
dataset/lm_dataset.py
parquet 数据读取、聊天模板、图像占位符展开、labels 生成、图像 bytes 转 tensor。
trainer/trainer_utils.py
参数统计、学习率、随机种子、DDP 初始化、模型初始化、冻结策略、检查点保存与恢复、collate_fn。
trainer/train_pretrain_vlm.py
可选图文对齐阶段，默认只训练 projector，学习率较高，最大序列长度 450。
trainer/train_sft_vlm.py
监督微调阶段，默认训练 projector 和 LLM 首尾层，学习率较低，最大序列长度 768。
eval_vlm.py
命令行评估入口，支持原生 PyTorch 权重和 Transformers 格式，遍历 eval_images 并输出速度。
scripts/web_demo_vlm.py
Gradio WebUI，扫描模型目录、加载模型、处理图片上传、流式生成回答。
scripts/convert_vlm.py
原生 PyTorch 与 Transformers 格式互转。
2. 推荐阅读顺序
- 先读
dataset/lm_dataset.py，确认一个样本如何变成input_ids, labels, pixel_values。 - 再读
model/model_vlm.py，重点看forward和count_vision_proj。 - 回到
trainer/trainer_utils.py，理解freeze_llm三种策略。 - 最后看训练脚本，确认日志、保存、resume、DDP 和 mixed precision。
3. 一条样本的调用链
DataLoader
└─ VLMDataset.__getitem__
├─ create_chat_prompt
├─ tokenizer(prompt)
├─ generate_labels
└─ MiniMindVLM.image2tensor
└─ vlm_collate_fn
└─ train_epoch
└─ model(input_ids, labels, pixel_values)
├─ embed_tokens
├─ get_image_embeddings
├─ vision_proj
├─ count_vision_proj
└─ MiniMind decoder + lm_head + cross_entropy4. 练习题
追踪 token
在 VLMDataset.__getitem__ 里临时打印 prompt、input_ids 长度、labels 中非 -100 的比例，观察不同样本的监督信号。
比较冻结策略
小规模数据上分别试 freeze_llm=2 和 freeze_llm=1，观察 loss、回答风格和语言能力变化。
改评估 prompt
把 eval_vlm.py 的 prompt 改成细节、位置、数量、颜色类问题，检查模型在哪些场景更容易幻觉。
读 MoE 辅助损失
在 MoE 模式下观察 aux_loss 是否过大，理解 router load balancing 对训练稳定性的意义。