fix(gemma): resolve Gemma 3 defaults a sparse config omits, and qualify gemma-3-12b (1362)

## Implementation

Extends `_GEMMA3_CONFIG_DEFAULTS` with `rope_theta`, `rope_local_base_freq`,
`sliding_window_pattern` and `query_pre_attn_scalar`, taken from `Gemma3TextConfig`'s own
`rope_parameters` rather than from the fields that happened to fail before. The three that
`graph_blocks` reads back through `_gemma_raw` are written into `config.raw`, so a nested
`text_config` still wins.

`gemma3_attention_schedule` now raises for a Gemma 3 `model_type` that arrives without both
`sliding_window` and `rope_local_base_freq`, instead of falling back to all-global. Gemma and
Gemma 2 keep the existing fallback.

Author: zhenshanx-nv

apps/benchmark/performance/release.yaml

@@ -90,6 +90,8 @@ excluded_profiles:
       gemma-2-2b, which exercises the same builder and runtime path.
   - model: gemma-3-270m
     reason: *gemma3_performance_exclusion
+  - model: gemma-3-12b
+    reason: *gemma3_performance_exclusion
   - model: gemma-3-1b
     reason: >-
       Functional and Hugging Face reference-parity qualification is present,

families/gemma/graph_blocks.py

@@ -374,6 +374,7 @@ def _gemma_raw(config) -> dict:
     return raw
 
 
+_GEMMA3_MODEL_TYPES = frozenset({"gemma3", "gemma3_text"})
 _GEMMA3_SLIDING_PATTERN = 6
 
 
@@ -395,6 +396,20 @@ def gemma3_attention_schedule(config, num_layers: int) -> dict:
     # A second rope base is what distinguishes Gemma 3 from Gemma 2 here.
     # Gemma 2 also interleaves windows but rotates every layer on one base, so
     # without this key the caller must keep building a single-base graph.
