DwarfStar：DeepSeek V4 专用本地推理引擎

DwarfStar 是一个小型原生推理引擎，首要针对 DeepSeek V4 Flash 进行了优化。它也支持 GLM 5.2，以及在内存容量极高的机器上运行 DeepSeek V4 PRO。它自成一体且刻意保持专用性，并不是通用的 GGUF 运行器。模型加载、提示词渲染、工具调用、KV 状态、HTTP 服务器和编码智能体均作为一个整体进行构建和测试。该仓库还包含用于 GGUF、imatrix、质量和速度的工具与数据。

Metal 是主要目标平台，适用于配备 96 GB 或更多内存的 Mac。内存较小的机器可以使用 SSD 流式加载。

支持 NVIDIA CUDA，包括多 GPU 系统和 DGX Spark。

支持 Framework Desktop 等 Strix Halo 系统上的 ROCm。

如果没有 llama.cpp 和 GGML，就不会有这个项目。请务必阅读致谢部分。衷心感谢 Georgi Gerganov 以及所有其他贡献者。

模型支持有意采取机会主义策略。该项目会跟进适合实用型本地机器内存容量的最佳开放权重模型，尤其是配备 128 GB 内存的笔记本电脑和配备 512 GB 内存的工作站。当更好的替代模型出现时，某个模型可能会被移除。

你可以在消费级硬件上运行能力非常强的模型，例如 MacBook、DGX Spark 或 Strix Halo。即使内存不足，也可以通过 SSD 流式加载以尚可的速度运行。

利用 CUDA 多 GPU 支持，以及 ds4-server 对解码和生成进行的微批处理，你可以将一台配备较旧 CUDA 显卡（Ada Lovelace 架构）、已不再受 vLLM 新模型支持的服务器，变成供公司使用的多用户 LLM 服务器。我们使用 8 块 NVIDIA L40S 显卡和多个会话测试了这种配置，取得了非常好的结果：聚合生成速度为 120 t/s，预填充速度为 2000 t/s。

通过两台采用 RDMA 连接的 MacBook M5 Max / M3 Ultra，你可以使用张量并行运行 4 位 DeepSeek Flash 或 GLM 5.2。

你还可以使用流水线并行将多个系统连接起来，汇总它们的内存以运行更大的模型。

能力强大的开放权重模型如今已经可以装入高端个人计算机。

DeepSeek V4 Flash 和 PRO、GLM 5.2 都能承受对路由专家的激进量化。

压缩 KV 缓存与高速本地 SSD 让长上下文变得切实可行。

其理念是打造一个专门服务于少数几个模型的推理系统。

本软件在 GPT 5.5、5.6 和 Claude Fable 的大力协助下开发，由人类主导构思、测试和调试。我们对此直言不讳，因为它影响了项目的构建方式。如果你无法接受由 AI 开发的代码，那么本软件并不适合你。下面的致谢同样重要：如果没有主要由人工编写的 llama.cpp 和 GGML，就不会有这个项目。

致谢 llama.cpp 和 GGML

ds4.c 并未链接 GGML，但它的诞生离不开 llama.cpp 项目所开辟的道路，也离不开该项目发展出的内核、量化格式、GGUF 生态系统以及历经艰辛积累的工程知识。我们感谢 llama.cpp 及其贡献者，也对他们心怀感激。在构建这条 DeepSeek V4 专用推理路径时，他们的实现、内核、测试和设计选择都是不可或缺的参考。本项目在 MIT 许可证下保留或改编了一些源码级内容：GGUF 量化布局和表、CPU 量化与点积逻辑，以及部分内核。因此，也因为我们由衷感激，我们在 LICENSE 文件中保留了 GGML 作者的版权声明。

本软件目前仍在快速变化。请将其视为 Beta 质量。每次发布之前都会执行大规模 QA，但仍然完全可能出现不稳定情况。

如果你正在寻找非常具体的内容，我们还有其他子 README 文件。否则，对于常规用法，请继续阅读后续章节。

CONTRIBUTING.md：面向贡献者的正确性和速度回归测试指南。提交拉取请求之前请先阅读此文件。

