用途
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 文件。
主要能力
- 硬件支持：Metal 是主要目标，面向 96GB 及以上的 Mac；较小机器可使用 SSD 流式加载，在 128GB 系统上运行完整 GLM 5.x（非 Flash）等超大模型也需要 SSD 流式加载。NVIDIA CUDA 以 DGX Spark 为主要目标，同时支持其他后端不支持的多 GPU 系统（例如在 Ada Lovelace 卡上运行 DeepSeek V4 Flash）。ROCm 支持 Strix Halo 系统，如 Framework Desktop。
- 消费级硬件运行：可在 MacBook、DGX Spark、Strix Halo 等设备上运行能力很强的模型；即使内存不足，通过 SSD 流式加载也能以尚可的速度运行。
- 多卡多机：多张 CUDA 卡可作为多用户 LLM 服务器；八个 L40S 的 Flash 配置在 16 个会话下达到约 126 t/s 的聚合生成速度。两台 128GB Mac 通过 RDMA 连接，可用张量并行运行 4-bit DeepSeek Flash 或 GLM 5.3 Flash。也可用流水线并行把多台系统组合起来，累加内存以运行更大模型。
- 量化与缓存：DeepSeek V4 Flash/PRO、GLM 5.2 能容忍激进的路由专家量化；压缩 KV 缓存与快速本地 SSD 使长上下文变得实用。
使用方式
选择构建版本，平台指南涵盖前置条件、内存估算与特定硬件设置。在 96 或 128GB 机器上首次运行可下载 DeepSeek V4 Flash Q2，下载文件放在 gguf/ 目录。构建完成并下载模型后：默认模型为 ds4flash.gguf，通过 -m FILE 显式指定；命令通常在仓库根目录运行，在其他位置启动时使用 --chdir /path/to/ds4。服务器默认监听 http://127.0.0.1:8000。交互式 CLI 保留多轮对话，可用 /help、/read FILE、/ctx N、/quit，Ctrl+C 中断生成并返回提示符；每个二进制可用 --help 查看完整选项。
- 原生编码智能体：
ds4-agent直接运行推理，无需单独的 HTTP 服务器，保持 token 历史与实时模型状态在一起，显示预填充进度，并使用模型原生工具格式。DeepSeek 和 GLM 有各自的模板。可用/hints on偶尔查看编程选择说明。会话保存在~/.ds4/kvcache。对于 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 上运行。配合
--vision FILE传入匹配编码器后，可在 CLI 中用/read image.png或在原生智能体中使用view_image。Qwen3.8 较小的 Q2 版本主权重为 41.73 GiB，是 64GB Mac 的起步选项；GGUF 还包含 95.37 GiB 原始 BF16 n-gram，直接从磁盘读取而非载入内存，需放在快速 SSD 上，起步建议 8K 上下文。推测解码为可选项：GLM 和 Qwen 使用--mtp，V4 Flash DSpark 需要匹配的支持 GGUF。 - 输出与功耗：思考默认启用，使用
--nothink或/nothink直接回答，--think或/think重新启用。V4.1 中还接受--think-level 25或/think 25（1 到 100 设置推理力度，0 禁用）。常规采样默认 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加载向量。--prefix-file FILE可在实时对话前预加载完整的 USER:/ASSISTANT: 对话对。 - 能力评估：
ds4-eval对真实 GGUF 运行内嵌能力回归测试，这是 DwarfStar 集成检查而非官方排行榜分数。默认套件为core，--suite all运行 core 与 hard 用例，--list-cases列出测试，--plain选择非交互输出，--regrade-trace FILE对现有轨迹评分。
适用场景与限制
ds4 适用于希望在自有消费级硬件上本地运行少数前沿开源模型的用户、需要多用户 LLM 服务器的多卡 CUDA 环境、以及用两台 Mac 或 Spark 通过 RDMA 做张量并行的场景。其模型支持是刻意机会主义的，项目跟随适合本地机器尺寸（尤其是 128GB 笔记本与 256/512GB 工作站）的最佳开源权重，当出现更好的替代品时某个模型可能被移除。需要重点注意：项目仍处于快速变化阶段，属于 beta 质量，尽管每次发布前会执行大型 QA 运行，但不稳定与回归仍有可能发生。此外，该软件在开发中大量借助 AI 编码智能体，由人类主导想法、测试与调试；如果不接受 AI 开发的代码，则不适合使用。项目不链接 GGML，但其存在得益于 llama.cpp 与 GGML 开辟的道路，部分源码级内容（GGUF 量化布局与表、CPU 量化/点积逻辑及某些内核）在 MIT 许可下保留或改编自该项目。软件可以按用途修改与定制，作者鼓励有编码智能体的用户把智能体作为发现项目、做出修改、创建个性化配置的接口。
详细指南
项目提供涵盖以下主题的详细指南：模型与视觉（Flash、PRO、GLM、Qwen 及匹配编码器）、Qwen3.8 Flash Next（模型设置、MTP、视觉与验证）、SSD 流式加载（运行大于内存的模型并设置缓存大小）、跨机器推理（双 Mac TP/RDMA 与层流水线）、推测解码（DSpark、GLM 与 Qwen MTP 及采样）、服务（API、图像、批处理与磁盘 KV 缓存）、编码智能体客户端（Pi、OpenCode、Codex CLI 与 Claude Code）、性能（可复现测量与记录的基线）、测试与开发（回归测试、调试与模型构建工具）。发送拉取请求前需阅读 CONTRIBUTING.md。
