From d7d0c09e359a459ba9d6416e08d0bfb38a63a105 Mon Sep 17 00:00:00 2001 From: yu-chen-code Date: Fri, 6 Nov 2026 22:47:53 +0800 Subject: [PATCH] fix(compile): enforce replay contracts and retain terminal executables --- hyper_parallel/compile/compiler.py | 15 ++- .../compile/tracer/dynamic_shapes.py | 50 ++++++++- hyper_parallel/compile/tracer/graph_tracer.py | 11 +- tests/ut/compile/test_dynamic_shapes.py | 103 +++++++++++++++++- 4 files changed, 168 insertions(+), 11 deletions(-) diff --git a/hyper_parallel/compile/compiler.py b/hyper_parallel/compile/compiler.py index a624ff4bdb..45633f4d71 100644 --- a/hyper_parallel/compile/compiler.py +++ b/hyper_parallel/compile/compiler.py @@ -254,12 +254,21 @@ def compile(self, **inputs: Any) -> None: if ac_scope is not None: pass_kwargs["ac_scope"] = ac_scope - # Passes mutate ``graph_module`` in place and return it, so the - # transformed graph lives on ``joint_graph`` for ``forward_backward``. - pipeline.run(joint_graph.graph_module, **pass_kwargs) + # A pass may replace the module, e.g. when installing an executable + # backend wrapper. Keep its returned graph as the runtime executable. + runtime_graph = pipeline.run(joint_graph.graph_module, **pass_kwargs) + for name in ( + "state_fqns", "state_is_param", "num_state_inputs", "user_inputs_spec", + "loss_dict_keys", "fsdp_sharded_param_names", + ): + if not hasattr(runtime_graph, name) and hasattr(joint_graph.graph_module, name): + setattr(runtime_graph, name, getattr(joint_graph.graph_module, name)) + joint_graph.graph_module = runtime_graph if joint_graph.input_guards is not None: joint_graph.input_guards.refresh() + if joint_graph.state_guards is not None: + joint_graph.state_guards.refresh(self.model) self._joint_graph = joint_graph def forward_backward(self, **inputs: Any) -> Any: diff --git a/hyper_parallel/compile/tracer/dynamic_shapes.py b/hyper_parallel/compile/tracer/dynamic_shapes.py index f0a084d22c..d02f64507a 100644 --- a/hyper_parallel/compile/tracer/dynamic_shapes.py +++ b/hyper_parallel/compile/tracer/dynamic_shapes.py @@ -122,10 +122,11 @@ class InputGuards: No real input tensors or storage are retained here. """ - def __init__(self, inputs: list[Any], fake_inputs: tuple[Any, ...], shape_env: ShapeEnv) -> None: + def __init__(self, inputs: list[Any], fake_inputs: tuple[Any, ...], shape_env: ShapeEnv | None) -> None: self.shape_env = shape_env self.fake_tensors = [value for value in fake_inputs if isinstance(value, torch.Tensor)] self.leaves = [self._metadata(value) for value in inputs] + self.static_geometry = None if shape_env is not None else self._geometry(inputs) self.aliases = self._aliases(inputs) self.expression = None self.refresh() @@ -144,9 +145,18 @@ def _aliases(inputs: list[Any]) -> list[int]: for index, value in enumerate(inputs) if isinstance(value, torch.Tensor) ] + @staticmethod + def _geometry(inputs: list[Any]) -> list[tuple]: + return [ + (tuple(value.shape), tuple(value.stride()) if value.layout == torch.strided else None, + value.storage_offset() if value.layout == torch.strided else None) + for value in inputs if isinstance(value, torch.Tensor) + ] + def refresh(self) -> None: """Include constraints introduced by tracing and graph passes.""" - self.expression = self.shape_env.produce_guards_expression(self.fake_tensors, ignore_static=False) + if self.shape_env is not None: + self.expression = self.shape_env.produce_guards_expression(self.fake_tensors, ignore_static=False) def validate(self, inputs: list[Any]) -> None: """Reject incompatible inputs before any graph or collective is executed.""" @@ -154,6 +164,8 @@ def validate(self, inputs: list[Any]) -> None: raise ValueError("Graph input rank, dtype, device, layout, requires_grad or Python constant changed") if self._aliases(inputs) != self.aliases: raise ValueError("Graph input tensor aliasing changed since compilation") + if self.static_geometry is not None and self._geometry(inputs) != self.static_geometry: + raise ValueError("Static graph input shape/stride changed; compile again for the new inputs") tensors = [value for value in inputs if isinstance(value, torch.Tensor)] if self.expression and not self.shape_env.evaluate_guards_expression(self.expression, tensors): raise ValueError( @@ -161,3 +173,37 @@ def validate(self, inputs: list[Any]) -> None: "related input sizes and shape-dependent branches. Compile with representative dynamic sizes > 1; " "sizes 0/1 and Python shape branches may specialize the graph." ) + + +class ModelStateGuards: + """Guard graph-specialized module modes and storage metadata, allowing value updates.""" + + def __init__(self, model: torch.nn.Module) -> None: + self.signature = self._signature(model) + + @staticmethod + def _signature(model: torch.nn.Module) -> tuple: + """Snapshot module identities, state roles and storage geometry without retaining values.""" + modes = tuple((name, id(module), type(module), module.training) for name, module in model.named_modules()) + state = [ + (kind, name, value) + for kind, entries in (("parameter", model.named_parameters(remove_duplicate=False)), + ("buffer", model.named_buffers(remove_duplicate=False))) + for name, value in entries + ] + tensors = tuple( + (kind, name, id(value), tuple(value.shape), value.dtype, value.device, value.layout, value.requires_grad, + tuple(value.stride()) if value.layout == torch.strided else None, + value.storage_offset() if value.layout == torch.strided else None) + for kind, name, value in state + ) + return modes, tensors + + def refresh(self, model: torch.nn.Module) -> None: + """Record the final storage contract after graph partitioning.""" + self.signature = self._signature(model) + + def validate(self, model: torch.nn.Module) -> None: + """Reject stale captures before running graph operators or collectives.""" + if self._signature(model) != self.signature: + raise ValueError("Graph model state or training mode changed; compile again before execution") diff --git a/hyper_parallel/compile/tracer/graph_tracer.py b/hyper_parallel/compile/tracer/graph_tracer.py index ea9a8f4627..3d913486f9 100644 --- a/hyper_parallel/compile/tracer/graph_tracer.py +++ b/hyper_parallel/compile/tracer/graph_tracer.py @@ -74,7 +74,7 @@ from torch.fx.traceback import preserve_node_meta from torch.nn.utils import stateless -from .dynamic_shapes import InputGuards, build_symbolic_inputs +from .dynamic_shapes import InputGuards, ModelStateGuards, build_symbolic_inputs # Older torch's make_fx predates record_stack_traces / record_module_stack # and rejects unknown kwargs; forward only the kwargs this torch supports. @@ -180,6 +180,7 @@ class JointGraph: state_fqns: List[str] example_inputs: tuple input_guards: InputGuards | None = None + state_guards: ModelStateGuards | None = None def extract_module_state(mod: nn.Module) -> Dict[str, torch.Tensor]: @@ -647,10 +648,10 @@ def trace_model_graph( # pylint: disable=too-many-locals num_layers=num_layers, state_fqns=state_fqns, example_inputs=fake_args, - input_guards=( - InputGuards(user_inputs_flat, fake_args[num_state_inputs:], fake_mode.shape_env) - if symbolic else None + input_guards=InputGuards( + user_inputs_flat, fake_args[num_state_inputs:], fake_mode.shape_env if symbolic else None ), + state_guards=ModelStateGuards(model), ) @@ -686,6 +687,8 @@ def run_traced_graph( f" Traced: {joint_graph.state_fqns}\n" f" Got: {list(model_state.keys())}" ) + if joint_graph.state_guards is not None: + joint_graph.state_guards.validate(model) user_flat, user_spec = torch.utils._pytree.tree_flatten(inputs) traced_spec = getattr(joint_graph.graph_module, "user_inputs_spec", None) diff --git a/tests/ut/compile/test_dynamic_shapes.py b/tests/ut/compile/test_dynamic_shapes.py index 4ed0348f69..1b93af86e6 100644 --- a/tests/ut/compile/test_dynamic_shapes.py +++ b/tests/ut/compile/test_dynamic_shapes.py @@ -48,6 +48,105 @@ def setUp(self) -> None: def _compiler(self, **kwargs): return GraphCompiler(self.model, _loss, pass_config=self.config, **kwargs) + def test_static_inputs_reject_specialization_changes_before_execution(self): + """Static geometry and Python constants cannot silently replay stale branches.""" + compiler = GraphCompiler( + self.model, lambda model, x, scale: model(x).sum() * scale, pass_config=self.config + ) + compiler.forward_backward(x=torch.randn(3, 4), scale=2) + invalid = [ + {"x": torch.randn(5, 4), "scale": 2}, + {"x": torch.randn(4, 3).t(), "scale": 2}, + {"x": torch.randn(4, 4)[1:], "scale": 2}, + {"x": torch.randn(3, 4, dtype=torch.float64), "scale": 2}, + {"x": torch.randn(3, 4), "scale": 3}, + ] + with patch.object(compiler._joint_graph.graph_module, "forward") as execute: + for inputs in invalid: + with self.subTest(inputs=inputs), self.assertRaisesRegex(ValueError, "[Gg]raph input"): + compiler.forward_backward(**inputs) + execute.assert_not_called() + + def test_state_values_remain_live_but_structural_changes_are_rejected(self): + """Optimizer updates are valid; changed mode, identity and gradient contract are not.""" + compiler = self._compiler() + x, y = torch.randn(3, 4), torch.randn(3, 3) + compiler.forward_backward(x=x, y=y) + with torch.no_grad(): + self.model.weight.add_(0.1) + actual, _ = compiler.forward_backward(x=x, y=y) + torch.testing.assert_close(actual, _loss(self.model, x, y), rtol=0, atol=0) + for change in ("mode", "parameter", "requires_grad"): + with self.subTest(change=change): + model = copy.deepcopy(self.model) + case = GraphCompiler(model, _loss, pass_config=self.config) + case.forward_backward(x=x, y=y) + if change == "mode": + model.eval() + elif change == "parameter": + model.weight = torch.nn.Parameter(torch.clone(model.weight)) + else: + model.weight.requires_grad_(False) + with patch.object(case._joint_graph.graph_module, "forward") as execute: + with self.assertRaisesRegex(ValueError, "Graph model state"): + case.forward_backward(x=x, y=y) + execute.assert_not_called() + + def test_replacement_executable_preserves_runtime_metadata(self): + """A terminal pass may return a wrapper; its loss dictionary and gradients survive.""" + class Executable(torch.nn.Module): + """Equivalent terminal backend wrapper without tracing metadata.""" + + def __init__(self, inner): + super().__init__() + self.inner = inner + self.calls = 0 + + def forward(self, *args): + self.calls += 1 + return self.inner(*args) + + compiler = GraphCompiler( + self.model, lambda model, x, y: (_loss(model, x, y), {"main": _loss(model, x, y).detach()}), + pass_config=self.config, + ) + with patch("hyper_parallel.compile.compiler.PassPipeline.run", + side_effect=lambda graph, **kwargs: Executable(graph)): + x, y = torch.randn(3, 4), torch.randn(3, 3) + actual, losses = compiler.forward_backward(x=x, y=y) + self.assertEqual(compiler._joint_graph.graph_module.calls, 1) + torch.testing.assert_close(actual, losses["main"], rtol=0, atol=0) + expected = torch.autograd.grad(_loss(self.model, x, y), tuple(self.model.parameters())) + for parameter, gradient in zip(self.model.parameters(), expected): + torch.testing.assert_close(parameter.grad, gradient, rtol=0, atol=0) + + def test_module_and_state_kind_changes_invalidate_capture(self): + """Reusing a tensor does not preserve a changed module or parameter contract.""" + class ShiftedLinear(torch.nn.Module): + """A distinct forward with the same parameter names and shapes.""" + + def __init__(self, weight): + super().__init__() + self.weight = weight + + def forward(self, inputs): + return inputs @ self.weight.T + 1 + + model = torch.nn.Sequential(torch.nn.Linear(4, 3, bias=False)) + compiler = GraphCompiler(model, _loss, pass_config=self.config) + inputs = {"x": torch.randn(3, 4), "y": torch.randn(3, 3)} + compiler.forward_backward(**inputs) + replacement = ShiftedLinear(model[0].weight) + model[0] = replacement + with self.assertRaisesRegex(ValueError, "Graph model state"): + compiler.forward_backward(**inputs) + compiler.compile(**inputs) + parameter = model[0].weight + delattr(model[0], "weight") + model[0].register_buffer("weight", parameter) + with self.assertRaisesRegex(ValueError, "Graph model state"): + compiler.forward_backward(**inputs) + def _assert_step(self, compiler, batch, sequence): x = torch.randn(batch, sequence, 4) y = torch.randn(batch, sequence, 3) @@ -225,12 +324,12 @@ def test_sample_storage_is_not_retained(self): def test_static_default_unchanged(self): """ Feature: Symbolic graph shape contracts. - Description: Opting out retains concrete tensor metadata and no symbolic guards. + Description: Opting out retains concrete tensor metadata and static input guards. Expectation: Dynamic dimensions reuse graphs and static dimensions retain guards. """ compiler = self._compiler() self._assert_step(compiler, 2, 5) - self.assertIsNone(compiler._joint_graph.input_guards) + self.assertIsNone(compiler._joint_graph.input_guards.shape_env) for dim in compiler._joint_graph.example_inputs[2].shape: self.assertIs(type(dim), int)