QA_BEFORE_RELEASES.md：完整的发布测试矩阵，包括远程 Metal、CUDA 和 ROCm 机器。

gguf-tools/README.md：离线 GGUF 生成、imatrix 收集、量化工具和质量检查。

gguf-tools/imatrix/README.md：如何收集和使用路由 MoE 的 imatrix。

gguf-tools/imatrix/dataset/README.md：如何生成校准提示词语料库。

gguf-tools/quality-testing/README.md：如何依据 DeepSeek V4 Flash/PRO 官方续写结果为本地 GGUF 评分。

dir-steering/README.md：方向性引导数据、向量生成及用法。

speed-bench/README.md：基准测试命令、图表和 CSV 生成。

tests/test-vectors/README.md：用于回归检查的官方续写向量。

此实现仅适用于下面列出的 DeepSeek V4 和 GLM 5.2 GGUF。它并非通用 GGUF 加载器，任意 GGUF 文件不会具备引擎所预期的张量布局、量化组合、元数据或可选 MTP 状态。这里提供的 2 位量化已经过验证，确实具有很高的质量：它们表现良好，可以在编码智能体中工作，并且能够可靠地调用工具。

2 位量化采用了高度非对称的量化方式：只量化路由 MoE 专家，其中 up/gate 使用 IQ2_XXS，down 使用 Q2_K。它们占据了模型绝大部分空间；其他组件（共享专家、投影、路由）则保持不变，以保证质量。

下载一个主模型。优先选择 imatrix 版本。

./download_model.sh q2-imatrix   # 96/128 GB RAM machines, imatrix-tuned q2
./download_model.sh q2-q4-imatrix  # 96/128 GB RAM machines, q2 with last 6 layers q4
./download_model.sh q4-imatrix   # >= 256 GB RAM machines, imatrix-tuned q4
./download_model.sh pro-q2-imatrix  # 512 GB RAM machines, PRO q2 imatrix quant

对于完整的 PRO Q4 分布式运行，请在每台机器上分别下载一半：

./download_model.sh pro-q4-layers00-30      # first half of PRO Q4 split
./download_model.sh pro-q4-layers31-output  # second half of PRO Q4 split

该脚本从 https://huggingface.co/antirez/deepseek-v4-gguf 下载文件，将其存储在 ./gguf/ 下，通过 curl -C - 续传未完成的下载，并更新 ./ds4flash.gguf，使其指向所选的主模型。pro-q4-layers00-30、pro-q4-layers31-output 和 pro-q4-split 目标会下载分布式 PRO Q4 分片，但不会更新 ./ds4flash.gguf。公共下载可以不进行身份验证，但如果提供了 --token TOKEN、HF_TOKEN 或本地 Hugging Face 令牌缓存，则会使用它们。

如果你想重新生成 GGUF 文件或收集新的 imatrix，请参阅 gguf-tools/README.md。这些工具用于离线模型构建工作，在完整的 DeepSeek V4 Flash 权重上可能需要很长时间。本地工具支持生成 Flash GGUF。PRO GGUF 的生成目前仍依赖外部基于 llama.cpp 的工作流；之后可以添加原生工具支持。

./download_model.sh mtp 会获取用于 Flash 的可选推测解码支持 GGUF。它可以与 q2-imatrix、q2-q4-imatrix 和 q4-imatrix 配合使用，但必须通过 --mtp 显式启用。当前的 MTP/推测解码路径仍处于实验阶段：它受到正确性门控，目前最多只能略微提速，无法显著提升生成速度。

GLM 5.2 支持仅限于此分支测试过的 GGUF 文件：

./download_model.sh glm-unsloth-q4  # Unsloth UD-Q4_K_XL, 11 shards
./download_model.sh glm-antirez-iq2xxs  # antirez routed IQ2_XXS single-file GGUF
./download_model.sh glm-antirez-q2  # antirez routed Q2_K single-file GGUF
./download_model.sh glm-antirez-q4  # antirez routed Q4_K single-file GGUF

