DwarfStar 4 (ds4) | Mac Studio 原生部署 DeepSeek V4 Flash 完整指南

ds4 是 Redis 创始人 antirez (Salvatore Sanfilippo) 于 2026 年 5 月用几千行纯 C 代码写成的 DeepSeek V4 Flash 专用推理引擎。它不是通用框架，而是围绕 DeepSeek V4 Flash 这一款模型做深度优化的「专属高速公路」—— 包括模型加载、KV 状态管理、Metal 推理内核以及 OpenAI / Anthropic 双协议 HTTP API 的全栈实现。

🚀 为什么 ds4 是 128GB Mac Studio 的最佳路径？
• q2 不对称量化 — 模型仅需 ~81 GB，在 128GB 设备上留出充裕的 KV 缓存空间
• 磁盘 KV 缓存 (Disk KV Cache) — 长上下文持久化到 SSD，重启服务后无需重新预填充
• 1M 超长上下文 — 原生支持百万 token，应对整库代码、长文档毫无压力
• Agent 就绪 — 工具调用稳定，可无缝接入 Claude Code / opencode 等生态

📦 项目与模型信息

项目	GitHub · antirez/ds4
模型仓库	Hugging Face · antirez/deepseek-v4-gguf
技术栈	C (55.4%) / Objective-C (30.2%) / Metal (13.8%)
硬件门槛	Apple Silicon (M1/M2/M3/M4)，96GB+ 内存（q2 量化推荐 128GB）
macOS	14.0 或更高版本 + Xcode Command Line Tools

⚙️ 部署步骤（完整实操）

1️⃣ 克隆仓库并编译

git clone https://github.com/antirez/ds4.git
cd ds4
make

编译完成后当前目录下会生成三个可执行文件：ds4 (CLI交互)、ds4-server (HTTP API服务)、ds4-bench (性能测试)。

2️⃣ 下载量化模型（必须使用专用 GGUF）

⚠️ 核心提醒：只能从 antirez/deepseek-v4-gguf 仓库下载。普通 DeepSeek GGUF 缺少必需的 tensor layout 和元数据，会加载失败。

📌 你的 128GB Mac Studio 请选择 q2 量化版 (≈81 GiB)，内存占用最优，Agent 能力保留出色。

方法 A：使用内置脚本（最推荐）

./download_model.sh q2

脚本自动下载主模型 deepseek-v4-flash-q2.gguf 和 MTP draft 模型 mtp-draft-q2.gguf（约 3.6 GiB，用于推测解码加速）。

方法 B：手动下载（huggingface-cli）

pip install huggingface-hub
huggingface-cli download antirez/deepseek-v4-gguf deepseek-v4-flash-q2.gguf --local-dir ./
huggingface-cli download antirez/deepseek-v4-gguf mtp-draft-q2.gguf --local-dir ./

3️⃣ 启动推理服务（推荐 API 模式）

使用 ds4-server 启动 HTTP 服务，支持 OpenAI/Anthropic 兼容接口。以下为针对 500K 上下文的推荐启动命令：

./ds4-server \
  --model deepseek-v4-flash-q2.gguf \
  --draft mtp-draft-q2.gguf \
  --ctx-size 500000 \
  --disk-cache ./kv_cache

参数说明：
• --ctx-size 500000 — 设置上下文为 500K token (可根据需求调整至 200K~1M)
• --disk-cache ./kv_cache — 开启磁盘 KV 缓存，对长上下文 极！其！重！要！
• 默认监听地址 http://localhost:8080，可用 --port 8888 修改端口。

⚠️ 特别提醒（Claude Code 用户）
Claude Code 的初始 prompt 通常超过 25k token，务必开启 Disk KV Cache，否则每次启动都要重新预填充，耗时漫长。ds4 的磁盘缓存支持跨进程、跨重启持久化，第二次请求相同长 prompt 时 TTFT 可缩短 6 倍以上。

4️⃣ 测试 CLI 交互（可选）

./ds4 --model deepseek-v4-flash-q2.gguf --draft mtp-draft-q2.gguf

可附加参数 --no-thinking 关闭思考模式（简单任务提速）、--ctx-size 200000 等。

🔌 API 调用与 Agent 生态集成

支持的核心端点

端点	说明
`/v1/chat/completions`	OpenAI 标准对话接口
`/v1/completions`	文本补全
`/v1/messages`	Anthropic 风格消息接口
`/v1/models`	模型列表查询

curl 调用示例

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [{"role": "user", "content": "介绍 ds4 的核心设计理念"}]
  }'

接入 Claude Code / opencode

Claude Code 通过 Anthropic 兼容端点对接：

export ANTHROPIC_BASE_URL="http://localhost:8080"
export ANTHROPIC_API_KEY="dummy"
claude

opencode 或其他 Agent 框架：将 API endpoint 指向 http://localhost:8080，选择 openai / anthropic 协议适配即可。ds4 完整支持 工具调用（Function Calling / Tool Use），智能体任务可靠稳定。

📊 性能实测参考

设备	量化	场景	预填充速度	生成速度
MacBook Pro M3 Max / 128GB	q2	短提示 · 32K	58.52 t/s	26.68 t/s
Mac Studio M3 Ultra / 512GB	q2	长提示(11.7K) · 1M上下文	468.03 t/s	36.86 t/s
Mac Studio M3 Ultra / 512GB	q4	短提示 · 200K	84.43 t/s	44.8 t/s

🧠 Disk KV Cache 实战增益
同一长 prompt 重发（同进程）：TTFT 从 19.04 秒 → 2.94 秒 (提速 6.47x)
服务重启后相同 prompt：TTFT 从 20.55 秒 → 3.11 秒 (提速 6.62x)
—— 对反复调用长上下文的场景体验飞跃。

⚠️ 重要注意事项 & 故障排查

模型必须匹配 — 仅使用 antirez/deepseek-v4-gguf 仓库中的专用 GGUF，其他来源无法加载。
内存门槛 — q2 量化强烈建议 128GB 统一内存，q4 需要 256GB+。你的 Mac Studio 128GB 正是 q2 的天选配置。
首次长上下文耗时正常 — 模型初次处理长 prompt 需要完整 prefill，可能数十秒，第二次请求因 Disk Cache 大幅提速。
Disk KV Cache 必须显式开启 — 启动时加 --disk-cache 路径，否则缓存不会落盘，且重启后无法恢复。
API 服务未响应 — 检查端口占用 netstat -an | grep 8080，或查看启动日志；确保没有防火墙拦截本地回环。
编译报错 / Metal 依赖缺失 — 执行 xcode-select --install，并确保 macOS SDK 已安装。

❗ 避坑指南
• 不要试图用 LM Studio / Ollama 加载 antirez 的 q2 GGUF — 这些工具没有 DS4 专用调度和 kv-cache 设计，会导致内存爆炸或极度低效。
• 普通社区 MLX 量化版在 MoE 路由器层上会完全失效，MMLU 跌至 25%，请认准 ds4 原生方案。

🧪 高级调优 & 参数说明

ds4-server 支持更多运行时参数：

--ctx-size <N> — 上下文长度，上限 1,000,000 (1M)。
--cache-size <MB> — 内存中 KV cache 上限（单位 MB），超出部分自动使用 disk cache。
--temp <float> — 采样温度，默认 0.7。
--top-p <float> — 核采样概率，默认 0.95。
--no-thinking — 禁用思考模式，适合简单问答提高速度。
--seed <int> — 随机种子。

若要变更 API 监听地址：--host 0.0.0.0 --port 8080 允许局域网访问（注意安全设置）。

📁 相关资源与延伸阅读

ds4 GitHub 官方仓库 — 源码、详细技术文档
Hugging Face 模型主页 — 下载 q2 / q4 专用 GGUF
antirez 博客 · A few words on DS4 — 作者设计哲学与性能解析
中文社区参考：知乎专栏 — ds4.c实战M3Ultra 512G部署 · 完整的基准测试数据

🎯 总结：为什么这是你当前最理想的解决方案？

对于 Mac Studio 128GB 统一内存，ds4 + q2 量化版是当下 唯一能够在本地流畅运行 DeepSeek V4 Flash (284B MoE) 且保留 Agent 能力的生产级方案。通过不对称 2-bit 压缩、磁盘 KV 缓存和纯 Metal 全图推理，它打破了超大模型对 256GB+ 内存的依赖，让百亿级参数真正走入桌面。

💡 三分钟启动速览（复制即用）

git clone https://github.com/antirez/ds4.git && cd ds4 && make

            ./download_model.sh q2

            ./ds4-server --model deepseek-v4-flash-q2.gguf --draft mtp-draft-q2.gguf --ctx-size 500000 --disk-cache ./kv_cache

启动成功后即可通过 http://localhost:8080 调用模型，将其接入 Claude Code / Cursor 等工具，获得完全本地的顶级 AI 编程与 Agent 体验。

🚀 从 MiniMax-M2.7 迁移到 ds4 将带来显著的智能提升、更长的上下文和更低的运行摩擦。试试这套方案，你的 Mac Studio 会真正进化成一台「本地超级智能引擎」。

🧠 DwarfStar 4 (ds4) v1.0 · 原生推理引擎