mattmireles/gemma-tuner-multimodal

Fine-tune Gemma 4 and 3n with audio, images and text on Apple Silicon, using PyTorch and Metal Performance Shaders.

Gemma 다중 모달 미세조정기 (macOS 전용)

무엇을 할 수 있나요 – Apple Silicon (MPS)에서 네이티브로 실행되는 Python 패키지로, Google의 Gemma 언어 모델(3n 및 4시리즈)을 LoRA 어댑터로 텍스트, 이미지, 오디오 데이터에 대해 미세조정할 수 있습니다. NVIDIA GPU가 필요 없으며, CLI 워즈드, 실시간 웹 시각화 도구, Google Cloud Storage 또는 BigQuery에서 대규모 데이터를 스트리밍할 수 있습니다. Core ML 또는 GGUF 추론을 위한 병합된 체크포인트를 내보낼 수 있습니다.

핵심 기능 (README에 기술됨)

기능 세부 사항
모달리티 지원 • 텍스트 전용 (지시어 또는 완성)
• 이미지 + 텍스트 (캡셔닝 또는 VQA)
• 오디오 + 텍스트 (ASR 형식)
하드웨어 PyTorch MPS를 통해 Apple Silicon에서 네이티브 실행; NVIDIA GPU가 있으면 CUDA 지원 가능.
데이터 수집 학습/검증용 CSV 파일만 필수 형식. CSV 행은 로컬 파일, HTTP URL, GCS 경로, BigQuery 테이블을 참조 가능. prepare 명령어는 데이터를 스트리밍하므로 테라바이트 단위의 데이터를 로컬로 복사할 필요 없음.
학습 UI 프로파일에서 visualize = true로 설정하면 브라우저 기반 시각화 도구(손실 곡선, 어텐션 히트맵, 기울기 신호, 메모리 사용량, 토큰 예측)가 자동으로 시작됨.
모델 대상 Hugging Face에서 제공하는 Gemma‑3n(2B 및 4B) 및 Gemma‑4(2B 및 4B) 체크포인트. LoRA 어댑터는 SafeTensors/HF 트리로 병합되어 내보내짐.
내보내기 gemma-macos-tuner export는 Core ML 변환 또는 GGUF 추론용으로 준비된 병합된 모델을 생성.
CLI 워즈드 gemma-macos-tuner wizard로 설정을 안내받아 구성 파일 생성, 모델 선택, 데이터셋 프로파일 선택, 단일 클릭으로 학습 시작.
스트리밍 및 대규모 데이터 prepare는 GCS/BigQuery에서 오디오 샤드를 스트리밍 가능. 동일한 파이프라인은 이미지/오디오 모달리티에도 적용되어 SSD를 가득 채우지 않고 TB급 코퍼스로 학습 가능.
패키지 구조 • gemma_tuner/cli_typer.py – 엔트리포인트 CLI (gemma-macos-tuner).
• gemma_tuner/scripts/finetune.py – Gemma 전용 트레이너로 디스패치.
• gemma_tuner/models/gemma/finetune.py – PEFT LoRA 미세조정 로직.
• gemma_tuner/wizard/ – Rich/Questionary UI를 사용한 워즈드.

일반적인 사용 사례 (README에서)

  • 도메인 특화 음성 인식 – 의료 기록, 법정 녹음, 콜센터 녹음 등에 Gemma + 오디오 LoRA를 적응.
  • 특수한 비전 작업 – 영수증, 차트, 제조 결함, 의료 이미지 등에 대해 캡셔닝 또는 VQA용으로 미세조정.
  • 문서 및 UI 이해 – 스크린샷 → 구조화 출력 쌍으로 온디바이스 어시스턴트용 학습.
  • 저자원 언어 또는 억양 적응 – 대표되지 않은 방언의 음성 인식 또는 번역 개선.
  • 개인 정보 보호 온디바이스 파이프라인 – 모든 학습 및 추론은 Mac에서 수행; 데이터는 기기 외부로 이동하지 않음.

시작하기 (README 요약)

  1. arm64 네이티브 Python 3.10+ venv 생성 (Homebrew python@3.12 사용 가능).
  2. PyTorch 설치 (pip install torch torchaudio).
  3. 패키지 설치 (pip install -e .).
  4. Hugging Face에 로그인하고 Gemma 모델 라이선스 수락.
  5. (옵션) Gemma‑4 확장 설치 (pip install -r requirements/requirements-gemma4.txt).
  6. 워즈드 실행 – gemma-macos-tuner wizard. config/config.ini 생성 후 모델, 데이터셋, 하이퍼파라미터 선택 안내.
  7. 학습 – 워즈드 또는 직접 실행: gemma-macos-tuner finetune <profile>. --json-logging로 기계가 읽을 수 있는 로그 사용 가능.
  8. 내보내기 – gemma-macos-tuner export <run‑dir-or‑profile>로 Core ML 또는 GGUF용으로 준비된 병합 체크포인트 생성.