受支持的 GLM 布局会让稠密张量和模型控制张量继续使用现有的 Q8/F32 路径，并支持采用 Q2_K、Q4_K 或 Q5_K 的路由专家 gate/up 张量；路由专家 down 张量支持 Q2_K、Q4_K、Q5_K 或 Q6_K。在有意添加其他 GLM GGUF 量化布局，并依据官方 100 用例测试集完成评分之前，应将其视为不受支持。

这些格式并非都支持相同的执行模式。Q4 文件可用于常规 Metal 和 CUDA 推理。双 Mac 张量并行目前需要能够感知所有权的 IQ2_XXS 或 Q2_K 路由布局；采用路由 Q4 的 GLM 必须在执行评估前被拒绝。

GLM 的 MTP 块是主 GGUF 的一部分；它不使用单独的 Flash MTP 文件。默认仍采用普通解码。--glm-mtp 会启用实验性的贪心推测。--glm-mtp-timing 同样会启用该功能，并输出接受率和计时计数器：

./ds4 -m gguf/GLM-5.2-UD-IQ2_XXS_RoutedIQ2XXS_blk78Q2K.gguf \
  --glm-mtp-timing --temp 0

GLM 推理使用 Metal、CUDA 或 ROCm 图后端。GLM 目前尚不支持方向性引导、低于 100 的 --power、显式指定的 --prefill-chunk，以及外部 --mtp 文件。

make                  # macOS Metal
make cuda-spark       # Linux CUDA, DGX Spark / GB10
make cuda-generic     # Linux CUDA, other local CUDA GPUs
make strix-halo       # Linux ROCm, AMD Strix Halo
make cpu              # CPU-only diagnostics build

./ds4flash.gguf 是两个二进制程序默认使用的模型路径。使用 -m 可从 ./gguf/ 中选择其他受支持的 GGUF。运行 ./ds4 --help 和 ./ds4-server --help 可查看完整的参数列表。

DSpark 推测解码

DSpark 是 DeepSeek 为 DeepSeek V4 Flash 发布的辅助草稿模型。它读取主模型的隐藏状态，并预测最多五个后续 token。DwarfStar 使用主 Flash 模型检查这些预测，只提交其中被接受的前缀。主模型始终拥有最终决定权；被拒绝或置信度较低的后缀会回退到常规的目标模型解码。

它可能带来的收益是生成速度更快：当多个预测 token 被接受时，一次目标验证就能让输出流前进多个 token。它无法加速预填充，而且草稿生成和验证本身也会产生开销。可预测的续写内容，尤其是代码，往往获益最大；对于接受率较低的提示词，速度可能不会提升，甚至可能变慢。因此，DSpark 目前仍处于实验阶段，必须显式选择启用。

这里发布的 DSpark 检查点被打包为一个单独的支持 GGUF，大小约为 5.6 GiB。它不是独立模型。只需下载一次：

./download_model.sh dspark-support

同一个支持文件可与上面列出的 Flash q2-imatrix、q2-q4-imatrix 和 q4-imatrix 模型配合使用。目前尚不支持 DeepSeek V4 PRO。在 Metal 上，主模型可以常驻内存，也可以使用 --ssd-streaming；支持模型仍会增加自身权重和运行时状态所需的内存。对于该次运行，DSpark 会取代旧版的单阶段 MTP 支持模型，而不是与其叠加使用。

使用贪心解码运行：

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

--mtp 用于提供支持 GGUF，而 --dspark 用于选择 DSpark 运行时。默认置信度阈值为 0.9；它会剪除那些不太可能抵消验证成本的后缀。--dspark-confidence 0 会强制使用固定的五 token 块，主要用于诊断。采样解码不会使用 DSpark 的预测。--quality 和 --dspark-strict 也会保持仅使用目标模型解码，这对于对比和正确性检查很有用。

警告：其中一些数字可能已不再更新，因为后续优化工作提升了运行时速度，却没有同步更新基准测试结果。

以下是单次运行的 Metal CLI 数据，使用 --ctx 32768、--nothink、贪心解码和 -n 256。短提示词是一个普通的小型意大利语故事提示词。长提示词用于测试分块预填充和长上下文解码。Q4 需要内存更大的机器，因此 M3 Max 的 Q4 数据为 N/A。

运行大于 RAM 容量的模型

