antirez/ds4 · 上手攻略
- 仓库：antirez/ds4
- 链接：https://github.com/antirez/ds4
- 分类：llm-infra · trending · production
- 作者：Jay
- 更新：2026-07-06
这是什么
ds4（DwarfStar）是意大利程序员 Salvatore Sanfilippo（网名 antirez，Redis 作者）用纯 C 语言手写的本地推理引擎，专门针对 DeepSeek V4 Flash 和 V4 PRO 两个权重模型优化。与一般 GGUF 通用加载器不同，它是专为这两款模型定制的闭着眼睛优化路径——不是万金油，而是专精选手。
项目有三大目标：1）本地跑得飞快；2）提供配套 GGUF 权重文件；3）直接集成 Coding Agent 对接能力。换句话说，ds4 不只是跑模型，还附带让 Claude Code / Codex 直接调用的接口。
核心定位：让 DeepSeek V4 在 96GB+ 内存的 Mac Studio / MacBook Pro / DGX Spark 上真正可用，而不是"能跑但龟速"。
解决什么问题
本地跑大语言模型有三个痛点：1）模型太大塞不进显存/RAM；2）上下文窗口一大就爆显存；3）跑起来太慢没实用价值。ds4 分别对应解决：
- 非对称 2-bit 量化：只量化 Routed MoE 专家层（占模型体积大头），其他层保持高精度，整体 Q2_K 量化下质量损失极小，30B+ 级别的模型体积大幅缩小。
- KV Cache SSD 流式处理：DeepSeek V4 的大上下文 KV Cache 设计本身就是为磁盘设计的，ds4 把路由专家层放在 SSD 上流式加载，MacBook 96GB 内存也能跑 32K 上下文——这是它最独门的设计哲学。
- Metal / CUDA / ROCm 三后端：Mac 上用 Metal（GPU 加速），NVIDIA DGX Spark 用 CUDA，Strix Halo（ROCm）系统用 ROCm，三条路线各自压榨硬件性能。
快速安装
前提条件
| 平台 | 最低内存 | 推荐配置 |
|---|---|---|
| macOS Metal | 96 GB（SSD 流式 64 GB 也行） | M3 Max / M5 Max MacBook Pro，M3 Ultra Mac Studio |
| Linux CUDA | 128 GB | DGX Spark（GB10） |
| Linux ROCm | 128 GB | Strix Halo 平台（如 Framework Desktop） |
⚠️ CPU 构建（
make cpu）仅用于诊断检查，不用于实际推理。macOS 上 CPU 构建有内核 panic bug，勿在生产环境使用。
下载 GGUF 权重
ds4 不加载通用 GGUF，只能用项目配套的专用权重：
# 下载脚本（从 HuggingFace antirez/deepseek-v4-gguf 获取）
git clone https://github.com/antirez/ds4.git
cd ds4
# 96/128 GB 内存机器 → Flash q2 imatrix 版（推荐起步）
./download_model.sh q2-imatrix
# >= 256 GB 内存机器 → Flash q4 imatrix
./download_model.sh q4-imatrix
# 512 GB 内存机器 → PRO q2 imatrix（质量更高）
./download_model.sh pro-q2-imatrix
# 完整 PRO Q4 分布式（两台 256 GB 机器各跑一半）
./download_model.sh pro-q4-layers00-30 # 第一台
./download_model.sh pro-q4-layers31-output # 第二台
脚本会自动把下载的 GGUF 软链接为 ./ds4flash.gguf，断点续传用 curl -C -。
编译
# macOS Metal（默认）
make
# Linux CUDA（DGX Spark / GB10）
make cuda-spark
# Linux CUDA（其他 NVIDIA GPU）
make cuda-generic
# CPU 仅诊断构建
make cpu
编译产物为 ./ds4（CLI）和 ./ds4-server（HTTP API 服务）。
核心用法
1. 基本 CLI 推理
# 最简单用法，默认读取 ./ds4flash.gguf
./ds4
# 带参数：指定模型路径、上下文长度、不调用思考模型
./ds4 \
-m ./ds4flash.gguf \
--ctx 32768 \
--nothink \
-n 256
--ctx N：上下文窗口大小，最大 32768 tokens--nothink：跳过 thinking/chain-of-thought 路径，直接输出答案-n N：最多生成 N 个 token
2. 启动 HTTP API 服务（Server 模式）
./ds4-server -m ./ds4flash.gguf --port 8080 --ctx 32768
服务启动后可通过 REST API 与 coding agent 对接，具体接口格式见 GitHub 仓库 ds4-agent/ 目录。
3. SSD 流式推理（内存不够时）
# 自动估算专家缓存大小（推荐起步）
./ds4 -m ./ds4flash.gguf --ssd-streaming
# 手动指定路由专家缓存（32GB = 缓存可容纳的完整专家层数量）
./ds4 -m ./ds4flash.gguf --ssd-streaming --ssd-streaming-cache-experts 32GB
⚠️ 注意：
--ssd-streaming-cache-experts是完整专家层数量，不是字节数。80% 自动档会从 Metal 推荐工作集中减去非路由权重后剩余空间来计算。
4. 启用投机解码（MTP）
# 先下载 MTP GGUF 辅助文件
./download_model.sh mtp
# 启动时加 --mtp（目前实验性，速度提升有限）
./ds4 -m ./ds4flash.gguf --mtp --ctx 32768
5. 调试与问题排查
# 开启完整 trace 日志
./ds4 -m ./ds4flash.gguf --trace # 提交 issue 时附上完整 trace
性能参考（官方 benchmarks）
| 机器 | 量化 | Prefill | Generation |
|---|---|---|---|
| MacBook Pro M3 Max 128GB（q2） | 短 prompt | 58.52 t/s | 26.68 t/s |
| MacBook Pro M3 Max 128GB（q2） | 11709 tokens 长 | 250.11 t/s | 21.47 t/s |
| MacBook Pro M5 Max 128GB（q2） | 11707 tokens | 463.44 t/s | 25.90 t/s |
| Mac Studio M3 Ultra 512GB（q2） | 11709 tokens | 468.03 t/s | 27.39 t/s |
| Mac Studio M3 Ultra 512GB（q4） | 12018 tokens | 448.82 t/s | 26.62 t/s |
| DGX Spark GB10 128GB（q2） | 7047 tokens | 343.81 t/s | 13.75 t/s |
⚠️ 数据来源为项目 README 标注的测试结果，实际性能因模型版本、macOS 版本差异可能有所不同，仅供参考。
典型适用场景
- 私密代码辅助：不想把代码发到云端，在本地跑 DeepSeek V4 做代码补全 / 审查 / 重构。
- 大上下文本地推理：需要 16K-32K 上下文分析大文件（代码库、论文），但又不想用云端 API。
- 离线开发环境：网络受限或需要完全离线运行的开发场景。
- 开发者调试 Coding Agent：ds4 的 server API 本身就是为 Claude Code / Codex 接入设计的，适合验证本地 agent 工具链。
- 量化研究对比：项目提供 imatrix 量化版本，适合对比不同量化精度对特定任务的影响。
坑与注意
-
只能用配套 GGUF：ds4 不加载通用的 DeepSeek GGUF 或其他模型。下载错了或者自己从别处复制过来都会报错。权重只能从
antirez/deepseek-v4-gguf（HuggingFace）下载。 -
PRO 版需要大内存：PRO q2 在 128GB MacBook 上生成速度只有 ~9.56 t/s，属于"能跑但慢"级别。如果追求体验，至少 512GB Mac Studio 上 PRO q2 才有实用价值。
-
macOS Metal SSD 流式是折中方案：SSD 流式不是银弹——长文本生成时每个新 token 都要重新路由专家，缓存 miss 多时速度明显下降。适合 prefilled 读取，不适合长篇流式对话。
-
MTP 投机解码目前效果有限：README 明确说当前 MTP 路径"at most a slight speedup"，不要抱太高期望。
-
macOS 虚拟内存 bug：CPU 推理路径在某些 macOS 版本上会触发内核 panic。官方建议用 Metal 构建，勿在生产环境跑 CPU 版本。
-
项目处于 beta 状态：README 自述代码"beta quality"，大版本更新可能带来 API 变化。
-
ds4-agent 是 alpha 状态：项目后期才加入的 agent 集成功能，质量不如核心推理引擎。
与同类对比
| 项目 | 支持模型 | 内存要求 | 量化方式 | 后端 | 特色 |
|---|---|---|---|---|---|
| ds4 | 仅 DeepSeek V4 Flash/PRO | 96GB+（SSD流式可更低） | 非对称 Q2（MoE专量化） | Metal/CUDA/ROCm | 专为DS V4定制，SSD KV流式 |
| llama.cpp | 通用于多种模型 | 取决于模型 | 对称量化（Q4/Q8等） | CPU/CUDA/Metal/... | 通用性最强，生态最广 |
| Ollama | 大量模型 | 取决于模型 | 主要是 Q4 | CUDA/Metal | 一键运行，用户体验最好 |
| LM Studio | 多种模型 | 取决于模型 | Q4/K/Q | CUDA/Metal | GUI界面，模型管理方便 |
| Jan | 多种模型 | 取决于模型 | 多种 | CUDA/Metal | 本地 agent 方向 |
结论：如果你只跑 DeepSeek V4 且追求最大优化，ds4 是当前最专精的选择；如果需要通用性、换模型省心，llama.cpp/Ollama 更合适。ds4 的 SSD KV 流式设计是它在 96GB 机器上能跑 32K 上下文的独门武器，其他通用加载器在这个内存档位很难做到。
一句话推荐结论
ds4 是当前 DeepSeek V4 本地推理的天花板优化工具——如果你有大内存 Mac/工作站且只跑 DS V4，它值得优先尝试；如果需要通用性或内存不够 96GB，Ollama/llama.cpp 生态更成熟。