제한 사항 및 알려진 문제 (문서 참조)

  • 이미지 및 오디오 스트리밍 – 현재 오디오 파이프라인만 GCS/BigQuery 스트리밍 지원. 이미지 미세조정은 여전히 로컬 CSV 파일 필요.
  • Gemma 4 대규모 체크포인트 (26B/31B)는 트레이너의 AutoModelForCausalLM 오디오 경로가 다른 아키텍처를 기대하기 때문에 지원되지 않음.
  • 오디오 전용 LoRA는 Apple Silicon에서 작동 가능. CUDA 전용 경로는 "⚠️" 표시되며 NVIDIA GPU 필요.
  • 메모리 – 최소 16GB RAM; 4B 모델은 32GB 이상 권장. OOM은 더 작은 배치 크기 또는 그래디언트 체크포인팅으로 완화 가능.
  • MPS 안정성 – 트레이너는 에이지 어텐션을 강제하고 bf16을 우선. 디버깅용 CPU 백업(PYTORCH_ENABLE_MPS_FALLBACK=1)은 느리게 동작.
  • Gemma 4 내보내기 – 일부 추론 유틸리티는 코드 경로 업그레이드 전까지 Gemma 4 ID를 거부함.

빠른 참조 요약 (README에서)

# 데이터 준비 (CSV → 선택적 스트리밍)
 gemma-macos-tuner prepare <dataset‑profile>

# 학습
 gemma-macos-tuner finetune <profile> --json-logging

# 평가
 gemma-macos-tuner evaluate <profile-or‑run>

# 병합된 체크포인트 내보내기
 gemma-macos-tuner export <run‑dir-or‑profile>

# 워즈드 UI 시작
 gemma-macos-tuner wizard

결론 – Gemma‑tuner‑multimodal은 Apple Silicon을 최우선으로 설계된 목적 지향 트레이너로, Gemma 패밀리에 LoRA 기반의 다중 모달 미세조정(텍스트, 이미지, 오디오)을 추가하며, 친근한 CLI 워즈드와 실시간 시각화를 제공하면서도, 클라우드에 저장된 대규모 데이터셋을 Mac에 직접 스트리밍할 수 있습니다.

관련

  • Dispatch
    Gemma 4 출시: 온디바이스 지원을 갖춘 오픈 소스 멀티모달 모델

    Google DeepMind의 새로운 오픈 소스 멀티모달 제품군인 Gemma 4가 이미지, 오디오, 비디오 지원, 최대 256K 컨텍스트, 그리고 transformers, llama.cpp, MLX, Rust, WebGPU와의 day-0 호환성을 갖추고 Hugging Face에 출시되었습니다.

  • Dispatch
    Hugging Face에서 Gemma 모델 파인튜닝

    Hugging Face는 Parameter-Efficient Fine-Tuning(PEFT)과 Low-Rank Adaptation(LoRA)을 활용해 Google의 Gemma 모델을 GPU와 Cloud TPU에서 맞춤화하는 가이드를 제공합니다.

  • Dispatch
    Google Gemma 오픈 LLM 릴리스

    Google은 Gemini를 기반으로 하는 오픈 액세스 대형 언어 모델 패밀리인 Gemma를 출시했으며, 2B 및 7B 파라미터 크기의 기본 및 인스트럭션 튜닝 변형을 제공합니다.

  • 프로젝트
    avifenesh/memra

    *memra*는 RTX PRO 6000 및 RTX 5090 GPU에 맞게 조정된 Rust + CUDA 추론 엔진입니다. Hugging Face safetensors 또는 GGUF 체크포인트를 로드하고, OpenAI 호환 HTTP API를 통해 이를 서비스하며, 접두사 캐시 재사용, MTP 추측 디코딩 및 이미지/비디오 입력과 같은 기능을 제공합니다. 이 프로젝트는 사전 빌드된 바이너리를 제공하고 빠른 시작 스크립트를 제공하며 측정된 성능(예: PRO 6000에서 140 tok/s 디코딩, 0.156 s TTFT)을 보고합니다. 엄선된 모델 목록(Qwen, Gemma-4, Ornith 등)을 지원하며 매우 큰 모델을 두 개의 GPU(PP-2)에 분할할 수 있습니다. 단일 GPU 또는 2-GPU 워크스테이션을 위해 설계되었으며, 다중 노드 텐서 병렬 처리를 목표로 하지 않습니다.

  • Dispatch
    macOS에서 Gemma 4와 llama.cpp를 사용하여 로컬 코딩 에이전트 설정하기

    llama.cpp, Gemma 4 26B, 그리고 Pi 에이전트 하네스를 사용하여 macOS에서 로컬 코딩 에이전트를 배포하는 방법을 배우십시오. Multi-Token Prediction (MTP)를 통해 최대 72.2 tokens per second를 달성할 수 있습니다.