# DSpark speculative decoding drafters for DeepSeek-V4.1-Flash-1017

DSpark drafter modules extracted from the official
[deepseek-ai/DeepSeek-V4.1-Flash-1017](https://huggingface.co/deepseek-ai/DeepSeek-V4.1-Flash-1017)
checkpoint (its 3-stage `mtp.0..2` block drafter), for llama.cpp speculative decoding.

These are **optional add-ons**. The quants in this repo work exactly the same without them, and neither file is
loaded unless you ask for it with `--spec-type draft-dspark`.

## Files

| File | Location | Size | FP8 source projections | Markov heads | Routed experts |
|---|---|---|---|---|---|
| `dspark-DeepSeek-V4.1-Flash-1017-Q8_0.gguf` | repo root | 7.98 GB | Q8_0 | BF16 | MXFP4 passthrough |
| `dspark-DeepSeek-V4.1-Flash-1017-BF16.gguf` | `dspark/` | 8.51 GB | BF16, bit exact | BF16 | MXFP4 passthrough |

Both files have 78 tensors and `general.architecture = dflash`. They differ only in the 25 FP8 (`E4M3`) projections
(attention, shared experts, `fc`): `BF16` upcasts them exactly (FP8 with a power-of-two scale fits BF16 with zero
error), `Q8_0` stores them as Q8_0 (worst relative RMSE 0.61%). The MXFP4 routed experts and every F32 tensor are byte
identical in both. The token embeddings and the LM head are not in the files: the drafter borrows the target's.

**Which one:** `Q8_0` is the default. It sits at the repo root, so llama.cpp finds it automatically for every quant
in this repo. It accepts drafts at the same rate as `BF16` in our tests. Take `BF16`
only if you want an exact reproduction of DeepSeek's weights.

## llama.cpp version

DeepSeek-V4.1 (`deepseek41`) and its DSpark drafter are not in upstream llama.cpp yet. Use the Unsloth llama.cpp
prebuilt (unslothai/llama.cpp releases), which carries them as a pin, or build
[unslothai/llama.cpp#298](https://github.com/unslothai/llama.cpp/pull/298).

## Usage

```bash
llama-server -hf unsloth/DeepSeek-V4.1-Flash-1017-GGUF:UD-Q4_K_XL \
  --spec-type draft-dspark \
  --spec-draft-n-max 3
```

With local files, or for the `BF16` drafter, pass the drafter path with `-md`:

```bash
llama-server \
  -m UD-Q4_K_XL/DeepSeek-V4.1-Flash-1017-UD-Q4_K_XL-00001-of-00009.gguf \
  -md dspark/dspark-DeepSeek-V4.1-Flash-1017-BF16.gguf \
  --spec-type draft-dspark --spec-draft-n-max 3 -ngld 99
```

- `--spec-draft-n-max` is clamped to the trained block size, 5 (`dspark_block_size` in DeepSeek's `config.json`).
- Do not pin the drafter to one device (`-devd`): it borrows the target's embeddings and output head, so it has to span
  the same devices as the target.
- `--mtp` / `--spec-type draft-mtp` do not apply: V4.1 ships a DSpark block drafter, not an MTP head.

## Notes

Use `--spec-draft-n-max 3` (llama.cpp's default); it was the fastest setting in our testing.

As with other speculative drafters in llama.cpp, greedy output with the drafter is not guaranteed to be bit identical
to a run without it: the target's batched verification can flip near-tie tokens on CUDA. It is not a drafter defect.