TL;DR

DwarfStar는 DeepSeek V4 Flash와 PRO 전용으로 설계된 C 기반 로컬 추론 엔진으로 Metal, CUDA, ROCm 백엔드를 네이티브로 최적화하고 GGUF/imatrix 도구 체인과 통합된 서버·CLI·내장 에이전트를 제공한다. SSD 스트리밍은 routed MoE 전문가를 디스크에서 캐시-온-미스 방식으로 로드해 RAM 한계를 넘는 모델 실행을 허용하고 분산 모드는 레이어 단위 분할로 대형 모델의 프리필을 파이프라인화해 프리필 처리량을 높인다. 벤치마크는 q2 imatrix에서 높은 프리필 처리량을 보였고 분산 프리필은 최대 1.85x의 향상을 기록했으나 생성 단계는 분산 시 오버헤드로 느려질 수 있다. 이 리포지토리는 특정 GGUF 레이아웃과 모델에 강하게 의존하므로 호환 GGUF와 충분한 스토리지/메모리 인프라가 전제되어야 한다.

주요 기능

• 로컬에서 DeepSeek V4 Flash와 PRO GGUF를 직접 로드하고 추론을 수행하며 HTTP API와 통합된 서버 바이너리를 제공해 OpenAI/Anthropic 호환 엔드포인트를 노출한다. 이 엔진은 모델의 특정 GGUF 레이아웃과 양자화 혼합을 기대하며 임의 GGUF는 호환되지 않는다. 또한 DSML 도구 호출을 정확하게 재현하는 툴 리플레이 맵과 디스크 KV 캐시를 제공한다.
• Metal, CUDA, ROCm 백엔드를 최적화한 네이티브 그래프 경로를 제공하며 SSD 스트리밍을 통해 RAM보다 큰 모델을 실행할 수 있게 한다. SSD 스트리밍은 routed MoE 전문가를 캐시하고 필요시 GGUF에서 로드하는 방식으로 동작하며 캐시 예산을 GB 단위로 설정할 수 있다. 자동 캐시 예산 계산은 비라우팅 가중치를 제외한 추천 작업 집합의 80%를 사용해 전문가 캐시 크기를 결정한다.
• 분산 추론 기능은 레이어 단위로 모델을 분할해 여러 머신에 걸쳐 대형 모델을 구동하거나 긴 프리필을 가속하는 파이프라인을 제공한다. 분산 환경에서는 prefill 경로가 파이프라인으로 동작해 토큰 블록을 서로 다른 머신이 병렬로 처리할 수 있지만 생성 단계는 엄격히 autoregressive여서 분산 생성이 느려질 수 있다. 전송 포맷은 기본적으로 32비트 float이며 16비트 또는 8비트로 축소해 네트워크 트래픽을 절감할 수 있다.

어떻게 동작하는가

DwarfStar는 모델 로딩·렌더링·KV 상태 관리·툴 호출을 엔진 내부에서 일괄적으로 처리하는 네이티브 C 기반 추론 스택이다. 모델의 routed MoE 전문가만 비대칭 2비트 양자화를 적용하고 비라우팅 파라미터는 상대적으로 높은 정밀도로 유지하며 SSD 스트리밍 및 전문가 캐시를 통해 메모리 한계를 우회한다. 분산 모드에서는 레이어 범위를 각 프로세스가 매핑하고 coordinator/worker 프로토콜로 활성화된 경로를 구성해 프리필 파이프라인을 병렬화한다.

해결 문제

대형 DeepSeek V4 계열 모델을 고메모리 개인 머신이나 Mac 스튜디오급 장비에서 로컬로 실행할 수 있게 하며, 모델이 RAM에 전부 올라오지 못하는 환경에서 SSD 기반 스트리밍과 전문가 캐시로 실행 가능성을 확장한다. 또한 모델-특화 GGUF를 전용 경로로 최적화하고 KV 디스크 캐시와 툴 재생 메커니즘으로 연속 대화와 에이전트 통합을 현실화한다. 분산 레이어 분할로 단일 머신에 맞지 않는 전체 모델을 여러 호스트에 분산해 용량 한계를 극복한다.

지금 주목받는 이유

고성능 오픈 웨이트 모델과 고메모리 개인 컴퓨터의 출현으로 대형 모델을 로컬에서 실행하려는 수요가 증가했고, DeepSeek V4의 KV 캐시 설계와 SSD 성능 개선이 로컬 대형 컨텍스트 실행을 현실화했다. DwarfStar는 이러한 환경 변화에 맞춰 SSD 스트리밍과 분산 레이어 분할을 결합해 개인 장비에서 대형 모델을 다룰 수 있게 한다. 또한 프로젝트가 Metal, CUDA, ROCm을 모두 타깃으로 하여 서로 다른 하드웨어 생태계에서 성능을 확보하려는 요구를 반영한다.

