antirez/ds4

来源：https://github.com/antirez/ds4

DwarfStar 旨在成为在消费级硬件（即用户可实际拥有的硬件）上运行少量优秀大语言模型的最佳方案。为实现此目标，我们构建了一个小型原生推理引擎，首先针对 DeepSeek V4 Flash（包括实验性视觉模型）、DeepSeek V4.1 Flash（Metal 支持，以及 CUDA 文本推理）进行优化，此外还支持 GLM 5.2 和 5.3、GLM 5.3 Flash、DeepSeek V4 PRO 以及 Qwen3.8 Flash Next（Metal 和 CUDA）。代码自包含且设计精简，并非通用 GGUF 运行器：您需要使用项目本身生成的 GGUF 文件，这些文件是项目的一部分。我们进行集成测试：模型加载、提示渲染、工具调用、KV 状态、HTTP 服务器以及编码代理均一同构建和测试。仓库还包含用于 GGUF、imatrix、质量和速度的工具及数据。

支持的硬件

• Metal（主要目标平台），适用于配备 96 GB 或更多内存的 Mac。较小内存的机器可使用 SSD 流式加载。若要在 128GB 系统上运行超大模型（如完整版 GLM 5.x，非 Flash 版），也需要 SSD 流式加载。
• NVIDIA CUDA，我们的主要目标是 DGX Spark。DwarfStar 还支持其他后端无法支持的多 GPU 系统，例如可在 Ada Lovelace 卡上运行 DeepSeek v4 Flash。
• 在 Framework Desktop 等 Strix Halo 系统上支持 ROCm。

本项目若无 llama.cpp 和 GGML 则无法存在，请务必阅读致谢部分，向 Georgi Gerganov 及所有其他贡献者致以诚挚感谢。

模型支持采用机会主义策略。项目遵循适用于实用本地机器尺寸的最佳开放权重，特别是 128 GB 笔记本电脑和 256/512 GB 工作站。当更好的替代品出现时，某个模型可能会被移除。

那么，这个软件能做什么？

• 您可以在消费级硬件（如 MacBook、DGX Spark 或 Strix Halo）上运行非常强大的模型。即使 RAM 不足，通过 SSD 流式加载，您仍能以可观的速度运行它。
• 您可以将多张 CUDA 卡用作多用户 LLM 服务器。支持 Ada Lovelace（包括 L40S）：即使其他推理实现需要更新的 GPU，更新的模型也可以在此运行。我们的八卡 L40S Flash 配置在 16 个会话下已达到约 126 t/s 的聚合生成速度。
• 使用两台通过 RDMA 连接的 128 GB Mac，您可以通过张量并行运行 4 位 DeepSeek Flash 或 GLM 5.3 Flash。更大的 GLM 5.2 量化版本需要更大的机器，例如 Mac Studio。
• 您还可以使用流水线并行将多个系统粘合在一起，以聚合其 RAM 来运行更大的模型。

动机

• 功能强大的开放权重模型现在可以适应高端个人机器。
• DeepSeek V4 Flash 和 PRO、GLM 5.2 容忍激进的路由专家量化。
• 压缩的 KV 缓存和快速本地 SSD 使长上下文变得实用。
• 一个专注于少量模型的推理系统理念。

AI 全披露

• 本软件是在 AI 编码代理的强力协助下开发的，由人类主导理念、测试和调试。我们公开说明这一点，因为它影响了项目的构建方式。如果您不喜欢 AI 开发的代码，本软件不适合您。下面的致谢同样重要：若无 llama.cpp 和 GGML（大部分由手工编写），本项目将不存在。

致谢 llama.cpp 和 GGML

ds4.c 不链接 GGML，但它的存在得益于 llama.cpp 项目开辟的道路，以及在那里开发的内核、量化格式、GGUF 生态系统和来之不易的工程知识。我们对 llama.cpp（https://github.com/ggml-org/llama.cpp）及其贡献者心怀感激并深表谢意。在构建这个针对 DeepSeek V4 的特定推理路径时，他们的实现、内核、测试和设计选择是重要的参考。一些源代码级别的片段在 MIT 许可证下保留或适配于此：GGUF 量化布局和表、CPU 量化/点积逻辑以及某些内核。因此，并且因为我们真诚地感激，我们在 LICENSE 文件中保留了 GGML 作者的版权声明。

