diff --git a/aspec/commands/convert_to_hf.py b/aspec/commands/convert_to_hf.py index 4059cef..e0b77d3 100644 --- a/aspec/commands/convert_to_hf.py +++ b/aspec/commands/convert_to_hf.py @@ -182,6 +182,12 @@ 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" + ) if raw_config.get("architectures") == ["MedusaDraftModel"]: raise NotImplementedError( @@ -259,7 +265,7 @@ def _serving_config(raw_config: dict) -> dict: def _checkpoint_training_contract(model_dir: Path, raw_config: dict) -> dict: """Recover authoritative training identity from the checkpoint/run artifacts.""" algorithm = resolve_draft_algorithm(raw_config) - family = "DSpark" if algorithm == "dspark" else "DFlash" + family = "DSpark" if algorithm == "dspark" else "Domino" if algorithm == "domino" else "DFlash" if algorithm == "dflash2": raw_config = AutoDraftModelConfig.from_dict(raw_config).to_dict() contract = {"algorithm": algorithm} @@ -271,7 +277,7 @@ def _checkpoint_training_contract(model_dir: Path, raw_config: dict) -> dict: raise ValueError("Export algorithm conflicts with the checkpoint algorithm") if topology.get("training_objective") is not None: contract["objective"] = topology["training_objective"] - if algorithm in {"dspark", "dflash", "dflash2"} and "block_size" in contract["objective"]: + if algorithm in {"dspark", "dflash", "dflash2", "domino"} and "block_size" in contract["objective"]: contract["block_size"] = contract["objective"]["block_size"] if algorithm == "eagle4": from aspec.config.eagle4 import eagle4_training_policy @@ -294,7 +300,7 @@ def _checkpoint_training_contract(model_dir: Path, raw_config: dict) -> dict: # A real run's snapshot records block size even for legacy checkpoints whose # standalone model config did not persist the training-only field. checkpoint_dir = model_dir.parent - if algorithm in {"dspark", "dflash", "dflash2"} and checkpoint_dir.parent.name == "checkpoints": + if algorithm in {"dspark", "dflash", "dflash2", "domino"} and checkpoint_dir.parent.name == "checkpoints": snapshot = checkpoint_dir.parent.parent / "config.yaml" if snapshot.is_file(): from omegaconf import OmegaConf @@ -309,7 +315,7 @@ def _checkpoint_training_contract(model_dir: Path, raw_config: dict) -> dict: if declared is not None and declared != size: raise ValueError("Export block_size conflicts with the training snapshot") contract["block_size"] = size - if algorithm in {"dspark", "dflash", "dflash2"}: + if algorithm in {"dspark", "dflash", "dflash2", "domino"}: size = contract.get("block_size", raw_config.get("block_size")) if size is not None: if type(size) is not int or size < 2: @@ -379,6 +385,11 @@ def convert_checkpoint( raise ValueError("Export output directory must not overlap the source checkpoint or config") raw_config = json.loads(config_path.read_text(encoding="utf-8")) + nested = raw_config.get("dflash_config") + if isinstance(nested, dict) and nested.get("projector_type") == "domino": + from aspec.models.draft.domino import normalize_official_domino_config + + raw_config = normalize_official_domino_config(raw_config) if artifact_format not in {"sglang", "aspec"}: raise ValueError("artifact_format must be sglang or aspec") if verify and artifact_format != "aspec": @@ -505,8 +516,10 @@ def convert_checkpoint( manifest["draft_structure"]["attention"]["dsa"] = policy["dsa"] algorithm = training_contract["algorithm"] block_proposal = algorithm in {"dspark", "dflash"} and not raw_config.get("mtp_conditioning") + domino_proposal = algorithm == "domino" and not raw_config.get("mtp_conditioning") mla_proposal = raw_config.get("architectures") == ["Eagle3DeepseekV2ForCausalLM"] proposal = ("aspec.draft_artifact.MLAEagleConsumer" if mla_proposal else + "aspec.draft_artifact.DominoConsumer" if domino_proposal else "aspec.draft_artifact.BlockDraftConsumer" if block_proposal else None) manifest["draft_structure"]["loader_contract"] = { "runtime": "aspec", "entrypoint": "aspec.draft_artifact.load_native_draft", @@ -518,7 +531,7 @@ def convert_checkpoint( "heads-only asset; strict reload and per-head held-out metrics; " "no candidate-tree acceptance" if algorithm == "medusa" else "asset loading and weights-only warmstart; no native proposal component"), - "borrowed_tensors": ["Target output head"] if algorithm in {"dspark", "dflash"} else [], + "borrowed_tensors": (["Target output head"] if algorithm in {"dspark", "dflash", "domino"} else []), } (output_dir / "export_manifest.json").write_text( json.dumps(manifest, indent=2, sort_keys=True) + "\n", diff --git a/aspec/draft_artifact.py b/aspec/draft_artifact.py index 5e52659..a4e7890 100644 --- a/aspec/draft_artifact.py +++ b/aspec/draft_artifact.py @@ -244,6 +244,99 @@ def propose(self, input_ids, target_features, *, lm_head_weight): return result +class DominoConsumer: + """One Domino block from verifier features and its frozen output head. + + The backbone stays block-parallel. Only the suffix is rolled out + sequentially through the GRU-conditioned correction head, matching the + published Domino inference path. The caller owns verification/acceptance. + """ + + def __init__(self, draft_model, *, block_size): + from aspec.models.dflash import DFlashModel + + self.model = draft_model.eval() + self.algorithm = resolve_draft_algorithm(draft_model.config.to_dict()) + if self.algorithm != "domino": + raise ValueError("DominoConsumer requires a Domino asset") + self.config = draft_model.config + if type(block_size) is not int or block_size < 2: + raise ValueError("block_size must be an integer >= 2") + if self.config.block_size != block_size: + raise ValueError("Proposal block size disagrees with the trained asset") + self.block_size = block_size + self.shift_label = bool(self.config.shift_label) + self.suffix_start = int(self.config.pure_draft_prefix_len) + if self.shift_label: + self.k_draft = block_size + else: + self.k_draft = block_size - 1 + if not 0 <= self.suffix_start < self.k_draft: + raise ValueError("Domino prefix leaves no corrected position in the block") + backend = "fa4" if next(draft_model.parameters()).device.type == "cuda" else "sdpa" + self.backbone = DFlashModel(draft_model, block_size=block_size, num_anchors=1, + attention_backend=backend) + # Match Domino training on CPU: hide context rows at/after the anchor and + # other blocks with the same dense block mask instead of plain SDPA. + self.backbone._materialize_cpu_block_mask = True + + @torch.no_grad() + def propose(self, input_ids, target_features, *, lm_head_weight): + """IDs/features describe one known prefix, including its last anchor token.""" + if input_ids.ndim != 2 or input_ids.shape[0] != 1 or input_ids.shape[1] < 1: + raise ValueError("Block proposal currently consumes one nonempty prefix") + length = input_ids.shape[1] + config = self.model.config + width = config.target_hidden_size * config.num_target_layers + if target_features.shape != (1, length, width): + raise ValueError("Target features must match the asset's ordered layers and prefix") + if lm_head_weight.shape != (config.vocab_size, config.hidden_size): + raise ValueError("Frozen Target output head shape does not match the Draft") + if input_ids.device != target_features.device or input_ids.device != lm_head_weight.device: + raise ValueError("Proposal IDs, features and output head must share a device") + if length + self.block_size - 1 > config.max_position_embeddings: + raise ValueError("Proposal exceeds the artifact's supported position range") + + anchor = torch.tensor([[length - 1]], device=input_ids.device) + padded = F.pad(input_ids, (0, self.block_size), value=config.mask_token_id) + mask = torch.ones((1, length + self.block_size), device=input_ids.device) + if self.backbone.attention_backend == "fa4": + features = target_features + packed_positions = torch.arange(length, device=input_ids.device)[None] + else: + # The non-direct-CP context path expects one feature row per context + # token. Anchor visibility excludes these padded future rows. + features = F.pad(target_features, (0, 0, 0, self.block_size)) + packed_positions = None + hidden = self.backbone._draft_backbone( + padded, features, mask, + packed_context_positions=packed_positions, + injected_anchors=anchor, injected_keep_mask=torch.ones_like(anchor, dtype=torch.bool), + )[0][0].unsqueeze(0) + if not self.shift_label: + hidden = hidden[:, 1:, :] + base_logits = F.linear(hidden, lm_head_weight) + + prefix_ids = base_logits[:, : self.suffix_start].argmax(-1) + realized = torch.cat((input_ids[:, -1:], prefix_ids), dim=1) + prefix_embeds = self.model.embed_tokens(realized).to(self.model.prefix_gru.weight_ih_l0.dtype) + _, gru_hidden = self.model.prefix_gru(prefix_embeds) + + tokens = [prefix_ids] + for position in range(self.suffix_start, self.k_draft): + z = hidden[:, position : position + 1, :] + state = gru_hidden.transpose(0, 1) + bias = self.model.embed_proj(torch.cat((z, state), dim=-1)) + current = (base_logits[:, position : position + 1, :] + bias).argmax(-1) + tokens.append(current) + if position + 1 < self.k_draft: + new_embed = self.model.embed_tokens(current).to( + self.model.prefix_gru.weight_ih_l0.dtype + ) + _, gru_hidden = self.model.prefix_gru(new_embed, gru_hidden) + return {"token_ids": torch.cat(tokens, dim=1), "algorithm": "domino"} + + class MLAEagleConsumer: """Greedy recurrent MLA proposals with an owner-local materialized KV cache. diff --git a/aspec/models/draft/auto.py b/aspec/models/draft/auto.py index e9e802a..ec99a3f 100644 --- a/aspec/models/draft/auto.py +++ b/aspec/models/draft/auto.py @@ -85,6 +85,12 @@ class AutoDraftModelConfig: def from_dict(cls, config: dict): config = dict(config) + nested = config.get("dflash_config") + if isinstance(nested, dict) and nested.get("projector_type") == "domino": + from aspec.models.draft.domino import normalize_official_domino_config + + config = normalize_official_domino_config(config) + if "tie_word_embeddings" in config and config.get("architectures") != ["MedusaDraftModel"]: logger.info("Set draft model tie_word_embeddings to False") config["tie_word_embeddings"] = False diff --git a/aspec/models/draft/domino.py b/aspec/models/draft/domino.py index 3e0823b..f5ced5e 100644 --- a/aspec/models/draft/domino.py +++ b/aspec/models/draft/domino.py @@ -177,3 +177,77 @@ def correct_logits( dim=2, ) return corrected.reshape(batch, draft_len, logits.size(-1)) + + +def normalize_official_domino_config(raw: dict) -> dict: + """Translate the published Domino config layout into ASpec's flat layout. + + The reference checkpoint publishes ``architectures=["DFlashDraftModel"]``, + ``model_type="qwen3"`` and nests the Domino fields under ``dflash_config``. + In that layout ``num_target_layers`` is the Target decoder depth, while + ASpec's flat config uses it as the number of captured feature layers. + """ + raw = dict(raw) + nested = raw.pop("dflash_config", None) + if not isinstance(nested, dict) or nested.get("projector_type") != "domino": + raise ValueError("Not an official Domino draft config") + layer_ids = nested.get("target_layer_ids") + if not isinstance(layer_ids, list) or not layer_ids: + raise ValueError("Official Domino config requires target_layer_ids") + target_depth = raw.get("num_target_layers") + if isinstance(target_depth, bool) or not isinstance(target_depth, int) or target_depth < 1: + raise ValueError("Official Domino config requires the Target decoder depth") + raw["architectures"] = ["DominoDraftModel"] + raw["model_type"] = "domino" + raw["projector_type"] = "domino" + for key in ( + "mask_token_id", + "shift_label", + "target_layer_ids", + "pure_draft_prefix_len", + "gru_hidden_dim", + "emb_dim", + ): + if key in nested: + raw[key] = nested[key] + raw["num_target_layers"] = len(layer_ids) + raw["target_num_hidden_layers"] = target_depth + raw.pop("auto_map", None) + raw.pop("max_window_layers", None) + return raw + + +def official_domino_config(raw: dict) -> dict: + """Translate ASpec's flat Domino config into the published HF layout.""" + from aspec.config.draft_algorithm import resolve_draft_algorithm + + raw = dict(raw) + if resolve_draft_algorithm(raw) != "domino": + raise ValueError("Not an ASpec Domino draft config") + target_depth = raw.get("target_num_hidden_layers") + layer_ids = raw.get("target_layer_ids") + if isinstance(target_depth, bool) or not isinstance(target_depth, int) or target_depth < 1: + raise ValueError("Domino export requires the Target decoder depth") + if not isinstance(layer_ids, list) or not layer_ids: + raise ValueError("Domino export requires target_layer_ids") + nested = { + key: raw[key] + for key in ( + "mask_token_id", + "shift_label", + "target_layer_ids", + "pure_draft_prefix_len", + "gru_hidden_dim", + "emb_dim", + ) + if key in raw + } + # DominoConfig defaults the flat field; the published layout must carry the + # discriminator explicitly so the normalizer can recognize it. + nested["projector_type"] = "domino" + raw["architectures"] = ["DFlashDraftModel"] + raw["model_type"] = "qwen3" + raw["num_target_layers"] = target_depth + raw["dflash_config"] = nested + raw.pop("auto_map", None) + return raw diff --git a/configs/recipes/domino_qwen3_8b.yaml b/configs/recipes/domino_qwen3_8b.yaml new file mode 100644 index 0000000..bf23a61 --- /dev/null +++ b/configs/recipes/domino_qwen3_8b.yaml @@ -0,0 +1,93 @@ +# Formal single-node Domino recipe: training, lambda_base curriculum, held-out +# backbone/corrected observations and exact recovery. Hyperparameters are a +# starting point, not a convergence or acceptance claim. +model: + target_model_path: ${oc.env:ASPEC_TARGET_MODEL,Qwen/Qwen3-8B} + native_context_length: 32768 + trust_remote_code: false + draft_model_config: aspec/config/domino_qwen3_8b_draft_config.json +dataset: + eval_interval: 100 + eval_micro_batch_size: 1 + train_data_path: ${oc.env:ASPEC_TRAIN_DATA} + eval_data_path: ${oc.env:ASPEC_EVAL_DATA} + chat_template: qwen3-instruct + prompt_key: conversations + min_loss_tokens: 32 + shuffle_dataset: true + dataset_seed: 42 +training: + attention_backend: flex_attention + draft_context_parallel_size: 1 + micro_batch_size: 1 + draft_accumulation_steps: 2 + learning_rate: 6e-4 + min_lr: 6e-5 + weight_decay: 0.0 + max_grad_norm: 1.0 + max_seq_length: 4096 + num_epochs: 3 + warmup_ratio: 0.04 + seed: 42 + continual_training: false + deterministic_anchor_sampling: false + training_num_gpus_per_node: 2 + training_num_nodes: 1 + placement_strategy: inference_first + fsdp_strategy: REPLICATE + fsdp_reduce_dtype: bfloat16 + compile_model: false + max_concurrent_batches: 1 + streaming_dispatch_with_training: true + pipeline_dispatch_with_training: true + prefetch_depth: 1 + save_interval: 100 + save_per_epoch: false + save_final_checkpoint: true + max_checkpoints: 2 + dflash_block_size: 16 + dflash_packing: false + dflash_num_target_layers: 5 + dflash_num_anchors: 128 + dflash_loss_objective: decay + dflash_loss_decay_gamma: 7.0 + dflash_ce_loss_alpha: 1.0 + dflash_l1_loss_alpha: 0.0 + domino_lambda_base: 0.3 + domino_lambda_base_start: 1.0 + domino_lambda_base_decay_ratio: 1.0 + domino_eval_backbone: true +inference: + inference_engine_type: sgl + store_last_hidden_states: false + target_prefill_memory_optimized: false + inference_num_gpus: 1 + inference_num_gpus_per_engine: 1 + inference_num_gpus_per_node: 3 + inference_fetch_batch: 8 + inference_buffer_threshold: 2 + max_sample_pool_size: 12 + inference_batch_size: 2 + sglang: + tp_size: 1 + mem_fraction_static: 0.5 +mooncake: + master_server_address: null + metadata_server: null + data_plane: store + protocol: tcp + enable_gpu_direct: false + allow_host_fallback: false + global_segment_size: 32GB + local_buffer_size: 8GB + host_buffer_size: 1GB + async_put_pool_size: 1 + enable_hard_pin: true + max_seq_len: 4096 + hidden_dim: 4096 +logging: + report_to: none +debug: + enable_perf_metrics: true +output_dir: outputs/domino-qwen3-8b +cache_dir: cache/domino-qwen3-8b diff --git a/docs/support.md b/docs/support.md index 6ee9d35..fa988c3 100644 --- a/docs/support.md +++ b/docs/support.md @@ -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 and consumer 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; native export, strict reload, proposal consumer and a bounded SpecForge comparison are validated; longer convergence/decoding acceptance 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 | diff --git a/docs/user-guide/domino.md b/docs/user-guide/domino.md index 9089ccd..1b18355 100644 --- a/docs/user-guide/domino.md +++ b/docs/user-guide/domino.md @@ -5,18 +5,18 @@ This implements [ASpec #38](https://github.com/inclusionAI/ASpec/issues/38) thro `aspec.models.domino.DominoModel`: a block-parallel DFlash backbone with a GRU-conditioned causal correction head. The ASpec training CLI now selects this algorithm through `aspec/config/domino_qwen3_8b_draft_config.json`. The -[supplementary held-out example](../../configs/examples/domino_qwen3_8b_eval.yaml) -and the [smoke workflow](../../configs/examples/domino_qwen3_8b_4k_tcp.yaml) both run -one Target GPU plus two Draft GPUs at 4K (three GPUs total). +[formal recipe](../../configs/recipes/domino_qwen3_8b.yaml) and the +[smoke workflow](../../configs/examples/domino_qwen3_8b_4k_tcp.yaml) both run one +Target GPU plus two Draft GPUs at 4K (three GPUs total). ## Training selection - Draft config: `aspec/config/domino_qwen3_8b_draft_config.json` (Qwen3-8B, `block_size=16`, `shift_label=true`, `pure_draft_prefix_len=1`). -- Held-out example: `configs/examples/domino_qwen3_8b_eval.yaml` (FlexAttention, - CP1, non-packing, REPLICATE, Store/TCP transport, held-out eval and the linear - `lambda_base` curriculum). Catalog promotion waits for native export/strict - reload validation; `domino_qwen3_8b_4k_tcp.yaml` remains a shorter smoke test. +- 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. - `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, @@ -42,7 +42,7 @@ CUDA_VISIBLE_DEVICES=0 aspec target \ ``` For held-out data and the curriculum, set `ASPEC_TRAIN_DATA` and `ASPEC_EVAL_DATA` -and use `configs/examples/domino_qwen3_8b_eval.yaml`. Compile the smoke example, +and use `configs/recipes/domino_qwen3_8b.yaml`. Compile the smoke example, then train with two Draft GPUs (GPUs 1 and 2): ```bash @@ -77,13 +77,70 @@ decoding-acceptance evidence. A GPU run with one Target plus two Draft GPUs has reported for training and exact resume; it does not establish model quality. Supply 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: + +```bash +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). + +### Official checkpoint mapping + +The published `Huang2020/Qwen3-8B-Domino-b16` checkpoint uses +`architectures=["DFlashDraftModel"]`, `model_type="qwen3"`, and nests the Domino +fields under `dflash_config`. In that layout `num_target_layers` is the Target +decoder depth (36), not ASpec's feature count (5). Convert the config once before +training: + +```python +import json +from aspec.models.draft import AutoDraftModelConfig + +raw = json.load(open("Qwen3-8B-Domino-b16/config.json")) +json.dump(AutoDraftModelConfig.from_dict(raw).to_dict(), open("aspec_domino.json", "w")) +``` + +`AutoDraftModelConfig.from_dict` detects `dflash_config.projector_type="domino"` +and produces the flat `DominoDraftModel`/`model_type="domino"` config. The published +weight names already match ASpec's export names (`fc`, `hidden_norm`, `norm`, +`layers.*`, `prefix_gru.*`, `embed_proj.*`); `load_initial_draft_weights` maps them +back and borrows the missing `embed_tokens.weight` from the Target. Verified against +the published config and all 62 tensor names/shapes. + +### Native proposal component + +`aspec.draft_artifact.DominoConsumer` loads a native Domino asset and rolls out one +block: the DFlash backbone stays block-parallel, the pure prefix keeps backbone +logits, and the suffix is generated sequentially with `prefix_gru` + `embed_proj` +using already generated tokens. It mirrors the reference `spec_generate` indexing for +both `shift_label=true` and `shift_label=false`. The manifest advertises this +entrypoint; verification and acceptance remain caller-owned. + ## Validation status Plan compilation, registration, trainer construction, checkpoint topology and the CPU numerical contracts are covered by `tests/cpu`. A GPU run with one Target and two Draft GPUs verified 8-step training and step-4 exact resume: losses, model tensors, optimizer state and RNG state matched the uninterrupted run. The public CI lane is -CPU-only; no throughput, quality or decoding-acceptance claim is made here. +CPU-only; no throughput or convergence claim is made here. + +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 +kept corrected acceptance above the backbone-only branch. Anchor sampling, batch +aggregation and acceptance naming differ (SpecForge reports accepted tokens including +the root), so the comparison is directional rather than a strict parity test. ## Reference and selected scope @@ -212,8 +269,9 @@ handling, empty supervision, and frozen Target/embedding behavior. ## Remaining work -Native export with strict reloading, Target bindings, proposal consumers and -acceptance observations remain pending. Recipe catalog promotion also waits for the -native export/strict reload check. The next planned increment is the aligned -SpecForge-vs-ASpec comparison. CPU numerical and Plan checks do not establish +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. diff --git a/docs/user-guide/recipes.md b/docs/user-guide/recipes.md index 0a1c3bc..59261d3 100644 --- a/docs/user-guide/recipes.md +++ b/docs/user-guide/recipes.md @@ -18,6 +18,7 @@ connections on your hardware before training. | `quickstart` | Qwen3-8B / DSpark | 1 node, 2 GPUs: 1T + 1D; 1K | Try training, recovery and export with bundled data | | `dspark` | Qwen3-8B / Dense DSpark | 1 node, 8 GPUs: 4T + 4D; 4K | Train on your data with packing and NVLink | | `dflash` | Qwen3-8B / DFlash | 1 node, 3 GPUs: 1T + 2D; 4K | Train a block-parallel DFlash Draft | +| `domino` | Qwen3-8B / Domino | 1 node, 3 GPUs: 1T + 2D; 4K | Train a DFlash backbone with a GRU correction head | | `medusa` | Qwen3-8B / heads-only Medusa | 1 node, 2 GPUs: 1T + 1D; 4K | Train parallel future-token heads and export a native heads asset | | `eagle3` | Qwen3-8B / EAGLE3 | 1 node, 3 GPUs: 1T + 2D; 4K | Train a recurrent EAGLE3 Draft | | `eagle4` | Qwen3-8B / EAGLE4 | 1 node, 3 GPUs: 1T + 2D; 4K; sequential stages | Train a Draft, then candidate retrieval projections | diff --git a/tests/cpu/test_domino_consumer.py b/tests/cpu/test_domino_consumer.py new file mode 100644 index 0000000..ed80226 --- /dev/null +++ b/tests/cpu/test_domino_consumer.py @@ -0,0 +1,131 @@ +# Copyright 2026 Ant Group Co., Ltd. +# SPDX-License-Identifier: Apache-2.0 + +"""Domino native proposal mirrors the published sequential correction rollout.""" + +import pytest +import torch + +from aspec.draft_artifact import DominoConsumer +from aspec.models.draft import AutoDraftModelConfig, AutoEagle3DraftModel + + +def _raw(*, shift_label, prefix_len): + return { + "architectures": ["DominoDraftModel"], + "model_type": "domino", + "projector_type": "domino", + "hidden_size": 16, + "intermediate_size": 32, + "num_hidden_layers": 1, + "num_attention_heads": 2, + "num_key_value_heads": 1, + "head_dim": 8, + "vocab_size": 32, + "target_hidden_size": 16, + "num_target_layers": 2, + "target_num_hidden_layers": 6, + "target_layer_ids": [1, 4], + "max_position_embeddings": 128, + "mask_token_id": 31, + "block_size": 5, + "emb_dim": 6, + "gru_hidden_dim": 8, + "shift_label": shift_label, + "pure_draft_prefix_len": prefix_len, + } + + +def _setup(*, shift_label, prefix_len): + torch.manual_seed(11) + model = AutoEagle3DraftModel.from_config( + AutoDraftModelConfig.from_dict(_raw(shift_label=shift_label, prefix_len=prefix_len)) + ).eval() + ids = torch.tensor([[2, 3, 5, 7]]) + features = torch.randn(1, 4, 32) + head = torch.randn(32, 16) + return model, ids, features, head + + +def _block_hidden(consumer, ids, features): + anchor = torch.tensor([[ids.shape[1] - 1]]) + padded = torch.nn.functional.pad(ids, (0, consumer.block_size), value=consumer.config.mask_token_id) + features = torch.nn.functional.pad(features, (0, 0, 0, consumer.block_size)) + hidden = consumer.backbone._draft_backbone( + padded, features, torch.ones((1, padded.shape[1])), + injected_anchors=anchor, + injected_keep_mask=torch.ones_like(anchor, dtype=torch.bool), + )[0][0] + return hidden.unsqueeze(0) if consumer.shift_label else hidden[1:].unsqueeze(0) + + +def _reference(consumer, ids, features, head): + hidden = _block_hidden(consumer, ids, features) + base_logits = torch.nn.functional.linear(hidden, head) + prefix = base_logits[:, : consumer.suffix_start].argmax(-1) + realized = torch.cat((ids[:, -1:], prefix), dim=1) + embeds = consumer.model.embed_tokens(realized) + _, state = consumer.model.prefix_gru(embeds) + tokens = [prefix] + for position in range(consumer.suffix_start, consumer.k_draft): + z = hidden[:, position:position + 1, :] + bias = consumer.model.embed_proj(torch.cat((z, state.transpose(0, 1)), dim=-1)) + token = (base_logits[:, position:position + 1, :] + bias).argmax(-1) + tokens.append(token) + if position + 1 < consumer.k_draft: + _, state = consumer.model.prefix_gru(consumer.model.embed_tokens(token), state) + return torch.cat(tokens, dim=1) + + +def test_domino_consumer_matches_sequential_reference_for_both_layouts(): + for shift_label, prefix_len, expected_len in ((True, 1, 5), (False, 0, 4)): + model, ids, features, head = _setup(shift_label=shift_label, prefix_len=prefix_len) + consumer = DominoConsumer(model, block_size=model.config.block_size) + actual = consumer.propose(ids, features, lm_head_weight=head) + expected = _reference(consumer, ids, features, head) + assert actual["algorithm"] == "domino" + assert actual["token_ids"].shape == (1, expected_len) + torch.testing.assert_close(actual["token_ids"], expected, atol=0, rtol=0) + + +def test_domino_prefix_is_backbone_only_and_suffix_uses_correction_head(): + model, ids, features, head = _setup(shift_label=True, prefix_len=1) + consumer = DominoConsumer(model, block_size=model.config.block_size) + baseline = consumer.propose(ids, features, lm_head_weight=head)["token_ids"] + + with torch.no_grad(): + model.embed_proj[2].weight.zero_() + model.embed_proj[2].weight[5].fill_(100.0) + corrected = consumer.propose(ids, features, lm_head_weight=head)["token_ids"] + torch.testing.assert_close(corrected[:, :1], baseline[:, :1], atol=0, rtol=0) + assert torch.equal(corrected[:, 1:], torch.full_like(corrected[:, 1:], 5)) + + +def test_domino_consumer_rejects_other_block_algorithms(): + from aspec.models.draft.dflash import DFlashDraftModel + + raw = _raw(shift_label=True, prefix_len=1) + raw.update(architectures=["DFlashDraftModel"], model_type="dflash") + config = AutoDraftModelConfig.from_dict(raw) + try: + DominoConsumer(DFlashDraftModel(config), block_size=5) + except ValueError as exc: + assert "Domino" in str(exc) + else: + raise AssertionError("DominoConsumer accepted a non-Domino asset") + + +@pytest.mark.parametrize("shift_label,prefix_len", [(True, 1), (False, 0)]) +def test_anchor_target_feature_is_hidden_from_the_block(shift_label, prefix_len): + model, ids, features, head = _setup(shift_label=shift_label, prefix_len=prefix_len) + consumer = DominoConsumer(model, block_size=model.config.block_size) + baseline = _block_hidden(consumer, ids, features) + + changed = features.clone() + changed[:, -1, :] += 10.0 + after = _block_hidden(consumer, ids, changed) + torch.testing.assert_close(after, baseline, atol=0, rtol=0) + + baseline_tokens = consumer.propose(ids, features, lm_head_weight=head)["token_ids"] + changed_tokens = consumer.propose(ids, changed, lm_head_weight=head)["token_ids"] + torch.testing.assert_close(changed_tokens, baseline_tokens, atol=0, rtol=0) diff --git a/tests/cpu/test_domino_export.py b/tests/cpu/test_domino_export.py new file mode 100644 index 0000000..3af3e5c --- /dev/null +++ b/tests/cpu/test_domino_export.py @@ -0,0 +1,186 @@ +# Copyright 2026 Ant Group Co., Ltd. +# SPDX-License-Identifier: Apache-2.0 + +"""Domino native export preserves correction-head semantics and strict weights.""" + +import json + +import pytest +import torch + +from aspec.draft_artifact import load_native_draft +from aspec.models.draft import AutoDraftModelConfig, AutoEagle3DraftModel +from aspec.models.draft.domino import official_domino_config +from aspec.training.checkpoint import load_initial_draft_weights +from tools import convert_to_hf + + +def _raw_config(**overrides): + raw = { + "architectures": ["DominoDraftModel"], + "model_type": "domino", + "projector_type": "domino", + "hidden_size": 16, + "intermediate_size": 32, + "num_hidden_layers": 1, + "num_attention_heads": 2, + "num_key_value_heads": 1, + "head_dim": 8, + "vocab_size": 32, + "target_hidden_size": 16, + "num_target_layers": 2, + "target_num_hidden_layers": 6, + "target_layer_ids": [1, 4], + "max_position_embeddings": 128, + "mask_token_id": 31, + "block_size": 5, + "emb_dim": 6, + "gru_hidden_dim": 8, + "shift_label": True, + "pure_draft_prefix_len": 1, + } + raw.update(overrides) + return raw + + +def _prepare_source(tmp_path, raw, *, block_size=None, semantics=None): + start = "iter_0000002" + source = tmp_path / start + (source / "model").mkdir(parents=True) + (source / "model/.metadata").write_bytes(b"stub") + (source / "draft_config.json").write_text(json.dumps(raw)) + (source / "meta.json").write_text(json.dumps({"training_topology": { + "draft_algorithm": "domino", + "training_objective": { + "block_size": raw["block_size"] if block_size is None else block_size, + "loss": "mixed_corrected_backbone_ce", + "loss_decay_gamma": 7.0, + "lambda_base": 0.3, + }, + "draft_model_semantics": semantics or raw, + }})) + return source + + +def _model(raw, dtype=torch.bfloat16): + config = AutoDraftModelConfig.from_dict(raw) + return AutoEagle3DraftModel.from_config(config, torch_dtype=dtype) + + +def _monkeypatch_checkpoint(monkeypatch, model): + wrapped = { + "model_state.model.draft_model." + key: value.detach().clone() + for key, value in model.state_dict().items() + } + monkeypatch.setattr(convert_to_hf, "_load_fsdp_state_dict", lambda _: wrapped) + + +def test_domino_native_export_roundtrips_every_tensor(tmp_path, monkeypatch): + raw = _raw_config() + model = _model(raw) + with torch.no_grad(): + for parameter in model.parameters(): + parameter.add_(0.0001234) + _monkeypatch_checkpoint(monkeypatch, model) + source = _prepare_source(tmp_path, raw) + output = tmp_path / "asset" + + manifest = convert_to_hf.convert_checkpoint( + input_dir=source, output_dir=output, artifact_format="aspec" + ) + + assert manifest["storage_format"] == "aspec_native" + assert manifest["algorithm"] == "domino" + assert manifest["training_contract"]["block_size"] == raw["block_size"] + loader = manifest["draft_structure"]["loader_contract"] + assert loader["proposal_entrypoint"] == "aspec.draft_artifact.DominoConsumer" + assert loader["borrowed_tensors"] == ["Target output head"] + exported = json.loads((output / "config.json").read_text()) + for key in ( + "architectures", "model_type", "projector_type", "block_size", "emb_dim", + "gru_hidden_dim", "shift_label", "pure_draft_prefix_len", "target_layer_ids", + "num_target_layers", "target_num_hidden_layers", + ): + assert exported[key] == raw[key] + + loaded = load_native_draft(output) + assert set(loaded.state_dict()) == set(model.state_dict()) + for key, value in model.state_dict().items(): + assert value.dtype == loaded.state_dict()[key].dtype + torch.testing.assert_close(value, loaded.state_dict()[key], atol=0, rtol=0) + for key, value in model.named_buffers(): + actual = dict(loaded.named_buffers())[key] + assert value.dtype == actual.dtype + torch.testing.assert_close(value, actual, atol=0, rtol=0) + + warm = _model(raw) + load_initial_draft_weights(warm, str(output)) + for key, value in model.state_dict().items(): + torch.testing.assert_close(warm.state_dict()[key], value, atol=0, rtol=0) + + +@pytest.mark.parametrize("field", ["shift_label", "pure_draft_prefix_len", "gru_hidden_dim"]) +def test_domino_native_export_rejects_semantics_that_disagree_with_checkpoint( + tmp_path, field +): + raw = _raw_config() + changed = dict(raw) + if field == "shift_label": + changed[field] = not raw[field] + changed["pure_draft_prefix_len"] = 0 + elif field == "pure_draft_prefix_len": + changed[field] = 0 + else: + changed[field] = raw[field] + 2 + source = _prepare_source(tmp_path, raw, semantics=raw) + with pytest.raises(ValueError, match="semantics conflict"): + convert_to_hf.convert_checkpoint( + input_dir=source, + output_dir=tmp_path / "asset", + config_path=_write_config(tmp_path, changed), + artifact_format="aspec", + ) + + +def test_domino_native_export_rejects_block_size_that_disagrees_with_checkpoint( + tmp_path, monkeypatch +): + raw = _raw_config() + _monkeypatch_checkpoint(monkeypatch, _model(raw)) + source = _prepare_source(tmp_path, raw, block_size=raw["block_size"] + 1) + with pytest.raises(ValueError, match="block_size conflicts"): + convert_to_hf.convert_checkpoint( + input_dir=source, output_dir=tmp_path / "asset", artifact_format="aspec" + ) + + +def test_domino_has_no_serving_export(): + with pytest.raises(NotImplementedError, match="--format aspec"): + convert_to_hf._serving_config(_raw_config()) + + +def _write_config(tmp_path, raw): + path = tmp_path / "changed_draft_config.json" + path.write_text(json.dumps(raw)) + return path + + +def test_native_export_accepts_the_published_domino_config(tmp_path, monkeypatch): + flat = _raw_config() + model = _model(flat) + _monkeypatch_checkpoint(monkeypatch, model) + published = official_domino_config(flat) + source = _prepare_source(tmp_path, published) + output = tmp_path / "asset" + + manifest = convert_to_hf.convert_checkpoint( + input_dir=source, output_dir=output, artifact_format="aspec" + ) + + assert manifest["algorithm"] == "domino" + assert manifest["training_contract"]["block_size"] == flat["block_size"] + exported = json.loads((output / "config.json").read_text()) + assert exported["architectures"] == ["DominoDraftModel"] + assert exported["model_type"] == "domino" + assert exported["num_target_layers"] == flat["num_target_layers"] + assert exported["target_num_hidden_layers"] == flat["target_num_hidden_layers"] diff --git a/tests/cpu/test_domino_official.py b/tests/cpu/test_domino_official.py new file mode 100644 index 0000000..016e902 --- /dev/null +++ b/tests/cpu/test_domino_official.py @@ -0,0 +1,148 @@ +# Copyright 2026 Ant Group Co., Ltd. +# SPDX-License-Identifier: Apache-2.0 + +"""Map the published Qwen3 Domino config/weight layout into ASpec.""" + + +import torch +from safetensors.torch import save_file + +from aspec.models.draft import AutoDraftModelConfig, AutoEagle3DraftModel +from aspec.models.draft.domino import ( + normalize_official_domino_config, + official_domino_config, +) +from aspec.models.draft.keymap import to_export_keys +from aspec.training.checkpoint import load_initial_draft_weights + +_OFFICIAL = { + "architectures": ["DFlashDraftModel"], + "auto_map": {"AutoModel": "dflash.DFlashDraftModel"}, + "model_type": "qwen3", + "dtype": "bfloat16", + "vocab_size": 151936, + "bos_token_id": 151643, + "eos_token_id": 151645, + "block_size": 16, + "num_target_layers": 36, + "num_hidden_layers": 5, + "hidden_size": 4096, + "intermediate_size": 12288, + "emb_dim": 256, + "num_attention_heads": 32, + "num_key_value_heads": 8, + "head_dim": 128, + "hidden_act": "silu", + "rms_norm_eps": 1e-06, + "max_position_embeddings": 40960, + "rope_theta": 1000000, + "tie_word_embeddings": False, + "layer_types": ["full_attention"] * 5, + "max_window_layers": 5, + "dflash_config": { + "projector_type": "domino", + "mask_token_id": 151669, + "shift_label": True, + "target_layer_ids": [1, 9, 17, 25, 33], + "pure_draft_prefix_len": 1, + "gru_hidden_dim": 1024, + "emb_dim": 256, + }, +} + + +def _raw(**overrides): + raw = { + "architectures": ["DominoDraftModel"], + "model_type": "domino", + "projector_type": "domino", + "hidden_size": 16, + "intermediate_size": 32, + "num_hidden_layers": 1, + "num_attention_heads": 2, + "num_key_value_heads": 1, + "head_dim": 8, + "vocab_size": 32, + "target_hidden_size": 16, + "num_target_layers": 2, + "target_num_hidden_layers": 6, + "target_layer_ids": [1, 4], + "max_position_embeddings": 128, + "mask_token_id": 31, + "block_size": 5, + "emb_dim": 6, + "gru_hidden_dim": 8, + "shift_label": True, + "pure_draft_prefix_len": 1, + } + raw.update(overrides) + return raw + + +def test_official_qwen3_domino_config_maps_to_flat_aspec_layout(): + config = AutoDraftModelConfig.from_dict(_OFFICIAL) + assert config.architectures == ["DominoDraftModel"] + assert config.model_type == "domino" + assert config.projector_type == "domino" + assert config.block_size == 16 + assert config.num_target_layers == 5 + assert config.target_num_hidden_layers == 36 + assert config.target_layer_ids == [1, 9, 17, 25, 33] + assert config.shift_label is True + assert config.pure_draft_prefix_len == 1 + assert config.emb_dim == 256 + assert config.gru_hidden_dim == 1024 + + +def test_flat_config_roundtrips_through_published_layout(): + flat = _raw() + published = official_domino_config(flat) + assert published["architectures"] == ["DFlashDraftModel"] + assert published["model_type"] == "qwen3" + assert published["num_target_layers"] == flat["target_num_hidden_layers"] + assert published["dflash_config"]["target_layer_ids"] == flat["target_layer_ids"] + restored = normalize_official_domino_config(published) + assert restored["architectures"] == ["DominoDraftModel"] + assert restored["model_type"] == "domino" + assert restored["num_target_layers"] == flat["num_target_layers"] + assert restored["target_num_hidden_layers"] == flat["target_num_hidden_layers"] + for key in ("projector_type", "block_size", "emb_dim", "gru_hidden_dim", + "shift_label", "pure_draft_prefix_len", "target_layer_ids", + "mask_token_id"): + assert restored[key] == flat[key] + + +def test_official_weight_names_load_with_borrowed_embedding(tmp_path): + raw = _raw() + source = AutoEagle3DraftModel.from_config(AutoDraftModelConfig.from_dict(raw)) + official = to_export_keys(source.state_dict()) + official.pop("embed_tokens.weight") + path = tmp_path / "model.safetensors" + save_file(official, str(path)) + + target = AutoEagle3DraftModel.from_config(AutoDraftModelConfig.from_dict(raw)) + load_initial_draft_weights(target, str(path), allow_target_embedding=True) + loaded = target.state_dict() + for key, value in source.state_dict().items(): + if key == "embed_tokens.weight": + continue + torch.testing.assert_close(loaded[key], value, atol=0, rtol=0) + + +def test_unknown_nested_projector_is_not_rewritten(): + published = {key: value for key, value in _OFFICIAL.items() if key != "max_window_layers"} + raw = {**published, "dflash_config": {**_OFFICIAL["dflash_config"], + "projector_type": "dflash"}} + config = AutoDraftModelConfig.from_dict(raw) + assert config.architectures == ["DFlashDraftModel"] + assert config.model_type == "qwen3" + + +def test_published_layout_includes_default_projector(): + flat = _raw() + flat.pop("projector_type") + published = official_domino_config(flat) + assert published["dflash_config"]["projector_type"] == "domino" + restored = normalize_official_domino_config(published) + assert restored["architectures"] == ["DominoDraftModel"] + assert restored["projector_type"] == "domino" diff --git a/tests/cpu/test_release_recipes.py b/tests/cpu/test_release_recipes.py index 4deb160..34af847 100644 --- a/tests/cpu/test_release_recipes.py +++ b/tests/cpu/test_release_recipes.py @@ -83,7 +83,7 @@ def test_qwen8b_recipes_plan_without_target_override(name, monkeypatch): def test_catalog_exactly_covers_formal_files(): entries = recipes.catalog() - assert len(entries) == 14 + assert len(entries) == 15 declared = {p for entry in entries.values() for p in entry["configs"]} assert declared == { str(p.relative_to(recipes.ROOT)) for p in (recipes.ROOT / "configs/recipes").glob("*.yaml") diff --git a/tools/recipe_catalog.json b/tools/recipe_catalog.json index 877e2e1..be2254a 100644 --- a/tools/recipe_catalog.json +++ b/tools/recipe_catalog.json @@ -32,6 +32,17 @@ "draft_gpus": 2, "native_only_export": false }, + "domino": { + "configs": [ + "configs/recipes/domino_qwen3_8b.yaml" + ], + "model": "Qwen3-8B", + "nodes": 1, + "gpus": 3, + "target_gpus": 1, + "draft_gpus": 2, + "native_only_export": true + }, "eagle3": { "configs": [ "configs/recipes/qwen3_8b_eagle3.yaml"