차별점

• 단일 모델에 집중해 DeepSeek V4 Flash/PRO의 공식 벡터(official logits)로 검증하는 전략을 사용하며, 일반 GGUF 러너가 아니라 특정 모델과 레이아웃에 맞춘 완전 자급형 네이티브 엔진을 제공한다. 이로 인해 내부 텐서 레이아웃·양자화·MTP 상태와 맞춰 성능과 정확도를 보장할 수 있다. 반면 다른 범용 러너처럼 많은 모델을 광범위히 지원하지 않으므로 사용자는 호환 GGUF를 확보해야 한다.
• KV 캐시를 디스크 일급 시민으로 취급하고 exact DSML 툴 리플레이 맵을 사용해 툴 호출의 바이트 정확성을 보존함으로써 재현 가능한 세션과 빠른 재개를 제공한다. 이 설계는 에이전트-내장 세션과 저장된 세션의 일관성을 유지하는 데 유리하며 서버 재시작 후에도 디스크 캐시로 빠르게 복구할 수 있다. 단일 라이브 KV 캐시 제한 때문에 동시에 많은 활성 세션을 메모리에서 유지하지 못할 수 있다.
• 분산 추론에서 프리필을 파이프라인화해 대형 컨텍스트 전처리 속도를 높이는 반면 생성 단계는 엄격한 autoregressive 제약 때문에 분산으로는 속도 이득을 얻기 어렵다는 점을 명백히 설계에 반영했다. 실제 측정에서 장문 프리필은 두 대의 Mac에서 최대 1.85x까지 향상되었고 분산 생성은 19.4% 성능 저하가 관찰되었다. 따라서 분산 모드는 용량 핸들링과 프리필 가속에 초점을 둔다.

사용 사례

• 대형 컨텍스트 기반 리서치나 코드 에디팅 작업에서 로컬로 DeepSeek V4 Flash/PRO를 구동해 긴 프리필과 상태 보존이 필요한 대화형 에이전트를 실행하는 데 사용된다. 디스크 KV 캐시를 통해 긴 세션을 저장하고 빠르게 재개할 수 있어 반복 실험과 디버깅 워크플로에서 유리하다. 에이전트는 툴 호출을 정확한 DSML 바이트로 재생해 툴-모델 일관성을 유지한다.
• 모델이 한 머신의 메모리를 초과하는 상황에서 두 대 이상의 Mac 또는 GPU 클러스터를 연결해 모델을 분할 구동하는 용량(use‑capacity) 시나리오에 적합하다. 분산 프리필 파이프라인은 대형 문서나 장문 작업의 전처리 시간을 줄여 대화 준비 시간을 단축한다. 네트워크가 느리면 생성 지연이 커지므로 이 사용은 주로 내부 고속 네트워크 환경에서 유효하다.
• 로컬 개발 환경에서 OpenAI/Anthropic 호환 API를 로컬 엔드포인트로 제공해 클라이언트 검증과 오프라인 에이전트 통합을 수행하는 데 사용된다. ds4-server는 chat/completions, responses, messages 엔드포인트를 지원해 기존 통합을 최소 변경으로 전환할 수 있다. 브라우저 클라이언트는 CORS 옵션으로 로컬 서버에 안전하게 연결할 수 있다.

시작하기

프로젝트는 소스에서 빌드하는 방식으로 시작하며 macOS Metal, Linux CUDA, 또는 CPU 전용 빌드를 선택하는 make 목표를 제공한다. 먼저 적절한 GGUF를 ./gguf/로 내려받아 ./ds4flash.gguf를 가리키게 한 뒤 플랫폼에 맞는 make 명령(예: make, make cuda-spark, make cpu)을 실행해 바이너리를 생성한다. 서버를 실행하려면 ./ds4-server --ctx 100000 --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192 같은 명령으로 시작하고 OpenAI 호환 REST 엔드포인트로 요청을 보낼 수 있다.

요구사항

• 지원되는 모델 GGUF 파일(DeepSeek V4 Flash 또는 PRO imatrix/q2/q4 변형)을 사전에 확보해야 하며 임의 GGUF는 호환되지 않는다.
• 메모리와 스토리지 요구는 선택한 모델과 양자화에 따라 달라지며 q2 imatrix는 96/128GB급 머신을 권장하고 PRO Q4는 512GB급 분산 구성이 필요하다.
• macOS에서 Metal 사용 시 빠른 NVMe/SSD 성능과 충분한 램이 권장되며 Linux에서는 CUDA 환경 및 네트워크(분산 사용 시) 설정이 필요하다.

벤치마크

이미지 분석