状态

该软件目前变化非常快。请将其视为 Beta 质量。每次发布前都会执行一次大规模的质量保证运行，但不稳定和回退问题绝对可能出现。

如何使用本项目？

我（Salvatore）认为，由于 AI，项目的交付和使用方式已经改变。今天的主要区别在于：

1. 借助 AI，用户可以以较低的努力、成本，甚至无需对任务所要完成的领域有深入了解，就能对软件进行重大修改。例如，拥有特定硬件配置的 DwarfStar 用户可以要求编码代理针对该特定硬件配置改进本软件的推理速度，要求模型在不影响正确性的情况下达到最大的预填充和生成速度，并要求进行深度质量保证检查。
2. 类似地，由于“1”，软件的发布方式可能与以往不同。它必须更侧重于核心使用场景的工作模板，而不是试图覆盖所有可能的配置。如果 DwarfStar 展示了几个良好的张量并行执行实现，代码将作为在特定条件下、为新模型等实现相同功能的轨道。

因此，虽然本项目力求对主要模型和最常见硬件配置可用，我请求您，如果您可以使用编码代理，请考虑将编码代理用作接口来发现项目、进行修改、创建个性化设置。这样您可能做得比我们提供的更多，而且一些未记录或未实现的、您需要的东西，可能很容易实现。

从这里开始

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

选择您的构建。平台指南涵盖了先决条件、内存规格和特定硬件设置：

在 96 或 128 GB 机器上首次运行时，请下载 DeepSeek V4 Flash Q2：

./download_model.sh ds4f-q2

下载内容位于 gguf/ 目录。重复该命令可恢复中断的下载。请为上下文、运行时缓冲区以及模型本身预留内存。参见其他模型或在较小 Mac 上使用 SSD 流式加载。

日常使用

构建完成并下载模型后：

./ds4 -p "Explain Redis streams in one paragraph."
./ds4-agent
./ds4-server --ctx 32768

默认模型是 ds4flash.gguf，这是一个由主模型下载更新的链接。通过 -m FILE 显式选择模型。命令通常从仓库根目录运行；在其他位置启动时使用 --chdir /path/to/ds4。服务器默认监听 http://127.0.0.1:8000；API 访问和多会话请参见服务。

交互式 CLI 保持多轮对话。使用 /help、/read FILE、/ctx N 和 /quit。Ctrl+C 中断生成并返回提示符。每个二进制文件运行 --help 可查看其完整选项。

原生编码代理

ds4-agent 直接运行推理，无需单独的 HTTP 服务器。它将令牌历史和实时模型状态保存在一起，显示预填充进度，并使用模型的原生工具格式。DeepSeek 和 GLM 有各自的模板。使用 /hints on 可获得关于背后编程选择的偶尔、简短解释，使用 /hints off 则停止。更改将在下一个对话边界生效，无需重建缓存的上下文。新建和恢复的会话默认关闭提示。会话存储在 ~/.ds4/kvcache：

兼容的本地 KV 快照可避免重建提示。剥离的会话和网络 TP 恢复需要预填充。包含图像的会话目前无法保存。保存的对话和跟踪可能包含私人信息。对于 Pi、OpenCode、Codex CLI 或 Claude Code，请改用 ds4-server 并遵循客户端设置指南。

模型、图像与推测

模型和视觉列出了支持的下载项和内存要求。DeepSeek Vision Experimental 使用与 Flash 0731 不同的检查点；GLM 5.3 Flash 和 Qwen3.8 Flash Next 通过单独的编码器为同一文本模型添加了视觉功能。DeepSeek V4.1 Flash 文本和视觉可在 Metal 上运行；文本也可在 DGX Spark 上运行。Q2 可在配备 128 GB RAM 的单台 Mac 或 Spark 上通过 SSD 流式加载运行，或在两台 Mac 或两台 Spark 上使用 RDMA 常驻运行。Q4 需要 SSD 流式加载或配备 512 GB RAM 的 Mac。在所有模式下，Engram 表都保留在磁盘上，因此请使用快速的本地 SSD。下载和设置请参见模型指南。通过 --vision FILE 传递匹配的编码器，在 CLI 中使用 /read image.png 或在原生代理中使用 view_image。

Qwen3.8 较小的 Q2 发行版具有 41.73 GiB 的主/MTP 权重，使用 imatrix IQ2_XXS 门/上专家和填充的 Q2_K 下投影。它是 64 GB Mac 的起始选项。GGUF 还包含 95.37 GiB 的原始 BF16 n-gram，直接从磁盘读取而非加载到 RAM 中。请将其保存在快速 SSD 上。从 8K 上下文开始：

./download_model.sh qwen38-q2
./ds4 --ctx 8192 --prefill-chunk 1024

下载会获取一个 137.10 GiB 的文件并更新 ds4flash.gguf。添加 --mtp 以启用推测解码。较大的 qwen38-q4k 目标也可用。通过 ./download_model.sh qwen38-vision 下载可选的视觉编码器，并通过 --vision 传递。详见 Qwen 设置。

推测解码是可选启用的。GLM 和 Qwen 使用 --mtp；V4 Flash DSpark 需要匹配的支持性 GGUF。它可以提高生成速度，但并非所有工作负载都能受益。有关设置以及默认机会性采样与 --mtp-exact-sampling 之间的区别，请阅读推测解码。

输出与功率

默认启用思考。使用 --nothink 或 /nothink 获取直接回答，使用 --think 或 /think 重新启用。对于 V4.1，ds4 和 ds4-agent 也接受 --think-level 25 或 /think 25：1 到 100 设置推理力度，0 则禁用思考。--think 选择 75，--think-max 选择 100。在对话中更改力度会重建其缓存的前缀。默认采样设置为 temperature 1、top-p 1 和 min-p 0.05；--temp 0 选择贪婪输出。对于 DeepSeek V4，--power N 以降低持续 GPU 负载为代价换取吞吐量。默认值为 100。V4.1 和 GLM 目前需要 --power 100。

DeepSeek V4 Flash 和 GLM 5.3 Flash 也支持定向引导。使用 --dir-steering-file FILE 加载向量；在本地 CLI 或代理会话中，/steer F 可调整其在后续令牌中的比例，无需重建现有 KV 缓存。参见引导文档。--prefix-file FILE 在实时对话前预加载完整的 USER: / ASSISTANT: 对。回合标记必须位于行首，角色必须交替，最后一个回合必须是 ASSISTANT:。

能力评估

ds4-eval 针对真实的 GGUF 运行嵌入式能力回归测试。这些是 DwarfStar 的集成检查，而非官方排行榜分数。

./ds4-eval -m ds4flash.gguf --trace /tmp/ds4-eval.txt
./ds4-eval -m ds4flash.gguf --suite hard-smoke
./ds4-eval -m ds4flash.gguf --suite hard --retry-incomplete

默认套件是 core；--suite all 运行核心和难题案例。--list-cases 列出测试而不加载模型。--plain 选择非交互式输出，--regrade-trace FILE 对现有跟踪进行评分而不重新生成。来源和许可证位于 EVAL_DATA.md。关于推理正确性和发布检查，请阅读测试。

速度

此记录的 DeepSeek V4 Flash Q2 扫描使用配备 128 GB RAM 的 M5 Max，2048 令牌的持续预填充间隔，以及每个边界 128 个贪婪生成令牌。这是一个基线，而非每次提交的全新基准测试。

M5 Max Flash Q2 吞吐量

完整数据、DGX Spark 结果、比较条件和基准测试命令，请参见性能和基准测试。

详细指南

• 模型和视觉：Flash、PRO、GLM、Qwen 及匹配的编码器。
• Qwen3.8 Flash Next：模型设置、MTP、视觉和验证。
• SSD 流式加载：运行超大 RAM 模型并调整缓存大小。
• 跨机器推理：双 Mac TP/RDMA 和流水线层。
• 推测解码：DSpark、GLM 和 Qwen MTP 及采样。
• 服务：API、图像、批处理和磁盘 KV 缓存。
• 编码代理客户端：Pi、OpenCode、Codex CLI 和 Claude Code。
• 性能：可复现的测量和记录的基线。
• 测试与开发：回归测试、调试和模型构建工具。

发送拉取请求前，请阅读 CONTRIBUTING.md。

Logo

DwarfStar Logo 由 Salvatore Sanfilippo 手工设计，通过 AI 进行图形化处理，并由 Ben Gnomino 手动修改，其人文气息让它焕发光彩。