DwarfStar는 DeepSeek V4 Flash에 우선적으로 최적화된 소형 네이티브 추론 엔진 (inference engine)입니다. 또한 GLM 5.2를 지원하며, 메모리가 매우 높은 기기에서는 DeepSeek V4 PRO도 지원합니다. 이 엔진은 범용 GGUF 러너 (runner)가 아니라, 독립적이고 의도적으로 범위를 좁게 설계되었습니다. 모델 로딩 (model loading), 프롬프트 렌더링 (prompt rendering), 도구 호출 (tool calls), KV 상태 (KV state), HTTP 서버, 그리고 코딩 에이전트 (coding agent)가 함께 구축되고 테스트되었습니다. 또한 이 저장소에는 GGUF, imatrix, 품질 및 속도를 위한 도구와 데이터가 포함되어 있습니다.

지원되는 백엔드 (backends):

Metal: 96 GB 이상의 메모리를 가진 Mac을 주요 대상으로 하며, 사양이 낮은 기기에서는 SSD 스트리밍 (SSD streaming)을 사용할 수 있습니다. NVIDIA CUDA: 멀티 GPU (multi-GPU) 시스템 및 DGX Spark를 포함합니다. ROCm: Framework Desktop과 같은 Strix Halo 시스템에서 지원됩니다.

이 프로젝트는 llama.cpp 및 GGML이 없었다면 존재할 수 없었을 것입니다. Georgi Gerganov와 다른 모든 기여자들에게 감사를 표하는 감사 (acknowledgements) 섹션을 반드시 읽어주시기 바랍니다.

모델 지원은 의도적으로 기회주의적 (opportunistic)으로 이루어집니다. 이 프로젝트는 유용한 로컬 기기 크기, 특히 128 GB 노트북과 512 GB 워크스테이션에 가장 적합한 최상의 오픈 웨이트 (open weights) 모델을 따릅니다. 더 나은 대체 모델이 등장하면 기존 모델은 제거될 수 있습니다.

• MacBook, DGX Spark 또는 Strix Halo와 같은 소비자용 하드웨어에서 매우 유능한 모델을 실행할 수 있습니다. RAM이 충분하지 않더라도 SSD 스트리밍을 통해 준수한 속도로 실행할 수 있습니다.

• CUDA 멀티 GPU 지원과 ds4-server의 디코딩 및 생성 마이크로 배치 (micro batching)를 사용하면, vLLM에서 더 이상 새로운 모델을 지원하지 않는 구형 CUDA 카드 (Ada Lovelace 아키텍처)를 탑재한 서버를 회사를 위한 멀티 유저 LLM 서버로 변환할 수 있습니다. 우리는 8xL40S NVIDIA 카드를 사용하여 이 설정을 테스트했으며, 여러 세션에서 매우 좋은 결과를 얻었습니다. 합계 생성 속도 120 t/s, 프리필 (prefill) 2000 t/s를 기록했습니다.

• 두 대의 MacBook M5 Max / M3 Ultra RDMA를 사용하면 텐서 병렬성 (tensor parallelism)을 통해 4-bit DeepSeek Flash 또는 GLM 5.2를 실행할 수 있습니다.

• 또한 파이프라인 병렬성 (pipeline parallelism)을 사용하여 여러 시스템을 결합함으로써 RAM을 합산하고 더 큰 모델을 실행할 수 있습니다.

• 역량 있는 오픈 웨이트 (open-weight) 모델들이 이제 고사양 개인용 기기에 탑재될 수 있습니다.

• DeepSeek V4 Flash 및 PRO, GLM 5.2는 공격적인 라우티드 엑스퍼트 양자화 (routed-expert quantization)를 견뎌냅니다.

• 압축된 KV 캐시 (KV caches)와 빠른 로컬 SSD를 통해 긴 컨텍스트 (long contexts)를 실용적으로 사용할 수 있습니다.

• 소수의 모델에 특화된 추론 (inference) 시스템이라는 아이디어.

