build(deps): support Transformers 5.20 (#6490)

Signed-off-by: Kamran Jafari <kjafarisadeg@nvidia.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: kamran-nvidia

docs/fern/versions/nightly/pages/models/minimax/minimax-m3.mdx

@@ -9,7 +9,7 @@ Bridge applies its full partial-3D vision RoPE correction only on Transformers
 [HF PR #49164](https://github.com/huggingface/transformers/pull/49164), so Bridge
 leaves those versions unpatched.
 
-The native 5.18/5.19 implementation stores inverse frequencies in buffers.
+The native 5.18-5.20 implementation stores inverse frequencies in buffers.
 Explicit `.half()` or `.bfloat16()` casts can round these buffers, producing
 different results from the earlier FP32-per-forward calculation. Bridge accepts
 this precision difference and does not promise bitwise equality across these

docs/fern/versions/nightly/pages/models/nemotron/nemotron3.5-super-vl.mdx

@@ -14,16 +14,16 @@ For language-only conversion and training without media components, see [the tex
 
 ## Native Hugging Face processor compatibility
 
-With Transformers 5.19.0, `AutoBridge.from_hf_pretrained(..., trust_remote_code=False)`
+With Transformers 5.18.0, 5.19.0, or 5.20.0, `AutoBridge.from_hf_pretrained(..., trust_remote_code=False)`
 uses a Bridge-local processor loading adapter for Super VL. It removes a legacy
 read-only video configuration field in memory and does not require an audio feature
 extractor for this audio-free model. The source checkpoint and installed Transformers
 code are not modified; image/video processing and token expansion use the native HF
 implementation. Remote-code loading remains available on older supported HF versions.
 
-The adapter is version-guarded to Transformers 5.19.0. Processor artifacts can be saved
+The adapter is version-guarded to Transformers 5.18.0, 5.19.0, and 5.20.0. Processor artifacts can be saved
 and reloaded through Bridge, but ordinary `AutoProcessor.from_pretrained` outside
-Bridge still encounters the native 5.19.0 audio-component requirement. This workaround
+Bridge still encounters the native 5.18.0-5.20.0 audio-component requirement. This workaround
 does not imply standalone HF processor compatibility or full model forward parity.
 The wrapper's `hf_pretrained.model` accessor selects `AutoModelForImageTextToText`
 for native Super VL and retains `AutoModelForCausalLM` for legacy remote-code

docs/models/minimax/minimax-m3.md

@@ -9,7 +9,7 @@ Bridge applies its full partial-3D vision RoPE correction only on Transformers
 [HF PR #49164](https://github.com/huggingface/transformers/pull/49164), so Bridge
 leaves those versions unpatched.
 
-The native 5.18/5.19 implementation stores inverse frequencies in buffers.
+The native 5.18-5.20 implementation stores inverse frequencies in buffers.
 Explicit `.half()` or `.bfloat16()` casts can round these buffers, producing
 different results from the earlier FP32-per-forward calculation. Bridge accepts
 this precision difference and does not promise bitwise equality across these

docs/models/nemotron/nemotron3.5-super-vl.md

@@ -14,16 +14,16 @@ For language-only conversion and training without media components, see [the tex
 
 ## Native Hugging Face processor compatibility
 
-With Transformers 5.19.0, `AutoBridge.from_hf_pretrained(..., trust_remote_code=False)`
+With Transformers 5.18.0, 5.19.0, or 5.20.0, `AutoBridge.from_hf_pretrained(..., trust_remote_code=False)`
 uses a Bridge-local processor loading adapter for Super VL. It removes a legacy
 read-only video configuration field in memory and does not require an audio feature
 extractor for this audio-free model. The source checkpoint and installed Transformers
 code are not modified; image/video processing and token expansion use the native HF
 implementation. Remote-code loading remains available on older supported HF versions.
 
-The adapter is version-guarded to Transformers 5.19.0. Processor artifacts can be saved
+The adapter is version-guarded to Transformers 5.18.0, 5.19.0, and 5.20.0. Processor artifacts can be saved
 and reloaded through Bridge, but ordinary `AutoProcessor.from_pretrained` outside
-Bridge still encounters the native 5.19.0 audio-component requirement. This workaround
+Bridge still encounters the native 5.18.0-5.20.0 audio-component requirement. This workaround
 does not imply standalone HF processor compatibility or full model forward parity.
 The wrapper's `hf_pretrained.model` accessor selects `AutoModelForImageTextToText`
 for native Super VL and retains `AutoModelForCausalLM` for legacy remote-code

pyproject.toml

@@ -71,7 +71,7 @@ classifiers = [
     "Topic :: Utilities",
 ]
 dependencies = [
-    "transformers>=5.15,<5.20",
+    "transformers>=5.15,<5.21",
     "mistral-common>=1.10.0",
     "peft>=0.20.0,<=0.21.0",
     "datasets>=2.20.0",

src/megatron/bridge/models/bailing/modeling_bailing_moe_v2.py

@@ -482,7 +482,10 @@ def __init__(self, config: BailingMoeV2Config, layer_idx: Optional[int] = None):
         self.hidden_size = config.hidden_size
         self.num_heads = config.num_attention_heads
         self.head_dim = config.head_dim or self.hidden_size // self.num_heads
-        partial_rotary_factor = config.partial_rotary_factor if hasattr(config, "partial_rotary_factor") else 1.0
+        partial_rotary_factor = getattr(config, "partial_rotary_factor", None)
+        if partial_rotary_factor is None:
+            # Transformers 5.20+ keeps partial_rotary_factor only in rope_parameters.
+            partial_rotary_factor = (getattr(config, "rope_parameters", None) or {}).get("partial_rotary_factor", 1.0)
         self.rope_dim = int(self.head_dim * partial_rotary_factor)
         self.num_key_value_heads = config.num_key_value_heads
         self.num_key_value_groups = self.num_heads // self.num_key_value_heads

src/megatron/bridge/models/conversion/model_bridge.py

@@ -80,6 +80,7 @@
 )
 from megatron.bridge.models.conversion.quant_bridge import MegatronQuantizationBridge
 from megatron.bridge.models.conversion.transformers_compat import (
+    partial_rotary_factor_from_hf,
     rope_theta_from_hf,
 )
 from megatron.bridge.models.conversion.utils import (
@@ -697,6 +698,12 @@ def _hf_config_to_megatron_kwargs(self, hf_config: PretrainedConfig) -> dict[str
             else:
                 value = getattr(hf_config, hf_name, None)
                 has_value = hasattr(hf_config, hf_name)
+                if not has_value and hf_name == "partial_rotary_factor":
+                    # Transformers 5.20+ keeps partial_rotary_factor only in rope_parameters.
+                    try:
+                        value, has_value = partial_rotary_factor_from_hf(hf_config), True
+                    except ValueError:
+                        pass
             if (
                 has_value
                 and megatron_name not in provider_kwargs

src/megatron/bridge/models/conversion/transformers_compat.py

@@ -87,6 +87,38 @@ def rope_theta_from_hf(config) -> float:
     )
 
 
+def partial_rotary_factor_from_hf(config) -> float:
+    """Extract partial_rotary_factor from a HuggingFace config.
+
+    Transformers 5.19 and earlier expose it as a ``partial_rotary_factor``
+    attribute (and also in ``rope_parameters``). Transformers 5.20+ keeps it
+    only in the flat ``rope_parameters`` dictionary.
+
+    Args:
+        config: HuggingFace configuration object.
+
+    Returns:
+        float: The fraction of each attention head dimension that gets rotary embeddings.
+
+    Raises:
+        ValueError: If partial_rotary_factor is not found in either format.
+    """
+    partial_rotary_factor = getattr(config, "partial_rotary_factor", None)
+    if partial_rotary_factor is not None:
+        return partial_rotary_factor
+
+    rope_parameters = getattr(config, "rope_parameters", None)
+    if isinstance(rope_parameters, dict):
+        partial_rotary_factor = rope_parameters.get("partial_rotary_factor")
+        if partial_rotary_factor is not None:
+            return partial_rotary_factor
+
+    raise ValueError(
+        "partial_rotary_factor not found in config. Expected either a 'partial_rotary_factor' attribute "
+        "(transformers <5.20) or 'rope_parameters[\"partial_rotary_factor\"]' (transformers >=5.20)."
+    )
+
+
 def rope_local_base_freq_from_hf(config) -> float:
     """Extract rope_local_base_freq from a HuggingFace config.
 

src/megatron/bridge/models/glm_vl/glm_45v_bridge.py

@@ -25,7 +25,7 @@
     QKVMapping,
     ReplicatedMapping,
 )
-from megatron.bridge.models.conversion.transformers_compat import rope_theta_from_hf
+from megatron.bridge.models.conversion.transformers_compat import partial_rotary_factor_from_hf, rope_theta_from_hf
 from megatron.bridge.models.glm_vl.glm_45v_provider import GLM45VModelProvider
 from megatron.bridge.models.glm_vl.modeling_glm_45v import GLM45VModel
 from megatron.bridge.models.hf_pretrained.causal_lm import PreTrainedCausalLM
@@ -51,7 +51,7 @@ def provider_bridge(self, hf_pretrained: PreTrainedCausalLM) -> GLM45VModelProvi
             kv_channels=text_config.head_dim,
             hidden_size=text_config.hidden_size,
             rotary_base=rope_theta_from_hf(text_config),
-            rotary_percent=text_config.partial_rotary_factor,
+            rotary_percent=partial_rotary_factor_from_hf(text_config),
             init_method_std=text_config.initializer_range,
             ffn_hidden_size=text_config.intermediate_size,
             seq_length=text_config.max_position_embeddings,

src/megatron/bridge/models/nemotron_omni/hf_pretrained.py

@@ -21,6 +21,12 @@
 from megatron.bridge.models.hf_pretrained.causal_lm import PreTrainedCausalLM
 
 
+# Bound the processor workaround to the releases whose loading behavior we tested.
+# Future releases use their own loader and surface errors rather than silently
+# dropping a required VLM artifact during conversion/export.
+_PROCESSOR_ADAPTER_RELEASES = ("5.18.0", "5.19.0", "5.20.0")
+
+
 class Nemotron35VLPretrained(PreTrainedCausalLM):
     """Keep native processor compatibility separate from legacy remote-code loading."""
 
@@ -38,23 +44,20 @@ def _get_auto_model_class(self) -> type:
         # uses it: native exports have no remote CausalLM registration.
         if self._uses_remote_model():
             return super()._get_auto_model_class()
-        if Version(transformers.__version__) < Version("5.19.0"):
-            raise ValueError("Native Super-VL requires Transformers >=5.19.0; use trust_remote_code=True otherwise.")
+        if Version(transformers.__version__) < Version("5.18.0"):
+            raise ValueError("Native Super-VL requires Transformers >=5.18.0; use trust_remote_code=True otherwise.")
         return AutoModelForImageTextToText
 
     def _load_processor(self) -> ProcessorMixin | None:
         if self.model_name_or_path is None or self._uses_remote_model():
             return super()._load_processor()
 
         version = Version(transformers.__version__)
-        if version < Version("5.19.0"):
-            raise ValueError("Native Super-VL requires Transformers >=5.19.0; use trust_remote_code=True otherwise.")
+        if version < Version("5.18.0"):
+            raise ValueError("Native Super-VL requires Transformers >=5.18.0; use trust_remote_code=True otherwise.")
 
         processor_cls = AutoProcessor
-        # Bound the workaround to the release whose loading behavior we tested.
-        # Future releases use their own loader and surface errors rather than
-        # silently dropping a required VLM artifact during conversion/export.
-        if version.base_version == "5.19.0" and getattr(self.config, "audio_config", None) is None:
+        if version.base_version in _PROCESSOR_ADAPTER_RELEASES and getattr(self.config, "audio_config", None) is None:
             from megatron.bridge.models.nemotron_omni.processing_super_vl import Nemotron35VLProcessor
 
             processor_cls = Nemotron35VLProcessor