Bridge instantiate_utils: drop unexpected config keys with warning

[yaoyu-33]

Risks of Using Lenient Mode for Config Handling**

Using lenient mode when loading configs (instead of strict) can avoid errors when config fields are missing or changed, but it introduces several concerns:

✅ Pros

• Prevents errors when config keys are missing or removed across versions.
• Makes backward compatibility easier initially.

⚠️ Risks / Potential Issues

1. Hidden Config Mismatches

   • Missing or outdated config fields won’t throw errors, so silent differences may go unnoticed.
   • This can lead to unexpected behaviors and makes debugging harder.

2. Reproducibility Concerns

   • With lenient mode, there are no guarantees that runs are reproducible across PyTorch/TE/MCore versions.
   • Config drift over time becomes hard to track.

3. Version Guarding Becomes MCore’s Problem

   • If configs are dropped or renamed, a lenient approach pushes the burden to MCore side to guard changes properly.

4. Technical Debt Over Time

   • Without strict checking, config schema changes accumulate “silent failures”.
   • Eventually, migrations or retroactive fixes become harder.

• Introduces defensive handling in megatron.bridge.utils.instantiate_utils.instantiate_node to gracefully ignore unexpected config keys when instantiating targets.

• Emits a logging.WARNING identifying dropped keys and the config full_key to aid debugging.

• Adds unit tests verifying both the drop-and-warn behavior and that targets accepting **kwargs are unaffected.

• Why

  • Backward compatibility with older checkpoints/config YAMLs that may contain stale fields (e.g., use_megatron_fsdp) caused failures like:
    • TypeError("OptimizerConfig.init() got an unexpected keyword argument 'use_megatron_fsdp'")
  • We prefer a non-fatal path with clear warnings rather than hard failures during resume/migration.

• What changed

  • instantiate_utils.py
    • New _filter_kwargs_for_target(target, kwargs, full_key):
      • Uses inspect.signature to determine accepted keyword parameters.
      • If the target has **kwargs, forwards all keys unchanged.
      • Otherwise, drops keys not present in keyword-capable params and logs a warning including the dropped key list and full_key.
    • Integrated the filter just before calling the resolved _target_.
  • Tests
    • tests/unit_tests/bridge/test_instantiate_utils.py:
      • test_drops_unexpected_kwargs_and_warns: ensures unexpected keys are removed and a warning mentioning them is emitted.
      • test_allows_kwargs_when_target_accepts_var_kwargs: ensures no warning is produced and keys are preserved when the target accepts **kwargs.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[ananthsub]

this avoids erroring out when fields are removed from the config. but in the case of changes like this, the semantics are lost: NVIDIA/Megatron-LM#1917

for example:

• a user previously used set external_cuda_graph=True and the config did not yet have cuda_graph_scope and has checkpoints saved with this config
• in a newer version where external_cuda_graph is removed, this PR will drop the arg in lenient mode.

it might not always be possible to infer the new setting from an old one so this might be inevitable, but we should make no claims about full reproducibility across versions in this case

[ananthsub]

move this into the existing test file: https://github.com/NVIDIA-NeMo/Megatron-Bridge/blob/main/tests/unit_tests/utils/test_instantiate_utils.py

[ananthsub]

this file can be removed now

[yaoyu-33]

/ok to test 70be68d

[yaoyu-33]

/ok to test d96f333

[yaoyu-33]

/ok to test 6d92b19

[yaoyu-33]

/ok to test dc5e056