TurboFieldfare 소개
로컬에서 큰 모델을 돌리려면 메모리가 먼저 걸립니다. Gemma 4 26B-A4B의 4비트 양자화 체크포인트는 설치 용량이 약 14.3GB인데, 통합 메모리 8GB짜리 맥북 에어에는 애초에 올라가지 않습니다. 전문가 혼합(Mixture of Experts) 구조라 토큰 하나에 실제로 쓰이는 파라미터는 약 38.8억 개뿐이지만, 어느 전문가가 필요한지는 계산해 봐야 알 수 있으니 보통은 전부 메모리에 올려 둡니다.
TurboFieldfare는 이 전제를 뒤집은 Swift·Metal 추론 런타임입니다. 공유되는 1.35GB 코어와 FP16 KV 캐시만 메모리에 두고, 나머지 전문가 가중치는 SSD에 남겨 둔 뒤 각 토큰에 필요한 것만 그때그때 읽어 옵니다. 이 방식으로 8GB 맥에서도 260억 파라미터 모델이 돌아가고, 실제 측정된 메모리 사용량은 약 2GB 수준입니다. iOS·Metal 엔지니어인 Andrey Mikhaylov가 개인 프로젝트로 만들었으며, Google과는 무관한 독립 연구 프로젝트라고 밝히고 있습니다.
MLX나 llama.cpp를 감싼 래퍼가 아니라 특정 모델 하나를 겨냥해 직접 작성한 런타임이라는 점이 이 프로젝트의 성격을 결정합니다. 커널부터 캐싱, 입출력, 프리필, 디코드까지 직접 구현했고, 그 과정에서 측정한 103건의 실험 결과를 실험 기록으로 함께 공개했습니다. 성공한 최적화만 남기지 않고 그럴듯했지만 실패한 시도, 더 엄격한 검증에서 뒤집힌 초기 결과까지 별도 문서에 정리해 둔 점이 눈에 띕니다.
기존 로컬 추론 방식과 TurboFieldfare의 비교
메모리를 아끼는 선택에는 대가가 따릅니다. 저자는 같은 24GB M5 Pro에서 같은 체크포인트와 같은 프롬프트 토큰으로 mlx-lm과 자신의 런타임을 나란히 측정해 그 대가를 그대로 공개했습니다.
| 호스트와 런타임 | 디코드 속도 | 보고된 메모리 |
|---|---|---|
| 8GB M2, TurboFieldfare | 5.10~6.30 tok/s | 약 1.9~2.1GB 사용량 |
| 24GB M5 Pro, TurboFieldfare | 31~35 tok/s | 약 2.1GB 사용량 |
| 24GB M5 Pro, mlx-lm | 76.33~82.07 tok/s | RSS 8.3~9.8GB, GPU 할당 14.7~15.3GB |
같은 하드웨어에서 mlx-lm이 두 배 이상 빠릅니다. 가중치를 전부 메모리에 올려 두면 매 토큰마다 SSD를 읽을 일이 없으니 당연한 결과입니다. TurboFieldfare가 얻는 것은 속도가 아니라 실행 가능성 입니다. mlx-lm 쪽 수치인 GPU 할당 14.7~15.3GB는 8GB 기기에서 애초에 성립하지 않는 조건이고, TurboFieldfare의 8GB M2 행은 그 기기에서 실제로 돌아간 기록입니다.
수치는 모두 저자가 자신의 두 대의 맥에서 측정한 것이며, 프롬프트 길이와 생성 길이, 페이지 캐시 상태에 따라 달라진다는 단서를 문서에 함께 달아 두었습니다. 저자는 이를 성능 한계가 아닌 참고점이라고 표현합니다. 다른 기기의 결과를 모으는 커뮤니티 벤치마크 안내도 함께 제공됩니다.
TurboFieldfare는 누구에게 유용한가
메모리가 8GB나 16GB인 애플 실리콘 맥을 쓰면서 큰 모델을 로컬에서 시험해 보고 싶은 경우, 그리고 온디바이스 추론 런타임의 내부 구현을 읽고 배우려는 경우에 값이 있습니다. 앞의 경우에는 다른 선택지가 마땅치 않고, 뒤의 경우에는 Metal 커널과 전문가 스트리밍, 실패한 실험 기록까지 공개된 저장소가 흔하지 않습니다.
반대로 처리량이 중요한 작업이나 여러 모델을 바꿔 가며 쓰는 환경에는 맞지 않습니다. 지원 대상이 고정된 Gemma 4 26B-A4B 명령 튜닝 체크포인트 하나이고, macOS 26과 Metal 4, Swift 6.2 이상을 요구하며 arm64 전용입니다. 텍스트만 지원하므로 이미지·오디오·비디오 입력은 쓸 수 없고, 메모리가 넉넉한 기기에서 속도가 우선이라면 위 비교표대로 MLX 계열이 더 나은 선택입니다.
TurboFieldfare의 전문가 스트리밍 구조
Gemma 4의 구조가 이 런타임의 모양을 결정했습니다. 모델은 30개 트랜스포머 레이어로 이뤄지고, 그중 25개는 슬라이딩 윈도우 어텐션, 5개는 전체 어텐션 레이어입니다. 레이어마다 128개의 라우팅 전문가가 있고 라우터는 토큰마다 그중 8개를 고릅니다. 여기에 라우팅 가중치 없이 더해지는 공유 전문가 분기가 별도로 붙습니다.
한 레이어의 처리는 세 국면으로 나뉩니다. 첫 국면인 cb1 에서 Metal이 입력 정규화와 Q/K/V 프로젝션, RoPE와 KV 기록, 어텐션, 출력 프로젝션, 그리고 라우터까지 상주 가중치로 계산합니다. 라우터가 상위 8개 전문가 번호를 내놓으면 CPU가 그 값을 읽어야 어떤 파일을 열지 알 수 있고, 여기서 CPU와 입출력 사이의 인계가 발생합니다.
두 번째 국면인 io 에서 CPU는 해당 레이어의 16칸 LFU 캐시를 조회해 적중과 누락을 가른 뒤, 누락된 칸만 병렬 pread 호출로 채웁니다. 읽어 온 데이터는 Metal이 바로 볼 수 있는 버퍼로 들어갑니다. 이 읽기가 도는 동안 Metal은 상주 공유 전문가 분기를 먼저 계산해 대기 시간을 덮고, 캐시에 이미 있던 전문가 계산도 먼저 시작할 수 있습니다. 마지막 국면인 cb2 는 라우팅된 8개 분기를 라우터 가중치로 합치고 공유 분기와 결합한 뒤 정규화와 잔차, 레이어 스칼라를 적용합니다.
라우터 계산 자체는 다음과 같이 정리되어 있습니다. 정규화한 은닉 상태를 스케일링한 뒤 8비트 양자화 프로젝션으로 128개 점수를 만들고, 상위 8개만 남겨 소프트맥스를 취하는 형태입니다.
router_input = rmsnorm_no_scale(hidden)
scaled_input = router_input * router_scale / sqrt(hidden_size)
logits = int8_affine(scaled_input)
top8 = highest_8(logits)
weights = softmax(logits[top8]) * per_expert_scale[top8]
프롬프트 프리필은 최대 128 토큰 단위 청크로 처리합니다. 한 번 읽어 온 전문가를 여러 행이 함께 쓸 수 있으므로, 같은 읽기 비용으로 더 많은 계산을 뽑아내는 구조입니다. 생성 단계에서는 같은 레이어 루프를 토큰 하나씩 반복합니다.
TurboFieldfare가 메모리를 아끼는 방식
양자화 구성은 원본 체크포인트를 그대로 따릅니다. MLX 어파인 방식으로 64개 가중치 그룹마다 BF16 스케일과 BF16 바이어스를 두는 4비트 값이고, 라우터 프로젝션만 8비트를 씁니다. 임베딩과 언어 모델 헤드는 같은 양자화 가중치를 공유합니다.
KV 캐시는 어텐션 종류에 따라 배치를 달리합니다. 25개 슬라이딩 윈도우 레이어는 최근 1,024 토큰만 보므로 1,152행 링 버퍼에 K/V를 저장하며, 여유로 둔 128행은 청크 프리필이 기록할 공간입니다. 5개 전체 어텐션 레이어는 추가만 하는 저장 방식으로 전체 문맥을 유지합니다. 전체 어텐션 레이어에서는 원본 K 프로젝션이 K와 V 양쪽 값을 공급하는데, K에는 스케일이 적용된 헤드별 정규화와 RoPE가 붙고 V에는 스케일 없는 별도 정규화만 붙어 RoPE가 들어가지 않습니다. 두 경로가 갈리므로 캐시도 K와 V를 따로 저장합니다.
디코드 시간이 어디에 쓰이는지도 측정되어 있습니다. 6토큰 프롬프트에서 162.8ms짜리 디코드 한 스텝을 나눈 결과입니다.
| 작업 | 토큰당 ms |
|---|---|
| 전문가 읽기 | 83.1 |
| 커맨드 버퍼 파이프라인 대기 | 55.6 |
| 가중치를 공유하는 출력 헤드 | 14.2 |
| 그 외 런타임 작업 | 9.9 |
절반가량이 전문가 읽기에 들어갑니다. 다만 이 측정은 진단 계측을 켜 평소의 커맨드 버퍼 파이프라인을 끈 상태이며 처리량이 4.23 tok/s로 떨어진 조건이라, 저자는 이 표가 독립적인 속도 향상 여지나 성능 한계를 뜻하지 않는다고 덧붙였습니다.
TurboFieldfare의 스트리밍 설치 방식
설치 과정에도 같은 메모리 규칙이 적용됩니다. 일반적인 방식이라면 Hugging Face 스냅샷을 전부 내려받은 뒤 자체 형식으로 다시 쓰겠지만, 그러면 디스크에 체크포인트가 두 벌 생깁니다. TurboFieldfare의 리패커는 고정된 리비전에서 필요한 바이트 범위만 요청해 받는 즉시 .gturbo 배치로 다시 씁니다.
- 원본 인덱스와 텐서 메타데이터를 읽고, 버전이 붙은 체크포인트를 고정된 소스와 범위 계획에 연결합니다.
- 제한된 원격 바이트 범위를 요청해 타일 크기 스크래치로 값과 스케일, 바이어스를 옮깁니다.
- 완료된 범위를 먼저 디스크에 확정한 뒤 목적지 다이제스트를 기록합니다.
- 비전 텐서는 건너뛰고,
manifest.json과verified-install.json을 검증한 뒤 임시 디렉토리를 원자적으로 승격합니다.
검증된 설치에서 가장 큰 페이로드와 스크래치 힙이 각각 524,288바이트였다고 밝히고 있습니다. 15GB급 원본이 Swift 힙 버퍼에 통째로 올라가는 순간이 없다는 뜻입니다. 양자화된 값은 배치만 바꿔 그대로 복사하며 역양자화와 재양자화를 하지 않습니다. 취소하면 트랜잭션을 삭제하지 않고 멈춰 두었다가, 재개할 때 완료된 범위의 다이제스트를 다시 확인해 빠지거나 손상된 범위만 내려받습니다.
첫 설치는 약 15GB를 전송하고 완성된 설치본은 약 14.3GB를 차지합니다. 매니페스트와 파일 해시 검증을 통과해야 설치로 인정되며, 설치 자체는 모델을 메모리에 올리지 않습니다.
TurboFieldfare 사용법: 맥 앱과 CLI, 로컬 서버
Swift 패키지는 여섯 개의 산출물을 제공합니다. 이 중 모델을 소유하는 제품은 한 번에 하나만 실행해야 합니다.
| 산출물 | 용도 |
|---|---|
TurboFieldfare |
런타임과 Metal 커널이 들어 있는 Swift 라이브러리 |
TurboFieldfareMac |
설치와 생성을 담당하는 네이티브 맥 앱 |
TurboFieldfareDecodeService |
맥 앱이 쓰는 일회성 모델·Metal 소유 프로세스 |
TurboFieldfareCLI |
명령행 명령 대화와 원시 완성 |
TurboFieldfareServer |
루프백 OpenAI 호환 Chat Completions 서버 |
TurboFieldfareRepack |
스트리밍 모델 설치기와 설치 검증기 |
맥 앱은 저장소를 클론해 릴리즈로 빌드한 뒤 실행합니다.
git clone https://github.com/drumih/turbo-fieldfare.git
cd turbo-fieldfare
swift build -c release
.build/release/TurboFieldfareMac
앱이 열리면 Download 로 모델을 받고 Load Model 로 올린 다음 프롬프트를 입력해 생성합니다. 위 화면의 상태 표시줄에는 생성 속도와 토큰 수, 메모리 사용량이 함께 표시되고, 오른쪽 패널에서 컨텍스트 길이와 전문가 캐시 슬롯 수, 샘플링 설정을 조절할 수 있습니다. 슬롯을 늘리면 더 많은 전문가가 메모리에 남아 디코드가 빨라지지만 그만큼 메모리를 더 쓴다는 설명이 패널에 함께 적혀 있습니다. 생성 기본값은 temperature 0.2, Top-K 64, Top-P 0.95 이고 temperature를 0 으로 두면 결정적 그리디 출력이 나옵니다.
CLI로 모델을 설치하려면 리패커를 직접 실행합니다. 중단된 다운로드는 --resume 으로 이어받고, 설치본만 검증하려면 --verify-install 을 씁니다.
swift run -c release TurboFieldfareRepack \
--output scratch/gemma4.gturbo \
--overwrite
swift run -c release TurboFieldfareRepack \
--verify-install \
--input-gturbo scratch/gemma4.gturbo
명령 대화는 JSON 배열 파일로 넘깁니다. 맥 앱과 같은 방식으로 Gemma 채팅 형식을 붙여 주며, 응답 길이 상한은 --max-new 로 정하고 기본값은 1,024 토큰입니다.
swift run -c release TurboFieldfareCLI \
--model scratch/gemma4.gturbo \
--messages-file messages.json
채팅 형식 없이 텍스트를 그대로 넣어 재현 가능한 비교를 하려면 --prompt 를 씁니다.
swift run -c release TurboFieldfareCLI \
--model scratch/gemma4.gturbo \
--prompt "The capital of France is" \
--max-new 64 \
--temperature 0
OpenAI 호환 서버는 별도 산출물로 빌드해 설치된 모델을 가리키면 http://127.0.0.1:8080/v1 에서 대기합니다. Chat Completions와 스트리밍, 함수 도구, 단일 접두 프롬프트 재사용을 지원하지만 원격 인증과 TLS가 없으므로 루프백에만 두라고 명시하고 있습니다. 도구 호출은 서버가 실행하지 않고 모델이 만든 호출을 그대로 돌려주므로, 승인과 실행은 클라이언트 몫입니다.
swift build -c release --product TurboFieldfareServer
.build/release/TurboFieldfareServer \
--model scratch/gemma4.gturbo
모델 실행 전에 메모리가 넉넉한지 확인하라는 안내도 있습니다. 무거운 앱을 닫고 memory_pressure -Q 로 여유를 확인하고, TurboFieldfare 관련 프로세스와 다른 로컬 모델 프로세스를 동시에 띄우지 않는 편이 안전합니다.
TurboFieldfare의 라이선스
TurboFieldfare의 소스와 문서는 Apache License 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다. 모델 가중치는 저장소에 포함되지 않고 설치기가 별도로 내려받으며, 가중치 자체는 원본 배포 조건을 따릅니다. 모델과 Swift 패키지의 라이선스 검토 내역은 THIRD_PARTY_NOTICES.md에 정리되어 있습니다.
TurboFieldfare 시스템 설계 문서
TurboFieldfare 프로젝트 GitHub 저장소
더 읽어보기
-
flash-moe: 순수 C와 Metal로 구현한, M3 Max 맥북 프로에서 397B 파라미터 MoE 모델을 실행하는 고성능 추론 엔진
-
cider: Apple Silicon M5의 INT8 TensorOps로 LLM prefill 속도를 끌어올리는 MLX W8A8 추론 SDK
-
mlxcel: 애플 실리콘에 최적화된 Rust 기반의 LLM/VLM 추론 런타임 및 서버 (feat. lablup)
-
mlx-vlm: M5와 같은 Apple Silicon에 최적화된 MLX 기반 시각-언어 모델(VLM) 추론 및 파인튜닝 도구
-
Google DeepMind, 모바일 기기부터 클라우드까지 사용 가능한, 통합 멀티모달 모델 Gemma 4 공개
이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다. 
이 도구를 직접 설치해 사용해보셨다면, 
파이토치 한국 사용자 모임
회원들을 위해 경험이나 팁을 댓글로 남겨주세요! 