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 d7516fa..1605840 100644 --- a/aspec/config/draft_algorithm.py +++ b/aspec/config/draft_algorithm.py @@ -19,6 +19,7 @@ DRAFT_ALGORITHMS = { "NativeMTPDraftModel": "mtp", "MedusaDraftModel": "medusa", + "DominoDraftModel": "domino", "DFlashDraftModel": "dflash", "DFlash2DraftModel": "dflash2", "DSparkDraftModel": "dspark", @@ -66,8 +67,9 @@ 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", "medusa_num_heads", "medusa_num_layers", "fc_norm", - "norm_output", "mask_token_id", + "num_aux_hidden_states", "medusa_num_heads", "medusa_num_layers", + "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 e701009..3fbb132 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/dflash.py b/aspec/models/dflash.py index 73c60a0..7c4bf17 100644 --- a/aspec/models/dflash.py +++ b/aspec/models/dflash.py @@ -191,6 +191,8 @@ class DFlashModel(nn.Module): # First label offset relative to an anchor. Base DFlash predicts the token at # the anchor itself (masked out); shifted-layout variants start at anchor + 1. label_start = 0 + # CPU fallback materializes the block mask only for wrappers that opt in. + _materialize_cpu_block_mask = False def __init__( self, @@ -878,24 +880,28 @@ def _draft_backbone( for layer_id in range(self.draft_model.num_layers): options = self._block_mask_options_for_layer(layer_id) causal = bool(options.get("is_causal", False)) - if causal and set(options) - {"is_causal"}: + materialize = causal or self._materialize_cpu_block_mask + if materialize and set(options) - {"is_causal"}: raise ValueError( - "CPU causal Draft attention does not implement these mask options" + "CPU Draft attention does not implement these mask options" ) - if causal and ctx_doc_ids is not None: + if materialize and ctx_doc_ids is not None: raise ValueError( - "CPU causal Draft attention does not support packed ctx_doc_ids" + "CPU block-mask Draft attention does not support packed ctx_doc_ids" ) - if causal not in dense_cache: - dense_cache[causal] = ( - _create_dflash_dense_mask( - anchor_positions, block_keep_mask, seq_len, - self.block_size, is_causal=True, + if materialize: + if causal not in dense_cache: + dense_cache[causal] = _create_dflash_dense_mask( + anchor_positions, + block_keep_mask, + seq_len, + self.block_size, + is_causal=causal, ) - if causal else None - ) - dense_masks.append(dense_cache[causal]) - if True in dense_cache: + dense_masks.append(dense_cache[causal]) + else: + dense_masks.append(None) + if dense_cache: dense_attention_masks = ( dense_masks[0] if len(dense_cache) == 1 else dense_masks ) @@ -1026,8 +1032,8 @@ def _draft_backbone( draft_position_ids=draft_position_ids, context_position_ids=context_position_ids, block_mask=block_mask, - draft_attention_mask=dense_attention_masks, noise_embedding=noise_embedding, + draft_attention_mask=dense_attention_masks, direct_cp_metadata=direct_cp_metadata, csa_metadata=csa_metadata, qsa_metadata=qsa_metadata, diff --git a/aspec/models/domino.py b/aspec/models/domino.py index 0aadb1a..5c810e8 100644 --- a/aspec/models/domino.py +++ b/aspec/models/domino.py @@ -11,12 +11,18 @@ import math +import torch + from aspec.models.dflash import DFlashModel class DominoModel(DFlashModel): """Block-parallel DFlash objective mixed with a causal correction head.""" + # The retained block backbone must still isolate blocks and hide future + # Target features when the CUDA FlexAttention path is unavailable. + _materialize_cpu_block_mask = True + def __init__(self, *args, lambda_base=0.0, **kwargs): super().__init__(*args, **kwargs) config = getattr(self.draft_model, "config", None) @@ -131,6 +137,32 @@ def _training_loss( loss_per_token = ( (1.0 - lambda_base) * corrected_per_token + lambda_base * base_per_token ) + # Keep detached per-token values for the trainer's loss-component curves. + self._last_loss_tokens = { + "mixed_ce": loss_per_token.detach(), + "backbone_ce": base_per_token.detach(), + "corrected_ce": corrected_per_token.detach(), + } # Report the corrected objective's per-position value; accuracy uses the # corrected logits as well. return loss_per_token, corrected_per_token, corrected_logits + + def _extra_training_loss( + self, + draft_hidden: torch.Tensor, + logits: torch.Tensor, + target_ids: torch.Tensor, + objective_weights: torch.Tensor, + ) -> tuple[torch.Tensor, dict]: + tokens = getattr(self, "_last_loss_tokens", None) + if tokens is None: + return logits.new_zeros(()), {} + flat_weights = objective_weights.reshape(-1) + denominator = flat_weights.sum() + components = {} + for name, values in tokens.items(): + numerator = ( + values.reshape(-1).to(flat_weights.dtype) * flat_weights + ).sum() + components[name] = (numerator, denominator) + return logits.new_zeros(()), components 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 b73f5ee..e9e802a 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, @@ -48,6 +49,7 @@ class AutoEagle3DraftModel(AutoModelForCausalLMBase): DeepseekV3Config: Eagle3DeepseekV2ForCausalLM, NativeMTPConfig: NativeMTPDraftModel, MedusaConfig: MedusaDraftModel, + DominoConfig: DominoDraftModel, DFlashConfig: DFlashDraftModel, DFlash2Config: DFlash2DraftModel, DSparkConfig: DSparkDraftModel, @@ -71,6 +73,7 @@ class AutoDraftModelConfig: "Eagle3DeepseekV2ForCausalLM": DeepseekV3Config, "NativeMTPDraftModel": NativeMTPConfig, "MedusaDraftModel": MedusaConfig, + "DominoDraftModel": DominoConfig, "DFlashDraftModel": DFlashConfig, "DFlash2DraftModel": DFlash2Config, "Qwen3DSparkModel": DSparkConfig, diff --git a/aspec/models/draft/dflash.py b/aspec/models/draft/dflash.py index 8a8ad70..1f24a7b 100644 --- a/aspec/models/draft/dflash.py +++ b/aspec/models/draft/dflash.py @@ -441,7 +441,6 @@ def forward( draft_position_ids: torch.Tensor, context_position_ids: torch.Tensor, block_mask=None, - draft_attention_mask=None, direct_cp_metadata=None, csa_metadata=None, csa_prepared=None, @@ -450,6 +449,8 @@ def forward( qsa_layout=None, dsa_metadata=None, dsa_layout=None, + *, + draft_attention_mask=None, ) -> torch.Tensor: """Forward pass with dual-source KV. @@ -459,8 +460,8 @@ def forward( draft_position_ids: [B, draft_len] — position IDs for draft tokens context_position_ids: [B, ctx_len] — position IDs for context tokens block_mask: FlexAttention BlockMask for block-causal attention - draft_attention_mask: Boolean [B, draft_len, ctx_len+draft_len] mask - for the non-FlexAttention fallback (for example CPU tests). + draft_attention_mask: Boolean [B, draft_len, ctx_len+draft_len] + mask for the non-FlexAttention fallback (for example CPU tests). """ bsz, draft_len, _ = draft_hidden.shape ctx_len = context_hidden.shape[1] @@ -1027,7 +1028,6 @@ def forward( draft_position_ids: torch.Tensor, context_position_ids: torch.Tensor, block_mask=None, - draft_attention_mask=None, direct_cp_metadata=None, csa_metadata=None, csa_prepared=None, @@ -1036,6 +1036,8 @@ def forward( qsa_layout=None, dsa_metadata=None, dsa_layout=None, + *, + draft_attention_mask=None, ) -> torch.Tensor: residual = draft_hidden draft_hidden = self.input_layernorm(draft_hidden) @@ -1322,12 +1324,13 @@ def forward( context_position_ids: torch.Tensor, block_mask=None, noise_embedding: Optional[torch.Tensor] = None, - draft_attention_mask=None, direct_cp_metadata=None, csa_metadata=None, qsa_metadata=None, dsa_metadata=None, return_router_logits: bool = False, + *, + draft_attention_mask=None, ) -> torch.Tensor: """Forward pass through draft model. diff --git a/aspec/models/draft/dflash2.py b/aspec/models/draft/dflash2.py index 64159f2..ea732c5 100644 --- a/aspec/models/draft/dflash2.py +++ b/aspec/models/draft/dflash2.py @@ -441,6 +441,8 @@ def forward( context_position_ids: torch.Tensor, block_mask=None, direct_cp_metadata=None, + *, + draft_attention_mask=None, **kwargs, ) -> torch.Tensor: residual = draft_hidden @@ -452,6 +454,7 @@ def forward( draft_position_ids=draft_position_ids, context_position_ids=context_position_ids, block_mask=block_mask, + draft_attention_mask=draft_attention_mask, direct_cp_metadata=direct_cp_metadata, ) draft_hidden = self.attention_conv.finish(draft_hidden, attention_kernel) diff --git a/aspec/planning.py b/aspec/planning.py index 25611aa..4b0d3d8 100644 --- a/aspec/planning.py +++ b/aspec/planning.py @@ -384,6 +384,50 @@ 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" + ) + if raw.get("cudnn_gqa_mode", "auto") != "auto": + raise PlanCompileError( + "Domino requires cudnn_gqa_mode=auto; the packed FlexAttention " + "mask controls visibility" + ) + backend = _select(config, "training.attention_backend") + if backend != "flex_attention": + raise PlanCompileError( + "Domino requires training.attention_backend=flex_attention; " + "that is the masked block-attention path the CUDA dispatcher uses" + ) + 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 does not support sequence packing; set " + "training.dflash_packing=false" + ) + 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( @@ -679,6 +723,10 @@ def _load_draft_descriptor(config: DictConfig) -> dict[str, Any]: "target_layer_ids": target_layer_ids, "medusa_num_heads": raw.get("medusa_num_heads"), "medusa_num_layers": raw.get("medusa_num_layers"), + "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"), } @@ -1382,6 +1430,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, @@ -1432,7 +1499,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 @@ -2029,6 +2096,7 @@ def compile_execution_plan( or draft["attention"]["csa"] is not None or draft["attention"]["qsa"] is not None or draft["attention"].get("dsa") is not None + or draft["family"] == "domino" ) direct_target_output = bool( _select(config, "inference.target_prefill_memory_optimized", False) diff --git a/aspec/training/checkpoint.py b/aspec/training/checkpoint.py index add1d5f..3738fab 100644 --- a/aspec/training/checkpoint.py +++ b/aspec/training/checkpoint.py @@ -77,7 +77,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"), @@ -92,6 +92,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: @@ -101,6 +103,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") @@ -163,7 +170,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")): @@ -195,10 +202,32 @@ def _validate_exact_resume_topology(args: Any, metadata: dict[str, Any], *, chec ): raise RuntimeError("Exact resume cannot change a legacy full-attention checkpoint to SWA") if saved_topology is None: + if getattr(args, "draft_algorithm", None) == "domino": + raise RuntimeError( + "Exact resume requires training_topology for Domino checkpoints; " + "use continual_training=true for a weights-only new stage." + ) # Older complete checkpoints recorded world_size only. Preserve that # compatibility while every newly published checkpoint records the # full logical parallelism contract below. return + if getattr(args, "draft_algorithm", None) == "domino": + objective = saved_topology.get("training_objective") or {} + semantics = saved_topology.get("draft_model_semantics") or {} + missing = [ + key for key in ("lambda_base", "block_size", "loss", "loss_decay_gamma") + if key not in objective + ] + missing += [ + key for key in ("shift_label", "pure_draft_prefix_len") + if key not in semantics + ] + if missing: + raise RuntimeError( + "Exact resume requires complete Domino training_topology; " + f"missing {missing}. Use continual_training=true for a " + "weights-only new stage." + ) if current_policy.get("dsa") is not None: # Chunk workspace is an execution bound, not the DSA objective. Preserve # every recorded semantic field while allowing a different memory budget. diff --git a/aspec/training/domino_trainer.py b/aspec/training/domino_trainer.py new file mode 100644 index 0000000..d55e38b --- /dev/null +++ b/aspec/training/domino_trainer.py @@ -0,0 +1,77 @@ +# 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 + _extra_loss_component_keys = ["mixed_ce", "backbone_ce", "corrected_ce"] + + 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): + wrapper = 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", "flex_attention"), + draft_context_parallel_size=getattr( + 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 + + def _aggregate_metrics(self, all_step_metrics, step, *, grad_norm=None): + metrics = super()._aggregate_metrics( + all_step_metrics, step, grad_norm=grad_norm + ) + mixed = metrics.get("train/mixed_ce") + if mixed is not None: + metrics["train/avg_loss"] = mixed + return metrics + + def _aggregate_eval_metrics(self, all_step_metrics): + metrics = super()._aggregate_eval_metrics(all_step_metrics) + mixed = metrics.get("eval/mixed_ce") + if mixed is not None: + metrics["eval/avg_loss"] = mixed + return metrics diff --git a/aspec/training/trainer_actor.py b/aspec/training/trainer_actor.py index 7b729a8..3077962 100644 --- a/aspec/training/trainer_actor.py +++ b/aspec/training/trainer_actor.py @@ -52,6 +52,10 @@ def _trainer_class_for_config(draft_model_config): from aspec.training.medusa_trainer import MedusaTrainer return MedusaTrainer + 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 @@ -71,7 +75,7 @@ def _trainer_class_for_config(draft_model_config): return Eagle3Trainer raise ValueError( - "ASpec supports DSpark, DFlash, EAGLE3, native MTP and Medusa draft model configs; " + "ASpec supports DSpark, DFlash, Domino, EAGLE3, native MTP and Medusa 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..24b18b0 --- /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 two Draft GPUs, +# 4K, CP1, no packing, FlexAttention, Store/TCP transport (no NVLink). This is a +# functional smoke test, not evidence of 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: flex_attention + 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: false + 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 8370c13..49f4391 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 FlexAttention, 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) | | Medusa heads-only | Parallel full-vocabulary future-token heads on the frozen Target post-norm state; training, exact recovery; SDPA CP1, MBS1, non-packing, REPLICATE | No packing/CP, warmstart, export or consumer 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/algorithms.md b/docs/user-guide/algorithms.md index 57146bc..b05d98c 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` (FlexAttention, 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..5811560 100644 --- a/docs/user-guide/domino.md +++ b/docs/user-guide/domino.md @@ -1,10 +1,80 @@ -# 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 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`). +- Example: `configs/examples/domino_qwen3_8b_4k_tcp.yaml` (FlexAttention, 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=flex_attention`, `draft_context_parallel_size=1` and + `dflash_packing=false`. The CUDA FlexAttention mask and the CPU dense fallback + share the same block visibility; the CPU mask is built for contract tests only. MoE, sparse attention, MTP conditioning, packing, CP>1 + and whole-model compile are rejected during Plan compilation or configuration. + +## Running + +Prepare the Target in a separate environment and keep it running on GPU 0: + +```bash +aspec patch-sglang +CUDA_VISIBLE_DEVICES=0 aspec target \ + --config configs/examples/domino_qwen3_8b_4k_tcp.yaml \ + model.target_model_path=/path/to/Qwen3-8B +``` + +Compile the example, then train with two Draft GPUs (GPUs 1 and 2): + +```bash +aspec --config configs/examples/domino_qwen3_8b_4k_tcp.yaml --dry-run \ + model.target_model_path=/path/to/Qwen3-8B +CUDA_VISIBLE_DEVICES=1,2 RAY_ADDRESS=local \ + aspec --config configs/examples/domino_qwen3_8b_4k_tcp.yaml \ + model.target_model_path=/path/to/Qwen3-8B +``` + +For exact recovery, stop the first run at step 4 while keeping `lr_total_steps=8`, +then resume that checkpoint into a fresh directory: + +```bash +CUDA_VISIBLE_DEVICES=1,2 RAY_ADDRESS=local \ + aspec --config configs/examples/domino_qwen3_8b_4k_tcp.yaml \ + model.target_model_path=/path/to/Qwen3-8B \ + training.num_train_steps=4 training.lr_total_steps=8 \ + output_dir=outputs/domino_qwen3_8b_4k_tcp_step4 + +CUDA_VISIBLE_DEVICES=1,2 RAY_ADDRESS=local \ + 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_step4/checkpoints \ + training.num_train_steps=8 training.lr_total_steps=8 \ + training.continual_training=false \ + output_dir=outputs/domino_qwen3_8b_4k_tcp_resumed +``` + +The example is a short functional smoke-test recipe, not evidence that GPU execution +has been validated. Only CPU and Plan checks have been reported; the GPU run remains +pending. It uses the bundled conversations and a short step budget, 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 @@ -73,7 +143,9 @@ only for the unshifted layout (`shift_label=false`) with otherwise matching weighting settings; the shifted layout supervises different slots. Anchor sampling, block masks, label bounds, `loss_mask` and DFlash-style exponential depth decay are reused; `ce_loss_alpha=1` and `l1_loss_alpha=0` are enforced. Reporting accuracy and per-position loss use the -corrected logits, while the returned loss applies the DFlash objective weights. +corrected logits. The trainer reports `mixed_ce` as `train/avg_loss`/`eval/avg_loss` +(the objective actually used for backward) and exposes `mixed_ce`, `backbone_ce` and +`corrected_ce` as separate token-pooled component curves. ## Minimal numerical use @@ -117,8 +189,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.py b/tests/cpu/test_domino.py index bc71bdb..14a819e 100644 --- a/tests/cpu/test_domino.py +++ b/tests/cpu/test_domino.py @@ -153,7 +153,18 @@ def reference_objective(model, draft_hidden, inputs): per_position = ( corrected_ce.reshape(-1, anchors.shape[1], block_size) * weights ).sum(dim=(0, 1)) / count.clamp(min=1.0) - return loss, corrected_ce.reshape(-1, anchors.shape[1], block_size), per_position + denominator = flat_weights.sum().clamp_min(1e-6) + components = { + "mixed_ce": ((mixed * flat_weights).sum(), denominator), + "backbone_ce": ((base_ce * flat_weights).sum(), denominator), + "corrected_ce": ((corrected_ce * flat_weights).sum(), denominator), + } + return ( + loss, + corrected_ce.reshape(-1, anchors.shape[1], block_size), + per_position, + components, + ) def _assert_parameter_gradients(actual, expected): @@ -239,10 +250,10 @@ def test_loss_and_gradients_match_independent_equations( result, captured = run_and_capture(actual, inputs) _, reference_captured = run_and_capture(reference, reference_inputs) - expected_loss, expected_ce, expected_per_position = reference_objective( + expected_loss, expected_ce, expected_per_position, _ = reference_objective( reference, reference_captured, reference_inputs ) - actual_loss, actual_ce, actual_per_position = reference_objective( + actual_loss, actual_ce, actual_per_position, _ = reference_objective( actual, captured, inputs ) @@ -261,7 +272,7 @@ def test_lambda_one_recovers_the_backbone_only_objective(): model = make_model(lambda_base=1.0, loss_decay_gamma=0.0) inputs = make_inputs() result, captured = run_and_capture(model, inputs) - expected, _, _ = reference_objective(model, captured, inputs) + expected, _, _, _ = reference_objective(model, captured, inputs) torch.testing.assert_close(result[0], expected, rtol=2e-5, atol=2e-6) result[0].backward() for parameter in ( @@ -279,10 +290,10 @@ def test_two_row_layout_matches_reference_and_backward(): inputs, reference_inputs = make_inputs(batch=2), make_inputs(batch=2) result, captured = run_and_capture(actual, inputs) _, reference_captured = run_and_capture(reference, reference_inputs) - expected_loss, expected_ce, _ = reference_objective( + expected_loss, expected_ce, _, _ = reference_objective( reference, reference_captured, reference_inputs ) - actual_loss, actual_ce, _ = reference_objective(actual, captured, inputs) + actual_loss, actual_ce, _, _ = reference_objective(actual, captured, inputs) assert result[0].ndim == 0 torch.testing.assert_close(result[0], expected_loss, rtol=2e-5, atol=2e-6) torch.testing.assert_close(actual_loss, expected_loss, rtol=2e-5, atol=2e-6) @@ -297,7 +308,7 @@ def test_loss_mask_excludes_unsupervised_labels(): inputs = make_inputs() inputs["loss_mask"][0, 6] = 0 result, captured = run_and_capture(model, inputs) - expected, _, _ = reference_objective(model, captured, inputs) + expected, _, _, _ = reference_objective(model, captured, inputs) torch.testing.assert_close(result[0], expected, rtol=2e-5, atol=2e-6) offsets = torch.arange(model.label_start, model.label_start + model.block_size) label_indices = inputs["injected_anchors"].unsqueeze(-1) + offsets @@ -340,7 +351,7 @@ def test_short_sequences_keep_loss_finite(length): inputs = make_inputs(length=length) inputs["injected_anchors"] = torch.tensor([[0, max(length - 3, 1)]]) result, captured = run_and_capture(model, inputs) - expected, _, _ = reference_objective(model, captured, inputs) + expected, _, _, _ = reference_objective(model, captured, inputs) torch.testing.assert_close(result[0], expected, rtol=2e-5, atol=2e-6) assert torch.isfinite(result[0]) result[0].backward() @@ -461,13 +472,16 @@ def _plain_dflash_with_domino_backbone(domino): } plain_draft.load_state_dict(backbone, strict=True) plain_draft.embed_tokens.requires_grad_(False) - return DFlashModel( + plain = DFlashModel( plain_draft, block_size=domino.block_size, num_anchors=domino.num_anchors, attention_backend="sdpa", loss_decay_gamma=domino.loss_decay_gamma, ) + # Compare the objective on the same block-isolated backbone visibility. + plain._materialize_cpu_block_mask = True + return plain @pytest.mark.parametrize( @@ -513,6 +527,76 @@ def test_unshifted_lambda_one_matches_plain_dflash_loss_and_gradients(): assert grad is None or torch.count_nonzero(grad) == 0, name +def test_draft_forward_keeps_existing_positional_arguments(): + import inspect + + from aspec.models.draft.dflash import DFlashDraftModel + + parameters = inspect.signature(DFlashDraftModel.forward).parameters + assert parameters["draft_attention_mask"].kind is inspect.Parameter.KEYWORD_ONLY + assert ( + parameters["return_router_logits"].kind + is inspect.Parameter.POSITIONAL_OR_KEYWORD + ) + + +def test_cpu_backbone_blocks_hide_later_target_features(): + model = make_model() + inputs = make_inputs() + inputs["injected_anchors"] = torch.tensor([[2, 7]]) + _, base_hidden = run_and_capture(model, inputs) + changed = {key: value.clone() if torch.is_tensor(value) else value + for key, value in inputs.items()} + # Block 0 (anchor 2) only sees context positions 0..1; position 2 is the + # strict cutoff, and later Target features belong to block 1's context. + changed["hidden_states_list"][0, 2:] += 5.0 + _, moved_hidden = run_and_capture(model, changed) + base_blocks = base_hidden.reshape(1, 2, 5, -1) + moved_blocks = moved_hidden.reshape(1, 2, 5, -1) + torch.testing.assert_close(base_blocks[:, 0], moved_blocks[:, 0], rtol=0, atol=0) + torch.testing.assert_close( + F.linear(base_blocks[:, 0], inputs["lm_head_weight"]), + F.linear(moved_blocks[:, 0], inputs["lm_head_weight"]), + rtol=0, atol=0, + ) + assert not torch.equal(base_blocks[:, 1], moved_blocks[:, 1]) + + +def test_cpu_draft_blocks_do_not_read_each_others_keys(): + model = make_model() + inputs = make_inputs() + inputs["injected_anchors"] = torch.tensor([[2, 7]]) + _, base_hidden = run_and_capture(model, inputs) + changed = {key: value.clone() if torch.is_tensor(value) else value + for key, value in inputs.items()} + changed["input_ids"][0, 2] = (changed["input_ids"][0, 2] + 1) % 32 + _, moved_hidden = run_and_capture(model, changed) + base_blocks = base_hidden.reshape(1, 2, 5, -1) + moved_blocks = moved_hidden.reshape(1, 2, 5, -1) + assert not torch.equal(base_blocks[:, 0], moved_blocks[:, 0]) + torch.testing.assert_close(base_blocks[:, 1], moved_blocks[:, 1], rtol=0, atol=0) + + +def test_loss_components_report_additive_pairs(): + model = make_model(lambda_base=0.3, loss_decay_gamma=3.0) + inputs = make_inputs() + inputs["loss_mask"][0, 9] = 0 + result, captured = run_and_capture(model, inputs) + _, _, _, expected = reference_objective(model, captured, inputs) + actual = result[5] + assert set(expected) <= set(actual) + for name, pair in expected.items(): + torch.testing.assert_close(actual[name][0], pair[0], rtol=2e-5, atol=2e-6) + torch.testing.assert_close(actual[name][1], pair[1], rtol=2e-5, atol=2e-6) + + mixed = (actual["mixed_ce"][0] / actual["mixed_ce"][1]).item() + backbone = (actual["backbone_ce"][0] / actual["backbone_ce"][1]).item() + corrected = (actual["corrected_ce"][0] / actual["corrected_ce"][1]).item() + assert mixed == pytest.approx(float(result[0].detach()), rel=1e-5, abs=1e-6) + assert mixed != pytest.approx(backbone, rel=1e-5, abs=1e-6) + assert corrected != pytest.approx(mixed, rel=1e-5, abs=1e-6) + + def test_correction_ignores_future_block_tokens(): model = make_model(shift_label=True) draft = model.draft_model diff --git a/tests/cpu/test_domino_integration.py b/tests/cpu/test_domino_integration.py new file mode 100644 index 0000000..b00baac --- /dev/null +++ b/tests/cpu/test_domino_integration.py @@ -0,0 +1,293 @@ +# 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 +import torch + +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=sdpa", PlanCompileError), + ("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] + assert "last_hidden_states" not in features["tensors"] + attention = next( + item for item in plan["capabilities"] if item["name"] == "draft_attention_execution" + ) + assert attention["requirement"] == "required" + assert attention["effective_state"] != "omitted" + + runtime = _runtime_values(config, _load_draft_descriptor(config)) + assert runtime["draft_algorithm"] == "domino" + assert runtime["domino_lambda_base"] == 0.3 + + +def test_trainer_aggregates_real_mixed_component(monkeypatch): + import aspec.training.dflash_trainer as trainer_module + + monkeypatch.setattr(trainer_module.dist, "all_reduce", lambda *args, **kwargs: None) + monkeypatch.setattr(trainer_module.dist, "get_rank", lambda: 1) + trainer = object.__new__(DominoTrainer) + trainer._anchor_slot_offset = 0 + trainer.global_step = 0 + trainer.optimizer = SimpleNamespace(get_learning_rate=lambda: 0.0) + trainer.dflash = SimpleNamespace(mtp_conditioning=None) + trainer.draft_model = SimpleNamespace(config=SimpleNamespace()) + trainer.loss_decay_gamma = 0.0 + + train_metrics = [ + { + "loss_per_position": torch.tensor([1.0]), + "acc_per_position": torch.tensor([1.0]), + "count_per_position": torch.tensor([1.0]), + "mixed_ce": (torch.tensor(2.0), torch.tensor(1.0)), + }, + { + "loss_per_position": torch.tensor([1.0]), + "acc_per_position": torch.tensor([1.0]), + "count_per_position": torch.tensor([1.0]), + "mixed_ce": (torch.tensor(9.0), torch.tensor(3.0)), + }, + ] + metrics = trainer._aggregate_metrics(train_metrics, step=1) + assert metrics["train/mixed_ce"] == pytest.approx(11 / 4) + assert metrics["train/avg_loss"] == pytest.approx(11 / 4) + + eval_metrics = [ + { + "loss_pp": torch.tensor([1.0]), + "acc_pp": torch.tensor([1.0]), + "count_pp": torch.tensor([1.0]), + "mixed_ce": (torch.tensor(2.0), torch.tensor(1.0)), + }, + { + "loss_pp": torch.tensor([1.0]), + "acc_pp": torch.tensor([1.0]), + "count_pp": torch.tensor([1.0]), + "mixed_ce": (torch.tensor(9.0), torch.tensor(3.0)), + }, + ] + eval_output = trainer._aggregate_eval_metrics(eval_metrics) + assert eval_output["eval/mixed_ce"] == pytest.approx(11 / 4) + assert eval_output["eval/avg_loss"] == pytest.approx(11 / 4) + + +def test_plan_rejects_explicit_cudnn_gqa_mode(tmp_path): + raw = json.loads(_DRAFT_JSON.read_text(encoding="utf-8")) + raw["cudnn_gqa_mode"] = "native" + draft_config = tmp_path / "domino_cudnn.json" + draft_config.write_text(json.dumps(raw), encoding="utf-8") + target = f"model.target_model_path={_fake_qwen_target(tmp_path)}" + args = [target, f"model.draft_model_config={draft_config}"] + with pytest.raises(PlanCompileError, match="cudnn_gqa_mode"): + config = load_config(config_path=str(_EXAMPLE), cli_args=args) + compile_execution_plan(config, config_path=str(_EXAMPLE), cli_args=args) + + +@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 + 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): + trainer._build_draft_model(_tiny_config()) + + +@pytest.mark.parametrize( + "missing", ["empty", "lambda_base", "loss_decay_gamma", "shift_label"] +) +def test_exact_resume_rejects_incomplete_domino_topology(missing): + args = _trainer_args() + topology = json.loads(json.dumps(_logical_training_topology(args, 2))) + if missing == "empty": + topology = {} + elif missing in {"lambda_base", "loss_decay_gamma"}: + del topology["training_objective"][missing] + else: + del topology["draft_model_semantics"]["shift_label"] + with pytest.raises(RuntimeError, match="complete Domino training_topology"): + _validate_exact_resume_topology( + args, {"world_size": 2, "training_topology": topology} + ) + + +def test_exact_resume_requires_topology_for_domino(): + args = _trainer_args() + with pytest.raises(RuntimeError, match="training_topology for Domino"): + _validate_exact_resume_topology(args, {"world_size": 2}) + + +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)