fix(train): raise on invalid constructor hyperparameters (#6306)

* fix(train): apply constructor hyperparameters in fine-tuning trainers

Passing hyperparameters={...} when constructing a fine-tuning trainer
(SFT, DPO, RLVR, RLAIF, MultiTurnRL) was silently ignored: BaseTrainer
stored the dict, but each trainer then unconditionally replaced
self.hyperparameters with a fresh FineTuningOptions built from the
model's Hub spec, discarding the user's values. The only way to set
values was post-construction via trainer.hyperparameters.<name> = value.

Capture the constructor-supplied hyperparameters in BaseTrainer and add a
shared _apply_user_hyperparameters helper that re-applies them onto the
rebuilt FineTuningOptions through its validating __setattr__. Each
fine-tuning trainer calls it after building options, so a dict passed at
construction is honored and validated against the model spec. Invalid
option names or out-of-spec values raise (consistent with the direct
attribute-assignment path) instead of being dropped.

Add unit tests for the helper (valid apply, invalid name, out-of-spec
value, empty/None no-op, non-FineTuningOptions no-op) and end-to-end
SFTTrainer tests covering the construction path.

* fix(train): only apply overridable constructor hyperparameters, warn on rest

Refine _apply_user_hyperparameters to apply a constructor-supplied
hyperparameter only when its name is overridable for the model (present
in the FineTuningOptions _specs). Non-overridable names are ignored
rather than raising, and a single warning lists them so the user knows
those values will not take effect. Overridable names are still applied
through __setattr__, so an out-of-spec value for an overridable name
still raises.

Update tests: a non-overridable name is now skipped with a warning
(instead of raising); out-of-spec value for an overridable name still
raises.

* fix(train): raise on invalid constructor hyperparameters

Change _apply_user_hyperparameters to route every constructor-supplied
hyperparameter through FineTuningOptions.__setattr__ instead of skipping
names that are not in the recipe spec. A dict passed at construction now
behaves exactly like the trainer.hyperparameters.<name> = value path:

- an unknown option name raises AttributeError
- an out-of-spec or off-enum value raises ValueError

Previously non-overridable names were ignored with a warning, which is
inconsistent with the direct-assignment path and can still let a job run
on a configuration the caller believed they set. Raising surfaces the
mistake immediately.

Update the helper and end-to-end SFT tests to assert the raise behavior.

* test(train): add constructor-hyperparameter wiring tests for DPO/RLVR/RLAIF

Each fine-tuning trainer calls _apply_user_hyperparameters at its own
call-site, so add a focused end-to-end test per trainer asserting a
constructor-supplied hyperparameter is applied onto the resolved
FineTuningOptions (value set + tracked in _user_set). This guards each
trainer's wiring against regressions; the apply/raise logic itself
remains covered centrally in test_apply_user_hyperparameters.py.

---------

Co-authored-by: Roja Reddy Sareddy <rsareddy@amazon.com>

Author: rsareddy0329

sagemaker-train/src/sagemaker/train/base_trainer.py

@@ -176,41 +176,35 @@ def _apply_user_hyperparameters(self, user_hyperparameters: Optional[Dict[str, A
         """Apply constructor-supplied hyperparameters onto the resolved FineTuningOptions.
 
         The fine-tuning trainers replace ``self.hyperparameters`` with a
-        ``FineTuningOptions`` built from the model's Hub spec, which would otherwise
-        discard any ``hyperparameters`` dict passed at construction. This re-applies
-        those user-provided values, but only for names that are overridable for the
-        model (i.e. present in the options' ``_specs``). Each applied value goes through
-        ``FineTuningOptions.__setattr__``, so it is still validated against the spec and
-        an out-of-spec value for an overridable name raises, exactly as
-        ``trainer.hyperparameters.<name> = value`` would.
+        ``FineTuningOptions`` built from the model's recipe override-params spec, which
+        would otherwise discard any ``hyperparameters`` dict passed at construction. This
+        re-applies those user-provided values by routing each one through
+        ``FineTuningOptions.__setattr__``, so a dict passed at construction behaves
+        exactly like the ``trainer.hyperparameters.<name> = value`` path and is validated
+        against the recipe spec:
 
-        Names that are not overridable are ignored (not applied), and a single warning
-        lists them so the user knows those values will not take effect.
+        * an unknown option name raises ``AttributeError``;
+        * an out-of-spec or off-enum value for a known name raises ``ValueError``.
+
+        Values are never silently dropped in favor of the recipe default, which would
+        otherwise launch a billable job on a configuration the caller did not set.
 
         No-op when nothing was supplied or when ``self.hyperparameters`` is not a
-        spec-backed ``FineTuningOptions`` (e.g. a plain dict).
+        spec-backed ``FineTuningOptions`` (e.g. ``ModelTrainer``'s plain dict).
 
         Args:
             user_hyperparameters: The hyperparameters dict captured from construction.
+
+        Raises:
+            AttributeError: If a supplied name is not a valid option for the recipe.
+            ValueError: If a supplied value fails the recipe spec (type/range/enum).
         """
         if not user_hyperparameters:
             return
-        specs = getattr(getattr(self, "hyperparameters", None), "_specs", None)
-        if not isinstance(specs, dict):
+        if not isinstance(getattr(getattr(self, "hyperparameters", None), "_specs", None), dict):
             return
-        ignored = []
         for name, value in user_hyperparameters.items():
-            if name not in specs:
-                ignored.append(name)
-                continue
             setattr(self.hyperparameters, name, value)
-        if ignored:
-            logger.warning(
-                "Ignoring hyperparameters that are not overridable for this model: %s. "
-                "These values will not take effect. Overridable hyperparameters: %s",
-                ignored,
-                list(specs.keys()),
-            )
 
     def _is_nova_model_for_telemetry(self) -> bool:
         """Check if the model is a Nova model for telemetry tracking."""

sagemaker-train/tests/unit/train/test_apply_user_hyperparameters.py

@@ -41,18 +41,12 @@ def test_applies_valid_values_and_marks_user_set():
     assert trainer.hyperparameters._user_set == {"learning_rate", "epochs"}
 
 
-def test_invalid_option_name_is_ignored_with_warning(caplog):
+def test_invalid_option_name_raises():
     options = _make_options()
-    with caplog.at_level("WARNING"):
-        trainer = _apply(options, {"not_a_real_option": 1, "learning_rate": 0.001})
-
-    # The overridable value is applied; the non-overridable one is skipped.
-    assert trainer.hyperparameters.learning_rate == 0.001
-    assert not hasattr(trainer.hyperparameters, "not_a_real_option")
-    assert trainer.hyperparameters._user_set == {"learning_rate"}
-    # A warning names the ignored, non-overridable hyperparameter.
-    assert "not_a_real_option" in caplog.text
-    assert "not overridable" in caplog.text.lower()
+    # An unknown option name raises (consistent with trainer.hyperparameters.x = v),
+    # rather than being silently ignored.
+    with pytest.raises(AttributeError):
+        _apply(options, {"not_a_real_option": 1})
 
 
 def test_out_of_spec_value_raises():

sagemaker-train/tests/unit/train/test_dpo_trainer.py

@@ -24,6 +24,24 @@ def test_init_with_defaults(self, mock_finetuning_options, mock_validate_group,
         assert trainer.training_type == TrainingType.LORA
         assert trainer.model == "test-model"
 
+    @patch('sagemaker.train.dpo_trainer._validate_and_resolve_model_package_group')
+    @patch('sagemaker.train.dpo_trainer._get_fine_tuning_options_and_model_arn')
+    def test_init_applies_constructor_hyperparameters(self, mock_finetuning_options, mock_validate_group, mock_session):
+        """Constructor hyperparameters are applied onto the resolved FineTuningOptions (wiring guard)."""
+        from sagemaker.train.common import FineTuningOptions
+        mock_validate_group.return_value = "test-group"
+        options = FineTuningOptions(
+            {"learning_rate": {"type": "float", "default": 0.0001, "min": 0.0, "max": 1.0}}
+        )
+        mock_finetuning_options.return_value = (options, "model-arn", False)
+        trainer = DPOTrainer(
+            model="test-model",
+            model_package_group="test-group",
+            hyperparameters={"learning_rate": 0.001},
+        )
+        assert trainer.hyperparameters.learning_rate == 0.001
+        assert "learning_rate" in trainer.hyperparameters._user_set
+
     @patch('sagemaker.train.dpo_trainer._validate_and_resolve_model_package_group')
     @patch('sagemaker.train.dpo_trainer._get_fine_tuning_options_and_model_arn')
     def test_init_with_full_training_type(self, mock_finetuning_options, mock_validate_group, mock_session):

sagemaker-train/tests/unit/train/test_rlaif_trainer.py

@@ -24,6 +24,24 @@ def test_init_with_defaults(self, mock_finetuning_options, mock_validate_group,
         assert trainer.training_type == TrainingType.LORA
         assert trainer.model == "test-model"
 
+    @patch('sagemaker.train.rlaif_trainer._validate_and_resolve_model_package_group')
+    @patch('sagemaker.train.rlaif_trainer._get_fine_tuning_options_and_model_arn')
+    def test_init_applies_constructor_hyperparameters(self, mock_finetuning_options, mock_validate_group, mock_session):
+        """Constructor hyperparameters are applied onto the resolved FineTuningOptions (wiring guard)."""
+        from sagemaker.train.common import FineTuningOptions
+        mock_validate_group.return_value = "test-group"
+        options = FineTuningOptions(
+            {"learning_rate": {"type": "float", "default": 0.0001, "min": 0.0, "max": 1.0}}
+        )
+        mock_finetuning_options.return_value = (options, "model-arn", False)
+        trainer = RLAIFTrainer(
+            model="test-model",
+            model_package_group="test-group",
+            hyperparameters={"learning_rate": 0.001},
+        )
+        assert trainer.hyperparameters.learning_rate == 0.001
+        assert "learning_rate" in trainer.hyperparameters._user_set
+
     @patch('sagemaker.train.rlaif_trainer._validate_and_resolve_model_package_group')
     @patch('sagemaker.train.rlaif_trainer._get_fine_tuning_options_and_model_arn')
     def test_init_with_full_training_type(self, mock_finetuning_options, mock_validate_group, mock_session):

sagemaker-train/tests/unit/train/test_rlvr_trainer.py

@@ -24,6 +24,24 @@ def test_init_with_defaults(self, mock_finetuning_options, mock_validate_group,
         assert trainer.training_type == TrainingType.LORA
         assert trainer.model == "test-model"
 
+    @patch('sagemaker.train.rlvr_trainer._validate_and_resolve_model_package_group')
+    @patch('sagemaker.train.rlvr_trainer._get_fine_tuning_options_and_model_arn')
+    def test_init_applies_constructor_hyperparameters(self, mock_finetuning_options, mock_validate_group, mock_session):
+        """Constructor hyperparameters are applied onto the resolved FineTuningOptions (wiring guard)."""
+        from sagemaker.train.common import FineTuningOptions
+        mock_validate_group.return_value = "test-group"
+        options = FineTuningOptions(
+            {"learning_rate": {"type": "float", "default": 0.0001, "min": 0.0, "max": 1.0}}
+        )
+        mock_finetuning_options.return_value = (options, "model-arn", False)
+        trainer = RLVRTrainer(
+            model="test-model",
+            model_package_group="test-group",
+            hyperparameters={"learning_rate": 0.001},
+        )
+        assert trainer.hyperparameters.learning_rate == 0.001
+        assert "learning_rate" in trainer.hyperparameters._user_set
+
     @patch('sagemaker.train.rlvr_trainer._validate_and_resolve_model_package_group')
     @patch('sagemaker.train.rlvr_trainer._get_fine_tuning_options_and_model_arn')
     def test_init_with_full_training_type(self, mock_finetuning_options, mock_validate_group, mock_session):

sagemaker-train/tests/unit/train/test_sft_trainer.py

@@ -47,24 +47,21 @@ def test_init_applies_constructor_hyperparameters(self, mock_finetuning_options,
 
     @patch('sagemaker.train.sft_trainer._validate_and_resolve_model_package_group')
     @patch('sagemaker.train.sft_trainer._get_fine_tuning_options_and_model_arn')
-    def test_init_ignores_non_overridable_constructor_hyperparameter(self, mock_finetuning_options, mock_validate_group, mock_session):
-        """A non-overridable constructor hyperparameter is ignored (not applied, no raise)."""
+    def test_init_invalid_constructor_hyperparameter_raises(self, mock_finetuning_options, mock_validate_group, mock_session):
+        """A non-overridable constructor hyperparameter raises rather than being dropped."""
         from sagemaker.train.common import FineTuningOptions
         mock_validate_group.return_value = "test-group"
         options = FineTuningOptions(
             {"learning_rate": {"type": "float", "default": 0.0001, "min": 0.0, "max": 1.0}}
         )
         mock_finetuning_options.return_value = (options, "model-arn", False)
 
-        trainer = SFTTrainer(
-            model="test-model",
-            model_package_group="test-group",
-            hyperparameters={"learning_rate": 0.001, "not_a_real_option": 1},
-        )
-
-        # Overridable value applied; non-overridable one ignored rather than raising.
-        assert trainer.hyperparameters.learning_rate == 0.001
-        assert not hasattr(trainer.hyperparameters, "not_a_real_option")
+        with pytest.raises(AttributeError):
+            SFTTrainer(
+                model="test-model",
+                model_package_group="test-group",
+                hyperparameters={"learning_rate": 0.001, "not_a_real_option": 1},
+            )
 
     @patch('sagemaker.train.sft_trainer._validate_and_resolve_model_package_group')
     @patch('sagemaker.train.sft_trainer._get_fine_tuning_options_and_model_arn')