刚刚在我的 Mac Studio M3 Ultra（256GB 内存）上跑了一下 @antirez 开发的 DS4，天哪，这性能真的令人印象深刻。这是一个为 DeepSeek V4 Flash 量身打造的精简高效推理引擎，真正让旗舰级推理能力在本地变得可用。100 万上下文窗口、极强的连贯性，以及在消费级硬件上出色的速度。这种专注、不整花架子的努力，终于将真正的旗舰模型带回了普通机器，而不再局限于巨大的 GPU 集群。向 @antirez 致敬——感谢你打造出这个项目。—

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

DwarfStar 4 (DS4)

DwarfStar 4 是一个专为 DeepSeek V4 Flash 设计的小型原生推理引擎。它的定位非常狭窄：它不是通用的 GGUF 运行器，不是其他运行时的封装，也不是一个框架。其主要路径是一个针对 DeepSeek V4 Flash 优化的 Metal 和 CUDA 图执行器，包含 DS4 特有的加载机制、提示词渲染、KV 状态管理和服务端 API 胶水代码。

如果没有 llama.cpp 和 GGML，这个项目根本不会存在。请务必阅读致谢部分，特别感谢 Georgi Gerganov 和所有其他贡献者。现在，回到本项目。

为什么我们认为 DeepSeek V4 Flash 是一个足够特殊、值得拥有独立引擎的模型？因为在与强大的小型密集模型进行对比后，我们可以报告以下几点：

1. 由于活跃参数量较少，DeepSeek V4 Flash 速度更快。
2. 在思考模式下，如果你避免使用 最大思考 选项，它产生的思考部分长度远短于其他模型，在许多情况下仅为其他模型的 1/5。至关重要的是，思考部分的长度与 问题复杂度成正比。这使得在其他模型几乎无法使用的情况下，DeepSeek V4 Flash 在开启思考功能时依然可用。
3. 该模型拥有 100 万 Token 的上下文窗口。
4. 由于规模庞大，在知识边界进行采样时，它知道更多的东西。例如，询问关于意大利电视剧或政治的问题，很快就会发现 2840 亿参数远多于 270 亿或 350 亿参数。
5. 它的英语和意大利语写作能力好得多。它 感觉 就像一个准前沿模型。
6. KV 缓存被极度压缩，允许在本地计算机上进行长上下文推理，并支持 磁盘 KV 缓存持久化。
7. 它在使用 2-bit 量化时表现良好（前提是采用特殊的量化方式，详见后文）。这使得它可以在拥有 128GB RAM 的 MacBooks 上运行（许多人报告在 96GB RAM 下也能运行，即使上下文窗口达到 250k！）。
8. 我们预计 DeepSeek 未来会发布 V4 Flash 的更新版本，比当前版本更好。

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

• 本地推理领域包含许多优秀的项目，但新模型不断发布，注意力会立刻被下一个需要实现的模型吸引。本项目做出了一个刻意的狭窄选择：一次只关注一个模型，进行官方向量验证（使用官方实现获得的 logits）、长上下文测试，以及足够的智能体（Agent）集成，以确认其是否真正有效。具体的模型可能会随着领域的发展而变化，但约束保持不变：在高端个人机器或 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 版本在虚拟内存实现中存在一个 bug，如果尝试运行 CPU 代码会导致内核崩溃。记得吗？软件很烂。由于每次崩溃都需要重启电脑，这并不好笑，因此无法修复 CPU 推理以避免崩溃。如果你有胆量，请帮助我们。

致谢 llama.cpp 和 GGML

ds4.c 不链接 GGML，但它 的存在得益于 llama.cpp 项目开辟的道路，以及那里开发的内核、量化格式、GGUF 生态系统和来之不易的工程知识。我们感谢并欠 llama.cpp (https://github.com/ggml-org/llama.cpp) 及其贡献者良多。他们的实现、内核、测试和设计选择在构建这个特定的 DeepSeek V4 Flash 推理路径时是至关重要的参考。一些源码级别的组件在 MIT 许可证下在这里被保留或改编：GGUF 量化布局表和 CPU 量化/点积逻辑，以及某些内核。出于这个原因，也因为我们要真诚地感谢，我们在 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。它们构成了模型空间的主体：其他组件（共享专家、投影、路由）保持不变以保证质量。

下载一个主要模型：

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

该脚本从 https://huggingface.co/antirez/deepseek-v4-gguf 下载，将文件存储在 ./gguf/ 下，使用 curl -C - 恢复部分下载，并更新 ./ds4flash.gguf 指向所选的 q2/q2-imatrix/q4 模型。

纯 q2 XXS 权重仅使用权重重要性向量生成，不使用 imatrix。q2-imatrix 变体使用 antirez 制作的 imatrix 生成配方，在 logits 上与 q4 量化相比显示较小的误差。

公共下载无需身份验证，但如果存在 --token TOKEN、HF_TOKEN 或本地 Hugging Face 令牌缓存，则会使用它们。

./download_model.sh mtp 获取可选的投机解码支持 GGUF。它可以与 q2、q2-imatrix 和 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。

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

示例文件是经过清理的公共领域 Project Gutenberg 文本，内容为亚历山德罗·曼佐尼的《婚约夫妇》（ebook #45334），去除了 Gutenberg 页眉和页脚。

使用 --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。工具模式被渲染为 DeepSeek 的 DSML 工具格式，生成的 DSML 工具调用映射回 OpenAI 工具调用。

/v1/messages 是用于 Claude Code 风格客户端的兼容 Anthropic 端点。它接受 system、messages、tools、tool_choice、max_tokens、temperature、top_p、top_k、stream、stop_sequences 和思考控制。工具使用作为 Anthropic tool_use 块返回。

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

工具调用处理和规范化

DeepSeek V4 Flash 将工具调用作为 DSML 文本发出 (https://huggingface.co/deepseek-ai/DeepSeek-V4-Pro/blob/main/encoding/README.md)。智能体客户端在下一个请求中不会将相同的文本发回：它们发送标准化的 OpenAI/Anthropic JSON 工具调用对象。如果服务器以略微不同的方式重新渲染这些对象，渲染的字节前缀将不再匹配实时 KV 检查点，下一轮将不得不重建。

第一道防线是精确重放。每个工具调用都有一个不可猜测的 API 工具 ID，服务器在一个由基数树支持的有界内存映射中记住 工具 ID -> 精确采样的 DSML 块。当客户端稍后发回该工具 ID 时，提示词渲染器使用模型采样的确切 DSML 字节，而不是新格式的近似值。此映射也可以保存在 KV 缓存文件中，因此精确重放可以在服务器重启后对缓存的历史记录幸存。

规范化仅是备用路径。如果缺少确切的 DSML 块，或者使用 --disable-exact-dsml-tool-replay 禁用精确重放，服务器将从 JSON 工具对象渲染确定性的 DSML 形式。在工具调用回合后，它比较实时采样的 Token 流与下一个客户端请求将渲染的提示词。如有必要，它重写实时检查点，或回退到较旧的磁盘 KV 快照并仅重放后缀。这保持模型延续与无状态 API 记录一致。

在生成期间，服务器还将 DSML 语法与负载区别对待。当模型发出稳定的协议结构（如 DSML 标签、参数头、JSON 标点符号或闭合标记）时，采样被强制为 temperature=0，以便工具调用保持可解析。这种贪婪模式 不 适用于参数负载：string=true 参数主体和 JSON 字符串值，包括文件内容和编辑文本，使用请求的正常采样设置。这种分离很重要：确定性解码对语法有帮助，但应用于长代码或文件主体时可能会创建重复文本。

最小的 OpenAI 示例：

curl http://127.0.0.1:8000/v1/chat/completions \
 -H 'Content-Type: application/json' \
 -d '{ "model":"deepseek-v4-flash", "messages":[{"role":"user","content":"List three Redis design principles."}], "stream":true }'

智能体客户端使用

ds4-server 可以被使用兼容 OpenAI 聊天补全的本地编码智能体使用。首先启动服务器，并将客户端上下文限制设置得不高于你启动服务器时使用的 --ctx 值：

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

如果你愿意，可以使用更大的上下文和更大的缓存。100 万 Token 的完整上下文将使用大约 26GB 的内存（仅压缩索引器就类似…