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

DwarfStar 4

DwarfStar 4 是一个为 DeepSeek V4 Flash 设计的小型原生推理引擎。它是有意限定了范围的：不是通用的 GGUF 运行器，不是其他运行时的封装器，也不是一个框架。其主要路径是一个针对 DeepSeek V4 Flash 的 Metal 和 CUDA 图执行器，并包含了 DS4 特定的加载、提示词渲染、KV 状态和服务器的 API 粘合代码。

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

现在，回到这个项目本身。为什么我们相信 DeepSeek v4 Flash 是一个相当特别的模型，值得拥有一个独立的引擎？因为经过与强大的小型稠密模型比较，我们可以报告如下：

• DeepSeek v4 Flash 由于激活参数更少，因此速度更快。
• 在思考模式下，如果你避免使用最大思考量，它产生的思考部分比其他模型短得多，在很多情况下甚至只有其他模型的 1/5，而且关键在于，思考部分的长度与问题的复杂度成正比。这使得 DeepSeek v4 Flash 可以在启用思考功能的情况下使用，而在相同条件下，其他模型实际上无法使用。
• 该模型拥有 100 万 token 的上下文窗口。
• 由于规模如此之大，当你在知识的边缘进行采样时，它会知道更多东西。例如，询问意大利节目或政治问题，很快就会揭示出 2840 亿个参数远多于 270 亿或 350 亿个参数。
• 它写出更地道的英语和意大利语。感觉就像一个准前沿模型。
• KV 缓存被高度压缩，允许在本地计算机上进行长上下文推理，并支持磁盘上的 KV 缓存持久化。
• 如果以一种特殊的方式量化（见后文），它在 2-bit 量化下也能很好地工作。这使得它可以在配备 128GB 内存的 MacBook 上运行（许多人报告说，即使在 96GB 内存和 25 万上下文窗口下也能运行！）。
• 我们预计 DeepSeek 将来会发布 v4 Flash 的更新版本，甚至会比当前版本更好。

话虽如此，关于这个项目有几点重要事项：

• 本地推理领域包含许多优秀的项目，但新模型不断发布，人们的注意力会立刻被下一个需要实现的模型所吸引。这个项目刻意选择了一个狭隘的方向：一次只专注于一个模型，使用官方向量进行验证，进行长上下文测试，并进行足够的代理集成以确认其是否真正有效。随着领域的发展，具体的模型可能会改变，但约束条件保持不变：本地推理在高端的个人电脑或 Mac Studio 上可信赖地运行，从 96/128GB 内存起步。
• 该软件的开发得到了 GPT 5.5 的大力协助，并由人类主导创意、测试和调试。我们公开这一点，因为它塑造了项目的构建方式。如果你对 AI 开发的代码不满意，那么这个软件不适合你。下面的致谢同样重要：如果没有主要由人工编写的 llama.cpp 和 GGML，这个项目就不会存在。
• 本实现基于一个理念：像 DeepSeek v4 这样的压缩 KV 缓存和现代 MacBook 的快速 SSD 磁盘应该改变我们认为 KV 缓存属于 RAM 的观念。KV 缓存实际上是磁盘的一等公民。
• 我们的愿景是，本地推理应该是一组开箱即用、能良好协同工作的三样东西：A) 带有 HTTP API 的推理引擎 + B) 专为在特定引擎和特定假设下良好运行而特别制作的 GGUF + C) 使用编码代理实现进行测试和验证。该推理引擎仅能与所提供的 GGUF 文件一起运行。它会针对在不同上下文大小下官方获得的 logits 进行测试。这个项目的存在是因为我们希望让一个本地模型从头到尾感觉是完整的，而不仅仅是可运行的。然而，这仅仅是 alpha 质量的代码，所以我们可能还没有达到那个目标。
• 优化的图执行路径针对 macOS 上的 Metal 和 Linux 上的 CUDA。CPU 路径仅用于正确性检查和模型/分词器的诊断。对于仅限 CPU 的 Linux 构建，请使用 make cpu；它会构建普通的 ./ds4 和 ./ds4-server 二进制文件，不包含 CUDA 或 Metal。在 macOS 上，警告：当前版本的 macOS 在虚拟内存实现中存在一个错误，如果你尝试运行 CPU 代码，会导致内核崩溃。还记得吗？软件糟透了。无法修复 CPU 推理以避免崩溃，因为每次崩溃你都必须重启计算机，这不好玩。如果你有胆量，请帮助我们。

致谢 llama.cpp 和 GGML

ds4.c 没有链接 GGML，但它的存在要感谢 llama.cpp 项目开辟的道路，以及在那里开发的 kernels、量化格式、GGUF 生态系统和来之不易的工程知识。我们非常感谢并感激 llama.cpp 及其贡献者。他们的实现、kernels、测试和设计选择在构建这个 DeepSeek V4 Flash 特定推理路径时是必不可少的参考。一些源代码级别的部分在此根据 MIT 许可证被保留或改编：GGUF 量化布局和表格、CPU 量化/点积逻辑以及某些 kernels。出于这个原因，并且因为我们由衷地感激，我们在 LICENSE 文件中保留了 GGML 作者的版权声明。

状态

代码和 GGUF 文件应被视为 alpha 质量，因为推理和模型服务是一件复杂的事情，而且所有这些只存在了几天。需要几个月的时间才能达到更稳定的形式。但是，我们努力使项目保持在可用状态，并且正在取得进展。如果你遇到问题，请确保使用 --trace 来记录会话，并在提交 issue 时包含完整的跟踪信息。

模型权重

此实现仅适用于为此项目发布的 DeepSeek V4 Flash GGUF。它不是通用的 GGUF 加载器，任意的 DeepSeek/GGUF 文件将不具备引擎所期望的张量布局、量化组合、元数据或可选的 MTP 状态。这里提供的 2-bit 量化不是玩笑：它们表现良好，能在编码代理下工作，以可靠的方式调用工具。2-bit 量化使用了一种非常不对称的量化方式：仅对路由的 MoE 专家进行量化，up/gate 使用 IQ2_XXS，down 使用 Q2_K。它们占了模型空间的大部分：其他组件（共享专家、投影、路由）保持不变以保证质量。

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

./download_model.sh q2-imatrix   # 适用于 96/128 GB RAM 的机器，经 imatrix 调优的 q2
./download_model.sh q4-imatrix   # 适用于 >= 256 GB RAM 的机器，经 imatrix 调优的 q4

如果你特别需要较旧的非 imatrix 量化版本，旧版 GGUF 文件仍然可用：

./download_model.sh q2           # 适用于 96/128 GB RAM 的机器，旧版非 imatrix
./download_model.sh q4           # 适用于 >= 256 GB RAM 的机器，旧版非 imatrix

脚本从 https://huggingface.co/antirez/deepseek-v4-gguf 下载，将文件存储在 ./gguf/ 下，使用 curl -C - 恢复部分下载，并更新 ./ds4flash.gguf 以指向所选的 q2-imatrix/q4-imatrix/q2/q4 模型。普通的 q2 XXS 权重仅使用权重重要性向量生成，没有 imatrix。imatrix 变体是首选。对于公共下载，身份验证是可选的，但如果提供了 --token TOKEN、HF_TOKEN 或使用本地的 Hugging Face token 缓存，则会使用它们。

./download_model.sh mtp

获取可选的推测解码支持 GGUF。它可以与 q2-imatrix、q4-imatrix、q2 和 q4 一起使用，但必须通过 --mtp 显式启用。当前的 MTP/推测解码路径仍是实验性的：它受到正确性门控，目前最多提供轻微的速度提升，而不是显著的生成速度提升。

然后构建：

make

./ds4flash.gguf 是两个二进制文件使用的默认模型路径。使用 -m 从 ./gguf/ 中选择另一个支持的 GGUF。运行 ./ds4 --help 和 ./ds4-server --help 查看完整的标志列表。

速度

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

机器	量化	提示	预填充	生成
MacBook Pro M3 Max, 128 GB	q2	短	58.52 t/s	26.68 t/s
MacBook Pro M3 Max, 128 GB	q2	11709 tokens	250.11 t/s	21.47 t/s
MacBook Pro M3 Max, 128 GB	q4	短	N/A	N/A
MacBook Pro M3 Max, 128 GB	q4	长	N/A	N/A
Mac Studio M3 Ultra, 512 GB	q2	短	84.43 t/s	36.86 t/s
Mac Studio M3 Ultra, 512 GB	q2	11709 tokens	468.03 t/s	27.39 t/s
Mac Studio M3 Ultra, 512 GB	q4	短	78.95 t/s	35.50 t/s
Mac Studio M3 Ultra, 512 GB	q4	12018 tokens	448.82 t/s	26.62 t/s
DGX Spark GB10, 128 GB	q2	7047 tokens	343.81 t/s	13.75 t/s

M3 Max t/s 图表（原文有图，此处略）

基准测试

ds4-bench 测量在上下文边界处的瞬时预填充和生成吞吐量，而不是报告整个运行的平均值。它加载模型一次，沿着固定的 token 序列走到边界（如 2048、4096、6144），并使用增量预填充，以便每行仅测量新添加的 token 区间。在每个边界之后，它将实时的 KV 状态保存到内存，生成一个固定的贪婪非 EOS 探针，恢复内存快照，然后继续预填充。

./ds4-bench \
  -m ds4flash.gguf \
  --prompt-file bench/promessi_sposi.txt \
  --ctx-start 2048 \
  --ctx-max 65536 \
  --step-incr 2048 \
  --gen-tokens 128

示例文件是 Alessandro Manzoni 的《约婚夫妇》（I Promessi Sposi）的 cleaned 公共领域 Project Gutenberg 文本（电子书 #45334），去掉了 Gutenberg 的页眉和页脚：https://www.gutenberg.org/ebooks/45334。

使用 --step-incr N 来设置不同的线性步长，或使用 --step-mul F 进行指数级扫描。输出为 CSV 格式，每个边界一行：最新的预填充区间 tokens/秒、该边界处的生成 tokens/秒，以及 kvcache_bytes。

CLI

一次性提示：

./ds4 -p "Explain Redis streams in one paragraph."

不带 -p 则启动交互式提示符：

./ds4
ds4>

交互式 CLI 是一个真正的多轮 DS4 聊天。它会保留渲染的聊天记录和实时的图 KV 检查点，因此每一轮都会延续之前的对话。有用的命令包括 /help、/think、/think-max、/nothink、/ctx N、/read FILE 和 /quit。按 Ctrl+C 可中断当前生成并返回到 ds4>。

CLI 默认为思考模式。使用 /nothink 或 --nothink 进行直接回答。--mtp MTP.gguf --mtp-draft 2 启用可选的 MTP 推测路径；它仅对贪婪解码有用，目前使用置信度门控（--mtp-margin）来避免缓慢的部分接受，应被视为一个实验性的轻微加速路径。

服务器

启动一个本地兼容 OpenAI/Anthropic 的服务器：

./ds4-server --ctx 100000 --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192

服务器在内存中维护一个可变的后端/KV 检查点，因此重新发送相同提示词的长版本的无状态客户端可以重用共享前缀，而不是从零开始预填充 token。

请求解析和套接字在客户端线程中运行，但推理本身通过一个图工作线程进行序列化。当前的服务器不会将多个独立的请求批处理在一起；并发的请求在单个活动的图/会话上轮流等待。

支持的端点：

• GET /v1/models
• GET /v1/models/deepseek-v4-flash
• POST /v1/chat/completions
• POST /v1/completions
• POST /v1/messages

/v1/chat/completions 接受标准的 OpenAI 风格参数：messages、max_tokens/max_completion_tokens、temperature、top_p、top_k、min_p、seed、stream、stream_options.include_usage、tools 和 tool_choice。工具模式（Tool schemas）会被渲染成 DeepSeek 的 DSML 工具格式，生成的 DSML 工具调用会被映射回 OpenAI 工具调用。

/v1/messages 是 Anthropic 兼容的端点，供 Claude Code 风格的客户端使用。它接受 system、messages、tools、tool_choice、max_tokens、temperature、top_p、top_k、stream、stop_sequences 和 thinking 控制参数。工具使用以 Anthropic 的 tool_use 块形式返回。

两个 API 都支持 SSE 流式传输。在思考模式下，推理会以原生 API 形状进行流式传输，而不是混入最终文本中。OpenAI 聊天流式传输还会在 DSML 调用被识别后立即流式传输工具调用：首先发送工具头部，然后在生成继续时，将参数字节作为 tool_calls[].function.arguments 的增量进行转发。Anthropic 端点会流式传输实时的思考和文本，然后在生成的工具块完成时发出结构化的 tool_use 块。