lab-mobileclip

CUHK-PEDES 기반 MobileCLIP 학습/평가 실험 레포입니다.
../lab_clip의 파이프라인 구조를 가져오고, 모델 로딩은 demo.py 기준 MobileCLIP(OpenCLIP) 방식으로 맞춘 버전입니다.

모델 정책

• 기본 모델 포맷: MobileCLIP-<variant>::<pretrained_tag>
• 기본 프리셋: MobileCLIP-S1::datacompdr, MobileCLIP-S2::datacompdr, MobileCLIP-B::datacompdr, MobileCLIP-B::datacompdr_lt, MobileCLIP2-S0::dfndr2b, MobileCLIP2-S2::dfndr2b, MobileCLIP2-S3::dfndr2b, MobileCLIP2-S4::dfndr2b, MobileCLIP2-B::dfndr2b, MobileCLIP2-L-14::dfndr2b
• 호환 레이어: src/utils/mobileclip_compat.py
  • 기존 CLIPModel/CLIPProcessor 인터페이스를 유지하면서 MobileCLIP으로 동작

프로젝트 구조

• src/train: 학습 스크립트
• src/eval/torch: 평가 스크립트
• src/core: 공통 train/eval 로직
• src/utils: 데이터로더, 로거, 체크포인트, MobileCLIP 어댑터
• src/demo.py: 단일 이미지 데모 추론

환경 준비

uv sync

또는 이미 생성된 venv 사용:

.venv/bin/python --version

데이터셋 경로

• 기본 경로: data/CUHK-PEDES
• 사용 파일:
  • data/CUHK-PEDES/caption_all.json
  • data/CUHK-PEDES/imgs/...

데모 실행

.venv/bin/python src/demo.py

커스텀 이미지:

.venv/bin/python src/demo.py --image-path /path/to/image.png

모델 구조 확인

백본 모델과 학습 체크포인트 구조를 함께 출력:

.venv/bin/python src/print_model_structure.py \
  --model-name MobileCLIP2-S4::dfndr2b \
  --model-path model/<model_id>/<run_dir>/epoch-03

학습 실행

• S1:

.venv/bin/python src/train/mobileclip-s1.py

• S2:

.venv/bin/python src/train/mobileclip-s2.py

• B:

.venv/bin/python src/train/mobileclip-b.py

• B (lt):

.venv/bin/python src/train/mobileclip-b-lt.py

• MobileCLIP2-S0:

.venv/bin/python src/train/mobileclip2-s0.py

• MobileCLIP2-S2:

.venv/bin/python src/train/mobileclip2-s2.py

• MobileCLIP2-S3:

.venv/bin/python src/train/mobileclip2-s3.py

• MobileCLIP2-S4:

.venv/bin/python src/train/mobileclip2-s4.py

• MobileCLIP2-B:

.venv/bin/python src/train/mobileclip2-b.py

• MobileCLIP2-L-14:

.venv/bin/python src/train/mobileclip2-l-14.py

KD 학습

.venv/bin/python src/train/knowledge_distillation.py \
  --teacher-name MobileCLIP-B::datacompdr \
  --student-name MobileCLIP-S2::datacompdr

평가 실행

Recall 단일 실행:

.venv/bin/python src/eval/torch/eval_recall.py \
  --dataset-root data/CUHK-PEDES \
  --model-name MobileCLIP-S2::datacompdr \
  --topk 1,5,10

전체 평가 일괄 실행:

.venv/bin/python src/eval/torch/run_all_evals.py \
  --dataset-root data/CUHK-PEDES \
  --model-name MobileCLIP-S2::datacompdr \
  --metrics all \
  --topk 1,5,10

학습 체크포인트 평가:

.venv/bin/python src/eval/torch/run_all_evals.py \
  --dataset-root data/CUHK-PEDES \
  --model-path model/<model_id>/<run_dir>/epoch-03 \
  --metrics all

ONNX Export

이미지/텍스트 백본 ONNX 내보내기:

.venv/bin/python export/onnx/export_clip_backbone_onnx.py \
  --model-name MobileCLIP2-S4::dfndr2b

로컬 체크포인트 기준 내보내기:

.venv/bin/python export/onnx/export_clip_backbone_onnx.py \
  --model-path model/<model_id>/<run_dir>/epoch-03

출력 경로

• 체크포인트: model/<model_id>/<run_dir>/epoch-XX
• 로그: logs/<logger_name>/<run_group>/<YYYY-MM-DD>/<timestamp>_<logger_name>.log

참고 사항

• 처음 실행 시 모델 가중치 다운로드를 위해 네트워크가 필요합니다.
• 오프라인 환경에서는 사전 캐시된 모델 또는 저장된 로컬 체크포인트(--model-path)를 사용하세요.