FreeToken 딥다이브
— 게이밍 PC 한 대로 284B 모델을 돌리는 엔진

1프로젝트 한줄 요약

FreeToken은 개인 PC 한 대에서 프런티어급 오픈웨이트 MoE 모델을 서빙하는 추론 엔진입니다. 게이밍 데스크탑, 노트북, 워크스테이션처럼 GPU가 한 장뿐이고 그 VRAM이 모델 전체를 담지 못하는 환경이 대상입니다. 버클리·MIT 계열 연구진이 만들었고 논문(arXiv:2608.16157)과 코드가 함께 공개돼 있습니다.

왜 이게 가능한지는 MoE라는 모델 구조에서 나옵니다. 논문이 드는 예를 그대로 옮기면, DeepSeek-V4-Flash는 43개 레이어 각각에서 256개 전문가 중 6개만 골라 씁니다. 파라미터는 284B인데 토큰 하나당 실제로 계산에 참여하는 건 13B뿐입니다. 13B는 RTX 5090의 32GB에 들어갑니다. 문제는 어느 6개가 뽑힐지 미리 모른다는 것, 그래서 256개 전부를 어딘가에 갖고 있어야 한다는 것입니다.

2왜 주목받는가

공개 첫 커밋이 2026년 8월 11일, 그로부터 2주도 안 돼 별 3.2k. 속도의 이유는 세 가지가 겹친 것입니다 — 실측 수치가 크고, 저자진이 화려하고(Ion Stoica · Matei Zaharia · Song Han · Kurt Keutzer), 대상이 개인 PC라 확인해 볼 사람이 많습니다.

비교 대상은 vLLM이 아니다

흔한 오해 하나를 먼저 정리해야 합니다. FreeToken이 겨루는 상대는 vLLM이나 SGLang이 아닙니다. 그쪽은 여러 장의 데이터센터 GPU에 모델이 다 들어가는 상황을 전제합니다. 실제로 README의 감사 문단은 vLLM · SGLang · FlashInfer · llama.cpp를 코드와 설계를 빌려온 상류(上流)로 명시합니다. 논문이 실험에서 비교한 baseline은 llama.cpp · Ollama · KTransformers · MoE-Infinity — 전부 "엣지에서 오프로딩으로 버티는" 진영입니다.

논문의 표현이 이 차이를 정확히 짚습니다 — "라우팅 계산은 정확하게, 모델은 손대지 않은 채 둔다. 바꾸는 것은 예측을 얼마나 잘하느냐가 아니라 남은 미스를 어떻게 서빙하느냐다."

실측 수치

실험은 모델 3종(Qwen3.6-35B-A3B · DeepSeek-V4-Flash · GLM-5.2) × 머신 6종(8GB RTX 4060 노트북부터 RTX PRO 6000 워크스테이션까지) × 실제 에이전트 워크로드 4종으로 돌렸습니다. 가중치 포맷은 모든 엔진이 비트 단위로 동일한 체크포인트를 쓰도록 맞췄습니다.

기준선으로 삼을 숫자가 하나 있습니다. 논문은 프로덕션 코딩 에이전트 트레이스의 중앙 디코드 속도 33 tok/s를 "대화 가능"의 임계선으로 잡습니다. 8GB 노트북의 39.3 tok/s가 이 선을 넘긴다는 게 이 프로젝트의 헤드라인입니다.

3기술 스택 전체 지도

언어 비율만 보면 Python 88.4% / CUDA 5.5% / C++ 2.8% / C 2.5%로 "파이썬 프로젝트"처럼 보입니다. 하지만 실제 성능은 그 안의 Triton 커널 44개와 C++/CUDA 12,419줄에서 나옵니다. Python은 조립과 스케줄링을 맡습니다.

플러그인처럼 갈아 끼우는 어텐션 백엔드

어텐션 구현이 레지스트리로 관리되고, 모델과 GPU에 따라 자동으로 선택됩니다. --attention-backend에 prefill,decode 쌍을 주면 두 단계에 서로 다른 백엔드를 쓰는 하이브리드로 합성됩니다.

4아키텍처 심화 분석

전체 구조도

구조도에서 눈여겨볼 곳은 맨 아래 세 갈래입니다. 전문가 가중치의 원본은 항상 호스트 RAM에 있고, GPU에 있는 건 캐시일 뿐입니다. 그래서 캐시가 작든 크든 결과는 같고 속도만 달라집니다. 이 성질이 나중에 "실행 중 메모리 재분배"를 안전하게 만들어 줍니다.