+    #
+    # For Gemma 3 that fallback is never right: it silently rebuilds all layers
+    # as global attention on one base, which builds cleanly and generates
+    # fluent, wrong text. google/gemma-3-12b-it states neither key and relies on
+    # the transformers defaults, so refuse rather than guess - the model layer
+    # is responsible for filling these in before the graph is built.
+    if str(getattr(config, "model_type", "")).lower() in _GEMMA3_MODEL_TYPES and not (
+        window and local_base
+    ):
+        raise ValueError(
+            "Gemma 3 needs both sliding_window and rope_local_base_freq to place "
+            f"local attention; got sliding_window={window!r} "
+            f"rope_local_base_freq={local_base!r}"
+        )
     if not window or not local_base:
         return {
             "is_local": [False] * num_layers,

families/gemma/model.py

@@ -57,13 +57,32 @@ def _decoder_prefix(readers) -> str:
 # mirror of the same weights states both, which is why local runs passed and
 # internal CI did not. rms_norm_eps is listed because this family would
 # otherwise fall back to 1e-5 where Gemma 3 uses 1e-6 - wrong, and silently so.
+# What Gemma3TextConfig fills in when the checkpoint stays silent. Google's own
+# configs state geometry and nothing else, so every value here is load-bearing;
+# the mirrors that write them out explicitly are why this went unnoticed.
+#
+# `rope_theta` and `rope_local_base_freq` come from that class's rope_parameters:
+#   sliding_attention -> {"rope_type": "default", "rope_theta": 10000.0}
+#   full_attention    -> {"rope_type": "linear",  "rope_theta": 1000000.0}
 _GEMMA3_CONFIG_DEFAULTS = {
     "hidden_activation": "gelu_pytorch_tanh",
     "rms_norm_eps": 1e-6,
     "max_position_embeddings": 131072,
     "head_dim": 256,
+    "query_pre_attn_scalar": 256,
+    "rope_theta": 1000000.0,
+    "rope_local_base_freq": 10000.0,
+    "sliding_window_pattern": 6,
 }
 
+# Defaults that belong in config.raw rather than on the config object, because
+# graph_blocks reads them back through _gemma_raw.
+_GEMMA3_RAW_DEFAULTS = (
+    "query_pre_attn_scalar",
+    "rope_local_base_freq",
+    "sliding_window_pattern",
+)
+
 
 def _apply_gemma3_config_defaults(config: ModelConfig, readers, model_prefix: str) -> None:
     """Fill in what a Gemma 3 config may legitimately omit.
@@ -81,6 +100,17 @@ def _apply_gemma3_config_defaults(config: ModelConfig, readers, model_prefix: st
         config.rms_norm_eps = _GEMMA3_CONFIG_DEFAULTS["rms_norm_eps"]
     if raw.get("max_position_embeddings") is None:
         config.max_position_embeddings = _GEMMA3_CONFIG_DEFAULTS["max_position_embeddings"]
+    if raw.get("rope_theta") is None:
+        # Gemma 3's global layers use 1e6. The parser's own fallback is 1e4,
+        # which is the *local* base, so staying silent here rebuilds every
+        # global layer on the wrong rope table.
+        config.rope_theta = _GEMMA3_CONFIG_DEFAULTS["rope_theta"]
+    for key in _GEMMA3_RAW_DEFAULTS:
+        # Written into raw, not onto the config: gemma3_attention_schedule and
+        # gemma_attention_scale read these back through _gemma_raw. A nested
+        # text_config still wins, because _gemma_raw overlays it last.
+        if raw.get(key) is None:
+            config.raw[key] = _GEMMA3_CONFIG_DEFAULTS[key]
     if raw.get("head_dim") is None:
         # head_dim is a derived property; _head_dim is the stated override it
         # reads first. Without it the property falls back to

families/gemma/tests/manifests/gemma-3-12b.json

@@ -0,0 +1,22 @@
+{
+  "name": "gemma-3-12b",
+  "hf_id": "google/gemma-3-12b-it",
+  "bundle": "gemma-3-12b.bundle",
+  "family": "gemma",
+  "task": "text_generation",
+  "precision": "bf16",
+  "trust_remote_code": false,
+  "testcases": [
+    {
+      "name": "gemma-3-12b",
+      "premerge": true,
+      "reference_precision": "fp32",
+      "prompt": "What is the capital of France? Answer with just the name.",
+      "max_new_tokens": 8,
+      "use_chat_template": true,
+      "enable_thinking": false
+    }
+  ],
+  "max_sequence_length": 256,
+  "tensor_parallel_size": 1
+}

families/gemma/tests/test_gemma3_schedule.py

@@ -81,12 +81,24 @@ def test_a_checkpoint_without_a_second_rope_base_stays_global() -> None:
 
     It declares sliding_window but no rope_local_base_freq, so no second rope
     table may be built for it.
+
+    This case previously passed a `gemma3_text` config, which made it assert
+    that a Gemma 3 checkpoint missing its local rope base quietly becomes an
+    all-global model. That is the shape of google/gemma-3-12b-it, and the
+    resulting engine built cleanly and generated fluent, wrong text. The
+    model_type below is the one the docstring always described.
     """
-    schedule = gemma3_attention_schedule(_config(sliding_window=4096), 26)
+    schedule = gemma3_attention_schedule(_config(model_type="gemma2", sliding_window=4096), 26)
     assert schedule["is_local"] == [False] * 26
     assert schedule["window"] is None
 
 
+def test_gemma3_without_a_second_rope_base_is_refused() -> None:
+    """The same inputs under a Gemma 3 model_type must not be guessed at."""
+    with pytest.raises(ValueError, match="rope_local_base_freq"):
+        gemma3_attention_schedule(_config(sliding_window=4096), 26)
+
+
 def test_an_absent_pattern_falls_back_to_the_gemma3_default() -> None:
     """google/gemma-3-270m-it omits sliding_window_pattern.
 

families/gemma/tests/test_gemma3_sparse_config.py

@@ -0,0 +1,136 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Gemma 3 checkpoints that state only geometry must still build correctly.
+
+google/gemma-3-12b-it names hidden_size, the layer and head counts,
+intermediate_size, sliding_window and rope_scaling, and nothing else; every
+other value comes from Gemma3TextConfig. Mirrors write the full set out, which
+is why a build against a mirror can pass while the same build against the
+official checkpoint silently produces a different model.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from families.gemma import graph_blocks
+from families.gemma.model import _GEMMA3_CONFIG_DEFAULTS, _apply_gemma3_config_defaults
+
+
+class _Config:
+    """Minimal stand-in for the parsed config, matching the sparse official shape."""
+
+    def __init__(self, **raw):
+        self.model_type = raw.pop("model_type", "gemma3")
+        self.hidden_size = raw.get("hidden_size", 3840)
+        self.num_hidden_layers = raw.get("num_hidden_layers", 48)
+        self.num_attention_heads = raw.get("num_attention_heads", 16)
+        self.num_key_value_heads = raw.get("num_key_value_heads", 8)
+        # The parser's own fallback, which is the local base rather than the
+        # global one; the defaults must overwrite it.
+        self.rope_theta = 10000.0
+        self.rms_norm_eps = None
+        self.hidden_act = None
+        self.max_position_embeddings = None
+        self._head_dim = None
+        self.raw = dict(raw)
+
+    @property
+    def head_dim(self):
+        if self._head_dim:
+            return self._head_dim
+        return self.hidden_size // self.num_attention_heads
+
+
+class _Readers:
+    tensor_map: dict = {}
+
+
+def _official_12b() -> _Config:
+    return _Config(
+        hidden_size=3840,
+        intermediate_size=15360,
+        num_attention_heads=16,
+        num_hidden_layers=48,
+        num_key_value_heads=8,
+        sliding_window=1024,
+        rope_scaling={"factor": 8.0, "rope_type": "linear"},
+    )
+
+
+def test_sparse_config_resolves_the_gemma3_rope_bases():
+    config = _official_12b()
+    _apply_gemma3_config_defaults(config, _Readers(), "model")
+
+    assert config.head_dim == 256
+    assert config.rope_theta == 1000000.0, "global layers must not inherit the local base"
+    schedule = graph_blocks.gemma3_attention_schedule(config, config.num_hidden_layers)
+    assert schedule["window"] == 1024
+    assert schedule["local_theta"] == 10000.0
+
+
+def test_sparse_config_places_local_attention_five_in_six():
+    config = _official_12b()
+    _apply_gemma3_config_defaults(config, _Readers(), "model")
+    schedule = graph_blocks.gemma3_attention_schedule(config, config.num_hidden_layers)
+
+    # transformers resolves layer_types for this config to full attention at
+    # indices 5, 11, 17, 23, 29, 35, 41 and 47.
+    assert sum(schedule["is_local"]) == 40
+    assert [i for i, local in enumerate(schedule["is_local"]) if not local] == [
+        5,
+        11,
+        17,
+        23,
+        29,
+        35,
+        41,
+        47,
+    ]
+
+
+def test_gemma3_refuses_to_fall_back_to_all_global():
+    """The old behavior built cleanly and generated fluent, wrong text."""
+    config = _official_12b()
+    # Defaults deliberately not applied, so the schedule inputs are missing.
+    with pytest.raises(ValueError, match="rope_local_base_freq"):
+        graph_blocks.gemma3_attention_schedule(config, config.num_hidden_layers)
+
+
+def test_a_stated_value_still_wins_over_the_default():
+    config = _official_12b()
+    config.raw["rope_local_base_freq"] = 12345.0
+    config.raw["sliding_window_pattern"] = 4
+    _apply_gemma3_config_defaults(config, _Readers(), "model")
+    schedule = graph_blocks.gemma3_attention_schedule(config, config.num_hidden_layers)
+
+    assert schedule["local_theta"] == 12345.0
+    assert [i for i, local in enumerate(schedule["is_local"]) if not local][:3] == [3, 7, 11]
+
+
+def test_gemma2_is_untouched_by_the_gemma3_defaults():
+    config = _Config(
+        model_type="gemma2",
+        hidden_size=2304,
+        num_attention_heads=8,
+        num_hidden_layers=26,
+        sliding_window=4096,
+    )
+    _apply_gemma3_config_defaults(config, _Readers(), "model")
+
+    assert config.rope_theta == 10000.0
+    assert "rope_local_base_freq" not in config.raw
+    schedule = graph_blocks.gemma3_attention_schedule(config, config.num_hidden_layers)
+    assert not any(schedule["is_local"])
+
+
+def test_defaults_cover_every_field_the_schedule_and_scale_read():
+    for key in (
+        "rope_theta",
+        "rope_local_base_freq",
+        "sliding_window_pattern",
+        "query_pre_attn_scalar",
+        "head_dim",
+    ):
+        assert key in _GEMMA3_CONFIG_DEFAULTS