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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions aspec/config/domino_qwen3_8b_draft_config.json
Original file line number Diff line number Diff line change
@@ -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
}
4 changes: 3 additions & 1 deletion aspec/config/draft_algorithm.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@

DRAFT_ALGORITHMS = {
"NativeMTPDraftModel": "mtp",
"DominoDraftModel": "domino",
"DFlashDraftModel": "dflash",
"DFlash2DraftModel": "dflash2",
"DSparkDraftModel": "dspark",
Expand Down Expand Up @@ -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",
Expand Down
3 changes: 3 additions & 0 deletions aspec/config/train_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions aspec/models/draft/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -35,6 +36,8 @@
"DFlashDraftModel",
"DFlash2Config",
"DFlash2DraftModel",
"DominoConfig",
"DominoDraftModel",
"DSparkConfig",
"DSparkDraftModel",
"K3DSparkConfig",
Expand Down
3 changes: 3 additions & 0 deletions aspec/models/draft/auto.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -46,6 +47,7 @@ class AutoEagle3DraftModel(AutoModelForCausalLMBase):
Eagle4Config: Eagle4DraftModel,
DeepseekV3Config: Eagle3DeepseekV2ForCausalLM,
NativeMTPConfig: NativeMTPDraftModel,
DominoConfig: DominoDraftModel,
DFlashConfig: DFlashDraftModel,
DFlash2Config: DFlash2DraftModel,
DSparkConfig: DSparkDraftModel,
Expand All @@ -68,6 +70,7 @@ class AutoDraftModelConfig:
"LlamaForCausalLMEagle4": Eagle4Config,
"Eagle3DeepseekV2ForCausalLM": DeepseekV3Config,
"NativeMTPDraftModel": NativeMTPConfig,
"DominoDraftModel": DominoConfig,
"DFlashDraftModel": DFlashConfig,
"DFlash2DraftModel": DFlash2Config,
"Qwen3DSparkModel": DSparkConfig,
Expand Down
62 changes: 61 additions & 1 deletion aspec/planning.py
Original file line number Diff line number Diff line change
Expand Up @@ -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":

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] Match the declared attention backend to the masked training path. This gate only accepts sdpa. On CUDA, DFlashModel._draft_backbone builds a BlockMask, which sends DFlashAttention.forward into compile_friendly_flex_attention. On CPU the mask is absent, so SDPA can attend to future Target features and other draft blocks. The current CPU loss checks reuse the resulting backbone activations and can pass even with that leakage. Please align the Plan and kernel dispatch, and add a visibility regression on the supported path: with anchors fixed, changing Target features after an anchor must leave that block’s logits unchanged.

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(
Expand Down Expand Up @@ -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"),
}


Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
Expand Down
11 changes: 9 additions & 2 deletions aspec/training/checkpoint.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"),
Expand All @@ -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:
Expand All @@ -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")
Expand Down Expand Up @@ -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")):
Expand Down
60 changes: 60 additions & 0 deletions aspec/training/domino_trainer.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# 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):
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,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Report the mixed objective used for backward. DominoModel returns mixed CE for optimization and corrected CE for per-position reporting. The inherited trainer reconstructs train/avg_loss and eval/avg_loss from the per-position values. At lambda_base=1, the optimizer follows backbone CE while both curves still show corrected CE. This makes a loss-curve comparison with SpecForge misleading. Please expose mixed, backbone and corrected CE separately, pooling numerators and supervision weights across microbatches and ranks. A test where the two heads give different CE at lambda_base=1 would catch the mismatch.

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
),
)
# 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
6 changes: 5 additions & 1 deletion aspec/training/trainer_actor.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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__}"
)

Expand Down
93 changes: 93 additions & 0 deletions configs/examples/domino_qwen3_8b_4k_tcp.yaml
Original file line number Diff line number Diff line change
@@ -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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Disable the unused final Target hidden state in the TCP example. Domino uses token-label CE with dflash_l1_loss_alpha=0 and no MTP conditioning, so DFlashTrainer._forward skips last_hidden_states. Enabling it still adds a tensor to the Store/TCP payload. For a full 4K sample that is 32 MiB (4096 × 4096 × 2 bytes in BF16), on top of the five auxiliary layers the backbone consumes. Please set store_last_hidden_states: false in this example.

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
Loading
Loading