[PyTorch] Add op-level activation offload opt-out API (#3108)

* Add TE op CPU offload opt-out API

Signed-off-by: hongbinl <hongbinl@nvidia.com>

* Rename op API to activation offloading

Signed-off-by: hongbinl <hongbinl@nvidia.com>

* Move CPU offload gating to TE op call sites

Signed-off-by: hongbinl <hongbinl@nvidia.com>

* Preserve grouped linear offload start semantics

Signed-off-by: hongbinl <hongbinl@nvidia.com>

* Use setter for activation offload policy

Signed-off-by: hongbinl <hongbinl@nvidia.com>

* Limit activation offload policy helper to marking

Signed-off-by: hongbinl <hongbinl@nvidia.com>

* Move CPU offload imports to op module scope

Signed-off-by: hongbinl <hongbinl@nvidia.com>

* Patch activation offload test bound symbols

Signed-off-by: hongbinl <hongbinl@nvidia.com>

* Refactor base class offloading infrastructure

Handle inclusion and exclusion in same function. Check whether CPU offloading is enabled internally. Tweak documentation and style.

Signed-off-by: Tim Moon <tmoon@nvidia.com>

* Propagate activation offload policy helper

Use BasicOperation.mark_for_cpu_offload_if_needed at op call sites and keep explicit offload synchronization checks where needed.

Co-authored-by: OpenAI Codex <codex@openai.com>
Signed-off-by: Tim Moon <tmoon@nvidia.com>

* Move test into TestFuser suite

Signed-off-by: Tim Moon <tmoon@nvidia.com>

* Debug failure with grouped linear

Signed-off-by: Tim Moon <tmoon@nvidia.com>

---------

Signed-off-by: hongbinl <hongbinl@nvidia.com>
Signed-off-by: Tim Moon <tmoon@nvidia.com>
Co-authored-by: Tim Moon <tmoon@nvidia.com>
Co-authored-by: OpenAI Codex <codex@openai.com>

Author: 3 people

tests/pytorch/test_fusible_ops.py

@@ -634,6 +634,40 @@ def test_pyt_autocast(
             assert x.grad.dtype == model_dtype
             assert op.weight.grad.dtype == model_dtype
 
+    def test_activation_offloading_policy(self, monkeypatch):
+        """Test opt-out API for activation CPU offloading."""
+        import transformer_engine.pytorch.ops.op as op_module
+
+        calls = []
+        tensor = torch.empty(1)
+        tensor_id = id(tensor)
+        op = te_ops.Identity()
+
+        monkeypatch.setattr(
+            op_module,
+            "mark_activation_offload",
+            lambda *tensors: calls.append(("mark", [id(t) for t in tensors])),
+        )
+        monkeypatch.setattr(
+            op_module,
+            "mark_not_offload",
+            lambda *tensors: calls.append(("skip", [id(t) for t in tensors])),
+        )
+        monkeypatch.setattr(op_module, "is_cpu_offload_enabled", lambda: True)
+
+        op.mark_for_cpu_offload_if_needed(tensor, None)
+        assert calls == [("mark", [tensor_id])]
+
+        calls.clear()
+        op.set_activation_offloading(False)
+        op.mark_for_cpu_offload_if_needed(tensor)
+        assert calls == [("skip", [tensor_id])]
+
+        calls.clear()
+        op.set_activation_offloading(True)
+        op.mark_for_cpu_offload_if_needed(tensor)
+        assert calls == [("mark", [tensor_id])]
+
 
 class TestBasicOps:
     """Tests for individual operations"""

transformer_engine/pytorch/ops/basic/activation.py

@@ -13,7 +13,6 @@
 
 import transformer_engine_torch as tex
 from ...constants import DType
-from ...cpu_offload import is_cpu_offload_enabled, mark_activation_offload
 from ...tensor.float8_tensor import Float8CurrentScalingQuantizer, Quantizer
 from ...utils import clear_tensor_data
 from ..op import BasicOperation, OperationContext
@@ -114,8 +113,7 @@ def op_forward(
 
         # Save state for backward pass
         if ctx.requires_grad:
-            if is_cpu_offload_enabled():
-                mark_activation_offload(x)
+            self.mark_for_cpu_offload_if_needed(x)
             ctx.save_for_backward(x)
             ctx.dtype = dtype
             ctx.prev_op_grad_output_quantizer = prev_op_grad_output_quantizer
@@ -414,8 +412,7 @@ def fuser_forward(
 
         ctx = basic_op_ctxs[0]
         if ctx.requires_grad:
-            if is_cpu_offload_enabled():
-                mark_activation_offload(x)
+            self.mark_for_cpu_offload_if_needed(x)
             ctx.input_requires_grad = True
             ctx.extra_input_requires_grad = extra_input.requires_grad
             ctx.dtype = dtype

transformer_engine/pytorch/ops/basic/basic_linear.py

@@ -13,7 +13,6 @@
 import torch
 
 from ...cpp_extensions import general_gemm
-from ...cpu_offload import is_cpu_offload_enabled, mark_activation_offload
 from ...distributed import (
     CudaRNGStatesTracker,
     gather_along_first_dim,
@@ -1049,11 +1048,13 @@ def op_forward(
             else:
                 saved_input = x_local
                 saved_weight = w
-            if is_cpu_offload_enabled():
-                # No special CPU offloading logic is needed for weights. saved_weight is
-                # either self.weight (nn.Parameter, auto-excluded from offload) or a
-                # workspace freshly created each forward pass.
-                mark_activation_offload(saved_input)
+
+            # Activation CPU offloading
+            # Note: No special CPU offloading logic is needed for weights. saved_weight is
+            # either self.weight (nn.Parameter, auto-excluded from offload) or a
+            # workspace freshly created each forward pass.
+            self.mark_for_cpu_offload_if_needed(saved_input)
+
             ctx.save_for_backward(saved_input, saved_weight)
             ctx.with_quantized_compute = with_quantized_compute and backward_override is None
             ctx.backward_override = backward_override

transformer_engine/pytorch/ops/basic/dropout.py

@@ -9,7 +9,6 @@
 
 import torch
 import transformer_engine_torch as tex
-from ...cpu_offload import is_cpu_offload_enabled, mark_activation_offload
 from ...tensor import Quantizer
 from ...tensor.storage.float8_tensor_storage import Float8TensorStorage
 from .._common import maybe_autocast_dtype, maybe_dequantize
@@ -71,8 +70,7 @@ def op_forward(
 
         # Save context for backward
         if ctx.requires_grad:
-            if is_cpu_offload_enabled():
-                mark_activation_offload(mask)
+            self.mark_for_cpu_offload_if_needed(mask)
             ctx.save_for_backward(mask)
             ctx.impl = impl
             ctx.dropout_probability = self.dropout_probability

transformer_engine/pytorch/ops/basic/grouped_linear.py

@@ -23,7 +23,7 @@
     _2X_ACC_DGRAD,
     _2X_ACC_WGRAD,
 )
-from ...cpu_offload import is_cpu_offload_enabled, mark_activation_offload, start_offload
+from ...cpu_offload import is_cpu_offload_enabled, start_offload
 from ...quantization import FP8GlobalStateManager, QuantizerRole, Recipe
 from ...quantized_tensor import QuantizedTensorStorage
 from ...tensor import MXFP8Quantizer, MXFP8Tensor, Quantizer
@@ -1032,19 +1032,14 @@ def fuser_forward_save_ctx(
         # Note: No special logic is needed for weights. They are
         # either nn.Parameter (auto-excluded from offload) or are
         # temporary workspaces freshly created in each forward pass.
-        if is_cpu_offload_enabled():
-            saved = tensors_to_save[0]
-            offset = 4 if self._scale_bias else 3
-            if use_grouped_tensor_path:
-                # Layout: [split_sizes, base_split_offsets, split_points, (scales?), grouped_x, *weights]
-                grouped_x = saved[offset]
-                if grouped_x is not None:
-                    mark_activation_offload(grouped_x)
-            else:
-                # Layout: [split_sizes, None, None, (scales?), *xs, *ws]
-                live_xs = [t for t in saved[offset : offset + self.num_groups] if t is not None]
-                if live_xs:
-                    mark_activation_offload(*live_xs)
+        saved = tensors_to_save[0]
+        offset = 4 if self._scale_bias else 3
+        if use_grouped_tensor_path:
+            # Layout: [split_sizes, base_split_offsets, split_points, (scales?), grouped_x, *weights]
+            self.mark_for_cpu_offload_if_needed(saved[offset])
+        else:
+            # Layout: [split_sizes, None, None, (scales?), *xs, *ws]
+            self.mark_for_cpu_offload_if_needed(saved[offset : offset + self.num_groups])
 
         ctx.save_for_backward(*tensors_to_save[0])
 

transformer_engine/pytorch/ops/basic/l2normalization.py

@@ -11,7 +11,6 @@
 import torch
 
 from ...torch_version import torch_version
-from ...cpu_offload import is_cpu_offload_enabled, mark_activation_offload
 from ...jit import (
     l2normalization_fused,
     l2normalization_fwd_fused,
@@ -102,8 +101,7 @@ def op_forward(
 
         # Save state for backward pass
         if requires_grad:
-            if is_cpu_offload_enabled():
-                mark_activation_offload(x, rsqrt_norm)
+            self.mark_for_cpu_offload_if_needed(x, rsqrt_norm)
             ctx.save_for_backward(x, rsqrt_norm)
 
         return y

transformer_engine/pytorch/ops/basic/layer_norm.py

@@ -14,7 +14,6 @@
 
 from transformer_engine_torch import layernorm_bwd, layernorm_fwd
 from ...constants import TE_DType
-from ...cpu_offload import is_cpu_offload_enabled, mark_activation_offload
 from ...export import is_in_onnx_export_mode
 from ...tensor import Quantizer
 from ...utils import (
@@ -216,8 +215,7 @@ def op_forward(
 
         # Save state for backward pass
         if ctx.requires_grad:
-            if is_cpu_offload_enabled():
-                mark_activation_offload(x, means, rstdevs)
+            self.mark_for_cpu_offload_if_needed(x, means, rstdevs)
             ctx.save_for_backward(x, means, rstdevs)
             ctx.dtype = dtype
 

transformer_engine/pytorch/ops/basic/rmsnorm.py

@@ -14,7 +14,6 @@
 
 from transformer_engine_torch import rmsnorm_bwd, rmsnorm_fwd
 from ...constants import TE_DType
-from ...cpu_offload import is_cpu_offload_enabled, mark_activation_offload
 from ...export import is_in_onnx_export_mode
 from ...tensor import Quantizer
 from ...utils import (
@@ -197,8 +196,7 @@ def op_forward(
 
         # Save state for backward pass
         if ctx.requires_grad:
-            if is_cpu_offload_enabled():
-                mark_activation_offload(x, rstdevs)
+            self.mark_for_cpu_offload_if_needed(x, rstdevs)
             ctx.save_for_backward(x, rstdevs)
             ctx.dtype = dtype
 

transformer_engine/pytorch/ops/basic/swiglu.py

@@ -12,7 +12,6 @@
 
 import transformer_engine_torch as tex
 from ...constants import DType
-from ...cpu_offload import is_cpu_offload_enabled, mark_activation_offload
 from ...tensor import Float8CurrentScalingQuantizer, Quantizer
 from ...utils import clear_tensor_data
 from ..op import BasicOperation, OperationContext
@@ -127,8 +126,7 @@ def op_forward(
 
         # Save state for backward pass
         if ctx.requires_grad:
-            if is_cpu_offload_enabled():
-                mark_activation_offload(input_)
+            self.mark_for_cpu_offload_if_needed(input_)
             ctx.save_for_backward(input_)
             ctx.dtype = dtype
             ctx.prev_op_grad_output_quantizer = prev_op_grad_output_quantizer
@@ -311,8 +309,7 @@ def op_forward(
 
         # Save state for backward pass
         if ctx.requires_grad:
-            if is_cpu_offload_enabled():
-                mark_activation_offload(x)
+            self.mark_for_cpu_offload_if_needed(x)
             ctx.save_for_backward(x)
             ctx.dtype = dtype
             ctx.prev_op_grad_output_quantizer = prev_op_grad_output_quantizer
@@ -462,8 +459,7 @@ def fuser_forward(
         # Save state for backward pass
         ctx = basic_op_ctxs[0]
         if ctx.requires_grad:
-            if is_cpu_offload_enabled():
-                mark_activation_offload(input_)
+            self.mark_for_cpu_offload_if_needed(input_)
             ctx.input_requires_grad = True
             ctx.extra_input_requires_grad = extra_input.requires_grad
             ctx.dtype = dtype

transformer_engine/pytorch/ops/fused/forward_grouped_mlp.py

@@ -13,7 +13,7 @@
 import torch
 
 import transformer_engine_torch as tex
-from ...cpu_offload import is_cpu_offload_enabled, mark_activation_offload, start_offload
+from ...cpu_offload import is_cpu_offload_enabled, start_offload
 from ...cpp_extensions import general_gemm, general_grouped_gemm_for_grouped_tensor
 from ...quantization import Recipe
 from ...tensor import NVFP4Quantizer, NVFP4Tensor, Quantizer
@@ -170,7 +170,7 @@ def fuser_forward(
         basic_op_kwargs: list[dict[str, Any]],
     ) -> tuple[torch.Tensor, Iterable[Iterable[torch.Tensor]]]:
         # Get basic operations
-        fc1_op, _, fc2_op = self.basic_ops
+        fc1_op, activation_op, fc2_op = self.basic_ops
         fc1_ctx, activation_ctx, fc2_ctx = basic_op_ctxs
 
         # Tensor properties
@@ -726,7 +726,6 @@ def fuser_forward(
         # Save state for backward pass
         if requires_grad:
             mark_grouped_tensor(grouped_fc1_x, activation_in, scales, grouped_fc2_x)
-            activation_op = self.basic_ops[1]
             cpu_offloading = is_cpu_offload_enabled()
             activation_is_srelu = isinstance(activation_op, ScaledSReLU)
             activation_recompute_in_mlp = bool(
@@ -754,7 +753,9 @@ def fuser_forward(
                     t for t in (grouped_fc1_x, activation_in, saved_grouped_fc2_x) if t is not None
                 ]
                 start_offload(*activation_tensors)
-                mark_activation_offload(*activation_tensors)
+                fc1_op.mark_for_cpu_offload_if_needed(grouped_fc1_x)
+                activation_op.mark_for_cpu_offload_if_needed(activation_in)
+                fc2_op.mark_for_cpu_offload_if_needed(saved_grouped_fc2_x)
 
             # FC1 saved-tensor layout.
             #   [split_sizes, base_split_offsets, split_points,