LLM Wiki

TurboFieldfare — Apple Silicon에서 Gemma 4 26B-A4B를 약 2GB RAM으로 추론

Properties2
descriptionApple Silicon Mac에서 Gemma 4 26B-A4B를 약 2GB RAM으로 실행하는 Swift·Metal 네이티브 추론 런타임이다.
tagsai-models, dev-tools, llm, local-ai, apple-silicon, metal, swift, moe, inference

10 min read

개요

TurboFieldfare는 Apple Silicon Mac에서 Google의 Gemma 4 26B-A4B instruction-tuned 모델을 낮은 메모리 예산으로 실행하기 위해 Swift와 Metal로 직접 구현한 모델 특화 추론 런타임이다. 약 14.3GB인 텍스트 전용 .gturbo 설치물을 통째로 메모리에 올리지 않고, 공용 가중치·KV 캐시를 상주시킨 뒤 현재 토큰에 필요한 routed expert만 SSD에서 읽는다. 따라서 8GB M2 MacBook Air에서도 실행 가능한 메모리 footprint를 목표로 한다.

이 프로젝트의 핵심은 “대형 모델을 범용 런타임에 얹는다”가 아니라, Gemma 4 26B-A4B의 MoE 구조와 Apple Silicon Metal 실행 모델에 맞춰 저장 포맷·리패커·전문가 캐시·커널·앱·CLI·서버를 함께 설계한 점이다.

현재 저장소 스냅샷

  • 최신 확인 커밋: 3a853bd0f9db891c062f9d4940ba54a7fd3cf091
  • GitHub API 기준: 4,909 stars · 244 forks · 43 open issues · Apache-2.0
  • 기본 브랜치: main; 마지막 push: 2026-08-04 22:56 UTC
  • README byte SHA-256: 343257a6a489bf579465446cb77fbabf41b94e9617e42b8ee0841f5be678594e
  • Raw 위키 body SHA-256: 85a09a81c6f80fad023efeff50ac081a52270601ce734c9711c0bc2cf1ac7e3b
  • 전체 저장소 트리: 489개 항목으로 확인

핵심 구조

Swift Package와 실행 표면

Package.swift는 Swift tools 6.2, macOS/iOS 26 플랫폼과 swift-transformers, swift-nio 의존성을 선언한다. 공개 제품은 다음 여섯 가지다.

제품역할
TurboFieldfareSwift 런타임과 Metal 커널을 담은 라이브러리
TurboFieldfareMac모델 설치·로드·생성을 위한 네이티브 Mac 앱
TurboFieldfareDecodeServiceMac 앱이 모델과 Metal 자원을 소유하도록 분리한 일회성 decode 서비스
TurboFieldfareCLIinstruction chat와 raw completion을 제공하는 CLI
TurboFieldfareServerloopback OpenAI-compatible Chat Completions 서버
TurboFieldfareRepack스트리밍 모델 설치·재개·검증 도구

README의 검증 대상은 Apple Silicon, macOS 26, Metal 4, Xcode 26/Swift 6.2 이상이며, 현재 공개된 실행 범위는 pinned Gemma 4 26B-A4B 텍스트 추론이다. Package.swift에 iOS 플랫폼 선언은 있지만 README의 iPhone/iPad는 future work로 남아 있어, iOS 지원이 완성됐다고 해석하면 안 된다.

메모리·전문가 스트리밍

  • Gemma 4의 30개 transformer layer 중 25개는 sliding-window attention, 5개는 full attention이다.
  • 각 layer에는 128개 routed expert가 있고 토큰마다 top-8이 선택된다. 별도의 dense shared expert branch도 함께 계산한다.
  • 공용 model_weights.bin은 약 1.35GB이며, FP16 KV cache는 4K 기준 약 305MiB다.
  • 각 layer의 expert streamer는 기본 16개 슬롯을 가지며, LFU를 기본 정책으로 사용하고 recency를 tie-breaker로 삼는다. 슬롯은 2MiB 정렬된 Metal buffer로 한 번 할당한 뒤 pread로 채운다.
  • RealForwardRunner는 router가 고른 expert를 캐시 hit/miss로 나누고, miss를 bounded parallel read로 채우는 동안 shared branch와 Metal 연산을 겹친다.
  • prefill은 최대 128-token chunk를 사용해 한 번 읽은 expert를 여러 prompt row에 재사용하며, decode는 한 토큰씩 routed layer loop를 반복한다.
  • K/V cache는 full-attention layer에서 원시 projection을 공유하더라도 정규화·RoPE 경로가 달라지므로 별도 버퍼를 유지한다. sliding-window layer는 선택적으로 FP16 ring storage를 사용한다.

설치와 무결성

