drumih/turbo-fieldfare

TurboFieldfare – Apple Silicon에서 Gemma 4 26B의 온디바이스 추론

무엇인가요

260억 파라미터의 Gemma 4 26B-A4B 지시 튜닝 모델을 모든 Apple-silicon Mac에서 실행할 수 있는 Swift + Metal 런타임. 8GB RAM만 있는 기기에서도 작동 가능.
전체 14GB 체크포인트를 메모리에 로드하지 않습니다. 대신 1.35GB의 공유 코어와 FP16 KV 캐시를 유지하고, 필요한 MoE "전문가" 가중치를 SSD에서 실시간으로 스트리밍합니다.
프로젝트는 커스텀 Metal 커널 기반으로, 네이티브 macOS 앱, CLI, Swift 라이브러리, 루프백형 OpenAI 호환 서버를 제공합니다.

왜 중요한가요

대규모 언어 모델은 일반적으로 수십 GB의 RAM이 필요하지만, TurboFieldfare는 추론을 약 2GB로 압축하여 M2 MacBook Air의 기본 사양에서도 26B 규모 모델을 사용 가능하게 합니다.
제한된 메모리 장치에서 다른 mixture-of-experts (MoE) 모델에 재사용 가능한 실용적인 "전문가 캐시 스트리밍" 기술을 보여줍니다.

주요 구성 요소

구성 요소	역할
`TurboFieldfare` (Swift 라이브러리)	양자화 GEMV, 어텐션, MoE 라우팅, 샘플링 등에 대한 핵심 런타임 + Metal 커널
`TurboFieldfareMac`	Hugging Face에서 모델을 다운로드, 재패키징, 로드하고 채팅할 수 있는 SwiftUI/AppKit GUI
`TurboFieldfareCLI`	동일한 `.gturbo` 모델 디렉터리와 호환되는 명령줄 채팅/완성 도구
`TurboFieldfareServer`	로컬 OpenAI 호환 HTTP 서버(루프백 전용), 채팅, 스트리밍, 함수 도구 호출 지원
`TurboFieldfareRepack`	Hugging Face에서 필요한 바이트 범위만 가져와 커스텀 `.gturbo` 레이아웃에 직접 쓰고 설치를 검증하는 스트리밍 설치기
`TurboFieldfareDecodeService`	GUI의 Metal 컨텍스트를 소유하는 작은 헬퍼 프로세스

시작 방법

클론 & 빌드

git clone https://github.com/drumih/turbo-fieldfare.git
cd turbo-fieldfare
swift build -c release   # 앱 + 디코딩 서비스 빌드
.build/release/TurboFieldfareMac

모델 다운로드 – 앱(또는 TurboFieldfareRepack)이 고정된 Hugging Face 체크포인트에서 약 15GB를 스트리밍하여 .gturbo 디렉터리(scratch/gemma4.gturbo)를 생성합니다.
로드 & 생성 – "모델 로드"를 누르고 프롬프트를 입력한 후 "생성"을 누르세요 (또는 TurboFieldfareCLI로 CLI 사용).
옵션 비전 지원 – --vision-output를 사용해 TurboFieldfareRepack를 실행하면 약 1.1GB의 이미지 타워 팩이 추가됩니다. 앱/CLI는 --image <file> 인수를 수락합니다.

지원되는 하드웨어 및 소프트웨어

Apple-silicon Macs (ARM64) – 8GB M2 MacBook Air에서 테스트 완료. M5, M4 등에서도 작동.
macOS 26 + Metal 4 (Xcode 26, Swift 6.2 이상).
모델용 약 15GB의 여유 스토리지와 추론 시 약 2GB의 RAM 필요.

성능 스냅샷 (리포지토리의 벤치마크 표에서)

M2 (8GB): 5.1 – 6.3 토큰/초 디코딩.
M5 (24GB): 31 – 35 토큰/초 디코딩. 커뮤니티 멤버는 제공된 벤치마크 가이드를 통해 자신의 수치를 제출할 수 있습니다.

사용 세부 정보

프롬프팅 – 기본값: temperature 0.2, top-k 64, top-p 0.95. 결정론적 출력을 원하면 --temperature 0 사용.
KV 캐시 – FP16, 슬라이딩 윈도우 레이어용 4K 토큰 윈도우, 전체 어텐션 레이어는 선형 저장 사용.
이미지 입력 – 비전 팩이 설치된 경우, CLI에서는 --image <file>로 단일 이미지를 전송하거나 GUI에서 첨부 가능. 다중 라운드 이미지 채팅은 JSON 메시지 파일로 지원.
OpenAI 서버 – http://127.0.0.1:8080/v1에서 실행. 채팅 완성, 스트리밍, 함수 도구 호출 지원 (클라이언트가 도구 실행을 승인해야 함).

개발 및 기여

Scripts/test.sh로 테스트 스위트 실행.
"커뮤니티 벤치마크 가이드"를 따르며 성능 결과 추가.
프로젝트는 Apache 2.0 라이선스. 모델 가중치는 별도 다운로드되며 원래 Hugging Face 이용 약관에 따라 유지.

현재 범위 및 향후 계획

범위 내: Apple-silicon Mac에서 텍스트 생성(Gemma 4 26B-A4B) 및 선택적 비전 타워.
범위 외: 오디오/비디오 모달리티, 원격 서버 배포, 비 Apple 하드웨어.
향후 작업: iPhone/iPad 앱, 더 많은 Apple-silicon 장치에서의 광범위한 벤치마크.

TL;DR: TurboFieldfare는 SSD에서 MoE 전문가를 스트리밍함으로써 저메모리 Apple-silicon Mac에서 26B 파라미터 Gemma 4 모델을 실행 가능한 Swift/Metal 기반 추론 엔진입니다. GUI, CLI, 로컬 OpenAI 호환 서버를 제공하며 Apache 2.0 라이선스 하에 공개됩니다.

drumih/turbo-fieldfare

TurboFieldfare – Apple Silicon에서 Gemma 4 26B의 온디바이스 추론

관련