Gemma Multimodal Fine-Tuner — Apple Silicon에서 Gemma 4/3n 멀티모달 LoRA를 실행하는 실전형 튜너

이 프로젝트는 Gemma 4 및 Gemma 3n 계열을 Apple Silicon(MPS) 환경에서 텍스트·이미지·오디오까지 미세조정할 수 있게 설계된 저장소다. 단순한 스크립트 모음이 아니라, Typer 기반 CLI, 질문형 Wizard, 계층형 INI 설정 시스템, 모달리티별 collator, 실시간 브라우저 시각화, LoRA 병합 export 경로를 하나의 워크플로로 묶어 놓은 것이 핵심이다.

공개 인터페이스를 기준으로 보면, 분석의 중심축은 README.md, README/ 하위 문서, gemma_tuner/ 코드 구조다. GitHub 저장소 표면상 별도 Wiki/Discussions 중심 프로젝트라기보다는,
README + docs + source tree 중심으로 운영되는 타입에 가깝다.

Quick Links

• Repository README: github.com/mattmireles/gemma-tuner-multimodal
• Training Visualizer Demo 섹션: README의 training-visualizer 앵커
• Datasets 문서: README/Datasets.md
• Apple Silicon / Gemma 4 가이드: README/guides/apple-silicon/gemma4-guide.md
• Gemma 3n 사양 문서: README/specifications/Gemma3n.md
• Official Gemma docs: Google AI for Developers · Gemma docs
• Background paper: Gemma 3 Technical Report

Key Features

1. 멀티모달 LoRA 튜닝
   • modality = text | image | audio 구조를 중심으로 하나의 학습 파이프라인 안에서 텍스트, 이미지+텍스트, 오디오+텍스트 튜닝을 처리한다.
   • 오디오가 기본 축이지만, 현재 버전은 텍스트와 이미지도 같은 Gemma 기반 학습 경로로 들어오도록 재구성되어 있다.
2. Apple Silicon 우선 설계
   • get_device()는 MPS → CUDA → CPU 순으로 디바이스를 선택한다.
   • MPS에서는 attn_implementation = eager, 미세한 배치 클램프, gradient checkpointing 기본값, unified memory 경고 등 현실적인 macOS 안전장치가 촘촘하게 들어가 있다.
3. 질문형 Wizard + CLI 공존
   • 초심자는 gemma-macos-tuner wizard로 모델, 데이터셋, 학습 방식을 고르고,
   • 숙련자는 prepare, finetune, evaluate, export, runs 같은 하위 명령으로 세밀하게 제어할 수 있다.
   • Wizard는 config.ini가 없으면 config.ini.example에서 복사해 즉시 실행 가능한 상태를 만든다.
4. 실시간 브라우저 시각화
   • visualize = true를 켜면 Flask + Socket.IO 서버가 뜨고,
   • loss, attention heatmap, gradient signal, learning-rate(step size), memory, token predictions를 로컬 브라우저에 실시간으로 내보낸다.

 

캡션: 저장소가 제공하는 training visualizer 예시. 단순 loss 로그가 아니라 attention, gradient signal, memory, token prediction까지 한 화면에 묶어 Apple Silicon 로컬 학습 상태를 빠르게 진단하게 해 준다.

5. 데이터 품질 보정 파이프라인
   • utils/dataset_utils.py는 단순 CSV 로더가 아니라,
   • override_*, do_not_blacklist, delete 패치 트리를 적용해 교정·보호·블랙리스트를 함께 관리한다.
   • 특히 의료 음성 전사처럼 수작업 교정이 반복되는 도메인에서 실무성이 높다.
6. 모달리티별 Collator 분리
   • DataCollatorGemmaText, DataCollatorGemmaImage, DataCollatorGemmaAudio가 각각 존재한다.
   • 이 구조 덕분에 입력 스키마는 달라도, 최종적으로는 Gemma chat template + Hugging Face processor/tokenizer 기반 입력으로 정규화된다.
7. LoRA export / 배포 경로 포함
   • scripts/export.py는 adapter 디렉터리를 자동 감지하고,
   • base model을 다시 불러와 adapter를 merge한 뒤 HF / SafeTensors 트리로 내보낸다.
   • 즉, 이 저장소는 “학습만 하는 툴”이 아니라 학습 후 전달 가능한 산출물 생성까지 닿아 있는 툴체인이다.