常规 Metal 路径会尝试让模型常驻于 GPU 可寻址内存中。这是最快的路径，只要模型能够装入内存，就应该继续将其作为默认选择。DwarfStar 还在 Metal 上提供 SSD 流式容量模式，并为 ROCm 上的 GLM 5.2 提供该模式。在此模式下，非路由模型权重保持常驻，而路由式 MoE 专家则保存在内存缓存中，并在缓存未命中时从 GGUF 文件加载。

流式运行的速度不如将完整模型装入 RAM。它仍然需要为非路由权重、KV 缓存、计算图暂存空间、激活值以及路由专家缓存预留内存。它之所以有用，是因为路由专家占据了模型大小的主要部分，而且现代 Mac 的 SSD 足够快，可以让缓存未命中的成本保持在可接受范围内。长预填充仍然可能很快；生成过程对缓存未命中更敏感，因为每个新 token 都需要再次通过专家进行路由。

首先使用自动缓存预算：

./ds4 -m ./ds4flash.gguf --ssd-streaming

如果启动时报告专家缓存过大，或者你想为上下文预留更多内存，请显式设置路由专家缓存：

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

32GB 是路由专家的内存预算，而不是通用的字节缓存。DwarfStar 首先会为重叠式流式预填充所使用的两个完整路由层预留空间，然后根据当前 GGUF，将剩余字节换算为可容纳的动态缓存专家数量。在完成上下文/KV 核算后，显式指定的 NGB 预算也可能受到限制，以确保后端工作集不会进入缓慢的内存压力区间。像 --ssd-streaming-cache-experts 4000 这样的纯数字参数含义不同：它表示恰好使用 4000 个动态专家槽位，不进行额外核算。非路由权重、KV 缓存、计算图暂存空间和激活值还需要额外内存。自动缓存预算会取后端推荐工作集的 80%，减去非路由权重，然后应用相同的路由预填充预留空间，再据此确定动态缓存大小。正常使用时请保持热专家预加载启用；--ssd-streaming-cold 和 --ssd-streaming-preload-experts N 仅用于测量。

SSD 流式运行实例

在 64GB MacBook 上，先使用 2 位 Flash GGUF 和中等大小的专家缓存：

./download_model.sh q2-imatrix

./ds4 \
  -m ./ds4flash.gguf \
  --ssd-streaming \
  --ssd-streaming-cache-experts 32GB \
  --ctx 32768 \
  --nothink

在 128GB MacBook 上，PRO q2 流式运行仍处于实验阶段，但如果你可以接受较慢的生成速度，它可用于检查模型和偶尔的工作。首先使用 --nothink：

./download_model.sh pro-q2-imatrix

./ds4 \
  -m gguf/DeepSeek-V4-Pro-IQ2XXS-w2Q2K-AProjQ8-SExpQ8-OutQ8-Instruct-imatrix.gguf \
  --ssd-streaming \
  --ctx 32768 \
  --nothink

在配备 128GB RAM 的 M5 Max 上，一次简短的 PRO q2 流式解码基准测试发现，自动预算的效果最好：它选择了约 59GB 的路由专家缓存。在该机器上，手动设置 64GB 到 75GB 的缓存，性能也较为接近。应优先使用自动预算；如果要在这类机器上手动设置缓存，可从约 48GB 到 64GB 开始，然后仅在机器仍能保持响应，并且启动日志显示所请求的动态缓存已生效时继续增加。机器稳定后，可以重新启用思考，并设置较为保守的生成上限：

./ds4 \
  -m gguf/DeepSeek-V4-Pro-IQ2XXS-w2Q2K-AProjQ8-SExpQ8-OutQ8-Instruct-imatrix.gguf \
  --ssd-streaming \
  --ctx 32768 \
  --think \
  --tokens 1500

GLM 5.2 使用相同的选项。它的流式路径会让能够完整装入内存的最大连续层前缀保持常驻，然后使用剩余预算建立动态专家缓存。首先使用自动预算：

./ds4 \
  -m gguf/GLM-5.2-UD-IQ2_XXS_RoutedIQ2XXS_blk78Q2K.gguf \
  --ssd-streaming \
  --ctx 32768