• 이 소프트웨어는 인간이 아이디어, 테스트, 디버깅을 주도하고, GPT 5.5, 5.6, Claude Fable의 강력한 지원을 받아 개발되었습니다. 우리는 프로젝트가 구축된 방식을 형성했기에 이를 공개적으로 밝힙니다. 만약 AI가 개발한 코드에 거부감이 있다면, 이 소프트웨어는 귀하를 위한 것이 아닙니다. 아래의 감사 인사 또한 똑같이 중요합니다: 이 프로젝트는 상당 부분 수작업으로 작성된 llama.cpp와 GGML 없이는 존재할 수 없었을 것입니다.

ds4.c는 GGML에 링크되지 않지만, llama.cpp 프로젝트가 열어준 길과 그곳에서 개발된 커널 (kernels), 양자화 형식 (quantization formats), GGUF 생태계, 그리고 어렵게 얻은 엔지니어링 지식 덕분에 존재할 수 있습니다.
우리는 llama.cpp와 그 기여자들에게 감사하며 빚을 지고 있습니다. 이 DeepSeek V4 특화 추론 경로를 구축하는 동안 그들의 구현, 커널, 테스트 및 설계 선택은 필수적인 참조 자료가 되었습니다. 일부 소스 수준의 구성 요소들은 MIT 라이선스 하에 이곳에 유지되거나 조정되었습니다: GGUF 양자화 레이아웃 및 테이블, CPU 양자화/dot 로직, 그리고 특정 커널들입니다. 이러한 이유와 진심 어린 감사함 때문에, 우리는 LICENSE 파일에 GGML 저작권 고지를 유지하고 있습니다.

이 소프트웨어는 현재 매우 빠르게 변화하고 있습니다. 베타 품질로 간주해 주십시오. 각 릴리스 전에 대규모 QA를 실행하지만, 불안정성이 발생할 가능성은 분명히 있습니다.

매우 구체적인 사항을 찾고 계신다면 다른 하위 README 파일들이 준비되어 있습니다. 그 외 일반적인 사용을 원하신다면 다음 섹션들을 계속 읽어주시기 바랍니다.

• CONTRIBUTING.md: 기여자들을 위한 정확성 및 속도 회귀 테스트 (regression testing) 가이드입니다. 풀 리퀘스트 (pull request)를 보내기 전에 반드시 읽어주세요.
• QA_BEFORE_RELEASES.md: 원격 Metal, CUDA, 그리고 ROCm 머신을 포함한 전체 릴리스 테스트 매트릭스 (test matrix)입니다.
• gguf-tools/README.md: 오프라인 GGUF 생성, imatrix 수집, 양자화 (quantization) 도구 및 품질 검사 관련 내용입니다.
• gguf-tools/imatrix/README.md: 라우티드 MoE (routed-MoE) imatrix가 어떻게 수집되고 사용되는지에 대한 설명입니다.
• gguf-tools/imatrix/dataset/README.md: 보정 프롬프트 코퍼스 (calibration prompt corpus)가 어떻게 생성되는지에 대한 설명입니다.
• gguf-tools/quality-testing/README.md: 로컬 GGUF가 공식 DeepSeek V4 Flash/PRO 연속 생성 (continuations) 모델과 비교하여 어떻게 점수가 매겨지는지에 대한 설명입니다.
• dir-steering/README.md: 방향성 스티어링 (directional steering) 데이터, 벡터 생성 및 사용법입니다.
• speed-bench/README.md: 벤치마크 명령, 차트 및 CSV 생성 관련 내용입니다.
• tests/test-vectors/README.md: 회귀 체크 (regression checks)에 사용되는 공식 연속 생성 벡터 (continuation vectors)입니다.

이 구현체는 아래 나열된 DeepSeek V4 및 GLM 5.2 GGUF와만 작동합니다. 이는 범용 GGUF 로더가 아니며, 임의의 GGUF 파일은 엔진이 기대하는 텐서 레이아웃 (tensor layout), 양자화 혼합 (quantization mix), 메타데이터 (metadata) 또는 선택적 MTP 상태를 갖추고 있지 않을 것입니다. 여기서 제공되는 2비트 양자화 (2 bit quantizations)는 실제로 높은 품질임이 검증되었습니다. 즉, 성능이 안정적이며, 코딩 에이전트 (coding agents) 환경에서 잘 작동하고, 도구 호출 (call tools)을 신뢰할 수 있는 방식으로 수행합니다.

