From c50d2f3195639580b6389b4e2ad78ce6e1e7bbb7 Mon Sep 17 00:00:00 2001 From: Hathway <60729800+hereisaway@users.noreply.github.com> Date: Wed, 18 Nov 2026 14:43:27 +0800 Subject: [PATCH 1/3] feat(domino): register training and wire Plan, trainer and checkpoint Select Domino through a shipped Qwen3-8B draft config and a DominoTrainer that reuses the DFlash optimizer/checkpoint path. Plan records the mixed corrected/backbone objective, pins a fixed lambda_base, and fails closed outside SDPA, CP1, padded dense-full-attention execution. Exact resume keeps the label layout and correction-head dimensions. CPU validation: tests/cpu 1123 passed; ruff and tools.check_docs pass. --- .../config/domino_qwen3_8b_draft_config.json | 25 +++ aspec/config/draft_algorithm.py | 4 +- aspec/config/train_config.py | 3 + aspec/models/draft/__init__.py | 3 + aspec/models/draft/auto.py | 3 + aspec/planning.py | 62 +++++- aspec/training/checkpoint.py | 11 +- aspec/training/domino_trainer.py | 56 ++++++ aspec/training/trainer_actor.py | 6 +- configs/examples/domino_qwen3_8b_4k_tcp.yaml | 93 +++++++++ docs/support.md | 2 +- docs/user-guide/algorithms.md | 10 +- docs/user-guide/domino.md | 36 +++- tests/cpu/test_domino_integration.py | 190 ++++++++++++++++++ 14 files changed, 484 insertions(+), 20 deletions(-) create mode 100644 aspec/config/domino_qwen3_8b_draft_config.json create mode 100644 aspec/training/domino_trainer.py create mode 100644 configs/examples/domino_qwen3_8b_4k_tcp.yaml create mode 100644 tests/cpu/test_domino_integration.py diff --git a/aspec/config/domino_qwen3_8b_draft_config.json b/aspec/config/domino_qwen3_8b_draft_config.json new file mode 100644 index 0000000..4359739 --- /dev/null +++ b/aspec/config/domino_qwen3_8b_draft_config.json @@ -0,0 +1,25 @@ +{ + "architectures": ["DominoDraftModel"], + "model_type": "domino", + "projector_type": "domino", + "hidden_size": 4096, + "intermediate_size": 12288, + "num_hidden_layers": 5, + "num_attention_heads": 32, + "num_key_value_heads": 8, + "vocab_size": 151936, + "rms_norm_eps": 1e-6, + "max_position_embeddings": 40960, + "rope_theta": 1000000.0, + "num_target_layers": 5, + "target_hidden_size": 4096, + "target_num_hidden_layers": 36, + "target_layer_ids": [1, 9, 17, 25, 33], + "mask_token_id": 151669, + "block_size": 16, + "emb_dim": 256, + "gru_hidden_dim": 1024, + "shift_label": true, + "pure_draft_prefix_len": 1, + "tie_word_embeddings": false +} diff --git a/aspec/config/draft_algorithm.py b/aspec/config/draft_algorithm.py index 134c03f..ec69b82 100644 --- a/aspec/config/draft_algorithm.py +++ b/aspec/config/draft_algorithm.py @@ -18,6 +18,7 @@ DRAFT_ALGORITHMS = { "NativeMTPDraftModel": "mtp", + "DominoDraftModel": "domino", "DFlashDraftModel": "dflash", "DFlash2DraftModel": "dflash2", "DSparkDraftModel": "dspark", @@ -65,7 +66,8 @@ def draft_model_semantics(config) -> dict: "vocab_size", "draft_vocab_size", "hidden_act", "rms_norm_eps", "max_position_embeddings", "rope_theta", "rope_scaling", "rope_parameters", "target_layer_ids", "num_target_layers", "target_num_hidden_layers", - "num_aux_hidden_states", "fc_norm", "norm_output", "mask_token_id", + "num_aux_hidden_states", "projector_type", "emb_dim", "gru_hidden_dim", + "shift_label", "pure_draft_prefix_len", "fc_norm", "norm_output", "mask_token_id", "lm_head_rank_divisor", "attention_mode", "q_lora_rank", "kv_lora_rank", "qk_nope_head_dim", "qk_rope_head_dim", "v_head_dim", "block_size", "conv_kernel_size", "conv_group_size", "selector_rank", "selector_top_k", diff --git a/aspec/config/train_config.py b/aspec/config/train_config.py index efb4107..596dd72 100644 --- a/aspec/config/train_config.py +++ b/aspec/config/train_config.py @@ -237,6 +237,9 @@ class TrainingConfig: dflash_l1_loss_alpha: float = 0.0 dflash_num_anchors: int = 512 dflash_num_target_layers: int = 5 + # Domino mixes corrected and backbone-only CE as + # (1 - lambda_base) * corrected + lambda_base * backbone. + domino_lambda_base: float = 0.3 # Pack multiple complete documents into one fixed row. The controller owns # grouping; the trainer preserves document boundaries for attention/RoPE. dflash_packing: bool = False diff --git a/aspec/models/draft/__init__.py b/aspec/models/draft/__init__.py index fab4f44..aa72ac3 100644 --- a/aspec/models/draft/__init__.py +++ b/aspec/models/draft/__init__.py @@ -21,6 +21,7 @@ from aspec.models.draft.auto import AutoDraftModelConfig, AutoEagle3DraftModel from aspec.models.draft.dflash import DFlashConfig, DFlashDraftModel from aspec.models.draft.dflash2 import DFlash2Config, DFlash2DraftModel +from aspec.models.draft.domino import DominoConfig, DominoDraftModel from aspec.models.draft.dspark import ( DSparkConfig, DSparkDraftModel, @@ -35,6 +36,8 @@ "DFlashDraftModel", "DFlash2Config", "DFlash2DraftModel", + "DominoConfig", + "DominoDraftModel", "DSparkConfig", "DSparkDraftModel", "K3DSparkConfig", diff --git a/aspec/models/draft/auto.py b/aspec/models/draft/auto.py index 1b0e5ff..55539e4 100644 --- a/aspec/models/draft/auto.py +++ b/aspec/models/draft/auto.py @@ -28,6 +28,7 @@ from aspec.models.draft.deepseek_eagle import Eagle3DeepseekV2ForCausalLM from aspec.models.draft.dflash import DFlashConfig, DFlashDraftModel from aspec.models.draft.dflash2 import DFlash2Config, DFlash2DraftModel +from aspec.models.draft.domino import DominoConfig, DominoDraftModel from aspec.models.draft.dspark import ( DSparkConfig, DSparkDraftModel, @@ -46,6 +47,7 @@ class AutoEagle3DraftModel(AutoModelForCausalLMBase): Eagle4Config: Eagle4DraftModel, DeepseekV3Config: Eagle3DeepseekV2ForCausalLM, NativeMTPConfig: NativeMTPDraftModel, + DominoConfig: DominoDraftModel, DFlashConfig: DFlashDraftModel, DFlash2Config: DFlash2DraftModel, DSparkConfig: DSparkDraftModel, @@ -68,6 +70,7 @@ class AutoDraftModelConfig: "LlamaForCausalLMEagle4": Eagle4Config, "Eagle3DeepseekV2ForCausalLM": DeepseekV3Config, "NativeMTPDraftModel": NativeMTPConfig, + "DominoDraftModel": DominoConfig, "DFlashDraftModel": DFlashConfig, "DFlash2DraftModel": DFlash2Config, "Qwen3DSparkModel": DSparkConfig, diff --git a/aspec/planning.py b/aspec/planning.py index 29542fc..64fd7af 100644 --- a/aspec/planning.py +++ b/aspec/planning.py @@ -325,6 +325,43 @@ def _load_draft_descriptor(config: DictConfig) -> dict[str, Any]: if isinstance(alpha, bool) or not isinstance(alpha, (int, float)) or not math.isfinite(alpha) or alpha < 0: raise PlanCompileError("DFlash2 selector_loss_alpha must be finite and non-negative") + if family == "domino": + from aspec.models.draft.domino import DominoConfig + + try: + raw = DominoConfig.from_dict(raw).to_dict() + except (ValueError, TypeError) as exc: + raise PlanCompileError(str(exc)) from exc + if raw["block_size"] != _select(config, "training.dflash_block_size"): + raise PlanCompileError( + "Domino block_size must match training.dflash_block_size" + ) + backend = _select(config, "training.attention_backend") + if backend != "sdpa": + raise PlanCompileError( + "Domino currently supports training.attention_backend=sdpa" + ) + if _select(config, "training.draft_context_parallel_size", 1) != 1: + raise PlanCompileError("Domino currently supports draft_context_parallel_size=1") + if _select(config, "training.dflash_packing", False): + raise PlanCompileError( + "Domino rejects padded-only inputs; sequence packing is not implemented" + ) + if _select(config, "training.compile_model", False): + raise PlanCompileError("Domino whole-model compile has not been enabled") + if _select(config, "training.dflash_loss_objective") != "decay": + raise PlanCompileError("Domino supports the decay loss objective only") + if (_select(config, "training.dflash_ce_loss_alpha") != 1.0 + or _select(config, "training.dflash_l1_loss_alpha") != 0.0): + raise PlanCompileError( + "Domino replaces the CE/L1 mix; set dflash_ce_loss_alpha=1.0 " + "and dflash_l1_loss_alpha=0.0" + ) + lambda_base = _select(config, "training.domino_lambda_base", 0.3) + if (isinstance(lambda_base, bool) or not isinstance(lambda_base, (int, float)) + or not math.isfinite(lambda_base) or not 0.0 <= lambda_base <= 1.0): + raise PlanCompileError("domino_lambda_base must be a finite number in [0, 1]") + target_layer_ids = raw.get("target_layer_ids") if not isinstance(target_layer_ids, list) or not target_layer_ids: raise PlanCompileError( @@ -618,6 +655,10 @@ def _load_draft_descriptor(config: DictConfig) -> dict[str, Any]: "target_hidden_size": raw.get("target_hidden_size"), "target_num_hidden_layers": raw.get("target_num_hidden_layers"), "target_layer_ids": target_layer_ids, + "domino_shift_label": raw.get("shift_label"), + "domino_pure_draft_prefix_len": raw.get("pure_draft_prefix_len"), + "domino_emb_dim": raw.get("emb_dim"), + "domino_gru_hidden_dim": raw.get("gru_hidden_dim"), } @@ -1316,6 +1357,25 @@ def _workload( "lk_eta": _select(config, "training.lk_eta"), "gradient_checkpointing": _select(config, "training.gradient_checkpointing"), } + elif family == "domino": + objective = { + "family": "domino", + "loss": "mixed_corrected_backbone_ce", + "block_size": _select(config, "training.dflash_block_size"), + "num_anchors": _select(config, "training.dflash_num_anchors"), + "num_target_layers": _select(config, "training.dflash_num_target_layers"), + "loss_objective": _select(config, "training.dflash_loss_objective"), + "loss_decay_gamma": _select(config, "training.dflash_loss_decay_gamma"), + "ce_loss_alpha": 1.0, + "l1_loss_alpha": 0.0, + "lambda_base": _select(config, "training.domino_lambda_base", 0.3), + "shift_label": draft["domino_shift_label"], + "pure_draft_prefix_len": draft["domino_pure_draft_prefix_len"], + "correction_head": { + "emb_dim": draft["domino_emb_dim"], + "gru_hidden_dim": draft["domino_gru_hidden_dim"], + }, + } elif family == "dspark": objective = { "family": family, @@ -1352,7 +1412,7 @@ def _workload( objective["frozen_parts"] = (["draft_body", "embedding", "lm_head"] if draft["eagle4"]["stage"] == "candidate_head" else ["embedding", "candidate_head"] + (["lm_head"] if _select(config, "model.freeze_lm_head", False) else [])) - if family in {"dspark", "dflash", "dflash2"}: + if family in {"dspark", "dflash", "dflash2", "domino"}: objective["anchor_sampling_scope"] = anchor_scope if draft.get("mtp_conditioning"): from aspec.config.mtp_conditioning import mtp_conditioning_semantics diff --git a/aspec/training/checkpoint.py b/aspec/training/checkpoint.py index baea2b4..57b83dd 100644 --- a/aspec/training/checkpoint.py +++ b/aspec/training/checkpoint.py @@ -70,7 +70,7 @@ def _logical_training_topology(args: Any, world_size: int) -> dict[str, Any]: key: getattr(args, key, None) for key in ("ttt_length", "loss_type", "lk_eta", "ploss_weights") } - elif getattr(args, "draft_algorithm", None) in {"dflash", "dflash2", "dspark"}: + elif getattr(args, "draft_algorithm", None) in {"dflash", "dflash2", "dspark", "domino"}: topology["training_objective"] = { "block_size": int(args.dflash_block_size), "anchor_sampling_scope": getattr(args, "anchor_sampling_scope", "row"), @@ -84,6 +84,8 @@ def _logical_training_topology(args: Any, world_size: int) -> dict[str, Any]: for name, default in (("temperature", 1.0), ("top_p", 1.0), ("top_k", -1)): key = f"l1_{side}_{name}" topology["training_objective"][key] = getattr(args, f"dspark_{key}", default) + elif args.draft_algorithm == "domino": + fields += ("loss_objective",) else: fields += ("loss_objective", "dpace_alpha") for name in fields: @@ -93,6 +95,11 @@ def _logical_training_topology(args: Any, world_size: int) -> dict[str, Any]: if args.draft_algorithm == "dflash2": topology["training_objective"]["selector_loss_alpha"] = args.dflash2_selector_loss_alpha topology["training_objective"]["selector_objective"] = "experimental_teacher_forced_topk_ce" + if args.draft_algorithm == "domino": + topology["training_objective"]["loss"] = "mixed_corrected_backbone_ce" + topology["training_objective"]["lambda_base"] = getattr( + args, "domino_lambda_base", 0.3 + ) if "training_objective" in topology: fields = ("max_seq_length", "micro_batch_size", "draft_accumulation_steps", "max_grad_norm", "seed") @@ -153,7 +160,7 @@ def _validate_exact_resume_topology(args: Any, metadata: dict[str, Any], *, chec raise RuntimeError(f"Exact resume cannot change dspark_{key}; use weights-only initialization") # Checkpoints predating this option always sampled per physical row. # Missing semantic identity must not authorize a switch to per-sample training. - if (getattr(args, "draft_algorithm", None) in {"dspark", "dflash", "dflash2"} + if (getattr(args, "draft_algorithm", None) in {"dspark", "dflash", "dflash2", "domino"} and ((saved_topology or {}).get("training_objective") or {}).get( "anchor_sampling_scope", "row" ) != getattr(args, "anchor_sampling_scope", "row")): diff --git a/aspec/training/domino_trainer.py b/aspec/training/domino_trainer.py new file mode 100644 index 0000000..e7d1dba --- /dev/null +++ b/aspec/training/domino_trainer.py @@ -0,0 +1,56 @@ +# Copyright 2026 Ant Group Co., Ltd. +# SPDX-License-Identifier: Apache-2.0 + +"""Domino trainer — DFlash backbone plus a GRU-conditioned correction head.""" + +from argparse import Namespace + +from aspec.models.domino import DominoModel +from aspec.models.draft.domino import DominoConfig, DominoDraftModel +from aspec.training.dflash_trainer import DFlashTrainer + + +class DominoTrainer(DFlashTrainer): + """Domino-specific trainer; reuses the DFlash optimizer/checkpoint path.""" + + _draft_config_class = DominoConfig + + def __init__(self, args: Namespace): + super().__init__(args) + self.lambda_base = getattr(args, "domino_lambda_base", 0.3) + + def _build_draft_model(self, config): + if config.block_size != self.block_size: + raise ValueError( + "training.dflash_block_size must match domino_config.block_size " + f"({self.block_size} != {config.block_size})" + ) + if config.num_target_layers != self.num_target_layers: + raise ValueError( + "training.dflash_num_target_layers must match the number of " + f"domino_config.target_layer_ids ({self.num_target_layers} != " + f"{config.num_target_layers})" + ) + return DominoDraftModel(config) + + def _build_training_wrapper(self, draft_model): + return DominoModel( + draft_model=draft_model, + block_size=self.block_size, + num_anchors=self.num_anchors, + loss_objective=self.loss_objective, + dpace_alpha=self.dpace_alpha, + loss_decay_gamma=self.loss_decay_gamma, + ce_loss_alpha=self.ce_loss_alpha, + l1_loss_alpha=self.l1_loss_alpha, + lambda_base=self.lambda_base, + deterministic_anchor_sampling=getattr( + self.args, "deterministic_anchor_sampling", False + ), + anchor_seed=getattr(self.args, "seed", 0), + anchor_sampling_scope=getattr(self.args, "anchor_sampling_scope", "row"), + attention_backend=getattr(self.args, "attention_backend", "sdpa"), + draft_context_parallel_size=getattr( + self.args, "draft_context_parallel_size", 1 + ), + ) diff --git a/aspec/training/trainer_actor.py b/aspec/training/trainer_actor.py index 2587568..36afc1a 100644 --- a/aspec/training/trainer_actor.py +++ b/aspec/training/trainer_actor.py @@ -48,6 +48,10 @@ def _trainer_class_for_config(draft_model_config): from aspec.training.mtp_trainer import MTPTrainer return MTPTrainer + if getattr(draft_model_config, "architectures", None) == ["DominoDraftModel"]: + from aspec.training.domino_trainer import DominoTrainer + + return DominoTrainer if isinstance(draft_model_config, DFlash2Config): from aspec.training.dflash2_trainer import DFlash2Trainer @@ -67,7 +71,7 @@ def _trainer_class_for_config(draft_model_config): return Eagle3Trainer raise ValueError( - "ASpec supports DSpark, DFlash and Llama EAGLE3 draft model configs; " + "ASpec supports DSpark, DFlash, Domino and Llama EAGLE3 draft model configs; " f"got {type(draft_model_config).__name__}" ) diff --git a/configs/examples/domino_qwen3_8b_4k_tcp.yaml b/configs/examples/domino_qwen3_8b_4k_tcp.yaml new file mode 100644 index 0000000..4ddcced --- /dev/null +++ b/configs/examples/domino_qwen3_8b_4k_tcp.yaml @@ -0,0 +1,93 @@ +# Supplementary configuration example; see the support matrix for supported workflows. +# Single-node Domino on a frozen Qwen3-8B Target: one Target GPU plus one Draft GPU, +# 4K, CP1, no packing, SDPA, Store/TCP transport (no NVLink). The short window +# validates the execution path, not convergence, acceptance or decoding quality. + +model: + target_model_path: ${oc.env:ASPEC_TARGET_MODEL} + native_context_length: 32768 + trust_remote_code: false + draft_model_config: aspec/config/domino_qwen3_8b_draft_config.json + +dataset: + train_data_path: ../../examples/data/sample_conversations.jsonl + eval_data_path: null + chat_template: qwen3-instruct + min_loss_tokens: 32 + shuffle_dataset: false + +training: + attention_backend: sdpa + draft_context_parallel_size: 1 + micro_batch_size: 1 + draft_accumulation_steps: 4 + learning_rate: 6e-4 + min_lr: 6e-5 + weight_decay: 0.0 + max_concurrent_batches: 1 + streaming_dispatch_with_training: true + pipeline_dispatch_with_training: true + max_grad_norm: 1.0 + max_seq_length: 4096 + num_epochs: 100 + num_train_steps: 8 + lr_total_steps: 8 + seed: 42 + training_num_gpus_per_node: 2 + training_num_nodes: 1 + placement_strategy: inference_first + fsdp_strategy: REPLICATE + fsdp_reduce_dtype: bfloat16 + prefetch_depth: 1 + save_interval: 0 + save_per_epoch: false + save_final_checkpoint: true + warmup_ratio: 0.04 + dflash_packing: false + dflash_block_size: 16 + dflash_num_target_layers: 5 + dflash_num_anchors: 128 + dflash_loss_objective: decay + dflash_ce_loss_alpha: 1.0 + dflash_l1_loss_alpha: 0.0 + domino_lambda_base: 0.3 + gradient_checkpointing: true + +inference: + inference_engine_type: sgl + store_last_hidden_states: true + target_prefill_memory_optimized: false + inference_num_gpus: 1 + inference_num_gpus_per_engine: 1 + inference_num_gpus_per_node: 2 + 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_4k_tcp +cache_dir: cache/domino_qwen3_8b_4k_tcp diff --git a/docs/support.md b/docs/support.md index 1c01a98..221b0f3 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 core | DFlash block backbone plus GRU causal correction head, mixed backbone/corrected CE, both documented label layouts, eager/SDPA | Model/loss prerequisite only; dense full attention, CP1 padded execution; no trainer, curriculum schedule, resume, export or consumer validation; see [scope](user-guide/domino.md) | +| Domino | DFlash block backbone plus GRU causal correction head, mixed backbone/corrected CE, both documented label layouts; training and exact recovery with SDPA, CP1, padded/non-packing | No packed/CP>1, MoE, sparse attention or MTP conditioning; `lambda_base` curriculum, export and consumer acceptance pending; see [scope](user-guide/domino.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 | | MTP-conditioned DSpark / DFlash | Target-side frozen native Qwen3.5 features, token/hidden dual-anchor training, exact recovery and strict native assets; legacy Draft-side assets retained | Dense full GQA, CP1, MBS1, REPLICATE, one node, non-packing, decay objective; Target capture PP1/unquantized; no generic serving consumer | diff --git a/docs/user-guide/algorithms.md b/docs/user-guide/algorithms.md index b895b63..1ea847f 100644 --- a/docs/user-guide/algorithms.md +++ b/docs/user-guide/algorithms.md @@ -61,15 +61,17 @@ The [P-EAGLE model/loss API](peagle.md) provides a dense unsampled Qwen3 paralle Draft and forward-KL objective with independent numerical checks. Public training, COD sampling, recovery, export and consumer validation remain pending. -## Domino core prerequisite +## Domino The [Domino model/loss API](domino.md) adds a GRU-conditioned causal correction head on the retained DFlash block backbone and mixes corrected with backbone-only cross-entropy through `lambda_base`. Both documented label layouts are explicit: the unshifted DFlash convention and the official shifted convention -(`shift_label=true`, `pure_draft_prefix_len=1`). Dense full attention is enforced. -Public training selection, the `lambda_base` curriculum, recovery, export and -consumer validation remain pending. +(`shift_label=true`, `pure_draft_prefix_len=1`). Training now selects the family +through `aspec/config/domino_qwen3_8b_draft_config.json`; start from +`configs/examples/domino_qwen3_8b_4k_tcp.yaml` (SDPA, CP1, non-packing, Store/TCP). +Scope is dense full attention with padded inputs only. The `lambda_base` curriculum, +export and consumer validation remain pending. ## EAGLE4: two stages diff --git a/docs/user-guide/domino.md b/docs/user-guide/domino.md index 1114af4..ea4583d 100644 --- a/docs/user-guide/domino.md +++ b/docs/user-guide/domino.md @@ -1,10 +1,27 @@ -# Domino model and loss core +# Domino Draft training -This is the first prerequisite for [ASpec #38](https://github.com/inclusionAI/ASpec/issues/38). -It provides `aspec.models.draft.domino.DominoDraftModel` and +This implements [ASpec #38](https://github.com/inclusionAI/ASpec/issues/38) through +`aspec.models.draft.domino.DominoDraftModel` and `aspec.models.domino.DominoModel`: a block-parallel DFlash backbone with a -GRU-conditioned causal correction head. It is a model/loss API; the ASpec training -CLI does not select this algorithm yet. +GRU-conditioned causal correction head. The ASpec training CLI now selects this +algorithm through `aspec/config/domino_qwen3_8b_draft_config.json`; the +[example workflow](../../configs/examples/domino_qwen3_8b_4k_tcp.yaml) runs one +Target GPU plus one Draft GPU at 4K. + +## 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`). +- Example: `configs/examples/domino_qwen3_8b_4k_tcp.yaml` (SDPA, CP1, MBS1, + non-packing, REPLICATE, Store/TCP transport). +- The trainer owns a fixed per-run `training.domino_lambda_base`; the curriculum + schedule is not implemented yet. Exact recovery records `lambda_base`, the label + layout and the correction-head dimensions. +- The supported path fails closed outside dense full attention, padded inputs, + `attention_backend=sdpa`, `draft_context_parallel_size=1` and + `dflash_packing=false`. MoE, sparse attention, MTP conditioning, packing, CP>1 + and whole-model compile are rejected during Plan compilation or configuration. + ## Reference and selected scope @@ -117,8 +134,7 @@ handling, empty supervision, and frozen Target/embedding behavior. ## Remaining work -Trainer/Plan selection, the `lambda_base` curriculum schedule, a runnable recipe, -exact resume of backbone/head/curriculum state, native export with strict reloading, -Target bindings, proposal consumers and held-out backbone-vs-corrected observations -remain pending. CPU numerical checks do not establish Qwen3-8B training quality, -GPU throughput or decoding acceptance. +The `lambda_base` curriculum schedule, a maintained recipe catalog entry, native +export with strict reloading, Target bindings, proposal consumers and held-out +backbone-vs-corrected observations remain pending. CPU numerical and Plan checks do +not establish Qwen3-8B training quality, GPU throughput or decoding acceptance. diff --git a/tests/cpu/test_domino_integration.py b/tests/cpu/test_domino_integration.py new file mode 100644 index 0000000..81a79bf --- /dev/null +++ b/tests/cpu/test_domino_integration.py @@ -0,0 +1,190 @@ +# Copyright 2026 Ant Group Co., Ltd. +# SPDX-License-Identifier: Apache-2.0 + +"""Domino integration contracts: registration, Plan, dispatch and resume.""" + +import json +from pathlib import Path +from types import SimpleNamespace + +import pytest + +from aspec.config.draft_algorithm import draft_model_semantics, resolve_draft_algorithm +from aspec.config.train_config import load_config +from aspec.models.domino import DominoModel +from aspec.models.draft.auto import AutoDraftModelConfig, AutoEagle3DraftModel +from aspec.models.draft.domino import DominoConfig, DominoDraftModel +from aspec.planning import ( + PlanCompileError, + _load_draft_descriptor, + _runtime_values, + compile_execution_plan, +) +from aspec.training.checkpoint import ( + _logical_training_topology, + _validate_exact_resume_topology, +) +from aspec.training.domino_trainer import DominoTrainer +from aspec.training.trainer_actor import _trainer_class_for_config + +_REPO_ROOT = Path(__file__).parents[2] +_EXAMPLE = _REPO_ROOT / "configs" / "examples" / "domino_qwen3_8b_4k_tcp.yaml" +_DRAFT_JSON = _REPO_ROOT / "aspec" / "config" / "domino_qwen3_8b_draft_config.json" + +_ILLEGAL_OVERRIDES = [ + ("training.dflash_packing=true", PlanCompileError), + ("training.draft_context_parallel_size=2", NotImplementedError), + ("training.attention_backend=fa4", PlanCompileError), + ("training.attention_backend=cudnn_flex_attention", PlanCompileError), + ("training.compile_model=true", PlanCompileError), + ("training.dflash_loss_objective=dpace", PlanCompileError), + ("training.dflash_ce_loss_alpha=0.5", PlanCompileError), + ("training.dflash_l1_loss_alpha=0.1", PlanCompileError), + ("training.dflash_block_size=8", PlanCompileError), + ("training.domino_lambda_base=2.0", PlanCompileError), +] + + +def _tiny_config(**overrides): + raw = dict( + architectures=["DominoDraftModel"], model_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, target_num_hidden_layers=4, target_layer_ids=[1], + num_target_layers=1, mask_token_id=31, max_position_embeddings=128, + block_size=5, emb_dim=6, gru_hidden_dim=8, + ) + raw.update(overrides) + return AutoDraftModelConfig.from_dict(raw) + + +def _fake_qwen_target(tmp_path): + target = tmp_path / "Qwen3-8B-test" + target.mkdir() + (target / "config.json").write_text(json.dumps({ + "model_type": "qwen3", + "architectures": ["Qwen3ForCausalLM"], + "hidden_size": 4096, + "vocab_size": 151936, + "num_hidden_layers": 36, + "max_position_embeddings": 40960, + }), encoding="utf-8") + return target + + +def _config(tmp_path, *overrides): + args = [f"model.target_model_path={_fake_qwen_target(tmp_path)}", *overrides] + return load_config(config_path=str(_EXAMPLE), cli_args=args), args + + +def test_registration_resolves_domino(): + assert resolve_draft_algorithm({"architectures": ["DominoDraftModel"]}) == "domino" + shipped = AutoDraftModelConfig.from_file(str(_DRAFT_JSON)) + assert isinstance(shipped, DominoConfig) + assert shipped.block_size == 16 + assert shipped.shift_label is True + assert shipped.pure_draft_prefix_len == 1 + assert shipped.emb_dim == 256 + assert shipped.gru_hidden_dim == 1024 + assert shipped.target_layer_ids == [1, 9, 17, 25, 33] + + tiny = _tiny_config() + model = AutoEagle3DraftModel.from_config(tiny) + assert isinstance(model, DominoDraftModel) + assert model.suffix_start == 1 + assert _trainer_class_for_config(tiny) is DominoTrainer + semantics = draft_model_semantics(tiny) + assert semantics["projector_type"] == "domino" + assert semantics["emb_dim"] == 6 + assert semantics["gru_hidden_dim"] == 8 + assert semantics["shift_label"] is True + assert semantics["pure_draft_prefix_len"] == 1 + + +def test_plan_compiles_with_domino_objective(tmp_path): + config, args = _config(tmp_path) + plan = compile_execution_plan(config, config_path=str(_EXAMPLE), cli_args=args).to_dict() + draft = plan["workload"]["models"]["draft"] + assert draft["family"] == "domino" + objective = plan["workload"]["objective"] + assert objective["loss"] == "mixed_corrected_backbone_ce" + assert objective["block_size"] == 16 + assert objective["lambda_base"] == 0.3 + assert objective["shift_label"] is True + assert objective["pure_draft_prefix_len"] == 1 + assert objective["ce_loss_alpha"] == 1.0 + assert objective["l1_loss_alpha"] == 0.0 + assert objective["correction_head"] == {"emb_dim": 256, "gru_hidden_dim": 1024} + features = plan["workload"]["features"] + assert features["aux_hidden_state_layers"] == [1, 9, 17, 25, 33] + + runtime = _runtime_values(config, _load_draft_descriptor(config)) + assert runtime["draft_algorithm"] == "domino" + assert runtime["domino_lambda_base"] == 0.3 + + +@pytest.mark.parametrize("override, error", _ILLEGAL_OVERRIDES) +def test_plan_rejects_unsupported_domino_combinations(tmp_path, override, error): + target = f"model.target_model_path={_fake_qwen_target(tmp_path)}" + args = [target, override] + with pytest.raises(error): + config = load_config(config_path=str(_EXAMPLE), cli_args=args) + compile_execution_plan(config, config_path=str(_EXAMPLE), cli_args=args) + + +def _trainer_args(): + return SimpleNamespace( + draft_algorithm="domino", draft_model_config_obj=_tiny_config(), world_size=2, + dflash_block_size=5, dflash_num_anchors=2, dflash_num_target_layers=1, + dflash_loss_objective="decay", dflash_dpace_alpha=0.5, + dflash_loss_decay_gamma=7.0, dflash_ce_loss_alpha=1.0, dflash_l1_loss_alpha=0.0, + domino_lambda_base=0.3, anchor_sampling_scope="row", + deterministic_anchor_sampling=False, max_seq_length=128, micro_batch_size=1, + draft_accumulation_steps=1, max_grad_norm=1.0, seed=42, + draft_context_parallel_size=1, training_num_nodes=1, training_num_gpus_per_node=2, + attention_backend="sdpa", fsdp_strategy="REPLICATE", sp_ulysses_size=1, + sp_ring_size=1, + ) + + +def test_trainer_builds_domino_wrapper_and_pins_block_size(): + trainer = object.__new__(DominoTrainer) + trainer.block_size = 5 + trainer.num_anchors = 2 + trainer.num_target_layers = 1 + trainer.loss_objective = "decay" + trainer.dpace_alpha = 0.5 + trainer.loss_decay_gamma = 7.0 + trainer.ce_loss_alpha = 1.0 + trainer.l1_loss_alpha = 0.0 + trainer.lambda_base = 0.3 + trainer.args = SimpleNamespace( + deterministic_anchor_sampling=False, seed=42, anchor_sampling_scope="row", + attention_backend="sdpa", draft_context_parallel_size=1, + ) + wrapper = trainer._build_training_wrapper(DominoDraftModel(_tiny_config())) + assert isinstance(wrapper, DominoModel) + assert wrapper.lambda_base == 0.3 + assert wrapper.block_size == 5 + + trainer.block_size = 4 + with pytest.raises(ValueError): + trainer._build_draft_model(_tiny_config()) + + +def test_checkpoint_topology_pins_domino_objective(): + args = _trainer_args() + current = _logical_training_topology(args, 2) + objective = current["training_objective"] + assert objective["loss"] == "mixed_corrected_backbone_ce" + assert objective["lambda_base"] == 0.3 + assert objective["block_size"] == 5 + assert current["draft_model_semantics"]["projector_type"] == "domino" + assert current["draft_model_semantics"]["shift_label"] is True + + metadata = {"world_size": 2, "training_topology": json.loads(json.dumps(current))} + _validate_exact_resume_topology(args, metadata) + changed = json.loads(json.dumps(metadata)) + changed["training_topology"]["training_objective"]["lambda_base"] = 0.5 + with pytest.raises(RuntimeError): + _validate_exact_resume_topology(args, changed) From 396a1ca9537b47f487bf3ac4c419b285ebc71b0d Mon Sep 17 00:00:00 2001 From: Hathway <60729800+hereisaway@users.noreply.github.com> Date: Wed, 18 Nov 2026 14:44:02 +0800 Subject: [PATCH 2/3] docs(domino): document training entry point and validation status --- docs/user-guide/domino.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/user-guide/domino.md b/docs/user-guide/domino.md index ea4583d..a7572fc 100644 --- a/docs/user-guide/domino.md +++ b/docs/user-guide/domino.md @@ -22,6 +22,28 @@ Target GPU plus one Draft GPU at 4K. `dflash_packing=false`. MoE, sparse attention, MTP conditioning, packing, CP>1 and whole-model compile are rejected during Plan compilation or configuration. +## Running + +Compile the example before launching GPUs, then train with the same recipe: + +```bash +aspec --config configs/examples/domino_qwen3_8b_4k_tcp.yaml --dry-run \ + model.target_model_path=/path/to/Qwen3-8B +RAY_ADDRESS=local aspec --config configs/examples/domino_qwen3_8b_4k_tcp.yaml \ + model.target_model_path=/path/to/Qwen3-8B +``` + +Resume with the same command plus `--resume` and the checkpoint directory. The +example uses the bundled conversations and a short step budget; it validates the +execution path, not convergence, throughput or decoding acceptance. Supply licensed +data and a full learning-rate horizon for a real run. + +## Validation status + +Plan compilation, registration, trainer construction, checkpoint topology and the +CPU numerical contracts are covered by `tests/cpu`. The public CI lane is CPU-only; +GPU end-to-end training and exact resume still need a hardware run before claiming +throughput or quality. ## Reference and selected scope From 9ca8f03588fc114f7344ac17cbbe596cf130a1a2 Mon Sep 17 00:00:00 2001 From: Hathway <60729800+hereisaway@users.noreply.github.com> Date: Wed, 18 Nov 2026 15:24:55 +0800 Subject: [PATCH 3/3] fix(domino): align metric offsets and document exact recovery Set the trainer's anchor slot offset from the Domino wrapper's prediction_start so shifted labels keep position 0 in per-position metrics while unshifted labels still skip the anchor. Replace the unsupported --resume instructions with training.load_path plus a fresh output_dir. --- aspec/training/domino_trainer.py | 6 +++++- docs/user-guide/domino.md | 13 +++++++++++-- tests/cpu/test_domino_integration.py | 9 +++++++++ 3 files changed, 25 insertions(+), 3 deletions(-) diff --git a/aspec/training/domino_trainer.py b/aspec/training/domino_trainer.py index e7d1dba..b3992e7 100644 --- a/aspec/training/domino_trainer.py +++ b/aspec/training/domino_trainer.py @@ -34,7 +34,7 @@ def _build_draft_model(self, config): return DominoDraftModel(config) def _build_training_wrapper(self, draft_model): - return DominoModel( + wrapper = DominoModel( draft_model=draft_model, block_size=self.block_size, num_anchors=self.num_anchors, @@ -54,3 +54,7 @@ def _build_training_wrapper(self, draft_model): self.args, "draft_context_parallel_size", 1 ), ) + # Shifted labels supervise block position 0; unshifted labels skip the + # anchor slot. Metric aggregators must drop the same prefix. + self._anchor_slot_offset = wrapper.prediction_start + return wrapper diff --git a/docs/user-guide/domino.md b/docs/user-guide/domino.md index a7572fc..f85b10b 100644 --- a/docs/user-guide/domino.md +++ b/docs/user-guide/domino.md @@ -33,8 +33,17 @@ RAY_ADDRESS=local aspec --config configs/examples/domino_qwen3_8b_4k_tcp.yaml \ model.target_model_path=/path/to/Qwen3-8B ``` -Resume with the same command plus `--resume` and the checkpoint directory. The -example uses the bundled conversations and a short step budget; it validates the +For exact recovery, point at a complete checkpoint with `training.load_path` and +write to a fresh `output_dir`; keep `training.continual_training=false` (the default): + +```bash +aspec --config configs/examples/domino_qwen3_8b_4k_tcp.yaml \ + model.target_model_path=/path/to/Qwen3-8B \ + training.load_path=outputs/domino_qwen3_8b_4k_tcp/checkpoints \ + training.continual_training=false output_dir=outputs/domino_qwen3_8b_4k_tcp_resumed +``` + +The example uses the bundled conversations and a short step budget; it validates the execution path, not convergence, throughput or decoding acceptance. Supply licensed data and a full learning-rate horizon for a real run. diff --git a/tests/cpu/test_domino_integration.py b/tests/cpu/test_domino_integration.py index 81a79bf..75e8a80 100644 --- a/tests/cpu/test_domino_integration.py +++ b/tests/cpu/test_domino_integration.py @@ -166,6 +166,15 @@ def test_trainer_builds_domino_wrapper_and_pins_block_size(): assert isinstance(wrapper, DominoModel) assert wrapper.lambda_base == 0.3 assert wrapper.block_size == 5 + assert trainer._anchor_slot_offset == 0 + + unshifted = object.__new__(DominoTrainer) + unshifted.__dict__.update(trainer.__dict__) + unshifted_wrapper = unshifted._build_training_wrapper( + DominoDraftModel(_tiny_config(shift_label=False, pure_draft_prefix_len=0)) + ) + assert unshifted_wrapper.prediction_start == 1 + assert unshifted._anchor_slot_offset == 1 trainer.block_size = 4 with pytest.raises(ValueError):