启动时最重要的是缓存报告那一行。先采用保守配置，如果机器仍有余量，再增大缓存。

在配备 128GB 内存的 Strix Halo 上，以路由式 Q2_K 模型和 4096 token 上下文作为起点。自动缓存预算会为 GLM 的计算图和 KV 状态留出空间：

./download_model.sh glm-antirez-q2
make strix-halo
./ds4 --rocm -m gguf/GLM-5.2-UD-Q2_K_RoutedQ2K.gguf \
  --ssd-streaming --ctx 4096

使用流水线并行进行分布式推理

流水线并行通过将 Transformer 层拆分到多台机器上，使 DwarfStar 能够运行单台机器无法容纳的模型。主要示例是在两台 128GB MacBook 上运行完整的 4 位 Flash 量化模型：每个进程只映射属于自己的层切片，激活值通过 TCP 发送，协调器则保持正常的 CLI/API 行为。

流水线并行还可以通过多个 GPU 同时处理处于不同层的不同微批次来加速预填充，就像一条装配线。只有预填充可以通过这种方式加速。生成过程是纯自回归的：每个 token 都必须完整走完路由，之后下一个 token 才能开始。模型计算量与单进程运行相同，此外还会增加协调延迟，因此分布式生成会更慢。

为了建立初步的理解，下面是一些高层概念：

你需要将 GGUF 放在每台机器上，但每台机器只会加载其中的一部分。--layers 控制要映射哪些张量，因此使用 --layers 20:output 的工作节点不会加载更早的层。

层范围包含两端：10:20 表示第 10、11、……、20 层。N:output 表示从第 N 层到最后一层，并包括输出头。

你需要将其中一台机器指定为协调器，其他机器则作为工作节点。工作节点会连接到协调器，并告知协调器自身已就绪以及能够处理哪些层。

每个工作节点都会维护属于其自身切片的 KV 缓存。

通信发生在工作节点之间，无需使用协调器进行中继。因此，如果协调器为 A，而你发起了一次请求，激活值的流向将是 A -> B -> C -> 返回 A。

工作原理及配置方式

预填充路径是管道化的（这就是为什么它可以比单机更快）。对于长提示词，协调器可以在 worker 处理第 N 块时运行它在第 N+1 块上的切片。下面的分布式行是在两台通过 Thunderbolt 5 连接的 M5 Max 128 GB MacBook 上测量的，使用 Q4 Flash GGUF 和默认的 4096 token 分布式预填充块。单进程列是在单机上使用 Q2 GGUF 的参考运行，因此实际上速度更快一些，因为路由的 MoE 更小。

生成是不同的。它严格遵循自回归：token N+1 必须等到 token N 生成了 logits 并且采样选择了下一个 token。这意味着分布式生成不能使用长预填充管道。它每生成一个 token 至少需要支付一次跨机器激活跳转，所以生成比单个本地进程要慢。在相同的两台 Mac 通过 Thunderbolt 连接的设置上，91 GB Flash 量化的 12k 上下文控制运行从单进程的 30.59 t/s 下降到分布式的 24.67 t/s，损失 19.4%。因此分布式推理主要用于适配更大的模型和加速长预填充，而不是为了让解码更快。

两台 Mac Studios 上的完整 DeepSeek V4 PRO Q4

完整大小的 PRO Q4 GGUF 可以通过给协调器第 0:30 层，worker 第 31:output 层，在两台 512 GB Mac Studio M3 Ultra 机器上运行。使用分割的 GGUF 文件以便每一侧只映射它需要的张量：

# 协调器机器
./download_model.sh pro-q4-layers00-30

# Worker 机器
./download_model.sh pro-q4-layers31-output

gguf/DeepSeek-V4-Pro-Q4K-Layers00-30.gguf
gguf/DeepSeek-V4-Pro-Q4K-Layers-31-output.gguf

这是一个容量使用场景：每个进程只映射模型的自己的一半，而 worker 拥有输出头并返回 logits。