설계 패턴 ① — 프리필: 전 레이어 더블 버퍼 스트리밍

프롬프트를 읽는 단계(프리필)에서는 어차피 전문가 대부분이 쓰입니다. 그래서 캐싱을 포기하고 레이어 순서대로 전문가 풀 전체를 스트리밍합니다. 대신 버퍼를 두 개 두고 layer_id % 2로 번갈아 씁니다 — 지금 레이어를 계산하는 동안 다음 레이어를 미리 실어 옵니다.

영리한 부분은 이 두 버퍼가 별도 할당이 아니라는 점입니다. 슬롯 캐시의 앞쪽 2 × 전문가수 칸을 빌려 쓰는 뷰입니다. 그래서 프리필이 끝나면 거기 남은 전문가가 그대로 디코드 캐시의 씨앗이 됩니다. 논문 표현으로는 "별도 프리필 캐시도, 단계 간 인수인계도 없다". 다만 대가가 있어서, --moe-cache-size가 2 × 전문가수보다 작으면 오버랩이 자동으로 꺼집니다.

설계 패턴 ② — 디코드: q* 대역폭 정합 분할

여기가 이 프로젝트의 심장입니다. 토큰을 하나씩 뱉는 디코드 단계에서, 캐시에 없는 전문가 m개를 만나면 세 갈래로 갈립니다.

이 계산을 파이썬이 아니라 GPU 커널 안에서 한다는 게 핵심 제약입니다. 미스 개수 m은 그 스텝의 실제 라우팅에 따라 달라지는데, 디코드 경로 전체가 CUDA Graph로 캡처돼 있어서 그 값을 호스트로 가져올 수 없습니다. 그래서 분할 결정 자체를 디바이스로 내렸습니다.

moe/offload_kernels.py — Triton 커널 안에서 Q16 고정소수점으로 q*를 푸는 부분입니다.

# 페치 개수에 상한을 건다. 넘치는 미스는 CPU가 계산한다(GPU에 올리지 않음).
if fetch_frac_q16 > 0:
    # 대역폭 정합 분할 (fetch_frac = pcie_bw / cpu_bw):
    #   페치 시간은 F * (1 - frac)에, CPU 시간은 (M - F) * frac에 비례.
    #   F = frac * M 에서 균형. 정수가 아니므로 양옆 정수 중
    #   "느린 쪽(max)"이 더 작아지는 값을 고른다.
    lo = (num_missing * fetch_frac_q16) >> 16
    cost_lo = tl.maximum(lo * ((1 << 16) - fetch_frac_q16),
                         (num_missing - lo) * fetch_frac_q16)
    cost_hi = tl.maximum((lo + 1) * ((1 << 16) - fetch_frac_q16),
                         (num_missing - lo - 1) * fetch_frac_q16)
    max_fetch = tl.where(cost_lo <= cost_hi, lo, lo + 1)
num_fetch = tl.minimum(num_missing, max_fetch)

fetch_frac_q16은 B_P / B_H를 65536을 곱한 정수로 표현한 값입니다(GPU 커널에서 부동소수점 나눗셈을 피하려는 것). 이 값의 출처는 ft bench bw가 남긴 프로파일인데, 여기서도 세심한 선택이 하나 있습니다 — 단독 측정값이 아니라 두 경로를 동시에 돌렸을 때의 측정값을 우선합니다. 실제 상황에서는 PCIe 전송과 CPU 연산이 메모리 컨트롤러를 놓고 경쟁하니까요.

같은 로직의 순수 파이썬 레퍼런스 구현이 같은 파일에 나란히 있습니다. 테스트가 GPU 커널과 이 레퍼런스의 결과를 비트 단위로 대조합니다.

if frac_q16 > 0:
    m, q = len(missing), 1 << 16
    lo = (m * frac_q16) >> 16
    cost = lambda f: max(f * (q - frac_q16), (m - f) * frac_q16)
    max_fetch = lo if cost(lo) <= cost(lo + 1) else lo + 1

설계 패턴 ③ — 각 전문가를 정확히 한 번만 계산하기

GPU와 CPU가 동시에 돌면 "누가 무엇을 맡았는지"를 표시해야 합니다. 그런데 CUDA Graph 안에서는 배열 크기가 바뀌면 안 되므로 리스트를 잘라내는 방식을 쓸 수 없습니다. 해법은 -1이라는 sentinel 값 하나와 마스킹입니다.

