DS4 分布式Shell客户端

项目概述

DwarfStar 是一个面向本地硬件优化的专用推理引擎，并非通用 GGUF 加载器。它针对 DeepSeek V4 Flash 做了深度优化，同时支持 GLM 5.2，在超大内存机器上可运行 DeepSeek V4 PRO。模型加载、提示渲染、工具调用、KV 状态、HTTP 服务与编程代理等模块协同构建与测试。

支持的后端：

• Metal：主要目标平台，适用于 96 GB 及以上的 Mac；较小内存机型可使用 SSD 流式加载。
• NVIDIA CUDA：覆盖多卡系统与 DGX Spark。
• ROCm：支持 Strix Halo 等架构（如 Framework Desktop）。

主要用途

• 在消费级硬件（MacBook、DGX Spark、Strix Halo）上运行能力较强的模型；内存不足时可借助 SSD 流式以尚可接受的速度运行。
• 利用 CUDA 多卡与 ds4-server 微批处理，将搭载旧款 Ada Lovelace 架构 GPU（如 8×L40S）的服务器改造为多用户 LLM 服务。实测聚合生成 120 t/s、预填充 2000 t/s。
• 使用两台 MacBook M5 Max / M3 Ultra 通过 RDMA 进行张量并行，运行 4 bit DeepSeek Flash 或 GLM 5.2。
• 使用流水线并行将多台机器的内存聚合，运行更大的模型。

设计动机

• 高性能开源权重模型已可装入高端个人设备。
• DeepSeek V4 Flash/PRO 与 GLM 5.2 对路由专家激进量化具有良好容忍度。
• 压缩 KV 缓存与高速本地 SSD 使长上下文成为现实。
• 专注于少数模型的专用推理系统具备工程价值。

构建方式

make                  # macOS Metal
make cuda-spark       # Linux CUDA，DGX Spark / GB10
make cuda-generic     # Linux CUDA，其他本地 CUDA GPU
make strix-halo       # Linux ROCm，AMD Strix Halo
make cpu              # 仅 CPU 的诊断构建

构建产物 ds4 与 ds4-server 默认读取 ./ds4flash.gguf 作为模型路径，可通过 -m 指定其他 GGUF。

模型下载

仅支持指定的 DeepSeek V4 与 GLM 5.2 GGUF 格式。2 bit 量化方案仅对路由 MoE 专家进行极不对称量化（up/gate 使用 IQ2_XXS，down 使用 Q2_K），其余组件保持原精度以确保质量。

./download_model.sh ds4f-q2          # 96/128 GB 内存机型
./download_model.sh ds4f-q2-q4       # q2 末尾 6 层专家为 q4
./download_model.sh ds4f-q4          # ≥256 GB 内存机型
./download_model.sh ds4f-mxfp4       # 原生 MXFP4 专家，约 156 GB
./download_model.sh pro-q2-imatrix   # 512 GB 内存机型的 PRO q2

PRO Q4 分布式运行需分别在两台机器下载分片：

./download_model.sh pro-q4-layers00-30
./download_model.sh pro-q4-layers31-output

GLM 5.2 支持以下目标：

./download_model.sh glm-unsloth-q4
./download_model.sh glm-antirez-iq2xxs
./download_model.sh glm-antirez-q2
./download_model.sh glm-antirez-q4

DSpark 投机解码

DSpark 是 DeepSeek 为 Flash 发布的辅助草稿模型，读取主模型的隐状态并提议最多 5 个未来 token，主模型校验后仅提交被接受的前缀。--mtp 指定辅助 GGUF，--dspark 启用 DSpark 路径，默认置信度阈值 0.7。DSpark 仅加速生成，不加速预填充，对代码类等可预测续写收益最大，仍属实验性功能。

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

性能概览

使用 ds4-bench 与标准 Promessi sposi 输入测得：

机器	后端	上下文	预填充	生成
MacBook Pro M5 Max 128 GB	Metal	2048	790.18 t/s	39.35 t/s
MacBook Pro M5 Max 128 GB	Metal	16384	572.53 t/s	36.14 t/s
MacBook Pro M5 Max 128 GB	Metal	32768	557.04 t/s	34.36 t/s
MacBook Pro M5 Max 128 GB	Metal	65536	398.50 t/s	27.64 t/s
DGX Spark GB10 128 GB	CUDA	2048	825.76 t/s	18.05 t/s
DGX Spark GB10 128 GB	CUDA	65536	822.98 t/s	13.84 t/s

超出内存容量的 SSD 流式

SSD 流式模式将非路由权重常驻内存，路由 MoE 专家通过内存缓存与 GGUF 文件按需加载。流式比完全装入内存更慢，但适合 64 GB 等较小机型。

./ds4 -m ./ds4flash.gguf --ssd-streaming
./ds4 -m ./ds4flash.gguf --ssd-streaming --ssd-streaming-cache-experts 32GB

32GB 表示路由专家内存预算；纯数字则表示动态专家槽位数。自动预算取后端推荐工作集的 80%，扣除非路由权重与预填充预留后分配专家缓存。

流水线并行

流水线并行将 Transformer 层拆分到多台机器运行，适合单台机器无法容纳的模型。--layers 控制每进程映射的层区间（如 0:30 或 31:output）。一台机器担任协调者，其余为 worker；激活通过 TCP 在 worker 之间直传。

预填充可流水线化（大数据集上能比单机更快），但生成为严格自回归：每生成一个 token 需经过完整路径，因此分布式生成通常慢于单机。

两台 M5 Max（Thunderbolt 5）实测分布式预填充：9421 token 提速 1.38×，28684 token 提速 1.66×，63819 token 提速 1.85×。

最小两机配置示例：

# 机器 A：协调者，持有 0..30 层
./ds4 -m gguf/DeepSeek-V4-Pro-Q4K-Layers00-30.gguf \
  --role coordinator --layers 0:30 \
  --listen 169.254.43.68 1234

# 机器 B：worker，持有 31..output 层
./ds4 -m gguf/DeepSeek-V4-Pro-Q4K-Layers-31-output.gguf \
  --role worker --layers 31:output \
  --coordinator 169.254.43.68 1234

常用调优选项包括 --dist-prefill-window N、--dist-prefill-chunk N、--dist-activation-bits 16|8。--debug 在协调者侧输出路由建立与逐跳延迟信息。