Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
4328a6a
Add an opt-in Miles v0.2.0 runtime and native checkpoints
frrad Nov 12, 2026
a7b8262
Type the Miles migration against the reference-run checks
frrad Nov 12, 2026
3d3213b
Copy trainer source before the Miles image import check
frrad Nov 12, 2026
57e0744
Pin the Miles v0.2.0 fork and capture native exports on shared storage
frrad Nov 12, 2026
f8090d1
Pin Miles migration validation to the reviewed development branch
frrad Nov 12, 2026
6375b7c
Reuse complete local shards when assembling native checkpoints
frrad Nov 12, 2026
ba352a3
Record native checkpoint and full reference validation
frrad Nov 12, 2026
93bf73a
Record deployment settings and completed restart checks
frrad Nov 12, 2026
527e761
Compare migration results with the recorded H100 baseline
frrad Nov 12, 2026
0fc0980
Pin the Miles v0.2.0 fork to the current miles#38 head
frrad Nov 13, 2026
2697bd1
Keep single-node Miles v0.2.0 captures on local disk
frrad Nov 13, 2026
9484679
Pass the LoRA layout to Miles explicitly
frrad Nov 13, 2026
6d96b1b
Hard-code the LoRA layout and keep capture locking to volume captures
frrad Nov 13, 2026
3a629c8
Share actor helpers without importing the legacy actor
frrad Nov 13, 2026
2364225
Limit Miles v0.2.0 to single-node bridge trainers and isolate capture…
frrad Nov 13, 2026
fd07c15
Drop out-of-scope checkpoint step checks and unused worker env vars
frrad Nov 13, 2026
8f66e96
Trim native checkpoint checks and tests
frrad Nov 13, 2026
016debf
Record the Miles v0.2.0 reference run in the shared-lora_A layout
frrad Nov 13, 2026
27187ad
Record the Miles v0.2.0 reference run on the final head
frrad Nov 13, 2026
ff37229
Drop the v0.2.0 results README
frrad Nov 13, 2026
1e6f69e
Fold the Miles v0.2.0 notes into the deployment docs
frrad Nov 13, 2026
4bd8b8e
Mount Spindle's source in the Miles v0.2.0 image
frrad Nov 13, 2026
7c4ed4a
Pin Miles v0.2.0 to the merged miles#38 commit
frrad Nov 16, 2026
a36f67d
Remove rejected Miles v0.2.0 captures
frrad Nov 16, 2026
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
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ Notable changes to Spindle, following [Keep a Changelog](https://keepachangelog.

### Added

- An opt-in `miles-v0.2.0` trainer image with native adapter checkpoints, for single-node trainers in bridge mode. It trains the same shared-`lora_A` adapter layout as the existing images, which remain the default. Checkpoints don't restore across Miles versions. See [Images](docs/deployment-configs.md#images).
- Token usage per session on shared trainers and samplers, stored on a `<frontend>-usage` Modal Volume and readable with Tinker's `get_billing_usage`. Label runs with `user_metadata`; `SPINDLE_USAGE_LABEL_KEYS` in the frontend's API secret lists the keys kept (default `run_id,team_id`). See [Cost attribution](docs/cost-attribution.md).
- `spindle usage` splits Modal app cost across runs or labels by tokens processed, reading costs from Modal's billing report. Idle and cold-start time of trainers and sampler pools isn't charged to a run but still costs you, so it's shown as separate lines; `--hide-overhead` hides them. If Modal's billing report doesn't cover the whole window yet, only the hours it covers are split.
- `reference_runs/`: a DAPO-Math GRPO workload on the stock Tinker SDK that records learning and timing metrics, with recorded results and a chart script for comparing deployments. Its deployment recipe fixes four H100 trainer GPUs and two single-H100 sampler replicas, and the client records that hardware contract.
Expand Down
6 changes: 5 additions & 1 deletion docs/deployment-configs.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,11 @@ Besides the LoRA settings, `miles_cfg` accepts `megatron_to_hf_mode` (`bridge`,

### Images

`trainer_image` selects a named trainer image instead of the backend default; the names are listed in [deployment_apps.py](../src/spindle/providers/modal/deployment_apps.py). The multi-LoRA actor runs on Miles v0.1.1 and v0.1.2.
`trainer_image` selects a named trainer image instead of the backend default; the names are listed in [deployment_apps.py](../src/spindle/providers/modal/deployment_apps.py). The multi-LoRA actor runs on Miles v0.1.1 (the default), v0.1.2 (`miles-v0.1.2`), and v0.2.0 (`miles-v0.2.0`).

`miles-v0.2.0` supports single-node trainers with `megatron_to_hf_mode` set to `bridge`; deploying it with more than one trainer node or with `raw` is rejected. Every Miles image trains the same adapter layout, one `lora_A` shared across each fused projection, and exports a standard PEFT adapter to the samplers.

A checkpoint restores only on a trainer with the same Miles revision as the one that saved it, so keep the original image to restore older checkpoints after switching images.

## Prepare and launch

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
"""Deployment settings used for the recorded Miles v0.2.0 run.

The reference recipe in reference_runs/dapo_math_config.py with the new trainer
image, deployed with the frontend, trainer and samplers in us-east.
"""

from copy import deepcopy

from spindle.configs.qwen35_4b_lora_32k import Config as Parent


class Config(Parent):
name = "dapo-math-qwen35-4b-h100"
trainer_image = "miles-v0.2.0"
trainer_gpu = "H100!"
trainer_gpus_per_node = 4
trainer_nodes = 1
trainer_max_instances = 1
trainer_max_clients_per_instance = 1
inference_gpu = "H100!"
inference_gpus_per_node = 1
inference_min_replicas = 2
inference_max_replicas = 2
platform = deepcopy(Parent.platform)
platform["modal"]["region"] = "us-east"


config = Config()

Large diffs are not rendered by default.

5 changes: 5 additions & 0 deletions src/spindle/backends/deployment.py
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,11 @@ def backend_config(spec, asset_path="/assets/pending"):
raise ValueError("expert parallel sizes must divide the trainer GPU allocation")
if spec.trainer_max_clients_per_instance > config.max_lora_slots:
raise ValueError("max_clients_per_instance exceeds max_lora_slots")
if spec.trainer_image == "miles-v0.2.0":
if config.megatron_to_hf_mode != "bridge":
raise ValueError("miles-v0.2.0 supports only megatron_to_hf_mode bridge")
if spec.trainer_nodes != 1:
raise ValueError("miles-v0.2.0 supports only single-node trainers")
settings = {"miles": config.model_dump(), "checkpoint_dir": "/checkpoints"}
if spec.trainer_nodes > 1:
# Captures on the shared volume let every node's shards be assembled.
Expand Down
3 changes: 3 additions & 0 deletions src/spindle/backends/miles_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,9 @@ def miles_arguments(self) -> list[str]:
str(int(self.default_lora_alpha)),
"--lora-dropout",
str(self.lora_dropout),
# Miles v0.2.0 defaults serve entries to canonical_lora; v0.1.x multi-LoRA supports only lora.
"--lora-type",
"lora",
"--target-modules",
",".join(self.target_modules),
"--no-gradient-accumulation-fusion",
Expand Down
27 changes: 19 additions & 8 deletions src/spindle/backends/miles_lora.py
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ def __init__(
self.slot_to_job: dict[int, str] = {}
# A volume refresh must not race checkpoint writes on the persistence lane.
self._checkpoint_io_lock = threading.RLock()
self._native = self.runtime.checkpoint_format == "miles_adapter_state"
self._checkpoint_captures: dict[str, dict[str, Any]] = {}
self._sampler_captures: dict[str, dict[str, Any]] = {}
self._timer = StepPhaseTimer()
Expand Down Expand Up @@ -316,7 +317,7 @@ def capture_checkpoint(
)
metadata = {
"schema_version": 1,
"checkpoint_format": "miles_torch_dist",
"checkpoint_format": self.runtime.checkpoint_format,
"backend": "miles",
"miles_revision": self.runtime.revision,
"base_model": self.base_model,
Expand Down Expand Up @@ -344,6 +345,8 @@ def capture_checkpoint(
"pipeline_model_parallel_size": 1,
},
}
if self._native:
metadata["lora_config"]["target_modules"] = list(self.config.target_modules)
(capture_path / "metadata.json").write_text(
json.dumps(metadata, sort_keys=True),
encoding="utf-8",
Expand Down Expand Up @@ -376,12 +379,15 @@ def persist_checkpoint(
),
self._record("spindle/persist_checkpoint"),
):
_install_capture(
capture["path"],
target,
overwrite=overwrite,
world_size=self.config.world_size,
)
if self._native:
_install_directory(capture["path"], target, overwrite=overwrite)
else:
_install_capture(
capture["path"],
target,
overwrite=overwrite,
world_size=self.config.world_size,
)
_commit_volume(os.environ.get("SPINDLE_CHECKPOINT_VOLUME"))
return str(target)
finally:
Expand Down Expand Up @@ -645,7 +651,7 @@ def _validate_checkpoint(
raise ValueError("checkpoint was not created by the Miles backend")
if metadata.get("miles_revision") != self.runtime.revision:
raise ValueError("checkpoint Miles revision does not match the deployment")
if metadata.get("checkpoint_format") != "miles_torch_dist":
if metadata.get("checkpoint_format") != self.runtime.checkpoint_format:
raise ValueError("unsupported Miles checkpoint format")
if metadata.get("base_model") != self.base_model:
raise ValueError("checkpoint base model does not match the deployment")
Expand All @@ -655,6 +661,11 @@ def _validate_checkpoint(
or float(lora.get("alpha", 0)) != state.alpha
):
raise ValueError("checkpoint LoRA configuration does not match the model")
# Checked here because a target mismatch found by Miles disables the whole trainer.
if self._native and lora.get("target_modules") != list(
self.config.target_modules
):
raise ValueError("checkpoint LoRA configuration does not match the model")
expected_targets = {
"train_attn": state.train_attn,
"train_mlp": state.train_mlp,
Expand Down
94 changes: 12 additions & 82 deletions src/spindle/backends/miles_runtime/actor.py
Original file line number Diff line number Diff line change
@@ -1,10 +1,6 @@
from __future__ import annotations

from datetime import timedelta

import torch
import torch.distributed as dist
from torch.distributed.constants import default_pg_timeout
from megatron.bridge import AutoBridge
from megatron.bridge.models.qwen_vl.modelling_qwen3_vl import model as qwen3_vl_model
from megatron.core import dist_checkpointing
Expand All @@ -13,8 +9,6 @@
from miles.backends.megatron_utils.lora import model as lora_model
from miles.backends.megatron_utils.lora.actor import MultiLoRATrainRayActor
from miles.backends.training_utils.weight_update import snapshot_publisher
from miles.ray import train_actor
from miles.utils import distributed_utils
from miles.utils.replay_base import routing_replay_manager
from miles_plugins.models import qwen3_vl as miles_qwen3_vl

Expand All @@ -41,15 +35,14 @@

from . import tinker_cp

from spindle.startup_timing import timeline

from . import allgather_cp_lora, expert_lora_compat, host_syncs
from .actor_shared import (
ProfiledActor,
install_replay_patches,
mark_actor_initialized as _mark_actor_initialized,
use_distributed_timeout_for_gloo as _use_distributed_timeout_for_gloo,
)
from .volumes import install_cross_node_checkpoint_publish, sync_checkpoint_volume
from .profiling import RankProfiler, TorchProfileConfig
from .qwen3_vl_cp import install_qwen3_vl_cp_position_ids
from .replay import install_replay_hooks
from .replay_data import install_distribution_sharding
from .score_centering import install_losses

try:
from miles.ray.rollout import train_data_conversion
Expand All @@ -62,20 +55,17 @@
if tinker_cp is not None:
tinker_cp.install()

install_replay_hooks(
install_replay_patches(
megatron_model=megatron_model,
lora_model=lora_model,
logit_processors=logit_processors,
tinker_losses=tinker_losses,
math_utils=math_utils,
fill_replay_data=fill_replay_data,
manager=routing_replay_manager,
)
install_losses(tinker_losses, logit_processors)
install_distribution_sharding(train_data_conversion)

install_qwen3_vl_cp_position_ids(
bridge_model=qwen3_vl_model, miles_qwen3_vl=miles_qwen3_vl
routing_replay_manager=routing_replay_manager,
train_data_conversion=train_data_conversion,
qwen3_vl_model=qwen3_vl_model,
miles_qwen3_vl=miles_qwen3_vl,
)

host_syncs.install()
Expand All @@ -93,26 +83,7 @@ def _sync_checkpoint_volume(action: str) -> None:
sync_checkpoint_volume(action)


def _use_distributed_timeout_for_gloo(minutes: int) -> None:
timeout = max(timedelta(minutes=minutes), default_pg_timeout)

def init_gloo_group():
if distributed_utils.GLOO_GROUP is None:
distributed_utils.GLOO_GROUP = dist.new_group(
backend="gloo", timeout=timeout
)
return distributed_utils.GLOO_GROUP

train_actor.init_gloo_group = init_gloo_group


def _mark_actor_initialized() -> None:
rank = dist.get_rank() if dist.is_initialized() else 0
if rank == 0:
timeline("trainer-rank0").mark("actor_model_loaded")


class SpindleMilesTrainRayActor(MultiLoRATrainRayActor):
class SpindleMilesTrainRayActor(ProfiledActor, MultiLoRATrainRayActor):
"""Upstream multi-LoRA actor with Qwen MTP and weights-only save support."""

def init(self, args, role, **kwargs):
Expand Down Expand Up @@ -140,29 +111,6 @@ def provider_without_mtp(bridge, *provider_args, **provider_kwargs):
_mark_actor_initialized()
return result

def torch_profile_start(self) -> None:
if not TorchProfileConfig.from_env().profiles_rank(dist.get_rank()):
self._spindle_profiler = None
return
self._spindle_profiler = RankProfiler()
self._spindle_profiler.start()

def torch_profile_stop(self, output_dir: str) -> dict | None:
profiler = self._spindle_profiler
if profiler is None:
return None
self._spindle_profiler = None
return profiler.stop(output_dir, f"rank{dist.get_rank()}")

def forward_backward(self, *args, **kwargs):
return self._profiled("forward_backward", *args, **kwargs)

def optim_step(self, *args, **kwargs):
return self._profiled("optim_step", *args, **kwargs)

def forward_only(self, *args, **kwargs):
return self._profiled("forward_only", *args, **kwargs)

def load_slot(
self,
slot: int,
Expand Down Expand Up @@ -195,24 +143,6 @@ def export_slot(self, *args, **kwargs):
_sync_checkpoint_volume("commit")
return result

def _profiled(self, operation: str, *args, **kwargs):
with torch.profiler.record_function(f"spindle/{operation}"):
result = getattr(super(), operation)(*args, **kwargs)
self._log_peak_memory(operation)
return result

@staticmethod
def _log_peak_memory(operation: str) -> None:
gib = 1024**3
print(
f"spindle_memory op={operation} "
f"allocated_gb={torch.cuda.memory_allocated() / gib:.2f} "
f"max_allocated_gb={torch.cuda.max_memory_allocated() / gib:.2f} "
f"reserved_gb={torch.cuda.memory_reserved() / gib:.2f} "
f"max_reserved_gb={torch.cuda.max_memory_reserved() / gib:.2f}",
flush=True,
)

def export_slot_peft(
self,
*,
Expand Down
Loading
Loading