当前 PRO Q4 Metal 路径对大型路由专家使用队列常驻精确专家表。这避免了早期分布式 PRO Q4 尝试中使得运行非常缓慢或触及 Metal 内存会计限制的宽泛的多 GiB 路由张量绑定。在直接 192.168.0.182 / 192.168.0.183 链接上的短贪心烟雾测试中，模型生成了连贯的文本，启动后测量到 11.47 t/s 的生成速度。每 token 的遥测是平衡的：本地层大约 39-43 ms，远程层大约 44-49 ms，总 token 时间大约 84-92 ms。预期启动时会很慢，当每一侧映射并使其模型的一半驻留。长上下文 PRO Q4 预填充和解码性能仍然需要单独基准测试。

上面的测量使用 Thunderbolt 5 电缆。实现是纯 TCP，也可以在较慢的链接上工作，包括 WiFi，但强烈建议使用快速以太网或 Thunderbolt 网络。慢速链接主要影响生成延迟和短预填充；当层分割平衡时，大型预填充仍然可以受益。在正常性能路径中，最后的 worker 拥有输出头并直接返回 logits。

最小双主机配置：

# 机器 A：协调器，拥有 tokenization、采样、提示词和第 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，连接到 A 并拥有第 31..output 层。
./ds4 \
  -m gguf/DeepSeek-V4-Pro-Q4K-Layers-31-output.gguf \
  --role worker \
  --layers 31:output \
  --coordinator 169.254.43.68 1234

通常最后的 worker 也应该拥有输出头，例如 --layers 20:output。这避免了在预填充后返回完整的最终隐藏状态批，并让最后的 worker 直接生成 logits。在非常慢或计量的链接上，也支持 --layers 20:42：协调器将加载输出头并在本地计算 logits，用额外的协调器工作换取更小的每 token 回复。

网络链接比较

下表显示了相同的两台 M5 Max 主机、相同的 91 GB Flash 量化、协调器 --layers 0:19、worker --layers 20:output、来自 speed-bench/promessi_sposi.txt 的 8192 token 提示词和 128 个生成的 token。WiFi 和 Internet 数字会因本地条件而变化，但形状是重要的部分：高延迟直接伤害生成，而较低的带宽也会拉低长预填充速度。

Internet/VPN 情况不是要提供好的交互体验。它对于集体测试仍然有用：多个人可以临时合并机器来运行一个在任何单个主机上都不适配的更大模型，接受缓慢的解码来换取能够检查模型的能力。

像使用正常的 ./ds4 一样使用协调器：交互聊天、/read 和普通生成都通过相同的高级会话 API 进行。相同的分布式选项也连接到 ds4-agent、ds4-eval 和 ds4-bench。对于基准测试，worker 应该已经在运行；ds4-bench 等待直到完整的路由可用。

有用的调优和诊断：

./ds4-bench \
  -m gguf/DeepSeek-V4-Flash-Q4KExperts-F16HC-F16Compressor-F16Indexer-Q8Attn-Q8Shared-Q8Out-chat-v2.gguf \
  --prompt-file speed-bench/promessi_sposi.txt \
  --ctx-start 32768 \
  --ctx-max 65536 \
  --step-incr 32768 \
  --gen-tokens 0 \
  --role coordinator \
  --layers 0:19 \
  --listen 169.254.43.68 1234 \
  --debug

协调器上的 --debug 打印路由形成和每跳遥测：层范围、token 跨度、本地评估时间、下游等待时间、socket 发送时间和输入/输出字节数。这是决定分割是否平衡的当前分析工具。--dist-prefill-window N 控制端到端可能有多少预填充块在飞行中；默认值是保守的且有界的。--dist-prefill-chunk N 用于实验，但默认的 4096 token 块是标准设置，除非你在显式验证不同的块大小，否则应该使用。

默认情况下 DwarfStar 将隐藏状态激活发送为 32 位浮点数。要减少流量，在协调器上传递 --dist-activation-bits 16 或 --dist-activation-bits 8。这只改变机器间的传输格式，不改变模型权重或 KV 缓存。16 位传输将激活流量减半，是在以太网或 WiFi 上首先尝试的选项。8 位传输更激进，除非你已验证了你用例的输出，否则应该视为近似/实验模式。然而实验