Tech Stack

Core

• Python: >=3.10
• Package version: 1.1.0
• PyTorch / torchaudio: 수동 설치 전제
• Transformers: >=5.5.0
• Datasets: >=4.0.0
• Accelerate: >=0.27.2
• Evaluate: >=0.4.1
• PEFT: >=0.9.0
  • Gemma 4 가이드는 더 최신 PEFT 조합을 별도 권장한다.

Audio / Image / Data

• librosa: >=0.10.0,<0.11.0
• soundfile: >=0.12.0,<0.13.0
• scikit-learn: >=1.2.0
• Pillow: >=10.0.0
• timm: >=1.0.0
• numpy: >=1.26.4
• pandas: >=1.3.0

CLI / UX / Viz

• Typer: >=0.9.0
• Rich: >=13.0.0
• Questionary: >=2.0.0,<3.0.0
• Flask: >=2.3.0,<3.0.0
• Flask-SocketIO: >=5.3.0,<6.0.0
• python-socketio: >=5.9.0,<6.0.0

Cloud / Large-Data Extras

• google-cloud-storage: >=2.10.0
• google-cloud-bigquery: >=3.11.0
• db-dtypes: >=1.4.0,<2.0.0

Architecture

 

캡션: 저장소가 별도 아키텍처 이미지를 제공하지 않아, README와 핵심 모듈(cli_typer.py, core/config.py, core/ops.py, scripts/finetune.py, models/gemma/finetune.py, visualizer.py)을 바탕으로 재구성한 시스템 흐름도.

이 저장소의 구조를 한 줄로 요약하면 다음과 같다.

CLI/Wizard에서 구성한 설정이 계층형 INI로 합쳐지고, dispatch 레이어를 거쳐 Gemma 전용 학습기와 모달리티별 collator로 흘러간 뒤, 결과는 run artifact / dashboard / export 경로로 분기된다.

1) Entry layer: CLI + Wizard

• 실제 엔트리포인트는 gemma-macos-tuner = gemma_tuner.cli_typer:app.
• cli_typer.py는 준비(prepare), 학습(finetune), 평가(evaluate), export, run 관리, wizard 실행까지 묶는다.
• 중요한 구현 포인트는 Torch import 전에 Apple Silicon bootstrap을 먼저 수행한다는 점이다. MPS 메모리 및 환경 변수를 먼저 세팅하려는 의도다.

2) Config layer: 계층형 설정 병합

• core/config.py는 다음 순서로 설정을 병합한다.
  • [DEFAULT]
  • [dataset_defaults]
  • [group:gemma]
  • [model:*]
  • [dataset:*]
  • [profile:*]
• 이 설계 덕분에, 모델/데이터셋/프로파일을 독립적으로 조합하면서도 공통값을 DRY하게 유지할 수 있다.
• core/ops.py는 여기에 더해 --config, GEMMA_TUNER_CONFIG, repo-relative fallback 순으로 설정 파일 위치를 해석한다.

3) Data layer: CSV + patch bundle

• dataset_utils.py는 split 로드뿐 아니라, 패치 적용까지 함께 담당한다.
• 텍스트/이미지 모드 v1은 로컬 CSV 전용 제약이 강하게 걸려 있다.
• 오디오 경로는 준비 단계와 스트리밍 워크플로를 통해 GCS/BigQuery와 더 자연스럽게 연결된다.
• 이 구조는 “멀티모달”이라는 말과는 다르게, 실제 데이터 운영 경험상 오디오가 가장 성숙하고 텍스트/이미지는 빠르게 확장 중인 상태로 읽힌다.

4) Training router: Gemma 전용 경로

• scripts/finetune.py는 모델명이 gemma를 포함하는지 검사하고, Gemma 전용 학습 모듈로 라우팅한다.
• 시각화가 켜져 있으면 여기서 Flask/Socket.IO 기반 대시보드를 띄운다.

5) Core trainer: Gemma model + PEFT LoRA