raw = topk_ids.clone()                            # 원본 전문가 id 보관
cache.ensure_experts_hybrid(layer_id, topk_ids)   # → 슬롯 번호, 아니면 -1
on_gpu = topk_ids >= 0

# CPU 쪽: GPU가 맡은 자리는 id를 -1로 (C++ 커널이 id<0을 건너뜀)
cpu_ids = torch.where(on_gpu, raw.new_full((), -1), raw)
pending = executor.decode_submit(layer_id, hidden_states, topk_weights, cpu_ids)
  ↑ CPU 작업을 먼저 던져 놓는다

cache.copy_missing()                              # ↓ 그 사이 PCIe 페치 진행

# GPU 쪽: CPU가 맡은 자리는 가중치를 0으로 (계산해도 결과에 안 더해짐)
gpu_slots = topk_ids.clamp_min(0)                 # -1 → 슬롯 0
gpu_w = torch.where(on_gpu, topk_weights, topk_weights.new_zeros(()))
gpu_routed = self._expert_gemm(cache, hidden_states, gpu_w, gpu_slots, ...)

cpu_routed = executor.decode_sync(pending)        # CPU 결과 회수
return gpu_routed + cpu_routed                   # 부분합 병합

분기(if) 없이 elementwise 연산만으로 두 경로를 갈랐습니다. clamp_min(0)이 -1을 슬롯 0으로 밀어 넣지만 그 자리의 가중치가 0이라 결과에 영향이 없습니다. 배열 모양이 고정되니 CUDA Graph 캡처가 그대로 통과합니다.

설계 패턴 ④ — CUDA Graph 안에서 CPU를 기다리는 두 가지 방법

GPU가 CPU 결과를 기다려야 하는데, 그래프 안에서는 일반적인 동기화를 쓸 수 없습니다. FreeToken은 두 가지를 구현해 두고 골라 씁니다.

여기 딸린 각주가 하나 있는데, 이게 엣지 환경 최적화의 성격을 잘 보여줍니다. "GPU에서 spin-wait 커널을 돌려 기다리면 안 되냐"에 대한 코드 주석의 답은 — 그렇게 하면 GPU 사용률이 99%로 보고되고, 노트북의 전력 스케줄러가 그걸 보고 CPU 클럭을 낮춰서 결과적으로 더 느려진다는 것입니다. 데이터센터에서는 나오지 않을 종류의 제약입니다.

설계 패턴 ⑤ — 두 겹의 LRU

전문가 캐시는 LRU(가장 오래 안 쓴 것부터 버리기)로 관리되는데, 실은 LRU가 두 개입니다.

• 1차 — 슬롯 LRU: usage라는 int64 타임스탬프 배열과 전역 step 카운터. 자리가 없으면 argmin(usage)로 희생자를 고릅니다. 전문가 id는 layer_id × 전문가수 + expert라는 평평한 하나의 번호 공간으로 관리해서, 버릴 때 (레이어, 전문가)로 되돌릴 필요가 없습니다.
• 2차 — expert_recency: 하이브리드 모드에서 어느 미스를 페치할지 고를 때 씁니다. q*가 "몇 개를 페치할지"를 정하면, 이쪽이 "그 몇 개가 무엇인지"를 정합니다 — 최근에 자주 활성화된 전문가를 우선합니다.

미스율 실측이 이 설계의 효과를 보여줍니다. 같은 라우팅 트레이스를 재생했을 때, RTX 5090이 담을 수 있는 용량(Qwen3.6 전문가 풀의 37%)에서:

설계 패턴 ⑥ — 크래시로부터 격리된 제어평면

ft daemon은 별도 프로세스이고, torch · CUDA · flashinfer · sgl_kernel을 절대 임포트하지 않습니다. 이유가 README에 명시돼 있습니다 — "CUDA 오류나 네이티브 확장의 세그폴트는 그것을 로드한 프로세스를 죽인다. 그리고 데몬은 그중 아무것도 로드하지 않는다."

더 인상적인 건 이 원칙을 테스트로 강제한다는 점입니다. tests/daemon/test_daemon_import_safety.py가 import sentinel을 심어 두고, 데몬 모듈을 임포트했을 때 금지 모듈이 딸려 들어오면 실패합니다. 규칙을 문서에만 적어 두면 6개월 뒤 누군가 무심코 어깁니다.

