AD-Styles/mini-llava-stage2

Mini-LLaVA — Stage 2 LoRA Weights

LLaVA-1.5 의 핵심 아키텍처를 처음부터 직접 구현한 멀티모달 LLM 의 학습된 가중치. HuggingFace 의 LlavaForConditionalGeneration 같은 고수준 추상화 미사용, 융합 로직 직접 구현.

🚀 Live Demo: https://huggingface.co/spaces/AD-Styles/mini-llava-demo (설치 없이 즉시 체험) 📂 코드 레포: https://github.com/AD-Styles/vlm-from-scratch 📝 상세 분석 (v1→v2 회고록 포함): GitHub README 📊 Test A/B/C 결과 표: GitHub README #-results

🧩 구성

파일	크기	역할
projector.pt	5.7 MB	CLIP-ViT-B/32 → Qwen2.5 임베딩 공간 매핑 (2-layer MLP)
lora_adapter/adapter_config.json	1 KB	PEFT LoRA 설정
lora_adapter/adapter_model.safetensors	~1 GB	LoRA r=16 가중치 + embed_tokens / lm_head (학습 시 변경분 포함)

왜 1GB? PEFT 가 <image> 특수 토큰 추가로 인한 embedding resize 를 감지해 embed_tokens / lm_head 를 함께 저장. 이를 단순 분리 시도했으나 (코드 레포 scripts/extract_lora.py), 5문항 중 3문항이 완전히 다른 응답으로 변하면서 embed_tokens 가 학습된 상태의 일부임을 실험으로 확인. 따라서 원본 1GB 그대로 배포.

🚀 사용법

# 1. 코드 + 환경 준비
git clone https://github.com/AD-Styles/vlm-from-scratch
cd vlm-from-scratch
pip install --upgrade "torch>=2.6.0" "torchvision>=0.21.0" --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

# 2. 이 레포에서 가중치 다운로드 (~1 GB)
huggingface-cli download AD-Styles/mini-llava-stage2 --local-dir checkpoints/v2_stage2_lora

# 3. Gradio 데모 실행
python app.py \
  --checkpoint checkpoints/v2_stage2_lora/projector.pt \
  --lora-adapter checkpoints/v2_stage2_lora/lora_adapter

브라우저에서 http://localhost:7860 접속 → 이미지 업로드 → 자연어 질문.

📊 학습 설정

항목	값
Base 모델	openai/clip-vit-base-patch32 (frozen) + Qwen/Qwen2.5-0.5B-Instruct (frozen + LoRA)
데이터	HuggingFaceM4/the_cauldron 3-config 믹스 (localized_narratives + aokvqa + vqav2), 9,000 샘플
LoRA	rank=16, alpha=32, target=q/k/v/o projection
Epochs	2
Batch size	2 (grad_accum=4 → effective 8)
Learning rate	2e-4 (cosine)
GPU	NVIDIA RTX 4060 Laptop (8GB VRAM)
학습 시간	47 분
학습 가능 파라미터	3,655,424 (전체의 0.66%)
Init	v1 baseline projector 이어 학습 (Stage 1 → Stage 2)

✅ 검증 결과 (영문 VQA, 강아지 사진)

질문	응답	정확도
What is in this image?	"Dog."	✅
What color is the dog?	"White."	✅
Is the dog wearing anything on its head?	"Yes."	✅
What is on the dog's head?	"Hat."	✅
Describe this image in one sentence.	"...cat on the floor."	⚠️ (헬로키티 모자 영향)

Test A: 4/5 정확, instruction format 자동 매칭 성공.

⚠️ 한계 (정직한 명시)

• 한국어: LoRA의 catastrophic forgetting — 학습 데이터 100% 영어. "이 강아지는 머리에 무엇을 쓰고 있나요?" → "개." (영어 단답 편향이 한국어 표현으로 잘못 변환)
• OOD (만화/애니메이션): CLIP-ViT-B/32 표현 한계. 피카츄 → "Giraffe" (학습 분포 내 가장 가까운 동물로 매핑)
• Hallucination: "모른다" 답변 못 함 (VLM 공통 문제)

자세한 분석은 GitHub README의 Test B/C 섹션 참조.

🔮 향후 개선 (v3 로드맵)

1. 한국어 instruction 데이터 30%+ 추가 → catastrophic forgetting 해소
2. CLIP-ViT-L/14 (576 patches) 업그레이드 → OOD 견고성 ↑
3. OOD detection module → "모른다" 답변 학습
4. vLLM / Triton Inference Server 통합 → 프로덕션 서빙

📚 References

• LLaVA-1.5 (Liu et al., 2023) — arxiv:2310.03744
• CLIP (Radford et al., 2021) — arxiv:2103.00020
• LoRA (Hu et al., 2022) — arxiv:2106.09685
• the_cauldron (Laurençon et al., 2024) — arxiv:2405.02246

License

MIT — 자유롭게 사용 / 수정 / 배포 가능.

---

🤖 김도윤 (AD-Styles) · 2026