- Apple Metal GPU에 최적화된 DeepSeek V4 Flash 전용 로컬 추론 엔진으로, 범용 GGUF 러너가 아닌 단일 모델에 집중한 네이티브 C 구현체
- DeepSeek V4 Flash는 활성 파라미터 수가 적어 빠른 속도를 제공하며, thinking 모드에서 다른 모델 대비 1/5 수준의 짧은 사고 구간 생성
- 100만 토큰 컨텍스트 윈도우와 극도로 압축된 KV 캐시를 통해 로컬 환경에서도 장문맥 추론이 가능하며, 디스크 KV 캐시 영속화 지원
- OpenAI 및 Anthropic 호환 HTTP API 서버를 내장해 Claude Code, opencode, Pi 등 다양한 코딩 에이전트와 즉시 연동 가능
- llama.cpp와 GGML 생태계의 기반 위에 구축되었으며, GPT 5.5의 강력한 코딩 지원을 받아 개발된 프로젝트
프로젝트 개요 및 설계 철학
ds4.c는 DeepSeek V4 Flash 전용 소형 네이티브 추론 엔진으로, 범용 GGUF 러너나 다른 런타임의 래퍼가 아님- 핵심 경로는 DeepSeek V4 Flash에 특화된 Metal 그래프 실행기이며, DS4 전용 로딩, 프롬프트 렌더링, KV 상태, 서버 API 접착 코드 포함
- 로컬 추론 분야에 우수한 프로젝트가 많지만, 새 모델이 계속 등장하면서 관심이 분산되는 문제가 존재
- 이 프로젝트는 한 번에 하나의 모델에 의도적으로 집중하며, 공식 벡터 검증(logits), 장문맥 테스트, 에이전트 통합까지 수행
- 로컬 추론의 비전: A) HTTP API가 포함된 추론 엔진 + B) 특정 엔진에 최적화된 GGUF + C) 코딩 에이전트 구현체를 통한 테스트 및 검증, 이 세 가지가 함께 작동하는 것
- Metal 전용이며, 향후 CUDA 지원 가능성은 있으나 확정되지 않음
- CPU 경로는 정확성 검증용으로만 존재하며, 현재 macOS 버전의 가상 메모리 구현 버그로 인해 CPU 코드 실행 시 커널 크래시 발생
- GPT 5.5의 강력한 지원을 받아 개발되었으며, 인간이 아이디어, 테스트, 디버깅을 주도
DeepSeek V4 Flash를 별도 엔진으로 만든 이유
- 활성 파라미터가 적어 더 빠른 추론 속도 제공
- thinking 모드에서 다른 모델 대비 1/5 수준의 짧은 사고 구간을 생성하며, 사고 구간 길이가 문제 복잡도에 비례
- 다른 모델이 thinking 모드에서 실용적으로 사용 불가능한 상황에서도 DeepSeek V4 Flash는 사용 가능
- 100만 토큰 컨텍스트 윈도우 지원
- 284B 파라미터 규모로 27B, 35B 모델 대비 지식의 경계에서 더 많은 정보를 알고 있음
- 이탈리아어 TV 프로그램, 정치 관련 질문 등에서 차이 확인 가능
- 영어와 이탈리아어 작문 품질이 준프론티어 모델 수준
- KV 캐시가 극도로 압축되어 로컬 컴퓨터에서 장문맥 추론이 가능하며, 디스크 KV 캐시 영속화 지원
- 특수 방식으로 양자화할 경우 2비트 양자화에서도 잘 작동하여 128GB RAM MacBook에서 실행 가능
- 향후 DeepSeek에서 V4 Flash 업데이트 버전 출시 예상
llama.cpp 및 GGML에 대한 감사
- ds4.c는 GGML에 링크하지 않지만, llama.cpp 프로젝트가 개척한 경로 위에 존재
- llama.cpp의 커널, 양자화 포맷, GGUF 생태계, 하드-원 엔지니어링 지식이 필수 참고 자료
- 일부 소스 레벨 코드가 MIT 라이선스 하에 유지 또는 적용됨: GGUF quant 레이아웃 및 테이블, CPU quant/dot 로직, 특정 Metal 커널 등
- LICENSE 파일에 GGML 저작자 저작권 표시 유지
모델 가중치
- 이 프로젝트 전용으로 게시된 DeepSeek V4 Flash GGUF만 작동하며, 임의의 DeepSeek/GGUF 파일은 호환되지 않음
- 2비트 양자화는 비대칭 양자화 방식 적용
- MoE 전문가(expert)만 양자화: up/gate는
IQ2_XXS, down은Q2_K - 공유 전문가, 프로젝션, 라우팅 등 나머지 컴포넌트는 양자화하지 않아 품질 보장
- MoE 전문가(expert)만 양자화: up/gate는
./download_model.sh q2로 128GB RAM 머신용,./download_model.sh q4로 256GB 이상 RAM 머신용 모델 다운로드- Hugging Face(
antirez/deepseek-v4-gguf)에서 다운로드하며,curl -C -로 부분 다운로드 재개 지원
- Hugging Face(
./download_model.sh mtp로 선택적 투기적 디코딩(speculative decoding) 지원 GGUF 다운로드 가능- MTP/투기적 디코딩 경로는 아직 실험적이며, 현재 약간의 속도 향상만 제공
속도 벤치마크
--ctx 32768,--nothink, greedy 디코딩,-n 256설정에서의 단일 실행 Metal CLI 수치- MacBook Pro M3 Max, 128GB (q2)
- 짧은 프롬프트: prefill 58.52 t/s, 생성 26.68 t/s
- 11709 토큰 프롬프트: prefill 250.11 t/s, 생성 21.47 t/s
- q4는 메모리 부족으로 N/A
- Mac Studio M3 Ultra, 512GB (q2)
- 짧은 프롬프트: prefill 84.43 t/s, 생성 36.86 t/s
- 11709 토큰 프롬프트: prefill 468.03 t/s, 생성 27.39 t/s
- Mac Studio M3 Ultra, 512GB (q4)
- 짧은 프롬프트: prefill 78.95 t/s, 생성 35.50 t/s
- 12018 토큰 프롬프트: prefill 448.82 t/s, 생성 26.62 t/s
CLI 사용법
-p옵션으로 원샷 프롬프트 실행,-p없이 실행하면 인터랙티브 멀티턴 채팅 모드 진입- 인터랙티브 CLI는 렌더링된 채팅 트랜스크립트와 라이브 Metal KV 체크포인트를 유지하여, 각 턴이 이전 대화를 확장
- 유용한 명령어:
/help,/think,/think-max,/nothink,/ctx N,/read FILE,/quit- Ctrl+C로 현재 생성 중단 후 프롬프트로 복귀
- 기본값은 thinking 모드이며,
/nothink또는--nothink로 직접 응답 모드 전환 --mtp MTP.gguf --mtp-draft 2로 선택적 MTP 투기적 경로 활성화 가능- greedy 디코딩에서만 유용하며, confidence gate(
--mtp-margin)를 사용해 느린 부분 수락 방지
- greedy 디코딩에서만 유용하며, confidence gate(
서버
- OpenAI/Anthropic 호환 로컬 HTTP 서버 실행 가능
- Metal 전용이며, 하나의 변경 가능한 그래프/KV 체크포인트를 메모리에 유지
- 상태 비저장 클라이언트가 동일 프롬프트의 더 긴 버전을 재전송하면 공유 접두사 재사용 가능
- 요청 파싱과 소켓은 클라이언트 스레드에서 실행되지만, 추론 자체는 단일 Metal 워커를 통해 직렬화
- 현재 서버는 여러 독립 요청을 일괄 처리하지 않으며, 동시 요청은 순서대로 대기
-
지원 엔드포인트
GET /v1/models,GET /v1/models/deepseek-v4-flashPOST /v1/chat/completions,POST /v1/completions,POST /v1/messages
-
/v1/chat/completions(OpenAI 호환)messages,max_tokens/max_completion_tokens,temperature,top_p,top_k,min_p,seed,stream,stream_options.include_usage,tools,tool_choice지원- 도구 스키마는 DeepSeek의 DSML 도구 포맷으로 렌더링되며, 생성된 DSML 도구 호출은 OpenAI 도구 호출로 역변환
-
/v1/messages(Anthropic 호환)- Claude Code 스타일 클라이언트용 엔드포인트
system,messages,tools,tool_choice,max_tokens,temperature,top_p,top_k,stream,stop_sequences, thinking 제어 지원- 도구 사용은 Anthropic
tool_use블록으로 반환
- 양쪽 API 모두 SSE 스트리밍 지원, thinking 모드에서 추론 과정은 네이티브 API 형태로 스트리밍
에이전트 클라이언트 연동
- ds4-server는 OpenAI 호환 chat completions을 사용하는 로컬 코딩 에이전트와 연동 가능
- 128GB RAM에서 2비트 quant(81GB)를 실행할 경우 100k~300k 토큰 컨텍스트 윈도우가 적절
- 전체 1M 토큰 컨텍스트는 약 26GB 메모리(압축 인덱서만 약 22GB) 사용
384000출력 제한 설정으로 토큰 캡 방지 가능 (모델은 최대 384k 토큰까지 생성 가능)-
opencode 연동
~/.config/opencode/opencode.json에 provider와 agent 항목 추가로 설정baseURL을http://127.0.0.1:8000/v1로 지정
-
Pi 연동
~/.pi/agent/models.json에 provider 설정 추가- DeepSeek의 thinking 포맷, reasoning effort 지원, 스트리밍 usage 지원 등 호환성 옵션 포함
~/.pi/agent/settings.json에서 기본 모델로 설정 가능
-
Claude Code 연동
- Anthropic 호환 엔드포인트 사용,
~/bin/claude-ds4래퍼 스크립트로 환경 변수 설정 ANTHROPIC_BASE_URL을 로컬 서버로 지정하고 모든 모델 변수를deepseek-v4-flash로 설정- Claude Code는 초기에 약 25k 토큰의 대형 프롬프트를 전송하므로,
--kv-disk-dir활성화 필수- 첫 번째 비싼 prefill 이후 디스크 KV 캐시가 저장된 접두사를 재사용하여 후속 세션에서 전체 프롬프트 재처리 불필요
- Anthropic 호환 엔드포인트 사용,
Thinking 모드
- DeepSeek V4 Flash는 non-thinking, thinking, Think Max 세 가지 모드 지원
- 서버 기본값은 thinking 모드
reasoning_effort=max로 Think Max 요청 가능하나, 컨텍스트 크기가 모델 카드 권장 사항에 충분히 큰 경우에만 적용- 작은 컨텍스트에서는 일반 thinking으로 폴백
- OpenAI
reasoning_effort=xhigh는 일반 thinking에 매핑되며, Think Max가 아님 - 직접 응답이 필요하면
thinking: {"type":"disabled"},think:false, 또는deepseek-chat같은 non-thinking 모델 별칭 사용
디스크 KV 캐시
- Chat/completion API는 상태 비저장이므로 에이전트 클라이언트는 매 요청마다 전체 대화를 재전송
- ds4-server는 렌더링된 토큰 스트림을 캐시된 토큰 접두사와 비교하여 처리
- 라이브 인메모리 체크포인트는 현재 세션 담당
- 디스크 KV 캐시는 세션 전환 및 서버 재시작 후 유용한 접두사를 유지하는 메커니즘
- 현재 메모리에는 하나의 라이브 KV 캐시만 존재하며, 새로운 비관련 세션이 이를 대체하면 이전 체크포인트는 디스크 KV 캐시에 기록된 경우에만 재처리 없이 재개 가능
--kv-disk-dir과--kv-disk-space-mb로 활성화-
캐시 키 및 파일 구조
- 캐시 키는 정확한 토큰 ID의 SHA1 해시이며, 원시 텍스트가 아님
- 각 토큰 ID는 리틀엔디안 32비트 정수로 해싱되며, 파일명은
<sha1>.kv - 일반
read/writeI/O로 기록하며mmap사용하지 않음 (이미 모델을 매핑하는 프로세스에 추가 VM 매핑 방지)
-
디스크 캐시 파일 레이아웃
- KVC 고정 헤더 48바이트: magic("KVC"), 버전, routed expert quant 비트, 저장 사유, 캐시된 토큰 수, 히트 카운트, 컨텍스트 크기, 생성/마지막 사용 Unix 타임, DS4 세션 페이로드 바이트 수
- 렌더링된 텍스트: 캐시된 토큰 접두사의 토크나이저 디코딩 텍스트 (관찰 용도, 키로 사용되지 않음)
- DS4 세션 페이로드: 13개의 리틀엔디안 u32 필드로 시작하며, magic("DSV4"), 페이로드 버전, 컨텍스트 크기, prefill 청크 크기, KV 링 용량 등 포함
- 체크포인트 토큰 ID, 다음 토큰에 대한 float32 logits, 레이어별 압축 어텐션 행 수, 라이브 raw 슬라이딩 윈도우 KV 행, 압축 레이어의 KV 행 및 compressor frontier 텐서 등 저장
-
체크포인트 저장 시점
cold: 긴 초기 프롬프트가 안정 접두사에 도달한 후, 생성 전continued: prefill 또는 생성이 설정된 간격만큼 진행될 때evict: 비관련 요청이 라이브 인메모리 세션을 대체하기 전shutdown: 서버가 정상 종료될 때
- cold 저장 시 작은 토큰 접미사를 트리밍하고 prefill 청크 경계에 정렬하여, 향후 요청에서 BPE 경계 재토큰화 미스 방지
- 기본값: 최소 512 토큰 접두사, cold 저장 최대 30000 토큰, 꼬리 32 토큰 트리밍, 2048 토큰 청크 정렬
- 기본적으로 2비트와 4비트 routed-expert 변형 간 토큰 접두사가 일치하면 체크포인트 재사용 가능
--kv-cache-reject-different-quant로 동일 양자화 전용 재사용 설정 가능
백엔드
- 기본 백엔드는 Metal (
--metal) - CPU 참조/디버그 경로도 존재 (
--cpu)하나 프로덕션 대상이 아님- 서버는 Metal 전용이며, 최적화된 구현은 Metal 그래프 경로에 존재
- MIT 라이선스, C/Objective-C/Metal 구현