2비트 양자화 모델은 매우 비대칭적인 양자화를 사용합니다: 오직 라우티드 MoE (routed MoE) 전문가 (experts)들만 양자화되며, up/gate는 IQ2_XXS로, down은 Q2_K로 설정됩니다. 이들이 전체 모델 공간의 대부분을 차지합니다. 품질을 보장하기 위해 다른 구성 요소들(공유 전문가 (shared experts), 프로젝션 (projections), 라우팅 (routing))은 수정하지 않고 그대로 둡니다.

하나의 메인 모델을 다운로드하세요. imatrix 버전을 권장합니다.

./download_model.sh q2-imatrix # 96/128 GB RAM 머신용, imatrix로 튜닝된 q2
./download_model.sh q2-q4-imatrix # 96/128 GB RAM 머신용, 마지막 6개 레이어는 q4인 q2
./download_model.sh q4-imatrix # >= 256 GB RAM 머신용, imatrix로 튜닝된 q4
...

전체 PRO Q4 분산 실행 (distributed run)을 위해서는, 각 머신에 절반씩 다운로드하세요:

./download_model.sh pro-q4-layers00-30 # PRO Q4 분할의 첫 번째 절반
./download_model.sh pro-q4-layers31-output # PRO Q4 분할의 두 번째 절반

이 스크립트는 https://huggingface.co/antirez/deepseek-v4-gguf에서 파일을 다운로드하고,

./gguf/ 아래에 파일을 저장하며,

curl -C -를 사용하여 부분 다운로드를 재개하고,

선택된 메인 모델을 가리키도록 ./ds4flash.gguf를 업데이트합니다.

pro-q4-layers00-30, pro-q4-layers31-output, 그리고 pro-q4-split 타겟은 분산된 PRO Q4 조각들을 다운로드하며 ./ds4flash.gguf를 업데이트하지 않습니다.

공개 다운로드에 대해 인증은 선택 사항이지만, --token TOKEN, HF_TOKEN 또는 로컬 Hugging Face 토큰 캐시가 존재할 경우 사용됩니다.

GGUF 파일을 다시 생성하거나 새로운 imatrix를 수집하려면 gguf-tools/README.md를 참조하세요. 해당 도구들은 오프라인 모델 구축 작업을 위한 것이며, 전체 DeepSeek V4 Flash 가중치에 대해 작업할 경우 매우 오랜 시간이 걸릴 수 있습니다. Flash GGUF 생성은 로컬 도구에 의해 지원됩니다. PRO GGUF 제작은 현재 여전히 외부 llama.cpp 기반 워크플로우에 의존하고 있으며, 추후 네이티브 툴링이 추가될 수 있습니다.

./download_model.sh mtp는 Flash를 위한 선택적 투기적 디코딩 (speculative decoding) 지원 GGUF를 가져옵니다. 이는 q2-imatrix, q2-q4-imatrix, q4-imatrix와 함께 사용할 수 있지만, --mtp를 통해 명시적으로 활성화해야 합니다. 현재의 MTP/투기적 디코딩 경로는 아직 실험적 단계입니다. 이는 정확성 검증(correctness-gated)을 거치며, 현재는 유의미한 생성 속도 향상이 아닌 기껏해야 약간의 속도 향상만을 제공합니다.

GLM 5.2 지원은 이 브랜치에서 테스트된 GGUF 파일로 제한됩니다:

./download_model.sh glm-unsloth-q4 # Unsloth UD-Q4_K_XL, 11 shards
./download_model.sh glm-antirez-iq2xxs # antirez routed IQ2_XXS 단일 파일 GGUF
./download_model.sh glm-antirez-q2 # antirez routed Q2_K 단일 파일 GGUF
...

지원되는 GLM 레이아웃은 dense/model-control 텐서를 기존 Q8/F32 경로에 유지하며, Q2_K, Q4_K 또는 Q5_K에서 routed expert gate/up 텐서를 지원합니다. routed expert down 텐서는 Q2_K, Q4_K, Q5_K에서 지원됩니다.

, 또는 Q6_K입니다.

기타 GLM GGUF 양자화 (quant) 레이아웃은 의도적으로 추가되고 공식 100-케이스 픽스처 (fixture)를 통해 점수가 검증될 때까지 지원되지 않는 것으로 간주해야 합니다.

이 형식들이 모두 동일한 실행 모드를 지원하는 것은 아닙니다. Q4 파일은 일반적인 Metal 및 CUDA 추론 (inference)에서 작동합니다. 현재 Two-Mac 텐서 병렬성 (tensor parallelism)을 위해서는 소유권 인식 (ownership-aware) IQ2_XXS 또는 Q2_K 라우티드 (routed) 레이아웃이 필요합니다. 라우티드 Q4 GLM은 평가 전에 거부되어야 합니다.

GLM의 MTP 블록은 메인 GGUF의 일부이며, 별도의 Flash MTP 파일을 사용하지 않습니다. 일반적인 디코드 (decode)가 기본값으로 유지됩니다. --glm-mtp는 실험적인 탐욕적 투기 (greedy speculation)를 활성화합니다. --glm-mtp-timing 또한 이를 활성화하며 수락 및 타이밍 카운터를 출력합니다:

./ds4 -m gguf/GLM-5.2-UD-IQ2_XXS_RoutedIQ2XXS_blk78Q2K.gguf \
--glm-mtp-timing --temp 0

GLM 추론은 Metal, CUDA 또는 ROCm 그래프 백엔드를 사용합니다. 방향성 스티어링 (Directional steering), 100 미만의 --power, 명시적인 --prefill-chunk, 그리고 외부 --mtp 파일은 아직 GLM에서 지원되지 않습니다.

그 다음 빌드합니다:

make # macOS Metal
make cuda-spark # Linux CUDA, DGX Spark / GB10
make cuda-generic # Linux CUDA, 기타 로컬 CUDA GPU
...

./ds4flash.gguf는 두 바이너리 모두에서 사용되는 기본 모델 경로입니다. ./gguf/에서 지원되는 다른 GGUF를 선택하려면 -m을 전달하세요. 전체 플래그 (flag) 목록을 보려면 ./ds4 --help 및 ./ds4-server --help를 실행하세요.

DSpark는 DeepSeek V4 Flash를 위해 DeepSeek에서 출시한 보조 초안 모델 (auxiliary draft model)입니다. 이는 메인 모델로부터 은닉 상태 (hidden states)를 읽어 최대 5개의 미래 토큰을 제안합니다. DwarfStar는 메인 Flash 모델로 해당 제안들을 확인하고 수락된 접두사 (prefix)만을 확정합니다. 메인 모델이 권위(authoritative)를 유지하며, 거부되거나 신뢰도가 낮은 접미사 (suffix)는 일반적인 타겟 디코딩 (target decoding)으로 되돌아갑니다.

가능한 이점은 더 빠른 생성 (generation)입니다. 제안된 여러 토큰이 수락될 때, 한 번의 타겟 검증 (target verification) 패스로 스트림을 여러 토큰만큼 전진시킬 수 있습니다. 이는 프리필 (prefill)을 가속화하지는 않으며, 초안 (draft) 작성과 검증 작업은 공짜가 아닙니다. 예측 가능한 연속성, 특히 코드가 가장 큰 혜택을 받는 경향이 있습니다. 수율이 낮은 프롬프트는 더 빨라지지 않거나 심지어 더 느려질 수도 있습니다. 따라서 DSpark는 여전히 실험적이며 명시적인 선택 사항 (opt-in)입니다.

출시된 DSpark 체크포인트는 약 5.6 GiB 크기의 별도 지원 GGUF로 여기에 패키징되어 있습니다. 이것은 단독 모델이 아닙니다. 한 번만 다운로드하세요:

./download_model.sh dspark-support

동일한 지원 파일을 위에 나열된 Flash q2-imatrix, q2-q4-imatrix, 그리고 q4-imatrix 모델과 함께 사용할 수 있습니다. 현재 DeepSeek V4 PRO는 지원되지 않습니다. Metal 환경에서 메인 모델이 메모리에 상주하거나 --ssd-streaming을 사용할 수 있지만, 지원 모델은 여전히 자체 가중치와 런타임 상태 (runtime state)를 메모리 요구 사항에 추가합니다. DSpark는 해당 실행 시 기존의 1단계 MTP 지원 모델과 중첩되는 대신 이를 대체합니다.

그리디 디코딩 (greedy decoding)으로 실행하세요:

./ds4 -m ds4flash.gguf \
--mtp gguf/DeepSeek-V4-Flash-DSpark-support.gguf \
--dspark --temp 0

--mtp는 지원 GGUF를 제공하며, --dspark는 DSpark 런타임을 선택합니다. 기본 신뢰도 임계값 (confidence threshold)은 0.9이며, 이는 검증 비용을 상쇄할 가능성이 낮은 접미사 (suffixes)를 제거합니다. --dspark-confidence 0은 고정된 5개 토큰 블록을 강제하며 진단용으로 의도되었습니다. 샘플링 디코딩 (Sampled decoding)은 DSpark 제안을 사용하지 않습니다. --quality 및 --dspark-strict 또한 타겟 전용 디코딩 (target-only decoding)을 유지하며, 이는 비교 및 정확성 확인에 유용합니다.

경고: 벤치마크 결과를 업데이트하지 않고 런타임 속도를 개선한 최적화 노력으로 인해, 일부 수치는 더 이상 업데이트되지 않을 수 있습니다.

이 수치들은 --ctx 32768, --nothink, 그리디 디코딩, 그리고 -n 256을 사용한 단일 실행 Metal CLI 수치입니다.

. 짧은 프롬프트 (short prompt)는 일반적인 작은 이탈리아 이야기 프롬프트입니다. 긴 프롬프트 (long prompts)는 청크 단위 프리필 (chunked prefill) 및 긴 컨텍스트 디코딩 (long-context decode)을 테스트합니다. Q4는 더 큰 메모리를 가진 머신 클래스를 요구하므로, M3 Max Q4 수치는 N/A입니다.

.

일반적인 Metal 경로는 모델이 GPU 주소 지정 가능 메모리 (GPU-addressable memory)에 상주하도록 시도합니다. 이것이 가장 빠른 경로이며, 모델이 메모리에 들어갈 때는 기본값으로 유지해야 합니다. DwarfStar는 Metal 환경과 ROCm 환경의 GLM 5.2를 위해 SSD 스트리밍 (SSD streaming) 기능 모드를 제공합니다. 이 모드에서는 라우팅되지 않는 모델 가중치 (non-routed model weights)는 상주하는 반면, 라우팅된 MoE 전문가 (routed MoE experts)들은 인메모리 캐시 (in-memory cache)에 유지되며, 캐시 미스 (cache miss) 발생 시 GGUF 파일로부터 로드됩니다.

스트리밍은 전체 모델을 RAM에 맞추는 것만큼 빠르지는 않습니다. 여전히 라우팅되지 않는 가중치, KV 캐시 (KV cache), 그래프 스크래치 (graph scratch), 활성화 값 (activations), 그리고 라우팅된 전문가 캐시를 위한 메모리가 필요합니다. 하지만 라우팅된 전문가들이 모델 크기의 대부분을 차지하고, 최신 Mac의 SSD는 캐시 미스를 허용할 수 있을 만큼 충분히 빠르기 때문에 유용합니다. 긴 프리필 (long prefills)은 여전히 빠를 수 있지만, 생성 (generation) 단계는 매 새로운 토큰이 다시 전문가를 통해 라우팅되기 때문에 캐시 미스에 더 민감합니다.

자동 캐시 예산 (automatic cache budget)으로 시작하세요:

./ds4 -m ./ds4flash.gguf --ssd-streaming