• models/gemma/finetune.py가 실질적인 핵심이다.
• 주요 동작은 다음과 같다.
  1. 디바이스 선택 및 dtype 정책 수립
  2. train/validation split 로드
  3. 텍스트면 AutoTokenizer, 이미지/오디오면 AutoProcessor 초기화
  4. load_base_model_for_gemma(...)로 Gemma 계열 base model 로드
  5. LoraConfig 생성 및 target module 검증
  6. get_peft_model(...)로 adapter 주입
  7. 모달리티에 따라 적절한 collator 부착
  8. 시각화 여부에 따라 Trainer 또는 GemmaVizTrainer 사용

6) Modality adapters: collator가 사실상 제품성의 핵심

• Text
  • instruction/completion 두 모드를 지원한다.
  • prompt masking, assistant span 보호, 긴 입력 left-truncation 등 실전형 세부 처리 로직이 들어 있다.
• Image
  • caption과 VQA 두 모드를 지원한다.
  • image_token_budget를 processor에 강제로 반영해 train/serve mismatch를 줄인다.
• Audio
  • audio waveform을 로드한 뒤, AutoProcessor를 통해 Gemma 오디오 입력 포맷으로 정규화한다.
  • 사용자 프롬프트는 "Please transcribe this audio." 형태의 chat template로 감싼다.

7) Visualization subsystem

• visualizer.py는 지연 초기화(lazy init)되는 Flask app + Socket.IO 서버를 제공한다.
• VisualizerTrainerCallback와 GemmaVizTrainer는 HF Trainer에서 필요한 배치/출력 일부를 붙잡아 브라우저에 흘려보낸다.
• 즉, 이 시각화는 외부 TensorBoard 의존이 아니라 트레이너 내부 훅과 웹소켓 스트리밍을 엮은 자체 구현이다.

8) Output / export layer

• 기본 run layout은 대략 다음과 같다.

output/
└── {id}-{profile}/
    ├── metadata.json
    ├── metrics.json
    ├── checkpoint-*/
    └── adapter_model/

• scripts/export.py는 LoRA adapter가 있는지 보고 merge export를 수행하므로,
• 실험 산출물을 재현 가능한 run artifact와 배포 가능한 merged checkpoint 두 층으로 나눠 관리한다.

Usage & Setup

기본 설치 흐름

brew install python@3.12
python3.12 -m venv .venv
source .venv/bin/activate

pip install torch torchaudio
pip install -e .

huggingface-cli login
# 또는
export HF_TOKEN=hf_...

# Gemma 4를 쓸 경우
pip install -r requirements/requirements-gemma4.txt

Wizard 실행

gemma-macos-tuner wizard

 

 

캡션: 저장소 README가 제공하는 wizard 예시. system check 이후 학습 방법, 모델, 데이터셋을 순차적으로 선택하는 구조이며, Apple Silicon 메모리와 예상 시간 힌트를 함께 노출하는 것이 특징이다.

90초 Quickstart

gemma-macos-tuner wizard
# 또는
gemma-macos-tuner finetune sample-text

• 저장소에는 data/datasets/sample-text/가 포함되어 있어,
• 16개 학습 샘플 / 5개 검증 샘플 규모의 최소 예제로 전체 파이프라인을 검증할 수 있다.
• 첫 실행 시 Gemma base weights 다운로드가 필요하므로 체감 시간은 네트워크에 좌우된다.

시각화 옵션

pip install -e ".[viz]"
# profile에서 visualize = true 설정
gemma-macos-tuner finetune <profile>

• 기본 포트는 로컬 127.0.0.1:8080이다.
• 시각화 의존성이 없어도 학습은 계속되도록 설계되어 있다.

데이터 형식 요약

Text instruction

id,prompt,response
1,Translate to French: Good morning.,Bonjour.
2,What is the capital of Japan?,Tokyo.

Image caption

id,image_path,caption
1,images/receipt_001.jpg,"Total: $42.18, paid in cash"
2,images/receipt_002.jpg,"Subtotal $19.99, tax $1.60, total $21.59"

Audio transcription

id,audio_path,text,language,duration
1,audio/sample_001.wav,"the quick brown fox jumps over the lazy dog",en,2.4

Personal Insights

1) 의료 AI 관점