TurboFieldfareRepack은 Hugging Face의 pinned revision 0d77464eeb233a2da68ebf9d7dc4edaac7db956d와 source-index SHA-256 bf198c9f5ea6462addca1966e5dd669c407537a876e82cf06db9084c5c850b13을 기준으로 동작하도록 문서화돼 있다.

  • 전체 checkpoint나 safetensors shard를 먼저 디스크에 저장하지 않고 bounded HTTP range를 요청한다.
  • tile-sized scratch를 통해 값을 최종 .gturbo 위치로 직접 복사하며, 문서에 기록된 검증 설치의 최대 payload/scratch는 각각 524,288 bytes다.
  • 중단 시 partial directory와 checkpoint를 보존하고 --resume에서 완료 range의 destination digest를 재검증한다.
  • manifest.json과 verified-install.json을 작성·검증한 뒤 atomic promotion한다.
  • .gturbo 설치물은 약 14.3GB, 최초 전송량은 약 15GB이며, vision tensor는 제외된다.

이 설계는 모델 실행뿐 아니라 설치 과정에서도 “전체 모델을 한 번에 메모리나 임시 디스크에 올리지 않는다”는 불변식을 유지하려는 것이다.

제공 인터페이스

Mac 앱과 CLI

Mac 앱은 설치 상태, 모델 로드, prompt composer, 생성 중지, sampling/context/expert-cache/runtime 설정과 HUD 형태의 속도·메모리 지표를 제공한다. CLI는 기존 .gturbo 설치물을 사용해 instruction chat 또는 --prompt raw completion을 실행하며, --max-new, --max-context, --temperature, --top-k, --top-p, --repetition-penalty, --seed, --stop 등을 노출한다.

Loopback OpenAI-compatible server

TurboFieldfareServer는 127.0.0.1에만 바인딩하는 단일 모델 서버다.

  • GET /health
  • GET /v1/models
  • POST /v1/chat/completions
  • JSON/SSE streaming, system/developer/user/assistant/tool message, function-tool call 반환을 지원
  • prompt prefix 하나를 검증해 재사용하는 KV cache를 기본 활성화
  • tool call을 반환할 뿐 승인·실행은 클라이언트가 담당
  • 원격 인증과 TLS가 없으므로 proxy/tunnel을 통해 외부에 노출하면 안 됨
  • Responses API, legacy Completions, embeddings, multimodal input, structured output, batching, log probabilities, remote model switching은 지원하지 않음

서버는 한 번에 하나의 warm model을 소유하고 generation을 직렬화한다. OpenAI 호환이라는 표현은 지원 API subset을 뜻하며, 범용 OpenAI 서버와 동일한 기능 집합은 아니다.

측정 결과와 트레이드오프

다음 수치는 저장소의 docs/BENCHMARKS.md에 기록된 upstream 측정값이다. 이번 ingest에서 Swift build, 모델 설치, 실제 추론 또는 benchmark 재현은 수행하지 않았다.

환경·런타임Decode보고된 메모리
8GB M2 MacBook Air · TurboFieldfare5.10–6.30 tok/s약 1.9–2.1GB footprint
24GB M5 Pro · TurboFieldfare31–35 tok/s약 2.1GB footprint
24GB M5 Pro · mlx-lm76.33–82.07 tok/s8.3–9.8GB RSS; 14.7–15.3GB GPU allocation

MLX 비교는 별도 실행 블록이고 TTFT·메모리 카운터의 측정 정의가 다르므로 단순한 “메모리 몇 배 절감”으로 읽으면 안 된다. TurboFieldfare의 성과는 최고 throughput보다, 일반적인 방식으로는 실행이 어려운 8GB 기기에서 모델을 실행 가능하게 만든 메모리/속도 trade-off에 있다.

범위와 한계

  • 현재 대상은 pinned Gemma 4 26B-A4B instruction checkpoint 하나이며 텍스트 입력만 지원한다.
  • Gemma 4 원본의 vision tower는 포함하지 않아 이미지·오디오·비디오 입력은 지원하지 않는다.
  • training, fine-tuning, 일반 모델 지원, remote serving, server batching은 범위 밖이다.
  • Mac 앱은 4K/8K/16K/32K/64K context 선택지를 제공하지만 공개 acceptance evidence는 4K까지다.
  • 8GB 검증 호스트에서는 TurboFieldfare 앱·decode service·CLI·server·test·다른 local-model process를 동시에 실행하지 않는 운영 규칙을 둔다.
  • RDADVISE는 실험적이고 기본값이 꺼져 있다. 최적화 여정에는 성공한 변경뿐 아니라 되돌린 실험과 측정상의 함정도 기록돼 있다.

의미

TurboFieldfare는 MoE의 선택적 expert 활성화를 SSD streaming과 결합해 “모델 전체를 메모리에 상주시키지 않아도 실행 가능한가?”를 모델 특화 런타임 수준에서 탐구한 사례다. 메모리 예산을 약 2GB로 제한하는 대신 expert I/O와 cache locality를 throughput의 비용으로 지불한다. 따라서 충분한 메모리와 높은 처리량이 우선이면 MLX 같은 범용 구현이 더 적합할 수 있고, 8GB Apple Silicon에서 해당 모델을 실행하는 것이 우선이면 TurboFieldfare의 접근이 의미 있다.

또한 103개 audited experiment record, system design, implementation references, community benchmark protocol을 함께 공개해 결과 숫자만이 아니라 커널·prefill·decode·I/O·캐시 설계가 어떻게 검증되고 수정됐는지를 따라갈 수 있다.

근거 자료

관련 위키

백링크