在 Apple Silicon 的 MLX 上用…

当在 Apple Silicon Mac 上运行 MLX、使用受支持的 Qwen3.5 等目标模型并希望用 DFlash 无损投机解码获得约 1.7–4.1x 推理加速时使用。

适用场景

解决思路

1. 安装：`pip install dflash-mlx`；或用隔离安装 `pipx install dflash-mlx`。运行需 Python 3.10+、MLX 0.31.1+、Apple Silicon Mac。
2. 文本生成：用 `dflash --model Qwen/Qwen3.5-9B --prompt "Explain backpropagation"`，会自动从 registry 解析 draft model。
3. 显式指定 draft model：`dflash --model Qwen/Qwen3.5-9B --draft z-lab/Qwen3.5-9B-DFlash --prompt "Explain backpropagation"`。
4. 禁用 EOS 以做固定 token 数基准测试：`dflash --model Qwen/Qwen3.5-9B --prompt "..." --max-tokens 1024 --no-eos`。
5. 启动 OpenAI 兼容 server：`dflash-serve --model Qwen/Qwen3.5-9B --port 8000`。
6. 带显式 draft 启动 server：`dflash-serve --model Qwen/Qwen3.5-9B --draft z-lab/Qwen3.5-9B-DFlash --port 8000`。
7. 禁用 Qwen3.5 thinking/reasoning tokens：CLI 或 server 加 `--chat-template-args '{"enable_thinking": false}'`。
8. 大模型长 prompt 提高 fallback threshold：`dflash-serve --model mlx-community/Qwen3.5-35B-A3B-4bit --port 8000 --chat-template-args '{"enable_thinking": false}' --dflash-max-ctx 16384`。
9. 基准测试：`dflash-benchmark --model Qwen/Qwen3.5-9B --draft z-lab/Qwen3.5-9B-DFlash --prompt "The function f satisfies..." --max-tokens 1024 --repeat 3 --no-eos`，输出每次运行的 JSON，含 tok/s、acceptance rate、相对 baseline 的 speedup。
10. 使用受支持模型对：`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`，未匹配 draft 的模型会在启动时被拒绝。
11. Python 流式生成：`from dflash_mlx import DFlashRuntime`，`runtime = DFlashRuntime.from_pretrained(model="Qwen/Qwen3.5-9B", draft="z-lab/Qwen3.5-9B-DFlash")`（draft 可选、可自动解析），再遍历 `runtime.stream_generate(prompt=prompt, max_tokens=512, use_chat_template=True)` 输出 token。
12. Python 完整生成并取统计：`runtime = DFlashRuntime.from_pretrained(model="Qwen/Qwen3.5-9B")`，`result = runtime.generate(prompt="What is speculative decoding?", max_tokens=256, use_chat_template=True)`，打印 `result.text`、`result.tokens_per_second`、`result.acceptance_rate`、`result.total_tokens`。
13. 自定义 draft block size 和 context：`DFlashConfig(draft_block_size=16, max_ctx=8192, enable_tape_replay=True, jit_sdpa=True)`，传给 `DFlashRuntime.from_pretrained(model="mlx-community/Qwen3.5-27B-4bit", config=config)`。
14. 用 OpenAI client 访问 dflash-serve 非流式：`OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")`，调用 `client.chat.completions.create(model="Qwen/Qwen3.5-9B", messages=[...], max_tokens=512)` 并读取 `response.choices[0].message.content`。
15. 用 OpenAI client 访问 dflash-serve 流式：同上 client，调用 `client.chat.completions.create(..., stream=True)`，遍历 chunk 输出 `chunk.choices[0].delta.content`。
16. 通过 dflash-serve 做 tool calling：定义 `tools`（含 function name、description、parameters），调用 `client.chat.completions.create(model="Qwen/Qwen3.5-9B", messages=[...], tools=tools, tool_choice="auto")`，解析 `response.choices[0].message.tool_calls[0].function.name` 和 `json.loads(tool_call.function.arguments)`。
17. 并排 demo（baseline vs DFlash）：`PYTHONPATH=. python3 -m examples.demo --mode dflash --target-model Qwen/Qwen3.5-9B --draft-model z-lab/Qwen3.5-9B-DFlash --prompt "Solve: f(x) + f(y) = f(x+y) - xy - 1" --max-tokens 2048 --no-eos`。
18. 接入 Open WebUI：先 `dflash-serve --model Qwen/Qwen3.5-9B --port 8000`；在 Open WebUI 设置 → Connections → 添加 OpenAI API，URL 填 `http://localhost:8000/v1`；在聊天 UI 选择模型 `Qwen/Qwen3.5-9B`。同样适用于 Continue、aider、OpenCode 及任意 OpenAI 兼容客户端。
19. 为不受支持模型覆盖 draft：`dflash --model my-org/MyCustomModel --draft my-org/MyCustomModel-DFlash --prompt "Hello"`，绕过 registry 检查。
20. 启动时模型被拒（`Error: No DFlash draft found for model 'org/ModelName'`）：显式传 `--draft org/ModelName-DFlash`，或改用受支持模型对。
21. 接受率低（<80%）：超长上下文（4096+）常导致此问题，试 `--dflash-max-ctx 8192` 扩大 fallback 阈值；Qwen3（非 3.5）模型接受率低于 Qwen3.5 hybrid 模型。
22. 数值分歧/输出与纯 AR 不同：这是预期行为，因为 MLX dispatch divergence，但不会发出未经验证的 token；若结果明显错误，确认 MLX 0.31.1+：`python -c "import mlx; print(mlx.__version__)"`。
23. server 无法连接：用 `lsof -i :8000` 检查端口占用；如需网络访问，绑定所有接口：`dflash-serve --model Qwen/Qwen3.5-9B --port 8000 --host 0.0.0.0`。
24. 大模型 OOM：改用 4-bit 量化变体（如 `mlx-community/Qwen3.5-27B-4bit` 代替全量模型）；draft model 会与 target 同时加载，额外预留约 1–2GB。
25. 查看 benchmark 结果 JSON：`ls benchmark/results/`，每次运行包含 tok/s、acceptance rate 和重复测量。
26. 对 hybrid GatedDeltaNet + attention 模型（Qwen3.5）启用 tape-replay rollback：在 verify 时记录 innovation tape，并通过自定义 Metal kernel 只重放 accepted steps，避免完整 state snapshots（`enable_tape_replay=True`）。
27. 对 context ≥1024 tokens 启用 JIT SDPA 2-pass 自定义 Metal attention kernel，以保持与 stock MLX attention 的数值对齐（`jit_sdpa=True`）。
28. 验证阶段使用 greedy acceptance：从 16 个 drafted token 中保留最长正确前缀，拒绝其余；不要期望 temperature/sampling 参与验证，输出严格无损。
29. Qwen3（纯 attention）模型也可运行，但不要启用/期待 tape-replay rollback 的收益（它是 GatedDeltaNet 专用）。

适用边界 · 注意事项

• 非 Apple Silicon Mac、无 MLX、Python 低于 3.10 或 MLX 低于 0.31.1 时不适用。
• 没有匹配 draft 且未显式提供兼容 `--draft` 的模型会在启动时被拒绝，不能直接使用。
• 若要求输出必须与纯 AR 逐 token 完全一致，虽然不会发出未验证 token，但可能因 MLX dispatch divergence 出现与纯 AR 不同的输出；需要温度采样/非 greedy 验证时也不适用。