miniLLM-VLM

miniLLM-VLM 是一个面向学习与实验的轻量视觉语言模型：以 miniLLM 训练的 Base 语言模型为基础，接入 SigLIP2 视觉编码器，经过视觉连接器预训练（Pretrain）和监督微调（SFT），探索如何让小型语言模型结合图像生成回答。

完整模型约 2.96 亿参数（0.296B，包含冻结的视觉编码器）。本目录提供完成 1 个 epoch、44,612 个优化器更新步的 SFT 权重，以及配套 tokenizer、训练配置、指标和生成记录。模型面向中英文图像描述、单图问答与纯文本对话实验，当前效果仍有明显局限，适合用于理解训练流程、复现实验和继续改进。

1. 模型架构

图像 → 256 × 256 输入 → SigLIP2 → 64 × 768 视觉特征
                                        ↓
                                两层 MLP 视觉连接器
                                        ↓
文本 → tokenizer → 文本嵌入 + 64 个视觉嵌入 → miniLLM MoE → 文本回答

视觉连接器采用 LayerNorm → Linear(768, 768) → GELU → Linear(768, 768)，将图像特征转换到语言模型的输入表示空间。转换后的特征替换输入序列中的图像占位位置，与文本一起进入语言模型，通过自回归方式生成回答。

视觉编码器来自 google/siglip2-base-patch32-256 的视觉部分导出版本。这里使用固定分辨率的视觉编码器。

参数量按模型中独立参数统计，共享的输入嵌入与输出权重只计一次：

2. 训练方法

本次实验采用两阶段训练，先建立图文连接，再让部分语言层适应多模态对话。

SFT 从 Pretrain结果初始化视觉连接器，语言部分从 miniLLM Base 初始化。SFT 使用 freeze_llm=1，解冻的是第 0 层与第 7 层的完整 Decoder 模块，包括注意力、归一化、MoE 路由器与专家参数。

训练的主要目标是 assistant 回答上的下一 token 预测。用户输入、图像占位位置和 padding 不参与语言建模损失，MoE 路由辅助损失一同加入优化目标。图文与纯文本样本混合训练，使模型在适应视觉输入的同时继续学习文本回答。

本次 SFT 配置

3. 验证结果与解读

下表依据 metrics.jsonl 与 best_sft.pt 内的评估记录整理。SFT 开始时已加载训练好的 Pretrain 连接器，因此第 0 步代表 Pretrain 初始化后的基线。

验证中的语言建模损失按受监督 token 加权计算，数值越低表示参考回答的预测损失越小。

本次记录没有显式的 instruction/caption 子类别标注，最佳模型按全部图文验证样本的损失选择。best_sft.pt 与 last_sft.pt 均对应第 44,612 步，即训练结束时取得了本次记录中的最佳选择指标。

正确图/错配图实验保持文本不变，将同一 batch 内的图片轮换，再比较参考回答的损失。本次两次评估均有 1,865 条有效配对样本；配对时会排除无法形成有效对照的记录。

可以从这些记录中得到以下结论：

• 参考回答的预测损失下降。 图文和纯文本两部分均得到改善。
• 正确图片仍优于错配图片。 最终差值为正，说明在这组对照中，正确的视觉输入有助于预测参考回答。
• 图文配对差值没有随 SFT 扩大。 差值从 0.227482 降至 0.172816，因此仅凭损失下降，还不能断言视觉依赖程度或图像理解能力同步增强。

以上结果属于固定验证子集上的训练评估，尚无本模型在独立公开基准上的得分。LM loss 与配对损失差都不能直接转换成图像问答准确率。

generations.jsonl 同时保留了固定样例的生成过程。最终步的记录中仍可见重复表达、逻辑不一致及与参考回答不符的内容，说明生成质量和指令遵循仍需改进。每个样例的生成上限为 64 个新 token，部分回答可能因达到上限而截断；这些文本记录未经过逐图人工核验。

4. 文件说明

两个 .pt 文件是自定义格式 minillm_vlm_sft 的推理导出产物，包含加载语言模型所需的全部参数，使用时无需再加载原始 miniLLM Base 或 Pretrain adapter。它们不包含视觉编码器，也不包含用于精确恢复训练的优化器、学习率调度器与随机数状态；断点续训需要训练目录中的专用 checkpoint。

该格式需要通过配套项目的 eval/eval_vlm.py --sft-model 加载，不能直接将本目录作为标准 Hugging Face 模型目录调用 AutoModel.from_pretrained()。

5. 快速使用

准备资源

推理需要独立的 miniLLM-vlm 项目代码、本目录中的 SFT 权重与 tokenizer，以及本次训练使用的 siglips 视觉编码器目录。可按下列结构放置：

miniLLM-vlm/
├── eval/eval_vlm.py
├── model/
│   ├── model_minillm.py
│   ├── model_vlm.py
│   └── siglips/             # 配套的视觉编码器与图像预处理配置
├── dataset/                 # 保留项目中的数据处理代码
├── trainer/                 # 保留项目中的加载与评估工具
├── minillm_vlm/
├── requirements.txt
└── out/
    ├── best_sft.pt
    └── tokenizer/

在已有可用 CUDA 版 PyTorch 的环境中，按项目 requirements.txt 安装其余依赖。以下命令均从 miniLLM-vlm 项目根目录执行。

视觉编码器需使用与训练时匹配的导出版本。 加载器会核对视觉资源和 tokenizer 的文件指纹；仅有相同的模型名称或张量形状不足以通过校验。完整的上游 SigLIP2 模型目录不能直接替代本次仅保留视觉部分的 siglips 目录。移动目录后，可通过下面的路径参数指定新位置。

6. 使用范围与局限

• 用途： VLM 架构学习、Pretrain/SFT 流程复现、图文对齐实验，以及小模型后续微调研究。接口支持中英文输入，具体回答质量需结合实际样例评估。
• 图像输入： 当前每个对话处理一张图片，固定缩放至 256 × 256。小字、密集物体和精细空间关系可能丢失，未验证可靠的 OCR、计数或复杂图表推理能力。
• 回答质量： 可能出现重复、答非所问、逻辑矛盾和未被图像支持的细节。已有生成记录表明这些问题仍然存在。
• 上下文长度： 本次 SFT 最长使用 768 token。语言模型配置中的更大位置上限不代表相应长上下文能力经过训练与验证。
• 模态范围： 输出为文本，当前实现未提供多图、视频、音频理解或图像生成功能。
• 评估范围： 当前结果来自训练过程中的固定验证子集，尚缺少独立测试集、公开基准和系统性人工评估。

7. 来源与许可信息

• 语言基座： miniLLM 项目训练的 Base 模型；本次导出权重内保留了基座配置及资源身份信息。

• 视觉编码器上游： google/siglip2-base-patch32-256，其官方模型页标注的许可证为 Apache-2.0。

本说明中的配置、样本数量和验证指标来自随附训练记录；模型层数、参数量、权重格式和训练步数已与导出产物核对。