Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions aspec/commands/convert_to_hf.py
Original file line number Diff line number Diff line change
Expand Up @@ -183,11 +183,18 @@ def _serving_config(raw_config: dict) -> dict:
if raw_config.get("mtp_conditioning"):
raise NotImplementedError("MTP-conditioned Drafts require native --format aspec export")
if raw_config.get("architectures") == ["DominoDraftModel"]:
raise NotImplementedError(
"Domino SGLang export is not validated in ASpec yet; use --format aspec. "
"Upstream SGLang 0.5.21 includes a Domino loader and an end-to-end test, "
"but ASpec has not validated its exported artifact against it"
)
from aspec.models.draft.domino import official_domino_config

config = official_domino_config(raw_config)
nested = config.get("dflash_config") or {}
if nested.get("pure_draft_prefix_len") != 1:
raise NotImplementedError(
"SGLang Domino serving requires pure_draft_prefix_len=1; "
"use --format aspec for another label layout"
)
if not isinstance(nested.get("shift_label"), bool):
raise ValueError("SGLang Domino serving requires a boolean shift_label")
return config

if raw_config.get("architectures") == ["MedusaDraftModel"]:
raise NotImplementedError(
Expand Down Expand Up @@ -355,8 +362,10 @@ def _draft_structure_manifest(raw_config: dict) -> dict:
"loader_contract": {
"runtime": "sglang",
"validated_version": "0.5.21",
"speculative_algorithm": ("DFLASH" if algorithm == "dflash2" else
"EAGLE" if algorithm == "mtp" else algorithm.upper()),
"speculative_algorithm": (
"DFLASH" if algorithm in {"dflash2", "domino"} else
"EAGLE" if algorithm == "mtp" else algorithm.upper()
),
"required_patch_features": (
["dflash_moe_v1"] if structure["ffn_type"] != "dense" else []
),
Expand Down
33 changes: 30 additions & 3 deletions aspec/commands/evaluate_draft.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,23 @@
import time
from pathlib import Path

_SPECULATIVE_ALGORITHMS = {
"dspark": "DSPARK",
"dflash": "DFLASH",
"dflash2": "DFLASH",
"domino": "DFLASH",
"eagle3": "EAGLE3",
"mtp": "EAGLE",
}


def serving_algorithm(name):
"""Map an exported draft algorithm to the official SGLang runtime name."""
try:
return _SPECULATIVE_ALGORITHMS[name]
except KeyError:
raise ValueError(f"unsupported exported draft algorithm: {name!r}") from None


def load_prompts(path, tokenizer, limit, *, enable_thinking=None):
"""Only user prefixes are evaluated; never prefill held-out assistant answers."""
Expand Down Expand Up @@ -127,6 +144,8 @@ def main():
parser.add_argument("--max-new-tokens", type=int, default=256)
parser.add_argument("--repeats", type=int, default=3)
parser.add_argument("--tp", type=int, default=1)
parser.add_argument("--domino-candidate-pool-size", type=int, default=0,
help="Domino only: 0 scores the full vocabulary")
parser.add_argument("--trust-remote-code", action="store_true",
help="Explicitly allow code supplied by the Target checkpoint")
parser.add_argument("--disable-thinking", action="store_true", help="match a non-thinking training corpus")
Expand All @@ -135,17 +154,22 @@ def main():
args = parser.parse_args()
if args.output.exists() or min(args.samples, args.max_new_tokens, args.repeats, args.tp) < 1:
raise ValueError("use positive budgets and a fresh output")
if args.domino_candidate_pool_size < 0:
raise ValueError("Domino candidate pool size must be non-negative")
import sglang as sgl
import torch
from transformers import AutoTokenizer

from aspec.inference.sglang_v0521 import TrainingEngine

manifest = json.loads((args.draft / "export_manifest.json").read_text())
algorithm = {"dspark": "DSPARK", "dflash": "DFLASH", "dflash2": "DFLASH",
"eagle3": "EAGLE3", "mtp": "EAGLE"}.get(manifest.get("algorithm"))
if algorithm is None or manifest.get("storage_format") != "sglang":
if manifest.get("storage_format") != "sglang":
raise ValueError("requires an official SGLang-format draft export")
algorithm = serving_algorithm(manifest.get("algorithm"))
expected = (((manifest.get("draft_structure") or {}).get("loader_contract") or {})
.get("speculative_algorithm"))
if expected is not None and expected != algorithm:
raise ValueError("export manifest loader contract disagrees with the speculative algorithm")
for filename, key in (("model.safetensors", "model_sha256"), ("config.json", "config_sha256")):
digest = hashlib.sha256()
with (args.draft / filename).open("rb") as stream:
Expand All @@ -160,6 +184,7 @@ def main():
draft_tokens = speculative_token_budget(config, algorithm)
record = {"schema": "aspec.decode-evaluation/v1", "target": args.target,
"draft": str(args.draft.resolve()), "algorithm": algorithm,
"draft_algorithm": manifest.get("algorithm"),
"export_manifest_sha256": hashlib.sha256((args.draft / "export_manifest.json").read_bytes()).hexdigest(),
"data_sha256": hashlib.sha256(args.data.read_bytes()).hexdigest(),
"prompt_tokens_sha256": hashlib.sha256(json.dumps(prompts).encode()).hexdigest(),
Expand All @@ -186,6 +211,8 @@ def persist():
if name == "speculative":
kwargs.update(speculative_algorithm=algorithm, speculative_draft_model_path=str(args.draft),
speculative_num_draft_tokens=draft_tokens)
if manifest.get("algorithm") == "domino":
kwargs["speculative_domino_candidate_pool_size"] = args.domino_candidate_pool_size
if algorithm in {"EAGLE", "EAGLE3"}:
kwargs.update(speculative_eagle_topk=1, speculative_num_steps=3)
record["runs"][name] = {"requested_engine_args": kwargs, "samples": []}
Expand Down
33 changes: 33 additions & 0 deletions docs/contributing/validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,39 @@ bash tools/run_in_env.sh python -m tools.recipes export \
--checkpoint outputs/my-run/checkpoints/iter_0000101 --output outputs/my-native-asset
```

## Domino decode ablation and anchor replay

Run a paired corrected-versus-backbone decode from one SGLang-format Domino asset.
The tool zeroes only the correction output projection in a copy, so both branches keep
the trained backbone and the same prompt set:

```bash
CUDA_VISIBLE_DEVICES=0 bash tools/run_in_env.sh python -m tools.validation.domino_acceptance_ablation \
--corrected outputs/domino-sglang --backbone outputs/domino-backbone \
--target /models/Qwen3-8B --data held-out.jsonl \
--output outputs/domino-ablation.json --samples 16 --max-new-tokens 32 --repeats 2
```

The summary rejects mismatched prompt identities and records acceptance length,
verification count and repeat stability for both branches. It is a bounded decode
comparison, not throughput or convergence evidence.

For matched training comparisons, materialize one canonical anchor stream and verify
it before either framework consumes it:

```bash
python -m tools.validation.domino_anchor_protocol build \
--source cache/tokenized_dataset.pt --anchors anchors.json \
--num-anchors 128 --block-size 16 --seed 42
python -m tools.validation.domino_anchor_protocol verify \
--source cache/tokenized_dataset.pt --anchors anchors.json \
--num-anchors 128 --block-size 16 --seed 42
```

`verify` regenerates the stream and checks that every kept anchor is supervised in
its source sample. Consuming the same file in both trainers is still required before
claiming a matched loss-curve comparison; an identical seed alone is not enough.

## Algorithm, capacity and fault checks

| Scope | Required additional evidence |
Expand Down
2 changes: 1 addition & 1 deletion docs/support.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ and tests do not imply CPU training support.
| DSpark / DFlash | Training, exact recovery, evaluation and export; Dense and selected MoE/attention structures | Objectives, feature bindings and assets remain algorithm-specific |
| EAGLE3 | Recurrent TTT, full/pruned vocabulary, GQA/MHA or materialized MLA; FA4 packing/CP | No EAGLE3 MoE, anchored mode or whole-model compile |
| P-EAGLE core | Qwen3 full-vocabulary parallel model/loss, deterministic dense slots, eager/SDPA | Model/loss prerequisite only; no public trainer, COD sampler, resume, export or consumer validation; see [scope](user-guide/peagle.md) |
| Domino | DFlash block backbone plus GRU causal correction head, mixed backbone/corrected CE, both documented label layouts; training, `lambda_base` curriculum, held-out corrected/backbone observations and exact recovery with FlexAttention, CP1, padded/non-packing | No packed/CP>1, MoE, sparse attention or MTP conditioning; native export, strict reload, proposal consumer and a bounded SpecForge comparison are validated; longer convergence/decoding acceptance pending; see [scope](user-guide/domino.md) |
| Domino | DFlash block backbone plus GRU causal correction head, mixed backbone/corrected CE, both documented label layouts; training, `lambda_base` curriculum, held-out corrected/backbone observations and exact recovery with FlexAttention, CP1, padded/non-packing | No packed/CP>1, MoE, sparse attention or MTP conditioning; SGLang/native export, strict reload, proposal consumer, a bounded SpecForge comparison and bounded SGLang decode acceptance are validated; harder data, longer convergence and a formal anchor-replay training mode remain pending; see [scope](user-guide/domino.md) |
| Medusa heads-only | Parallel full-vocabulary future-token heads on the frozen Target post-norm state; training, exact recovery and native export; SDPA CP1, MBS1, non-packing, REPLICATE, one node | No packing/CP, warmstart or candidate-tree acceptance yet; see [scope](user-guide/medusa.md) |
| EAGLE4 | Dense and selected upstream MoE; Draft/candidate stages; packing/CP and native assets | Candidate Top-K forward-KL is explicitly implemented from public semantics, not an unpublished official recipe; no serving integration |
| DFlash2 | Experimental full/causal/SWA training with Flex, cuDNN THD or FA4 packing/CP | Experimental objective; no claim to reproduce an official training recipe |
Expand Down
73 changes: 56 additions & 17 deletions docs/user-guide/domino.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ Target GPU plus two Draft GPUs at 4K (three GPUs total).
`block_size=16`, `shift_label=true`, `pure_draft_prefix_len=1`).
- Formal recipe: `configs/recipes/domino_qwen3_8b.yaml` (FlexAttention, CP1,
non-packing, REPLICATE, Store/TCP transport, held-out eval and the linear
`lambda_base` curriculum). It is catalogued as `domino`; its export boundary is
native-only. `domino_qwen3_8b_4k_tcp.yaml` remains a shorter smoke test.
`lambda_base` curriculum). It is catalogued as `domino`; SGLang and native export
are both validated. `domino_qwen3_8b_4k_tcp.yaml` remains a shorter smoke test.
- `training.domino_lambda_base` is the constant fallback. Set both
`training.domino_lambda_base_start` and `training.domino_lambda_base_decay_ratio`
to apply the reference linear schedule. Exact recovery records the constant,
Expand Down Expand Up @@ -79,21 +79,41 @@ licensed data, a full learning-rate horizon and the recipe for a real run.

## Export and strict reload

Export a trained checkpoint with the native ASpec artifact format:
Export a trained checkpoint either for SGLang serving (default) or as a native ASpec
artifact:

```bash
aspec export --input-dir outputs/domino-qwen3-8b/checkpoints/iter_0000009 \
--output-dir outputs/domino-qwen3-8b-sglang

aspec export --input-dir outputs/domino-qwen3-8b/checkpoints/iter_0000009 \
--output-dir outputs/domino-qwen3-8b-asset --format aspec
```

Domino currently exports native-only. ASpec has not validated its SGLang export:
upstream SGLang 0.5.21 does load `prefix_gru`/`embed_proj` and has an end-to-end
test for the published checkpoint, but a silent DFlash-style export could still
drop or mis-bind the correction head. The native manifest records the Domino
algorithm, trained `block_size`, label layout, Target feature layers and the full
training objective. `aspec.draft_artifact.load_native_draft` validates the checksums and
semantics, then loads every tensor strictly. A real 8-step checkpoint has been
roundtripped through this path (63 tensors, exact values and dtypes).
SGLang export maps Domino to the published layout
(`architectures=["DFlashDraftModel"]`, `model_type="qwen3"`, nested
`dflash_config.projector_type="domino"`) and preserves the trained `block_size`,
`shift_label`, `pure_draft_prefix_len=1`, `emb_dim`, `gru_hidden_dim` and Target
feature layers. Other label layouts fail closed and require the native format. The
manifest records runtime `DFLASH`; SGLang 0.5.21 loads the exported
`prefix_gru`/`embed_proj` tensors.

The native manifest records the Domino algorithm, trained `block_size`, label layout,
Target feature layers and the full training objective.
`aspec.draft_artifact.load_native_draft` validates the checksums and semantics, then
loads every tensor strictly. A real 8-step checkpoint has been roundtripped through
this path (63 tensors, exact values and dtypes).

Run real decode acceptance against the SGLang export with `aspec evaluate`. Domino
defaults to the full-vocabulary candidate pool (`--domino-candidate-pool-size 0`),
reports measured acceptance length (including Target tokens) and checks greedy
equality and repeat stability:

```bash
aspec evaluate --target /path/to/Qwen3-8B \
--draft outputs/domino-qwen3-8b-sglang \
--data /path/to/held-out-prompts.jsonl --output outputs/domino-decode.json
```

### Official checkpoint mapping

Expand Down Expand Up @@ -135,6 +155,22 @@ Draft GPUs verified 8-step training and step-4 exact resume: losses, model tenso
optimizer state and RNG state matched the uninterrupted run. The public CI lane is
CPU-only; no throughput or convergence claim is made here.

The SGLang export was loaded by official SGLang 0.5.21 and evaluated with
`aspec evaluate` on 16 held-out prompts (32 new tokens, greedy, two repeats):
speculative output matched target-only greedy output, both repeats were stable, and
the measured acceptance length was 2.016 tokens/verification including Target
tokens. This is a bounded decode integration check, not convergence or throughput
evidence.

`tools.validation.domino_acceptance_ablation` runs a paired corrected-versus-backbone
decode by zeroing only the correction output projection in a copy of the same SGLang
asset. On the published checkpoint (16 prompts x 32 greedy tokens, two repeats) the
corrected branch measured 2.829 and backbone-only 2.473 tokens/verification
(+0.355). On the 450-step synthetic ASpec checkpoint the same comparison measured
2.016 versus 2.065 (-0.049), so the correction benefit is checkpoint/data-dependent
rather than unconditional. Both runs kept greedy equality and repeat stability; the
tool rejects mismatched prompts.

A bounded comparison against SpecForge at its Domino merge commit used the same
published Qwen3-8B Domino checkpoint, 16 train / 16 held-out rows, 8 steps, block 16,
128 anchors, FlexAttention and the same linear `lambda_base` schedule. Both trainers
Expand Down Expand Up @@ -269,9 +305,12 @@ handling, empty supervision, and frozen Target/embedding behavior.

## Remaining work

Native export with strict reloading works for ASpec FSDP checkpoints, the official
Qwen3-8B Domino config/weight layout maps into ASpec, and the native
`DominoConsumer` produces proposal tokens for both label layouts. Remaining work is
longer convergence/quality evidence and a real decoding-serving acceptance run;
the recipe is catalogued because the native export/strict reload check passes. CPU numerical and Plan checks do not establish
Qwen3-8B training quality, GPU throughput or decoding acceptance.
SGLang and native export with strict reloading work for ASpec FSDP checkpoints, the
official Qwen3-8B Domino config/weight layout maps into ASpec, the native
`DominoConsumer` produces proposal tokens for both label layouts, bounded real SGLang
decode reports corrected and backbone-only acceptance, and
`tools.validation.domino_anchor_protocol` can materialize and verify a hashed
canonical anchor stream. Remaining work is harder/real data, longer convergence and a
formal anchor-replay training mode (the aligned comparison here used a local validation
harness). CPU numerical and Plan checks do not establish Qwen3-8B training quality
or throughput.
56 changes: 53 additions & 3 deletions tests/cpu/test_domino_export.py
Original file line number Diff line number Diff line change
Expand Up @@ -154,9 +154,59 @@ def test_domino_native_export_rejects_block_size_that_disagrees_with_checkpoint(
)


def test_domino_has_no_serving_export():
with pytest.raises(NotImplementedError, match="--format aspec"):
convert_to_hf._serving_config(_raw_config())
def test_domino_serving_config_uses_the_published_layout():
raw = _raw_config()
exported = convert_to_hf._serving_config(raw)

assert exported["architectures"] == ["DFlashDraftModel"]
assert exported["model_type"] == "qwen3"
assert exported["block_size"] == raw["block_size"]
assert exported["num_target_layers"] == raw["target_num_hidden_layers"]
assert exported["dflash_config"] == {
"projector_type": "domino",
"mask_token_id": raw["mask_token_id"],
"shift_label": True,
"target_layer_ids": raw["target_layer_ids"],
"pure_draft_prefix_len": 1,
"gru_hidden_dim": raw["gru_hidden_dim"],
"emb_dim": raw["emb_dim"],
}


@pytest.mark.parametrize("change, message", [
({"pure_draft_prefix_len": 0}, "pure_draft_prefix_len=1"),
({"shift_label": 1}, "boolean shift_label"),
])
def test_domino_serving_export_rejects_unsupported_layout(change, message):
with pytest.raises((NotImplementedError, ValueError), match=message):
convert_to_hf._serving_config({**_raw_config(), **change})


def test_domino_sglang_export_writes_published_config(tmp_path, monkeypatch):
raw = _raw_config()
model = _model(raw)
_monkeypatch_checkpoint(monkeypatch, model)
source = _prepare_source(tmp_path, raw)
output = tmp_path / "serving"

manifest = convert_to_hf.convert_checkpoint(
input_dir=source, output_dir=output, artifact_format="sglang"
)

assert manifest["storage_format"] == "sglang"
assert manifest["algorithm"] == "domino"
assert manifest["training_contract"]["block_size"] == raw["block_size"]
loader = manifest["draft_structure"]["loader_contract"]
assert loader["runtime"] == "sglang"
assert loader["speculative_algorithm"] == "DFLASH"
exported = json.loads((output / "config.json").read_text())
assert exported["architectures"] == ["DFlashDraftModel"]
assert exported["model_type"] == "qwen3"
assert exported["block_size"] == raw["block_size"]
assert exported["num_target_layers"] == raw["target_num_hidden_layers"]
assert exported["dflash_config"]["projector_type"] == "domino"
assert exported["dflash_config"]["pure_draft_prefix_len"] == 1
assert (output / "model.safetensors").is_file()


def _write_config(tmp_path, raw):
Expand Down
15 changes: 14 additions & 1 deletion tests/test_decode_evaluation.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,13 @@

import pytest

from tools.evaluate_draft import load_prompts, output_checks, speculative_token_budget, summarize
from tools.evaluate_draft import (
load_prompts,
output_checks,
serving_algorithm,
speculative_token_budget,
summarize,
)


def test_decode_prompt_does_not_contain_held_out_answer(tmp_path):
Expand Down Expand Up @@ -90,6 +96,13 @@ def test_dspark_verify_budget_includes_the_target_token_not_an_extra_training_sl
speculative_token_budget({"block_size": 7, "dflash_config": {"block_size": 8}}, "DSPARK")


def test_domino_uses_dflash_verification_with_the_trained_block_size():
assert serving_algorithm("domino") == "DFLASH"
assert speculative_token_budget({"block_size": 16}, "DFLASH") == 16
with pytest.raises(ValueError, match="unsupported exported draft algorithm"):
serving_algorithm("unknown")


def test_equality_between_frameworks_does_not_hide_repeat_instability():
repeats = [[{"output_ids": [1]}], [{"output_ids": [2]}]]
verdict = output_checks(repeats, repeats)
Expand Down
Loading