ARahim3/mlx-dspark

什么是 mlx‑dspark？

mlx‑dspark 是一个 Python 包（同时也是 macOS 应用），让你可以在 Apple 芯片 Mac 上运行推测解码——一种加速文本生成的技术。它内置两个“草稿生成”引擎，最初分别由 DeepSeek（DSpark）和 z‑lab（DFlash）发布。这两个引擎都是无损的：它们会预先提出若干个 token，然后由真正的模型逐一验证，因此最终输出与普通解码完全相同，只是更快。

工作原理

• 推测解码：快速的“草稿器”预测一小段 token 序列。随后由完整模型检查这些 token；如果全部匹配，整个块都会被接受，否则模型会回退到普通解码。由于草稿器成本很低，整体吞吐量可提升 2‑5 倍。
• 两个草稿器系列：
  • DSpark——来自 DeepSeek DeepSpec 代码库的半自回归草稿器。
  • DFlash——来自 z‑lab 的块扩散草稿器。
• 该包会自动为你加载的模型选择最佳草稿器，你也可以强制指定某一个。
• 首次使用时会测量你的 Mac 性能，并选择最优草稿大小（--max-draft auto）。

你可以做什么

1. CLI 生成——mlx-dspark generate --model <repo> --prompt "…"。
2. 本地 OpenAI 兼容服务器——mlx-dspark serve … 提供 HTTP API，可与任何使用 OpenAI（或 Anthropic）API 的客户端配合工作（Ollama、Open WebUI、SillyTavern 等）。
3. macOS GUI 应用——提供点击式界面，用于聊天、模型管理、实时遥测，以及一键设置编程助手代理。
4. 与 Claude Code 和 Codex 集成——服务器可作为 Anthropic 的 Claude Code 或 OpenAI 的 Codex API 后端。

支持的模型

README 列出了一个表格，包含已预注册草稿器并测得加速的模型，例如：

• Gemma‑4 12B（8‑bit）——最高快 4.24×。
• Qwen‑3.8‑27B（8‑bit，DFlash 2）——最高快 4.22×。
• MiniCPM5‑2B——最高快 4.21×。
• LFM2.5‑1.2B——最高快 3.83×。
• 还有许多其他模型（Qwen、Ornith、Nemotron、Bonsai 等）。 即使不在表格中的模型，也能以“无草稿器”查找模式（--mode auto）运行。

安装与要求

• 在 Apple Silicon 上需要 Python ≥ 3.10。
• pip install mlx-dspark（会自动安装 MLX 运行时 ≥ 0.32）。
• 可选通过 Homebrew Cask 安装 GUI，或从 releases 页面下载 DMG。
• 不需要额外的服务器框架——HTTP API 基于 Python 标准库构建。

关键命令行标志（最常用）

Flag	Purpose
--model <repo>	目标模型的 HF repo 或本地路径。
`--mode auto	dspark
--max-draft auto	让工具为你的 Mac 自动调整草稿长度。
--max-batch N	批处理最多 N 个并发请求（约 2.5 倍总吞吐量）。
--kv-bits 8	量化 KV 缓存以节省长上下文的显存。
--api-key <key>	如果你将服务器暴露到 localhost 之外，可使用简单认证。
--trust‑remote‑code	允许加载附带自定义 Python 代码的检查点。

为什么重要

推测解码是一项前沿技术，能让消费级 LLM 在单台 Mac 上明显更快，同时不牺牲答案质量。通过提供标准 OpenAI／Anthropic API，mlx‑dspark 能轻松将这些本地模型接入现有工具和代理，让一切保持在设备本地且私密。

---

以上所有细节均直接取自该仓库的 README；未添加任何外部信息。