SuperAPI AI 工具集

dflash-mlx-speculative-decoding

智能体与模型

查看项目

更新于 10-15 13:44

技能介绍

DFlash 是为 Apple Silicon 上的 MLX 实现的无损投机解码(speculative decoding)工具,由 ara.so 提供,属于 Daily 2026 Skills 合集。

用途

DFlash 的目标是在 Apple Silicon 上加速 MLX 的大语言模型推理。它采用投机解码思路:由一个小型草稿模型(约 1B 参数)通过块扩散(block diffusion)并行生成 16 个 token,再由目标模型在单次前向传播中验证这 16 个 token。只有经过目标模型验证的 token 才会被输出,因此输出是无损的——每个 token 都是目标模型的贪心 argmax。

主要能力

  • 无损投机解码:草稿 token 必须经目标模型验证后才输出,验证阶段不做温度采样,严格保持无损。
  • 加速效果:相比基线 mlx_lm,典型加速为 1.7 倍至 4.1 倍,具体取决于模型规模和上下文长度;Qwen3.5 模型的接受率约为 87%–90%。
  • 草稿模型自动解析:对于受支持的模型对,草稿模型会从注册表中自动解析,无需手动指定 --draft;没有匹配草稿模型的模型会在启动时被拒绝。
  • 提供命令行生成、OpenAI 兼容服务器、基准测试和 Python API 四种使用方式。
  • 支持流式生成、工具调用(通过 dflash-serve)、自定义草稿块大小与上下文配置。

安装

pip install dflash-mlx

或隔离安装:

pipx install dflash-mlx

要求 Python 3.10+、MLX 0.31.1+、Apple Silicon Mac。

使用方式

命令行生成文本:

dflash --model Qwen/Qwen3.5-9B --prompt "Explain backpropagation"

也可显式指定草稿模型:

dflash --model Qwen/Qwen3.5-9B --draft z-lab/Qwen3.5-9B-DFlash --prompt "Explain backpropagation"

可通过 --no-eos 禁用 EOS(便于按固定 token 数进行基准测试)。

OpenAI 兼容服务器:

dflash-serve --model Qwen/Qwen3.5-9B --port 8000

可配合 --chat-template-args '{"enable_thinking": false}' 禁用 Qwen3.5 思考模型的思考/推理 token;对大模型长提示可用 --dflash-max-ctx 16384 提高回退阈值。

基准测试:

dflash-benchmark --model Qwen/Qwen3.5-9B --draft z-lab/Qwen3.5-9B-DFlash --prompt "..." --max-tokens 1024 --repeat 3 --no-eos

输出每次运行的 JSON 报告,包含 tok/s、接受率以及相对基线的加速比。

Python API:

from dflash_mlx import DFlashRuntime

runtime = DFlashRuntime.from_pretrained(model="Qwen/Qwen3.5-9B", draft="z-lab/Qwen3.5-9B-DFlash")

支持 stream_generate 流式生成,以及 generate 返回带统计信息的结果(tokens_per_second、acceptance_rate、total_tokens)。可通过 DFlashConfig 自定义 draft_block_size、max_ctx、enable_tape_replay、jit_sdpa 等参数。

OpenAI 客户端可连接 dflash-serve(base_url 为 http://localhost:8000/v1,默认无需鉴权),支持非流式、流式以及工具调用。

支持的模型对

  • Qwen/Qwen3.5-4B → z-lab/Qwen3.5-4B-DFlash
  • Qwen/Qwen3.5-9B → z-lab/Qwen3.5-9B-DFlash
  • mlx-community/Qwen3.5-27B-4bit → z-lab/Qwen3.5-27B-DFlash
  • mlx-community/Qwen3.5-35B-A3B-4bit → z-lab/Qwen3.5-35B-A3B-DFlash

对于不在列表中的模型,可通过 --draft 显式指定草稿模型以绕过注册表检查。

适用场景

  • 在 Apple Silicon Mac 上本地加速 MLX 大模型推理。
  • 需要无损输出、可接受贪心解码的生成任务。
  • 通过 OpenAI 兼容接口接入 Open WebUI、Continue、aider、OpenCode 等客户端。
  • 需要工具调用能力的本地服务场景。

架构说明

  • Tape-replay 回滚:针对混合 GatedDeltaNet + attention 模型(Qwen3.5),dflash 在验证期间记录 innovation tape,并通过自定义 Metal 内核仅重放被接受的步骤,避免完整状态快照。
  • JIT SDPA 两遍:对上下文 ≥ 1024 token 的情况,使用自定义 Metal attention 内核保持与原生 MLX attention 的数值对齐。
  • 贪心接受:保留 16 个草稿 token 中最长的正确前缀,拒绝其余部分;验证阶段不做温度/采样,严格无损。
  • Qwen3(纯 attention)模型可用,但无法受益于 tape-replay 回滚(该机制专用于 GatedDeltaNet)。

限制与注意事项

  • 仅支持 Apple Silicon Mac,要求 Python 3.10+、MLX 0.31.1+。
  • 没有匹配草稿模型的模型会在启动时被拒绝,除非显式指定 --draft。
  • 接受率偏低(< 80%)通常由超长上下文(4096+)引起,可尝试 --dflash-max-ctx 8192 扩展回退阈值;Qwen3(非 3.5)模型的接受率低于 Qwen3.5 混合模型。
  • 输出可能与纯自回归不同,这是 MLX 调度差异导致的预期行为,但不会输出未经验证的 token。
  • 大模型可能内存不足,建议使用 4-bit 量化变体;草稿模型与目标模型同时加载,需额外预留约 1–2GB 内存。
  • 服务器默认不要求鉴权。

关于收费、价格、平台支持范围等更多信息,资料中暂未提供。