이 저장소는 특히 프라이버시를 민감하게 다루는 의료 음성/영상 튜닝에 잘 맞는다. Apple Silicon 로컬 환경에서 돌 수 있고, 오디오 전사·이미지 설명·VQA를 한 저장소 안에서 다루므로 진료 녹취 전사, 의료 문서 화면 인식, 기초 영상 QA 같은 파이프라인의 출발점이 된다. 여기에 patch/blacklist 시스템이 있어, 임상의가 교정한 gold sample을 누적 반영하기 쉽다.

다만 한계도 분명하다. 병원 규모 데이터 운영에서는 텍스트/이미지 모드도 결국 대규모 원격 저장소 스트리밍이 필요해지는데, 현재 v1 제약상 텍스트/이미지는 로컬 CSV 중심이다. 즉, 의료 AI 관점에서는 개인 연구자·소규모 부서용 MVP로는 매력적이지만, 엔터프라이즈급 multimodal data plane까지 이미 완성된 것은 아니다.

2) Bioinformatics 관점

Bioinformatics에 바로 쓰려면 “생물학 고유 구조”를 이해해야 하는 경우가 많다. 이 저장소는 그런 의미의 sequence-native / structure-native trainer는 아니다. FASTA, PDB, graph, 3D molecular geometry를 직접 다루는 전용 inductive bias는 없다.

그 대신 현미경 이미지 캡션, 실험 기록 화면 요약, 랩 노트 전사, 장비 UI 스냅샷→정형 출력처럼, 바이오 연구 현장에서 실제로 많이 생기는 “멀티모달 문서화” 문제에는 상당히 잘 맞는다. 즉, 생물학 자체를 학습시키는 모델이라기보다, 생물학 워크플로 주변의 인간-기계 인터페이스를 보강하는 모델로 보는 편이 정확하다.

3) Autonomous Agent 관점

가장 흥미로운 부분 중 하나는 이미지 모드가 caption + VQA 두 가지를 이미 공식화하고 있다는 점이다. 이것은 곧 스크린샷 → 상태 설명, 스크린샷 + 질문 → 답변, 스크린샷 → 구조화 출력 같은 agentic training data를 만들기 좋은 형태다. README가 “document & screen understanding”를 예시로 드는 이유도 여기에 있다.

하지만 이 저장소는 에이전트 런타임이 아니라 튜닝 인프라다. 툴 사용 계획, memory, self-reflection, planner/executor 분리, benchmark harness 같은 agent framework 요소는 별도 구현이 필요하다. 따라서 Autonomous Agent 개발에서는 “정책 모델을 현장 화면에 맞게 적응시키는 학습 레이어”로 보는 것이 적절하다.

4) 코드 품질/운영 관점에서의 총평

강점은 분명하다.

• 학습 엔트리포인트가 비교적 일관되고,
• Wizard와 CLI가 같은 런타임 경로로 수렴하며,
• collator 분리가 좋아서 modality 확장이 상대적으로 명확하다.
• visualizer가 trainer 훅과 자연스럽게 연결되어 있어 디버깅 피드백 루프가 짧다.

주의할 점도 있다.

• 텍스트/이미지 v1은 아직 로컬 CSV 중심이다.
• 문서 일부에는 구버전 Gemma 3n 중심 서술과 Gemma 4 중심 최신 구현이 혼재한다.
• 즉, 운영 시에는 README와 pyproject.toml, 핵심 Python 모듈을 우선 진실원천(source of truth)으로 보는 편이 안전하다.

Bottom Line

이 저장소는 “Gemma를 Mac에서 돌릴 수 있다” 수준을 넘어서, Apple Silicon 친화적 멀티모달 LoRA 학습 제품에 더 가깝다.
특히 가치가 큰 부분은 다음 세 가지다.

1. 입력 모달리티 확장성 — text / image / audio가 하나의 학습 골격에 모여 있다.
2. 운영 친화성 — wizard, config 계층, run artifact, export 경로가 연결되어 있다.
3. 관찰 가능성(observability) — training visualizer가 초보자와 연구자 모두에게 디버깅 비용을 낮춘다.

완성형 범용 플랫폼이라기보다는, 의료 AI·문서 AI·스크린 이해형 에이전트 데이터를 빠르게 실험하고 로컬에서 적응시키는 데 매우 실용적인 저장소라고 평가할 수 있다.