Tái hiện thực nghiệm bài báo "LEO-MINI: An Efficient Multimodal Large Language Model using Conditional Token Reduction and Mixture of Multi-Modal Experts" (EMNLP 2025).
Yimu Wang, Mozhgan Nasr Azadani, Sean Sedwards, Krzysztof Czarnecki — University of Waterloo
Repo này có hai variant:
| Variant | LLM | Vision experts | N^V | Benchmark | Mục đích |
|---|---|---|---|---|---|
| LEO-MINI (gốc) | Llama-3.2-1B/3B, Phi-3.5-mini | CLIP + EVA-02 + ConvNeXt + Pix2Struct | 64 | MME, POPE, TextVQA, … | Tái hiện paper |
| Vi-LEO-MINI | Qwen2.5-3B-Instruct | CLIP + Pix2Struct | 128 | ViTextVQA | Hỏi đáp ảnh có chữ tiếng Việt |
LEO-MINI giải quyết hai vấn đề cốt lõi của MLLM hiện đại:
Hiệu quả (Efficiency): Visual tokens chiếm phần lớn context length của LLM.
LEO-MINI giảm 576 tokens/expert xuống còn 64 tokens bằng module CoTR (Conditional Token Reduction).
Hiệu năng (Effectiveness): Nhiều domain yêu cầu features đặc thù.
LEO-MINI dùng MMoE (Mixture of Multi-Modal Experts) — nhiều vision expert đa dạng và LoRA expert có routing thông minh trong LLM.
| So sánh | LEO-MINI-Llama3-8B | LLaVA-NeXT (2880 tokens) |
|---|---|---|
| Visual tokens | 64 | 2880 |
| FLOPs | −63.83% | baseline |
| CUDA time | −90.69% | baseline |
| MME | 1583 | 1533 |
| POPE | 90.3 | 86.5 |
| TextVQA | 75.1 | 67.6 |
Image(s) + Text Instruction
│
├─ MMoE-Vision (4 experts — tất cả frozen trong Stage 3)
│ ├─ CLIP ViT-L/14-336 → (B, 576, 1024)
│ ├─ EVA-02 CLIP-L-14-336 → (B, 576, 1024)
│ ├─ ConvNeXt-Large-D → (B, 576, 768)
│ └─ Pix2Struct-Large → (B, 576, 2048) d^V tổng = 4864
│
├─ CoTR [Stage 3 only] 576×4 → 64 tokens/expert
│ Eq.2 s_QUERY = Q̄_i · Ī_i^T ∈ R^{N^V × N_i}
│ Eq.3 s_SELF = 1·Ī_i · Ī_i^T ∈ R^{1 × N_i}
│ Eq.4 s_CROSS = Σ_{j≠i} 1·Ī_j · Ī_i^T ∈ R^{1 × N_i}
│ Eq.5 s_TEXT = 1·T̂ · Ī_i^T ∈ R^{1 × N_i}
│ Eq.6 α_i = softmax((Σ scores) / √d_i^V)
│ Eq.7 Ī_i = α_i · I_i → concat → (B, 64, 4864)
│
├─ Visual Projector (B, 64, 4864) → (B, 64, d_LLM)
│ Linear → GELU → Linear
│
└─ LLM + MMoE-LLM [Stage 3 only]
concat([Ī_proj, T_embed]) → LLM
down_proj replaced by:
y = f_ORI(x) + f_GEN(x) + f_top1(x) (Eq.8)
Router: 2-layer MLP + GELU ← (Ī, T, x)
Balance loss: λ·Σ_i(fraction_i − 1/E)² (λ=0.05)
Image (tiếng Việt có chữ) + Câu hỏi tiếng Việt
│
├─ MMoE-Vision (2 experts — frozen trong Stage 3)
│ ├─ CLIP ViT-L/14-336 → (B, 576, 1024) nhận biết cảnh tổng quát
│ └─ Pix2Struct-Large → (B, 576, 2048) chuyên OCR / document
│ d^V tổng = 3072
│
├─ CoTR [Stage 3 only] 576×2 → 128 tokens (N^V=128 để giữ detail chữ)
│
├─ Visual Projector (B, 128, 3072) → (B, 128, 2048)
│
└─ Qwen2.5-3B-Instruct + MMoE-LLM [Stage 3 only]
Chat template: <|im_start|>user / <|im_end|> / <|im_start|>assistant
Lý do chọn cấu hình này:
- Bỏ EVA-02 + ConvNeXt: hai expert này tối ưu cho object detection / scene understanding, ít giá trị cho ViTextVQA (scene-text heavy). Tiết kiệm ~1.8 GB VRAM.
- Tăng N^V từ 64 → 128: ảnh có chữ tiếng Việt (biển hiệu, hóa đơn, biển số) cần nhiều spatial tokens hơn để giữ nguyên vẹn hình dạng ký tự.
- Qwen2.5-3B: hỗ trợ tiếng Việt tốt hơn Llama-3.2 nhờ dữ liệu pretraining đa ngôn ngữ phong phú hơn.
| Stage | Trainable | Frozen | Data |
|---|---|---|---|
| 1 — Warmup Projector | Visual Projector | LLM, Vision Experts | EAGLE alignment / KTVIC (captioning) |
| 2 — Full SFT | Tất cả | — | EAGLE SFT / OpenViVQA (general VQA) |
| 3 — Token Reduction | CoTR + MMoE-LLM + Projector | LLM backbone, Vision Experts | LLaVA-v1.5 665K / ViTextVQA (scene-text) |
| Model | VRAM Stage 2 | VRAM Stage 3 | Optimizer Stage 2 | Ghi chú |
|---|---|---|---|---|
meta-llama/Llama-3.2-1B-Instruct |
~14 GB | ~8 GB | adamw_torch | LEO-MINI gốc |
meta-llama/Llama-3.2-3B-Instruct |
~27 GB | ~14 GB | adamw_bnb_8bit | LEO-MINI gốc |
microsoft/Phi-3.5-mini-instruct |
~30 GB | ~16 GB | adamw_bnb_8bit | LEO-MINI gốc |
Qwen/Qwen2.5-3B-Instruct |
~27 GB | ~14 GB | adamw_bnb_8bit | Vi-LEO-MINI |
meta-llama/Meta-Llama-3-8B-Instruct |
~65 GB | ~32 GB | DeepSpeed Zero2 | Paper gốc (8× GPU) |
Llama-3.2-3B, Phi-3.5-mini, Qwen2.5-3B cần
adamw_bnb_8bit+ gradient checkpointing ở Stage 2 (đã cấu hình sẵn trong model configs).
| Kịch bản | GPU | Ghi chú |
|---|---|---|
| Paper (full scale) | 8× A6000 48 GB | DeepSpeed Zero2 |
| Vi-LEO-MINI / LEO-MINI 3B / Phi | 1× A6000 / A100 48 GB | 8-bit Adam + gradient checkpointing |
| LEO-MINI 1B | 1× RTX 3090 24 GB | AdamW chuẩn |
| Quick eval (Colab) | T4 16 GB | 4-bit quantisation |
conda create -n leomini python=3.10 -y
conda activate leomini
# PyTorch 2.5.1 + CUDA 12.4
# Kiểm tra CUDA version: nvidia-smi | grep "CUDA Version"
# Thay cu124 → cu120/cu121 nếu driver chỉ hỗ trợ CUDA 12.0/12.1
pip install "torch==2.5.1+cu124" "torchvision==0.20.1+cu124" "torchaudio==2.5.1+cu124" \
--index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txtLưu ý NumPy:
requirements.txtpinnumpy<2.0. Nếu gặp_ARRAY_API not found, chạypip install "numpy<2".
# Đăng nhập một lần, token lưu vào ~/.cache/huggingface/token
hf auth loginMột số model là gated repos — cần accept license tại trang model:
- Meta Llama: được approve ngay lập tức
- Qwen2.5: không cần gate
# LLM backbone
hf download meta-llama/Llama-3.2-1B-Instruct # LEO-MINI gốc
hf download meta-llama/Llama-3.2-3B-Instruct # LEO-MINI gốc
hf download microsoft/Phi-3.5-mini-instruct # LEO-MINI gốc
hf download Qwen/Qwen2.5-3B-Instruct # Vi-LEO-MINI
# Vision experts (dùng cho cả hai variant)
hf download openai/clip-vit-large-patch14-336
hf download google/pix2struct-large
# EVA-02 và ConvNeXt: tải tự động qua open_clip (chỉ LEO-MINI gốc)
# EAGLE Stage-2 checkpoint (shortcut Stage 1+2, chỉ Llama3-8B)
hf download NVEagle/Eagle-X4-8B-Plusmkdir -p data/eagle data/eagle_sft
# Stage 1 — LLaVA-Pretrain 558K (alignment, ~12 GB)
hf download liuhaotian/LLaVA-Pretrain \
--repo-type dataset \
--local-dir data/eagle
unzip data/eagle/images.zip -d data/eagle/images
# Stage 2 — LLaVA-1.5 SFT 665K
hf download liuhaotian/LLaVA-Instruct-150K \
--repo-type dataset \
--local-dir data/eagle_sftẢnh Stage 2 đến từ nhiều nguồn (COCO, GQA, OCR-VQA, TextVQA, VisualGenome).
Xem LLaVA Data Preparation. Đặt vàodata/eagle_sft/images/.Flag
--repo-type datasetlà bắt buộc.
Cả 3 bộ dữ liệu cho Vi-LEO-MINI (KTVIC, OpenViVQA, ViTextVQA) đều được tải tự động qua HuggingFace datasets khi chạy training lần đầu. Không cần tải thủ công.
# Tương đương với điều trainer thực hiện:
from datasets import load_dataset
ds = load_dataset("ai-enthusiasm-community/KTVIC", split="train")
# Cache tự động tại ~/.cache/huggingface/datasets/Nếu muốn cache về thư mục cụ thể:
# configs/models/qwen2_5_3b_vi.yaml
vi_cache_dir: "/data/hf_cache"Model-specific configs nằm ở configs/models/. Mỗi file chỉ chứa các key khác với stage config mặc định.
# Stage 1 — Warmup Projector
bash scripts/run_stage1.sh configs/models/llama3_2_1b.yaml
bash scripts/run_stage1.sh configs/models/llama3_2_3b.yaml
bash scripts/run_stage1.sh configs/models/phi3_5_mini.yaml
# Stage 2 — Full SFT
bash scripts/run_stage2.sh configs/models/llama3_2_1b.yaml
bash scripts/run_stage2.sh configs/models/llama3_2_3b.yaml
bash scripts/run_stage2.sh configs/models/phi3_5_mini.yaml
# Stage 3 — Token Reduction
bash scripts/run_stage3.sh configs/models/llama3_2_1b.yaml
bash scripts/run_stage3.sh configs/models/llama3_2_3b.yaml
bash scripts/run_stage3.sh configs/models/phi3_5_mini.yaml
# Multi-GPU
NUM_GPUS=4 bash scripts/run_stage3.sh configs/models/llama3_2_3b.yamlbase_model_path: "meta-llama/Llama-3.2-1B-Instruct"
output_dir: "checkpoints/llama3_2_1b"
per_device_batch_size: 8
gradient_accumulation: 8
optim: "adamw_torch"
gradient_checkpointing: falsebase_model_path: "meta-llama/Llama-3.2-3B-Instruct"
output_dir: "checkpoints/llama3_2_3b"
per_device_batch_size: 2
gradient_accumulation: 32
optim: "adamw_bnb_8bit" # bắt buộc để tránh OOM Stage 2
gradient_checkpointing: truebase_model_path: "microsoft/Phi-3.5-mini-instruct"
output_dir: "checkpoints/phi3_5_mini"
per_device_batch_size: 2
gradient_accumulation: 32
optim: "adamw_bnb_8bit"
gradient_checkpointing: trueQuan trọng: Dùng
base_model_path(không phảillm_path) trong model configs.
Trainer tự động derivellm_pathcho Stage 2/3 từoutput_dir/stage{n-1}/llm_checkpoint/.
# Stage 1 — Projector warmup trên KTVIC (image captioning)
bash scripts/run_vi_stage1.sh configs/models/qwen2_5_3b_vi.yaml
# Stage 2 — Full SFT trên OpenViVQA (yêu cầu Stage 1 xong)
bash scripts/run_vi_stage2.sh configs/models/qwen2_5_3b_vi.yaml
# Stage 3 — CoTR + MMoE-LLM trên ViTextVQA (yêu cầu Stage 2 xong)
bash scripts/run_vi_stage3.sh configs/models/qwen2_5_3b_vi.yaml
# Multi-GPU
NUM_GPUS=2 bash scripts/run_vi_stage3.sh configs/models/qwen2_5_3b_vi.yamlNếu Stage trước chưa chạy, trainer sẽ thoát ngay với lỗi rõ ràng (sys.exit(1)) — không silent fallback.
base_model_path: "Qwen/Qwen2.5-3B-Instruct"
output_dir: "checkpoints/qwen2_5_3b_vi"
# 2 vision experts chuyên cho text-image
vision_experts:
- clip
- pix2struct
n_visual: 128 # 128 tokens giữ detail chữ tiếng Việt
d_proj_cotr: 256
lora_rank: 16
num_special: 3
vi_train_path: "train"
vi_val_path: "validation"
log_dir: "logs/qwen2_5_3b_vi"
gradient_accumulation: 32
gradient_checkpointing: true
optim: "adamw_bnb_8bit"
bf16: truecheckpoints/qwen2_5_3b_vi/
├── stage1/
│ ├── llm_checkpoi
8BD0
nt/ ← Qwen2.5-3B đã fine-tune projector warmup
│ └── projector_weights.pt ← dùng làm projector_path cho Stage 2
├── stage2/
│ ├── llm_checkpoint/ ← Qwen2.5-3B đã full SFT
│ └── projector_weights.pt ← dùng làm projector_path cho Stage 3
└── stage3/
└── stage3_adapter_weights.pt ← projector + CoTR + MMoE-LLM LoRA weights
Khi Stage 3 kết thúc, hai artifacts cần thiết để chạy evaluation là:
| Artifact | Đường dẫn | Chứa gì |
|---|---|---|
| LLM backbone (Stage 2) | checkpoints/qwen2_5_3b_vi/stage2/llm_checkpoint/ |
Qwen2.5-3B đã full SFT |
| Stage 3 adapters | checkpoints/qwen2_5_3b_vi/stage3/stage3_adapter_weights.pt |
projector + CoTR + MMoE-LLM LoRA |
Chạy evaluation ngay sau Stage 3:
python -m src.eval.vi_evaluator \
--model_path checkpoints/qwen2_5_3b_vi/stage2/llm_checkpoint \
--stage3_weights checkpoints/qwen2_5_3b_vi/stage3/stage3_adapter_weights.pt \
--split test \
--output_dir results/vi_leomini/ \
--log_dir logs/qwen2_5_3b_vi/ \
--vision_experts clip pix2struct \
--n_visual 128Sai lầm thường gặp: dùng
--model_path Qwen/Qwen2.5-3B-Instruct(base model) thay chostage2/llm_checkpoint.stage3_adapter_weights.ptkhông bao gồm LLM backbone — nếu không load Stage 2 backbone, LLM vẫn là model gốc chưa fine-tune, dẫn đến ANLS thấp hơn đáng kể.
Vi-LEO-MINI dùng Qwen2.5 chat template thay cho USER:/ASSISTANT: của bản gốc:
<|im_start|>system
Bạn là trợ lý AI thông minh, hãy trả lời câu hỏi dựa trên nội dung hình ảnh...<|im_end|>
<|im_start|>user
<image>
{câu hỏi tiếng Việt}<|im_end|>
<|im_start|>assistant
{câu trả lời}<|im_end|>
Label masking: tất cả tokens trước <|im_start|>assistant\n được mask bằng -100.
python -m src.eval.evaluator \
--model_path checkpoints/stage3 \
--model_name "Llama-3.2-3B" \
--tasks pope,scienceqa,textvqa,mme,mmmu \
--output_dir results/llama3bBASE_1B="meta-llama/Llama-3.2-1B-Instruct" \
CKPT_1B="checkpoints/llama3_2_1b/stage3/stage3_adapter_weights.pt" \
BASE_3B="meta-llama/Llama-3.2-3B-Instruct" \
CKPT_3B="checkpoints/llama3_2_3b/stage3/stage3_adapter_weights.pt" \
BASE_PHI="microsoft/Phi-3.5-mini-instruct" \
CKPT_PHI="checkpoints/phi3_5_mini/stage3/stage3_adapter_weights.pt" \
bash scripts/run_benchmark_compare.sh| Benchmark | Metric | Target (paper, 8B) |
|---|---|---|
| MME | Perception score | 1583.0 |
| MMBench | Overall acc | 77.0 |
| SEED-Bench | Overall acc | 75.8 |
| GQA | Exact match | 64.5 |
| ScienceQA | Acc | 84.5 |
| MMMU | Acc | 38.8 |
| POPE | Acc | 90.3 |
| AI2D | Acc | 75.7 |
| TextVQA | Acc | 75.1 |
| ChartQA | Relaxed acc | 80.5 |
| OCRBench | Acc | 62.4 |
| VizWiz | VQA acc | 69.3 |
| Metric | Mô tả | Công thức |
|---|---|---|
| ANLS (main) | Average Normalized Levenshtein Similarity | 1 - NL nếu NL < 0.5, else 0; trung bình trên tất cả câu hỏi |
| EM | Exact Match (%) | 1 nếu dự đoán khớp chính xác với bất kỳ GT nào sau normalize |
| F1 | Token-level F1 (%) | Bag-of-words overlap, max over GT answers |
Lưu ý: Normalize tiếng Việt giữ nguyên dấu thanh (tone marks) vì chúng thay đổi nghĩa hoàn toàn (ma / má / mà / mả / mã / mạ). Bước normalize: (1) NFC Unicode normalization trước tiên — tránh trường hợp NFD tách combining diacritical marks (U+0300–U+036F) bị regex
[^\w\s]xóa mất dấu; (2) lowercase; (3) bỏ punctuation; (4) collapse spaces.
Lưu ý quan trọng về
--model_path:stage3_adapter_weights.ptchỉ chứa adapters (projector + CoTR + MMoE-LLM LoRA), không chứa LLM backbone. LLM backbone đã được fine-tune ở Stage 2 và lưu tạicheckpoints/qwen2_5_3b_vi/stage2/llm_checkpoint/. Phải dùng đường dẫn đó thay choQwen/Qwen2.5-3B-Instructđể có kết quả đúng.
# Sau khi hoàn thành Stage 3:
python -m src.eval.vi_evaluator \
--model_path checkpoints/qwen2_5_3b_vi/stage2/llm_checkpoint \
--stage3_weights checkpoints/qwen2_5_3b_vi/stage3/stage3_adapter_weights.pt \
--split test \
--output_dir results/vi_leomini/ \
--log_dir logs/qwen2_5_3b_vi/ \
--vision_experts clip pix2struct \
--n_visual 128
# Nhanh — chỉ 200 mẫu:
python -m src.eval.vi_evaluator \
--model_path checkpoints/qwen2_5_3b_vi/stage2/llm_checkpoint \
--stage3_weights checkpoints/qwen2_5_3b_vi/stage3/stage3_adapter_weights.pt \
--split validation \
--limit 200 \
--output_dir results/vi_leomini/Output file JSON được lưu tại results/vi_leomini/eval_stage3_test_<timestamp>.json:
{
"stage": 3,
"split": "test",
"anls": 0.6123,
"em": 0.4891,
"f1": 0.5934,
"anls_pct": 61.23,
"em_pct": 48.91,
"f1_pct": 59.34,
"n_samples": 2000,
"per_sample": [
{
"idx": 0,
"pred": "Phở Bắc",
"gts": ["Phở Bắc", "PHỞ BẮC"],
"anls": 1.0,
"em": 1.0,
"f1": 1.0
},
...
]
}Mỗi training run tự động ghi log vào logs/<model>/<run_id>.json:
{
"run_id": "Qwen2.5_3B_Instruct_stage1_20260623_143000",
"config": { "stage": 1, "n_visual": 128, "vision_experts": ["clip", "pix2struct"], ... },
"events": [
{ "type": "train_step", "stage": 1, "global_step": 10, "loss": 2.314, "learning_rate": 9.8e-4 },
{ "type": "train_step", "stage": 1, "global_step": 20, "loss": 1.982, "balance_loss": 0.021 },
{ "type": "eval", "stage": 2, "global_step": 500, "split": "validation",
"anls": 0.412, "em": 0.283, "f1": 0.471, "n_samples": 1000 },
{ "type": "stage_end", "stage": 1, "duration_sec": 3600, "checkpoint_path": "..." }
]
}# Tự động sau mỗi eval run
python -m src.utils.visualizer \
--log logs/qwen2_5_3b_vi/run_id.json \
--output results/vi_leomini/
# Charts được tạo ra trong results/vi_leomini/plots/:
# training_loss_stage1.png — loss curve Stage 1
# training_loss_stage2.png — loss curve Stage 2
# training_loss_stage3.png — loss curve Stage 3
# balance_loss_stage3.png — balance loss vs total loss (Stage 3)
# eval_metrics_history.png — ANLS / EM / F1 qua các checkpoints
# learning_rate_schedule.png — LR schedule
# anls_distribution_stage3_test.png — histogram phân phối ANLS per-sample!pip install "torch==2.5.1+cu124" "torchvision==0.20.1+cu124" "torchaudio==2.5.1+cu124" \
--index-url https://download.pytorch.org/whl/cu124
!pip install "numpy<2" transformers peft bitsandbytes accelerate timm \
open-clip-torch lmms-eval huggingface_hub[hf_xet] datasets matplotlib
from google.colab import drive
drive.mount('/content/drive')
import sys
sys.path.insert(0, '/content/leo_mini')Lưu ý: Nếu bạn có
stage2/llm_checkpoint/trên Drive, hãy dùng đường dẫn đó làmllm_pathđể có kết quả tốt hơn.Qwen/Qwen2.5-3B-Instructchỉ dùng khi không có checkpoint Stage 2 (kết quả sẽ thấp hơn vì LLM backbone chưa được fine-tune).
import torch
from src.models
D74B
.leo_mini import LeoMini
# Tốt nhất: dùng Stage 2 checkpoint (LLM đã fine-tune)
model = LeoMini.from_pretrained(
llm_path="/content/drive/MyDrive/vi_leomini/stage2/llm_checkpoint",
stage3_weights="/content/drive/MyDrive/vi_leomini/stage3_adapter_weights.pt",
load_in_4bit=True,
vision_experts=["clip", "pix2struct"],
n_visual=128,
)
model.eval()from PIL import Image
from transformers import CLIPImageProcessor, AutoProcessor
image = Image.open("bien_hieu.jpg") # ảnh biển hiệu tiếng Việt
question = "Tên cửa hàng trên biển hiệu là gì?"
# Visual preprocessing
clip_proc = CLIPImageProcessor.from_pretrained("openai/clip-vit-large-patch14-336")
p2s_proc = AutoProcessor.from_pretrained("google/pix2struct-large")
pixel_values = clip_proc(images=image, return_tensors="pt").pixel_values
p2s_inputs = p2s_proc(images=image, text="", return_tensors="pt", max_patches=576)
pix2struct_inputs = {
"flattened_patches": p2s_inputs.flattened_patches,
"attention_mask": p2s_inputs.attention_mask,
}
# Text preprocessing (Qwen2.5 chat format)
from src.data.vitextvqa_dataset import _qwen2_prompt_only
from src.models.leo_mini import IMAGE_TOKEN_INDEX
prompt = _qwen2_prompt_only(question)
enc = model.tokenizer(prompt, return_tensors="pt", add_special_tokens=False)
input_ids = enc.input_ids
input_ids[input_ids == model.tokenizer.convert_tokens_to_ids("<image>")] = IMAGE_TOKEN_INDEX
with torch.no_grad():
output_ids = model.generate(
input_ids=input_ids.cuda(),
pixel_values=pixel_values.cuda(),
pix2struct_inputs={k: v.cuda() for k, v in pix2struct_inputs.items()},
max_new_tokens=64,
do_sample=False,
)
answer = model.tokenizer.decode(output_ids[0], skip_special_tokens=True)
print("Câu trả lời:", answer)!python -m src.eval.vi_evaluator \
--model_path /content/drive/MyDrive/vi_leomini/stage2/llm_checkpoint \
--stage3_weights /content/drive/MyDrive/vi_leomini/stage3_adapter_weights.pt \
--split validation \
--limit 500 \
--load_in_4bit \
--vision_experts clip pix2struct \
--n_visual 128 \
--output_dir /content/resultsleo_mini/
├── docs/
│ └── leomini.pdf # Bài báo gốc (EMNLP 2025)
├── src/
│ ├── models/
│ │ ├── cotr.py # CoTR: Eq.2–7 (token reduction)
│ │ ├── mmoe_llm.py # MMoE-LLM: LoRA experts + router + balance loss
│ │ ├── vision_experts.py # CLIP / EVA-02 / ConvNeXt / Pix2Struct
│ │ │ # build_mmoe_vision(experts=["clip","pix2struct"])
│ │ ├── projector.py # Visual Projector (2-layer MLP)
│ │ └── leo_mini.py # Full pipeline + from_pretrained + set_stage()
│ ├── data/
│ │ ├── dataset.py # EAGLEDataset + LLaVADataset (gốc)
│ │ ├── collator.py # Batch collation
│ │ └── vitextvqa_dataset.py # ViTextVQADataset (HF auto-download, Qwen2.5 format)
│ ├── train/
│ │ └── trainer.py # 3-stage trainer + Vi fields + logging callback
│ ├── eval/
│ │ ├── evaluator.py # lmms-eval wrapper + compare_models()
│ │ ├── lmms_adapter.py # lmms-eval @register_model adapter
│ │ ├── metrics.py # ANLS / EM / F1 (Vietnamese-aware)
│ │ └── vi_evaluator.py # ViTextVQAEvaluator + CLI
│ └── utils/
│ ├── logger.py # ViLeoMiniLogger (JSON) + LeoMiniLoggingCallback
│ └── visualizer.py # 5 chart types: loss, metrics, LR, ANLS dist
├── configs/
│ ├── config_stage1.yaml # LEO-MINI Stage 1 (gốc)
│ ├── config_stage2.yaml # LEO-MINI Stage 2 (gốc)
│ ├── config_stage3.yaml # LEO-MINI Stage 3 (gốc)
│ ├── config_vi_stage1.yaml # Vi-LEO-MINI Stage 1
│ ├── config_vi_stage2.yaml # Vi-LEO-MINI Stage 2
│ ├── config_vi_stage3.yaml # Vi-LEO-MINI Stage 3
│ ├── models/
│ │ ├── llama3_2_1b.yaml # Override: Llama-3.2-1B
│ │ ├── llama3_2_3b.yaml # Override: Llama-3.2-3B
│ │ ├── phi3_5_mini.yaml # Override: Phi-3.5-mini
│ │ └── qwen2_5_3b_vi.yaml # Override: Qwen2.5-3B (Vi-LEO-MINI)
│ └── deepspeed_zero2.json # DeepSpeed config (multi-GPU)
├── scripts/
│ ├── run_stage1.sh # LEO-MINI gốc
│ ├── run_stage2.sh
│ ├── run_stage3.sh
│ ├── run_vi_stage1.sh # Vi-LEO-MINI
│ ├── run_vi_stage2.sh
│ ├── run_vi_stage3.sh
│ ├── run_benchmark_compare.sh # so sánh LEO-MINI models
│ └── run_eval_leomini.py # wrapper cho lmms-eval
├── logs/ # JSON training logs (auto-created)
├── results/ # eval JSON + plots (auto-created)
├── requirements.txt
└── README.md
Với mỗi expert
Scale factor dùng
Vi-LEO-MINI:
Thay thế down_proj trong mọi MLP block của LLM:
-
$f_{\text{ORI}}$ : original frozendown_proj -
$f_{\text{GEN}}$ : general LoRA adapter (rank=16, luôn active) -
$f_i^E$ :$E=3$ special LoRA experts, top-$k=1$ được router chọn
Balance loss (tránh routing collapse):
Tổng loss = cross-entropy +
| Metric | Paper (8B) | Llama-1B | Llama-3B | Phi-3.5 |
|---|---|---|---|---|
| MME | 1583.0 | 1380–1450 | 1480–1530 | 1510–1560 |
| POPE | 90.3 | 83–85 | 86–88 | 87–89 |
| ScienceQA | 84.5 | 77–79 | 80–82 | 81–83 |
| TextVQA | 75.1 | 66–69 | 70–72 | 71–73 |
| Visual Tokens | 64 | 64 | 64 | 64 |
| Metric | Qwen2.5-3B (Stage 2) | Qwen2.5-3B (Stage 3 + CoTR) |
|---|---|---|
| ANLS | (baseline) | kỳ vọng tăng với token reduction |
| EM (%) | — | — |
| F1 (%) | — | — |
| Visual Tokens | 576×2 = 1152 | 128 |
Kết quả thực tế phụ thuộc vào dữ liệu training và số epoch. Chạy eval sau từng Stage để theo dõi tiến trình.
@inproceedings{wang2025leomini,
title = {LEO-MINI: An Efficient Multimodal Large Language Model
using Conditional Token Reduction and Mixture of
Multi-Modal Experts},
author = {Wang, Yimu and Nasr Azadani, Mozhgan and
Sedwards, Sean and Czarnecki, Krzysztof},
booktitle = {Proceedings of EMNLP 2025},
pages = {7246--7261},
year = {2025}
}Các công trình liên quan: