DwarfStar：antirez 为 DeepSeek V4 打造的本地推理引擎

Redis 之父 antirez（Salvatore Sanfilippo）出手了。他没有继续打磨 Redis，而是用纯 C 写了一个专门为 DeepSeek V4 Flash 优化的本地推理引擎——DwarfStar（项目名 ds4）。不到一个月，GitHub 星标突破 12,000。

这不是又一个 GGUF 加载器。DwarfStar 的野心是：把一个 284B 参数的 MoE 大模型，在 96GB 内存的 MacBook 上做到「用起来像云服务」的体验——包括磁盘 KV 缓存持久化、原生编程 Agent、OpenAI/Anthropic 兼容 API、以及跨机器分布式推理。

一、为什么 DeepSeek V4 Flash 值得一个专属引擎

antirez 在项目文档里列了九条理由，核心逻辑可以浓缩为三点：

模型够大，思考够短，KV 够省。

DeepSeek V4 Flash 是一个 284B 参数的 MoE 模型（激活参数约 37B），支持 100 万 token 上下文窗口。和 27B 或 35B 的稠密模型相比，它在知识边界处的表现明显更强——问意大利政治、冷门技术细节，差距立刻显现。

更关键的是它的 thinking 模式：思考链长度只有其他模型的五分之一，且与问题复杂度成正比。这意味着在本地有限上下文窗口里，DeepSeek V4 Flash 可以开 thinking 模式正常使用，而其他模型的思考链会把上下文撑爆。

KV 缓存压缩率极高，配合现代 MacBook 的高速 SSD，antirez 提出了一个颠覆性的观点：KV 缓存应该是一等磁盘公民，而不仅仅是内存中的临时数据。

二、DwarfStar 的技术架构

DwarfStar 的架构可以用一句话概括：围绕一个模型做垂直整合。

推理核心

整个引擎的核心是 ds4.c——一个纯 C 实现的文件，包含 Tokenizer、Graph Backend、KV Session 管理、采样器和 Prompt 渲染器。不链接 GGML，但深度借鉴了 llama.cpp 的量化格式、内核和工程经验。

antirez 在文档开头就致谢了 llama.cpp 和 Georgi Gerganov：「这个项目不会存在，如果没有 llama.cpp 和 GGML 打开的道路。」

后端支持

非对称量化：只量化该量化的

DwarfStar 的 2-bit 量化方案不是简单的「全部压到 2 bit」。它的策略是非对称的：

• 路由 MoE 专家（占模型绝大部分空间）：up/gate 用 IQ2_XXS，down 用 Q2_K
• 共享专家、投影层、路由层：保持原始精度不动

这种「抓大放小」的量化方式，让 2-bit 版本在编程 Agent 场景下依然可靠——工具调用准确，生成质量可接受。实测中，96GB 的 MacBook 可以跑 2-bit 量化版本，甚至有用户报告在 96GB 机器上跑通了 250k 上下文窗口。

三、磁盘 KV 缓存：重启即恢复

这是 DwarfStar 最具特色的设计之一。

传统推理引擎的 KV 缓存存在内存里，会话结束就丢了。DwarfStar 把 KV 缓存写到磁盘上，用渲染后文本的 SHA1 作为文件名。下次请求进来时，先做 token 前缀匹配，命中就直接恢复，不需要重新 prefill。

缓存文件结构：

1
2
3
4
5
6
7
8
9
10
11
12

KVC 固定头部（48 字节）
├── 缓存 token 数量
├── 命中次数
├── 上下文大小
├── 创建/最后使用时间
├── 会话 payload 字节数
渲染后文本（UTF-8）
DS4 会话 payload
├── checkpoint token IDs
├── 下一个 token 的 logits
├── 压缩 KV 行 + 索引器状态
└── 工具调用 ID 映射（可选）

四个写入时机：首次长 prompt 完成（cold）、生成到达对齐边界（continued）、无关请求替换当前会话（evict）、服务器正常退出（shutdown）。

对于编程 Agent 场景，这意味着：Claude Code 的初始 25k token prompt 只需要 prefill 一次，之后的会话切换、服务器重启都可以从磁盘恢复。

四、分布式推理：两台 MacBook 跑满血模型

DwarfStar 支持 Coordinator-Worker 架构的分布式推理。核心场景是：用两台 128GB 的 MacBook 跑 4-bit 量化的 Flash 模型——每台只加载一半层，激活值通过 TCP 传输。

prefill 阶段可以流水线化：coordinator 处理第 N+1 个 chunk 的同时，worker 处理第 N 个 chunk 的后续层。实测两台 M5 Max 通过 Thunderbolt 5 连接，长 prompt prefill 加速比达到 1.85x。

但生成阶段是严格自回归的——token N+1 必须等 token N 完成，跨机器传输会带来约 20% 的性能损失。所以分布式的主要价值是让模型跑起来，而不是让生成更快。

Internet/VPN 模式虽然慢，但仍然有用：多个人可以临时拼凑机器来跑一个单机放不下的大模型。

五、内置编程 Agent

DwarfStar 有一个原生的编程 Agent（ds4-agent），和其他 Agent 系统的关键区别是：推理在 Agent 内部直接控制，没有 socket/API 边界。会话就是磁盘上的 KV 缓存本身。

这带来几个优势：

• 低延迟：显示生成文本、工具调用、新会话开始都是即时的
• 不会出现 KV 缓存不匹配：当前状态永远是真实的
• 会话切换零成本：/list 列出保存的会话，/switch 直接恢复，不需要 prefill
• 工具调用原生支持：不经过 DSML 转换，直接用 LLM 原生格式

Agent 的会话存储在 ~/.ds4/kvcache，支持 /save、/list、/switch、/del、/strip 等命令。

六、Server API：开箱即用的兼容层

ds4-server 提供 OpenAI 和 Anthropic 兼容的 HTTP API：

工具调用处理是技术亮点之一。DeepSeek V4 用 DSML 格式输出工具调用，但客户端返回的是 OpenAI/Anthropic JSON 格式。如果服务端重新渲染的 DSML 和模型原始输出不一致，KV 缓存就会失效。

DwarfStar 的解决方案是「精确回放」：每个工具调用分配一个不可猜测的 ID，服务端记住 ID → 原始 DSML 文本 的映射。客户端返回工具结果时，直接用原始字节，不重新格式化。

工具调用生成时，DSML 语法结构部分强制 temperature=0（保证可解析），参数内容部分使用正常的采样设置（避免重复文本）。

七、性能实测

以下是 Metal 平台的单机性能数据（--ctx 32768，greedy decoding）：

M5 Max 相比 M3 Max 的生成速度提升约 28%——从 26.68 t/s 到 34.27 t/s。

八、与 llama.cpp 的关系

DwarfStar 不是 llama.cpp 的竞品，而是建立在 llama.cpp 基础上的垂直定制。项目明确承认使用了 GGML 的量化布局、CPU 量化逻辑和部分内核，许可证文件保留了 GGML 的版权声明。

两者的定位差异在于：llama.cpp 追求通用性，支持尽可能多的模型；DwarfStar 追求深度，只服务一个模型但做到极致。如果你只跑 DeepSeek V4，DwarfStar 提供的体验更完整——从量化到 Agent 到 API 都是为这个模型量身定制的。

九、局限性

DwarfStar 有明确的局限，antirez 也没有试图掩盖：

• 模型锁定：只能跑 DeepSeek V4 Flash/PRO 的专用 GGUF，不能加载通用 GGUF 文件
• Beta 质量：代码存在不到一个月，可能有未发现的问题
• Agent 是 Alpha：内置编程 Agent 功能还在早期
• 高内存门槛：最低 96GB RAM（MacBook），PRO 需要 512GB（Mac Studio）
• 协议未加密：分布式推理的 TCP 通信没有加密和认证，只能在可信网络上使用
• AI 辅助开发：项目坦诚使用了 GPT 5.5 辅助编码，不适合对 AI 生成代码有顾虑的用户
• macOS CPU 路径有内核 bug：当前 macOS 版本的虚拟内存实现有 bug，CPU 推理会触发内核崩溃

十、快速上手

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 克隆仓库
git clone https://github.com/antirez/ds4.git
cd ds4

# 下载 2-bit 量化模型（96/128GB 机器）
./download_model.sh q2-imatrix

# 构建（macOS Metal）
make

# 交互式聊天
./ds4

# 启动 API 服务器
./ds4-server --ctx 100000 --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192

# 启动编程 Agent
./ds4-agent

CUDA 构建需要指定目标：

1
2

make cuda-spark      # DGX Spark / GB10
make cuda-generic    # 其他本地 CUDA GPU

相关链接

• GitHub 仓库
• antirez 博客
• DeepSeek V4 官方文档
• llama.cpp（DwarfStar 的技术基础）
• GGML 量化格式说明