설계 패턴 ⑦ — 파괴하기 전에 검증하기

실행 중 캐시 재분배(ft ctl cache --moe 4096 --kv 32k)는 위험한 연산입니다. 기존 캐시를 해제한 뒤 새 크기로 잡는데, 중간에 실패하면 서빙 불가 상태로 영구히 떨어집니다. 그래서 순서를 뒤집었습니다 — 해제 전에 기하 구조와 메모리 예산 적합성을 전부 검증하고, 안 맞으면 CacheRebuildRejected로 거절합니다. 거절은 복구 가능하고, 반쯤 해제된 상태는 복구 불가능하니까요.

5디렉토리 구조 해부

이 트리에서 읽어 낼 것이 몇 가지 있습니다.

• kernel/이 가장 크다(16k줄). 파이썬 프로젝트로 보이지만 무게중심은 커널입니다. 그중 csrc/gguf/ 5,733줄은 llama.cpp의 ggml 커널을 그대로 이식한 것 — 남의 검증된 커널을 다시 안 짜고 가져왔습니다.
• function_call_parser.py 하나가 3,735줄. 모델 패밀리마다 툴콜을 표현하는 형식이 제각각이라, 그걸 전부 파싱하는 코드입니다. "에이전트를 제대로 지원한다"는 말의 실제 비용이 여기 있습니다.
• 테스트가 24,708줄 / 854개. 코드 대비 테스트 비율이 높습니다. 다만 CI에서 안 돌립니다 — GPU가 필요해서 로컬 GPU 머신에서 수동으로 돌리는 전제입니다(tests/README.md: GPU 박스에서 2~4분).
• 모델 13종 각각이 독립 디렉토리. deepseek_v4/는 10개 파일(args · attention · compress · config · layers · model · moe · ops · weight)로 쪼개져 있습니다. 공통 추상화로 억지로 묶지 않고 모델별로 펼친 구조입니다.

6학습 포인트 (기술별)

추론 엔진을 만들 일이 없어도 배울 게 남는 저장소입니다. 여기 있는 기법 대부분은 "제약이 심한 환경에서 어떻게 설계하나"에 대한 답이라 범용성이 있습니다.

7하드웨어 / 시스템 요구사항

CPU 쪽도 조건이 붙습니다. CPU MoE 실행기는 실행 시점에 명령어 집합을 골라 씁니다 — AVX-512-BF16 → AVX-512F → AVX2+FMA → 스칼라 순. 스칼라로 떨어지면 하이브리드 모드의 이점이 사실상 사라집니다. 스레드는 물리 코어당 하나만 고정하는데, 이유가 명확합니다 — MoE 디코드는 메모리 대역폭에 묶인 작업이라 하이퍼스레딩 형제 스레드는 같은 코어의 로드 포트만 두고 다툴 뿐 대역폭을 늘려 주지 않습니다.

알려진 제약 (설치 전에 알아 둘 것)

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

FreeToken 자체

• github.com/FlashML-org/FreeToken — 저장소 (Apache-2.0)
• arXiv:2608.16157 — 논문 FreeToken: Efficient Edge-Native MoE Serving with Bandwidth-Adaptive Execution
• flashml.ai — 데스크탑 앱 (Windows / Linux)
• 이슈 #84 — 사실상의 FAQ. 하드웨어·RAM 요구사항이 여기 있음
• 이슈 #79 — 로드맵 (ROCm · aarch64 · 멀티 GPU · speculative decoding)
• CONTRIBUTING.md — 순수 AI 생성 PR 금지 정책이 명시돼 있어 읽어 볼 만함

비교해 볼 만한 저장소

• ggml-org/llama.cpp — 같은 문제를 정적 분배로 푼 쪽. FreeToken이 ggml 커널을 이식해 오기도 했음
• kvcache-ai/ktransformers — CPU AMX 최적화 계열. 논문의 주요 baseline
• vllm-project/vllm · sgl-project/sglang — 데이터센터 쪽 표준. FreeToken이 코드를 빌려온 상류
• ollama/ollama — 개인 PC 추론의 대중적 선택지. 사용성 vs 성능의 반대편

배경 지식

• Triton 공식 튜토리얼 — 4주차 로드맵의 교재
• CUDA C++ 프로그래밍 가이드 — CUDA Graphs 절
• PagedAttention (vLLM) 논문 — KV 캐시를 페이지로 관리하는 발상의 원본
• Switch Transformer 논문 — MoE 라우팅의 고전