feat: support muon optimizer in PaddleFormers trainer

- Update trainer.py to integrate Muon optimizer support
- Update trainer_utils.py with Muon-related utilities

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: xxyux

paddleformers/trainer/trainer.py

@@ -1991,7 +1991,8 @@ def _inner_training_loop(
                         steps_trained_progress_bar.update(1)
                     if steps_trained_in_current_epoch == 0:
                         self._load_rng_state(resume_from_checkpoint)
-                    self.timers and self.timers("read-data").start()
+                    if self.args.ignore_data_skip:
+                        self.timers and self.timers("read-data").start()
                     # Reset data loading timer for skipped steps
                     _data_load_start_time = time.time()
                     continue
@@ -2912,6 +2913,15 @@ def apply_decay_param_fun(x):
             if hasattr(optimizer_cls, "_create_master_weight") and self.args.fp16_opt_level == "O2":
                 optimizer_kwargs["multi_precision"] = True
 
+            if self.args.optim.value == "muon":
+                # Attach per-head metadata to fused QKV weights so the Muon
+                # optimizer can orthogonalise each head independently.
+                for name, param in self.model.named_parameters():
+                    if "qkv_proj.weight" in name and len(param.shape) == 2:
+                        param.needs_qkv_split = True
+                        param.head_num = self.model.config.num_attention_heads
+                        param.kv_head_num = self.model.config.num_key_value_heads
+
             self.optimizer = optimizer_cls(
                 learning_rate=self.lr_scheduler if lr_scheduler is None else lr_scheduler,
                 apply_decay_param_fun=apply_decay_param_fun,
@@ -3052,6 +3062,18 @@ def get_optimizer_cls_and_kwargs(args: TrainingArguments) -> Tuple[Any, Any]:
 
             optimizer_cls = AdamWCustom
             optimizer_kwargs.update(adam_kwargs)
+        elif args.optim == OptimizerNames.MUON:
+            from paddle.optimizer import Muon
+
+            logger.info("Creating Muon optimizer")
+            muon_kwargs = {
+                **adam_kwargs,
+                "momentum": 0.95,
+                "muon_version": 3,
+                "is_split_qkv": True,
+            }
+            optimizer_cls = Muon
+            optimizer_kwargs.update(muon_kwargs)
         else:
             raise ValueError(f"Trainer cannot instantiate unsupported optimizer: {args.optim}")
 

paddleformers/trainer/trainer_utils.py

@@ -498,6 +498,7 @@ class OptimizerNames(ExplicitEnum):
     ADAFACTOR = "adafactor"
     ADAMW_MINI = "adamw_mini"
     ADAMW_CUSTOM = "adamw_custom"
+    MUON = "muon"
 
 
 class ShardingOption(ExplicitEnum):
@@ -1502,6 +1503,12 @@ def init_optimizer(optimizer, model_sharded_state_dict, state_dict_metadata):
         return
 
     elif DygraphShardingOptimizerV2 is not None and isinstance(inner_opt, DygraphShardingOptimizerV2):
+        # Unwrap to the innermost optimizer (e.g. Muon inside a sharding wrapper).
+        core_opt = optimizer._inner_opt
+        while hasattr(core_opt, "_inner_opt"):
+            core_opt = core_opt._inner_opt
+        is_muon_opt = type(core_opt).__name__ == "Muon"
+
         parameter_list = []
         for buffer in optimizer._comm_buffer_list:
             for param_name, grad_view in buffer._sharding_param_grad_view.items():
@@ -1515,6 +1522,9 @@ def init_optimizer(optimizer, model_sharded_state_dict, state_dict_metadata):
                     slice_param = paddle.slice(param_buffer, axes=[0], starts=[param_begin], ends=[param_end])
                     assert slice_param.numel().item() > 0
                     slice_param.name = param_name
+                    # Preserve original shape so Muon's should_use_muon() can identify 2-D weights.
+                    if is_muon_opt and hasattr(grad_view, "_param") and grad_view._param is not None:
+                        slice_param.original_shape = grad_view._param.shape
                     parameter_list.append(slice_param)
 
         optimizer._create_accumulators(paddle.base.framework.default_main_program().global_block(), parameter_list)