Gemma MLX Studio

Gemma MLX Studio는 macOS Apple Silicon 환경에서 FastAPI + Gradio + MLX-LM/MLX-LM-LoRA 조합으로 로컬 학습 실험을 반복하기 위한 작은 워크벤치입니다.
목표는 한 프로젝트 폴더 안에서 데이터 업로드, JSONL 검증, train/valid/test 분할, YAML 설정 Save As, 학습 실행, 로그 확인, adapter 추론 테스트까지 한 번에 돌리는 것입니다.

UI Preview

Help 탭의 빠른 시작 체크리스트 예시입니다.

GitHub / Hugging Face 연결

이 프로젝트는 코드 저장소와 모델 배포 저장소를 분리해서 운영합니다.

• GitHub 코드 저장소: Dalsontimes/Gemma-MLX-Studio
• Hugging Face 모델 저장소: sangwon1472/Gemma-MLX-Studio

역할 구분:

• GitHub에는 앱 코드, Help 문서, 설정 파일, 스크린샷, 사용법 문서를 올립니다.
• Hugging Face에는 대용량 모델 파일과 GGUF 배포본을 올립니다.

즉, 이 저장소는 "워크벤치와 문서", Hugging Face 저장소는 "실제 배포 모델"이라고 보면 됩니다.

공개 모델 파일

현재 공개된 모델 파일:

• best_4b_v2_stronger-Q4_K_M.gguf
• best_4b_v2_stronger-f16.gguf

권장 사용:

• Q4_K_M: LM Studio, llama.cpp 계열에서 바로 쓰는 실사용용
• F16: 보관용, 재양자화용, 변환 기준 파일

직접 링크:

• Q4_K_M GGUF
• F16 GGUF
• Model Card / README

어떤 저장소를 보면 되는가

• 앱 설치, 실행, Help 문서, UI 변경 내역을 보려면 GitHub 저장소를 봅니다.
• 실제 GGUF 파일을 받거나 LM Studio에서 쓸 모델을 찾으려면 Hugging Face 저장소를 봅니다.
• 모델 개선 과정은 GitHub 코드 변경과 Hugging Face 모델 파일 갱신이 함께 가는 구조입니다.

대상 환경

• macOS Apple Silicon
• 권장 하드웨어: MacBook Air/Pro M2 16GB
• 기본 학습 엔진: mlx_lm_lora.train
• 기본 추론 엔진: mlx_lm.generate

핵심 기능

• FastAPI API와 /docs 제공
• Gradio UI를 /ui에 마운트
• raw JSONL 업로드 및 messages 구조 검증
• data/prepared/<dataset_name>/ 기준의 split 저장
• YAML 설정 목록 조회, 값 편집, Save As 저장
• 단일 학습 실행 잠금과 logs/current_run.json 상태 복구
• 로그 tail 조회와 마지막 실행 상태 확인
• adapter 선택 후 base model + prompt 기반 추론 테스트
• 최근 프롬프트 10개 저장

프로젝트 구조

gemma_mlx_studio/
├── app/
│   ├── main.py
│   ├── routes/
│   ├── schemas/
│   ├── services/
│   └── ui_gradio.py
├── adapters/
├── configs/
├── data/
│   ├── raw/
│   ├── uploads/
│   └── prepared/
├── logs/
├── outputs/
└── scripts/

Quick Start

처음 실행할 때는 아래 순서만 따라가면 됩니다.

1. gemma_mlx_studio 폴더로 이동합니다.
2. 가상환경을 만들고 의존성을 설치합니다.
3. uvicorn app.main:app --reload --port 9001로 앱을 실행합니다.
4. 브라우저에서 /ui를 열어 Datasets -> Configs -> Train -> Logs -> Inference 순서로 진행합니다.

빠른 실행 예시:

cd gemma_mlx_studio
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt
pip install -U mlx-lm mlx-lm-lora
uvicorn app.main:app --reload --port 9001

브라우저 주소:

• UI: http://127.0.0.1:9001/ui
• API docs: http://127.0.0.1:9001/docs

설치 방법

프로젝트 루트로 이동한 뒤 가상환경을 준비합니다.

cd gemma_mlx_studio
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

학습까지 실제로 사용하려면 MLX 계열 패키지를 추가 설치해야 합니다.

pip install -U mlx-lm mlx-lm-lora

설치 확인 예시:

command -v mlx_lm.generate
command -v mlx_lm_lora.train

실행 방법

uvicorn app.main:app --reload --port 9000

브라우저 주소:

• API 문서: http://127.0.0.1:9000/docs
• UI: http://127.0.0.1:9000/ui

만약 9000 포트가 이미 사용 중이면 다른 포트를 지정해도 됩니다.

uvicorn app.main:app --reload --port 9001

데이터 준비 방법

기본 입력 형식은 JSONL이며, 각 줄은 아래처럼 messages 배열을 가져야 합니다.

{
  "messages": [
    {"role": "system", "content": "당신은 세계관 도우미다."},
    {"role": "user", "content": "First Fire Horizon을 소개해줘."},
    {"role": "assistant", "content": "First Fire Horizon은 잿빛 평원 끝자락의 붉은 방벽 도시다."}
  ]
}

지원 규칙:

• 각 줄은 유효한 JSON 객체여야 함
• messages 필드는 비어 있지 않은 list여야 함
• 각 message는 role, content를 가져야 함
• role은 system, user, assistant 중 하나여야 함
• content는 문자열이거나 문자열로 안전하게 변환 가능한 JSON 구조여야 함

UI 사용 순서:

1. Datasets 탭에서 JSONL 파일을 업로드하거나 로컬 경로를 입력합니다.
2. Validate Dataset으로 오류 수와 예시를 확인합니다.
3. Preview Samples로 샘플 10개를 확인합니다.
4. Split Dataset으로 train/valid/test를 생성합니다.

split 결과는 아래에 저장됩니다.

data/prepared/<dataset_name>/
├── train.jsonl
├── valid.jsonl
├── test.jsonl
└── manifest.json

예시 결과 형식은 outputs/examples/dataset_validation_example.json에서 볼 수 있습니다.

설정 관리 방법

Configs 탭에서 다음 작업을 할 수 있습니다.

• configs/ 폴더의 YAML 목록 읽기
• 선택한 YAML의 원문 확인
• 주요 필드 편집
  • model
  • batch-size
  • gradient-accumulation-steps
  • learning-rate
  • num-layers
  • iters
  • max-seq-length
  • adapter-path
  • data
• 유효성 검사
• 원본 덮어쓰기 없이 Save As 저장

기본 추천 프리셋:

• configs/m2_safe_minimal.yaml
• configs/m2_balanced.yaml
• configs/longer_context_experimental.yaml

주의:

• data 경로는 보통 data/prepared/<dataset_name>를 가리키도록 수정해야 합니다.
• adapter-path는 아직 없는 경로여도 괜찮지만, 부모 디렉터리는 존재해야 합니다.

학습 시작 방법

1. Datasets 탭에서 split을 먼저 완료합니다.
2. Configs 탭에서 data를 방금 만든 prepared dataset 폴더로 맞춥니다.
3. Train 탭에서 config를 선택합니다.
4. Start Training을 누릅니다.

실제 학습 명령은 아래 형식으로 실행됩니다.

mlx_lm_lora.train --config <yaml>

학습 상태 파일:

• logs/current_run.json

학습 로그 파일:

• logs/train_<timestamp>.log

상태는 다음 값으로 관리됩니다.

• idle
• running
• finished
• failed

중복 실행 방지:

• 이미 실행 중이면 두 번째 학습은 시작되지 않습니다.

로그 확인 방법

Logs 탭에서 아래 정보를 확인할 수 있습니다.

• 현재 상태
• 최근 실행 정보
• 로그 tail

로그 예시 형식은 outputs/examples/train_log_example.txt를 참고하면 됩니다.

추론 테스트 방법

Inference 탭에서 다음 순서로 확인합니다.

1. Known base models에서 모델을 선택하거나 직접 입력합니다.
2. Adapter run에서 저장된 adapter를 고릅니다.
3. System prompt와 User prompt를 입력합니다.
4. Run Inference를 누릅니다.

최근 프롬프트 10개는 outputs/prompt_history.json에 저장됩니다.

샘플 프롬프트 모음은 outputs/sample_prompts.json에 있습니다.

탭별 권장 사용 흐름

1. Overview에서 환경과 설치 상태를 확인합니다.
2. Datasets에서 업로드, 검증, split을 수행합니다.
3. Configs에서 YAML을 불러와 Save As로 실험용 설정을 만듭니다.
4. Train에서 학습을 시작하거나 중지합니다.
5. Logs에서 진행 상황과 에러를 봅니다.
6. Inference에서 adapter 결과를 테스트합니다.

API 엔드포인트 개요

• GET /overview
• GET /configs
• GET /configs/load
• POST /configs/save-as
• GET /datasets/validate
• GET /datasets/preview
• POST /datasets/split
• POST /train/start
• POST /train/stop
• GET /train/status
• GET /train/logs
• GET /inference/models
• GET /inference/adapters
• GET /inference/history
• POST /inference/generate

보조 스크립트

• python scripts/prepare_dataset.py
• python scripts/start_train.py
• python scripts/test_generate.py

자주 나는 오류와 해결법

mlx_lm_lora.train is not available

원인:

• mlx-lm-lora가 현재 앱과 같은 Python 환경에 설치되지 않음

해결:

pip install -U mlx-lm-lora
command -v mlx_lm_lora.train

모델 다운로드 실패

원인:

• 모델 이름 오타
• Hugging Face 접근 문제
• 네트워크 문제

해결:

• YAML의 model 값을 다시 확인합니다.
• 직접 mlx_lm.generate --model <model_name> --prompt "hello"로 먼저 테스트합니다.

메모리 부족

원인:

• max-seq-length, num-layers, gradient accumulation 설정이 현재 장비보다 큼

해결:

• configs/m2_safe_minimal.yaml부터 시작합니다.
• max-seq-length를 낮추고 num-layers를 줄입니다.
• 다른 메모리 사용 앱을 종료합니다.

YAML 경로 오류

원인:

• data 또는 adapter-path 경로가 잘못되었음

해결:

• Configs 탭의 Validate Config 결과를 확인합니다.
• data는 data/prepared/<dataset_name>를 가리키게 맞춥니다.

adapter path 없음

원인:

• 아직 학습이 끝나지 않았거나 잘못된 adapter 폴더를 선택함

해결:

• Logs 탭에서 학습 완료 여부를 먼저 확인합니다.
• adapters/ 아래 실제 생성된 폴더를 다시 선택합니다.

현재 구현 메모

• 앱은 logs/current_run.json을 기준으로 마지막 상태를 복구합니다.
• app 재시작 이후에도 마지막 실행 정보와 로그 파일 경로를 다시 읽을 수 있습니다.
• 학습 명령이 설치되지 않은 환경에서는 UI와 API가 명확한 오류 메시지를 반환합니다.