keras-hub-nightly 0.20.0.dev202503260356__py3-none-any.whl → 0.20.0.dev202503270400__py3-none-any.whl

keras_hub/src/models/gemma3/gemma3_backbone.py

@@ -0,0 +1,352 @@
+import keras
+from keras import ops
+
+from keras_hub.src.api_export import keras_hub_export
+from keras_hub.src.layers.modeling.reversible_embedding import (
+    ReversibleEmbedding,
+)
+from keras_hub.src.models.backbone import Backbone
+from keras_hub.src.models.gemma.rms_normalization import RMSNormalization
+from keras_hub.src.models.gemma3.gemma3_decoder_block import Gemma3DecoderBlock
+from keras_hub.src.models.gemma3.gemma3_interleave_embeddings import (
+    Gemma3InterleaveEmbeddings,
+)
+
+
+@keras_hub_export("keras_hub.models.Gemma3Backbone")
+class Gemma3Backbone(Backbone):
+    """Gemma3 core network with hyperparameters.
+
+    This backbone implements the Gemma3 model architecture. Gemma3 is a
+    vision-language model (image-text in, text out). The text input is encoded
+    using an embedding layer; images are encoded using a vision transformer.
+    After encoding these two modalities, the image embeddings are placed in the
+    correct position in the text embedding sequence. The mixed sequence of
+    embeddings is then passed through transformer decoder layers.
+
+    Currently, this model supports only the `vision_encoder = None` case, i.e.,
+    working only with text.
+
+    For a higher-level object for text-generation, see
+    `keras_hub.models.Gemma3CausalLM`.
+
+    The default constructor gives a fully customizable, randomly initialized
+    Gemma3 model with any vision encoder, number of heads, embedding dimensions,
+    and equivalent configuration for the decoder layers. To load preset
+    architectures and weights, use the `from_preset` constructor.
+
+    Args:
+        vocabulary_size: int. The size of the token vocabulary.
+        image_size: int. The resolution of the image in both width and height.
+            The input images must be square.
+        num_layers: int. The number of transformer mixed decoder layers.
+        num_query_heads: int. The number of heads for the query projections in
+            the mixed decoder attention layer.
+        num_key_value_heads: int. The number of heads for the key and value
+            projections in the mixed decoder attention layers.
+        hidden_dim: int. The size of the transformer hidden state at the end
+            of each mixed transformer layer.
+        intermediate_dim: int. The output dimension of the first Dense layer in
+            a two-layer feedforward network for each transformer decoder block.
+        head_dim: int. The size of each attention head in the mixed decoder.
+        query_head_dim_normalize: boolean. If `True` normalize the query before
+            attention with `head_dim`. If `False`, normalize the query with
+            `hidden_dim / num_query_heads`. Defaults to `True`.
+        use_query_key_norm: bool. If `True`, apply a RMS Norm layer to query and
+            key before projecting them. Defaults to `True`.
+        use_post_ffw_norm: boolean. Whether to normalize after the feedforward
+            block. Defaults to `False`.
+        use_post_attention_norm: boolean. Whether to normalize after the
+            attention block. Defaults to `False`.
+        attention_logit_soft_cap: `None` or int. Soft cap for the attention
+            logits. Defaults to `None`.
+        final_logit_soft_cap: `None` or int. Soft cap for the final logits.
+            Defaults to `None`.
+        use_sliding_window_attention: boolean. Whether to use sliding local
+          window attention. Defaults to `False`.
+        sliding_window_size: int. Size of the sliding local window. Defaults to
+            `4096`.
+        vision_encoder: `keras.Model` or `keras.layers.Layer` instance. `call()`
+            takes in images and returns corresponding sequence of embeddings.
+        layer_norm_epsilon: float. The epsilon value user for every layer norm
+            in all transformer blocks. Defaults to `1e-6`.
+        dropout: float. Dropout probability for the Transformer decoder blocks.
+            Defaults to `0`.
+        dtype: string or `keras.mixed_precision.DTypePolicy`. The dtype to use
+            for the models computations and weights. Note that some
+            computations, such as softmax and layer normalization will always
+            be done a float32 precision regardless of dtype.
+
+    Example:
+    ```python
+    input_data = {}
+    input_data["token_ids"] = np.ones(shape=(1, 300), dtype="int32")
+    input_data["padding_mask"] = (
+        np.expand_dims(np.array([1] * 280 + [0] * (300 - 280)), axis=0)
+        .astype(bool)
+    )
+
+    # Pretrained Gemma3 decoder.
+    model = keras_hub.models.Gemma3Backbone.from_preset("gemma3_instruct_4b")
+    model(input_data)
+
+    config = {
+        'vocabulary_size': 262144,
+        'image_size': 896,
+        'num_layers': 34,
+        'num_query_heads': 8,
+        'num_key_value_heads': 4,
+        'hidden_dim': 2560,
+        'intermediate_dim': 10240,
+        'head_dim': 256,
+        'query_head_dim_normalize': True,
+        'use_post_ffw_norm': True,
+        'use_post_attention_norm': True,
+        'final_logit_soft_cap': None,
+        'attention_logit_soft_cap': None,
+        'sliding_window_size': 1024,
+        'use_sliding_window_attention': True,
+        'vision_encoder': None,
+        'layer_norm_epsilon': 1e-06,
+        dtype: "bfloat16",
+    }
+
+    model = keras_hub.models.Gemma3Backbone(**config)
+    model(input_data)
+    ```
+    """
+
+    def __init__(
+        self,
+        vocabulary_size,
+        image_size,
+        num_layers,
+        num_query_heads,
+        num_key_value_heads,
+        hidden_dim,
+        intermediate_dim,
+        head_dim,
+        query_head_dim_normalize=True,
+        use_query_key_norm=True,
+        use_post_ffw_norm=False,
+        use_post_attention_norm=False,
+        attention_logit_soft_cap=None,
+        final_logit_soft_cap=None,
+        use_sliding_window_attention=False,
+        sliding_window_size=1024,
+        vision_encoder=None,
+        layer_norm_epsilon=1e-6,
+        dropout=0,
+        dtype=None,
+        **kwargs,
+    ):
+        if vision_encoder is not None:
+            raise ValueError(
+                "Currently, only the text version of the Gemma3 model is "
+                "supported."
+            )
+
+        # === Layers ===
+        self.token_embedding = ReversibleEmbedding(
+            input_dim=vocabulary_size,
+            output_dim=hidden_dim,
+            tie_weights=True,
+            embeddings_initializer=keras.initializers.VarianceScaling(
+                scale=1.0,
+                mode="fan_in",
+                distribution="untruncated_normal",
+                seed=None,
+            ),
+            dtype=dtype,
+            logit_soft_cap=final_logit_soft_cap,
+            name="token_embedding",
+        )
+
+        self.vision_encoder = vision_encoder
+        text_only_model = True if vision_encoder is None else False
+        if not text_only_model:
+            self.interleave_embeddings = Gemma3InterleaveEmbeddings(
+                num_vision_tokens_per_image=self.vision_encoder.num_vision_tokens_per_image,
+                dtype=dtype,
+                name="interleave_embeddings",
+            )
+
+        self.transformer_layers = []
+        for i in range(num_layers):
+            # 5 local, 1 global
+            sliding_window = use_sliding_window_attention and (i % 6 < 5)
+            rope_wavelength = 10_000.0 if sliding_window else 1_000_000.0
+            rope_scaling_factor = 1.0 if sliding_window else 8.0
+            layer = Gemma3DecoderBlock(
+                hidden_dim=hidden_dim,
+                intermediate_dim=intermediate_dim,
+                head_dim=head_dim,
+                num_query_heads=num_query_heads,
+                num_key_value_heads=num_key_value_heads,
+                query_head_dim_normalize=query_head_dim_normalize,
+                use_query_key_norm=use_query_key_norm,
+                use_post_ffw_norm=use_post_ffw_norm,
+                use_post_attention_norm=use_post_attention_norm,
+                gate_dim_reduction=1,
+                logit_soft_cap=attention_logit_soft_cap,
+                use_sliding_window_attention=sliding_window,
+                sliding_window_size=sliding_window_size,
+                rope_wavelength=rope_wavelength,
+                rope_scaling_factor=rope_scaling_factor,
+                dropout=dropout,
+                dtype=dtype,
+                name=f"decoder_block_{i}",
+            )
+            self.transformer_layers.append(layer)
+        self.layer_norm = RMSNormalization(
+            epsilon=layer_norm_epsilon,
+            dtype=dtype,
+            name="final_normalization",
+        )
+
+        # === Functional Model ===
+
+        # == Model inputs ==
+        if not text_only_model:
+            image_input = keras.Input(
+                shape=(None, image_size, image_size, 3),
+                name="images",
+            )
+            vision_indices_input = keras.Input(
+                shape=(None,), dtype="int32", name="vision_indices"
+            )
+            # TODO: Consider removing `text_mask_input` and using
+            # `vision_indices_input` to infer it directly.
+            text_mask_input = keras.Input(
+                shape=(None,), dtype="int32", name="text_mask"
+            )
+
+        token_id_input = keras.Input(
+            shape=(None,), dtype="int32", name="token_ids"
+        )
+        padding_mask_input = keras.Input(
+            shape=(None,), dtype="int32", name="padding_mask"
+        )
+
+        # == Text embeddings ==
+        text_embeddings = self.token_embedding(token_id_input)
+
+        text_embeddings = text_embeddings * ops.cast(
+            ops.sqrt(hidden_dim), text_embeddings.dtype
+        )
+
+        # == Image Embeddings ==
+        if not text_only_model:
+            img_embeddings = self.vision_encoder(image_input)
+
+            ## == Interleaving text and images ==
+            # Place image embeddings in the right position in
+            # `text_embeddings`.
+            x = self.interleave_embeddings(
+                image_embeddings=img_embeddings,
+                text_embeddings=text_embeddings,
+                vision_indices=vision_indices_input,
+            )
+        else:
+            x = text_embeddings
+
+        # == Decoder layers ==
+        for transformer_layer in self.transformer_layers:
+            x = transformer_layer(
+                x,
+                padding_mask=padding_mask_input,
+                text_mask=None if text_only_model else text_mask_input,
+            )
+        sequence_output = self.layer_norm(x)
+
+        inputs = {
+            "token_ids": token_id_input,
+            "padding_mask": padding_mask_input,
+        }
+        if not text_only_model:
+            inputs.update(
+                {
+                    "images": image_input,
+                    "vision_indices": vision_indices_input,
+                    "text_mask": text_mask_input,
+                }
+            )
+
+        super().__init__(
+            inputs=inputs,
+            outputs=sequence_output,
+            dtype=dtype,
+            **kwargs,
+        )
+
+        # === Config ===
+        self.vocabulary_size = vocabulary_size
+        self.image_size = image_size
+        self.num_layers = num_layers
+        self.num_query_heads = num_query_heads
+        self.num_key_value_heads = num_key_value_heads
+        self.hidden_dim = hidden_dim
+        self.intermediate_dim = intermediate_dim
+        self.head_dim = head_dim
+        self.query_head_dim_normalize = query_head_dim_normalize
+        self.use_query_key_norm = use_query_key_norm
+        self.use_post_ffw_norm = use_post_ffw_norm
+        self.use_post_attention_norm = use_post_attention_norm
+        self.attention_logit_soft_cap = attention_logit_soft_cap
+        self.final_logit_soft_cap = final_logit_soft_cap
+        self.use_sliding_window_attention = use_sliding_window_attention
+        self.sliding_window_size = sliding_window_size
+        self.layer_norm_epsilon = layer_norm_epsilon
+        self.dropout = dropout
+
+        # Keep `num_vision_tokens_per_image` as a backbone property for easy
+        # access.
+        if not text_only_model:
+            self.num_vision_tokens_per_image = (
+                self.vision_encoder.num_vision_tokens_per_image
+            )
+        # Also, the `text_only_model`.
+        self.text_only_model = text_only_model
+
+    def get_config(self):
+        config = super().get_config()
+        config.update(
+            {
+                "vocabulary_size": self.vocabulary_size,
+                "image_size": self.image_size,
+                "num_layers": self.num_layers,
+                "num_query_heads": self.num_query_heads,
+                "num_key_value_heads": self.num_key_value_heads,
+                "hidden_dim": self.hidden_dim,
+                "intermediate_dim": self.intermediate_dim,
+                "head_dim": self.head_dim,
+                "query_head_dim_normalize": self.query_head_dim_normalize,
+                "use_query_key_norm": self.use_query_key_norm,
+                "use_post_ffw_norm": self.use_post_ffw_norm,
+                "use_post_attention_norm": self.use_post_attention_norm,
+                "attention_logit_soft_cap": self.attention_logit_soft_cap,
+                "final_logit_soft_cap": self.final_logit_soft_cap,
+                "use_sliding_window_attention": (
+                    self.use_sliding_window_attention
+                ),
+                "sliding_window_size": self.sliding_window_size,
+                "vision_encoder": None
+                if self.vision_encoder is None
+                else keras.layers.serialize(self.vision_encoder),
+                "layer_norm_epsilon": self.layer_norm_epsilon,
+                "dropout": self.dropout,
+            }
+        )
+        return config
+
+    @classmethod
+    def from_config(cls, config):
+        config.update(
+            {
+                "vision_encoder": None
+                if config["vision_encoder"] is None
+                else keras.layers.deserialize(config["vision_encoder"]),
+            }
+        )
+
+        return super().from_config(config)

keras_hub/src/models/gemma3/gemma3_causal_lm.py

@@ -0,0 +1,306 @@
+from keras import ops
+
+from keras_hub.src.api_export import keras_hub_export
+from keras_hub.src.models.causal_lm import CausalLM
+from keras_hub.src.models.gemma3.gemma3_backbone import Gemma3Backbone
+from keras_hub.src.models.gemma3.gemma3_causal_lm_preprocessor import (
+    Gemma3CausalLMPreprocessor,
+)
+from keras_hub.src.utils.tensor_utils import any_equal
+
+
+@keras_hub_export("keras_hub.models.Gemma3CausalLM")
+class Gemma3CausalLM(CausalLM):
+    """An end-to-end multi modal Gemma3 model for causal language modeling.
+
+    A causal language model (LM) predicts the next token based on previous
+    tokens. This task setup can be used to train the model unsupervised on
+    image and plain text input, or to autoregressively generate plain text
+    similar to the data used for training.
+
+    This model has a `generate()` method, which generates text based on a
+    prompt. The generation strategy used is controlled by an additional
+    `sampler` argument on `compile()`. You can recompile the model with
+    different `keras_hub.samplers` objects to control the generation. By
+    default, `"greedy"` sampling will be used.
+
+    This model can optionally be configured with a `preprocessor` layer, in
+    which case it will automatically apply preprocessing to string inputs during
+    `fit()`, `predict()`, `evaluate()` and `generate()`. This is done by default
+    when creating the model with `from_preset()`.
+
+    Args:
+        backbone: A `keras_hub.models.Gemma3Backbone` instance.
+        preprocessor: A `keras_hub.models.Gemma3CausalLMPreprocessor` or
+            `None`. If `None`, this model will not apply preprocessing, and
+            inputs should be preprocessed before calling the model.
+    """
+
+    backbone_cls = Gemma3Backbone
+    preprocessor_cls = Gemma3CausalLMPreprocessor
+
+    def __init__(
+        self,
+        preprocessor,
+        backbone,
+        **kwargs,
+    ):
+        # === Layers ===
+        self.preprocessor = preprocessor
+        self.backbone = backbone
+
+        # === Functional Model ===
+        # This must be "backbone.input" i.e. the full input structure,
+        # rather than "backbone.inputs" which is the flattened list of inputs.
+        inputs = backbone.input
+        hidden_state = backbone(inputs=inputs)
+        outputs = backbone.token_embedding(hidden_state, reverse=True)
+
+        super().__init__(
+            inputs=inputs,
+            outputs=outputs,
+            **kwargs,
+        )
+
+    def compile(
+        self,
+        optimizer="auto",
+        loss="auto",
+        *,
+        weighted_metrics="auto",
+        sampler="greedy",
+        **kwargs,
+    ):
+        super().compile(
+            optimizer=optimizer,
+            loss=loss,
+            weighted_metrics=weighted_metrics,
+            sampler=sampler,
+            **kwargs,
+        )
+
+    def call_with_cache(
+        self,
+        token_ids,
+        cache,
+        cache_update_index,
+        img_embeddings=None,
+        text_mask=None,
+        padding_mask=None,
+        vision_indices=None,
+    ):
+        """Forward pass of `Gemma3CausalLM` with cache.
+
+        `call_with_cache` adds an additional forward pass for the model for
+        autoregressive inference. Unlike calling the model directly, this method
+        allows caching previous key/value Tensors in multi-head attention layer,
+        and avoids recomputing the outputs of seen tokens.
+
+        Args:
+            token_ids: a dense int Tensor with shape `(batch_size, max_length)`.
+            cache: a dense float Tensor, the cache of key and value.
+            cache_update_index: int, or int Tensor. The index of current inputs
+                in the whole sequence.
+            img_embeddings: a dense float Tensor with shape
+                `(batch_size, image_sequence_length, hidden_dim)`.
+            padding_mask: a dense int Tensor with shape
+                `(batch_size, max_length)`.
+
+        Returns:
+            A (logits, hidden_states, cache) tuple. Where `logits` is the
+            language model logits for the input token_ids, `hidden_states` is
+            the final hidden representation of the input tokens, and `cache` is
+            the decoding cache.
+        """
+
+        text_embeddings = self.backbone.token_embedding(token_ids)
+        text_embeddings = text_embeddings * ops.cast(
+            ops.sqrt(self.backbone.hidden_dim), text_embeddings.dtype
+        )
+
+        # Interleaving logic.
+        ## == Interleaving text and images ==
+        # Place the image embeddings in the right position in `text_embeddings`.
+        if img_embeddings is not None:
+            x = self.backbone.interleave_embeddings(
+                image_embeddings=img_embeddings,
+                text_embeddings=text_embeddings,
+                vision_indices=vision_indices,
+            )
+        else:
+            x = text_embeddings
+
+        # Each decoder layer has a cache; we update them separately.
+        caches = []
+        for i, transformer_layer in enumerate(self.backbone.transformer_layers):
+            current_cache = cache[:, i, ...]
+            x, next_cache = transformer_layer(
+                x,
+                cache=current_cache,
+                cache_update_index=cache_update_index,
+                padding_mask=padding_mask,
+                text_mask=text_mask,
+            )
+            caches.append(next_cache)
+        cache = ops.stack(caches, axis=1)
+        hidden_states = x = self.backbone.layer_norm(x)
+        logits = self.backbone.token_embedding(x, reverse=True)
+        return logits, hidden_states, cache
+
+    def _build_cache(
+        self,
+        token_ids,
+        img_embeddings,
+        text_mask,
+        padding_mask,
+        vision_indices,
+    ):
+        """Build an empty cache for use with `call_with_cache()`."""
+        batch_size = ops.shape(token_ids)[0]
+        max_length = (
+            ops.shape(token_ids)[1]
+            # + self.backbone.image_sequence_length
+        )
+        num_layers = self.backbone.num_layers
+        num_heads = self.backbone.num_key_value_heads
+        head_dim = self.backbone.head_dim
+        shape = [batch_size, num_layers, 2, max_length, num_heads, head_dim]
+        cache = ops.zeros(shape, dtype=self.compute_dtype)
+        # Seed the cache.
+        logits, hidden_states, cache = self.call_with_cache(
+            token_ids=token_ids,
+            img_embeddings=img_embeddings,
+            text_mask=text_mask,
+            cache=cache,
+            cache_update_index=0,
+            padding_mask=padding_mask,
+            vision_indices=vision_indices,
+        )
+        return hidden_states, cache
+
+    def generate_step(self, inputs, stop_token_ids=[106]):
+        """A compilable generation function for a single batch of inputs.
+
+        This function represents the inner, XLA-compilable, generation function
+        for a single batch of inputs. Inputs should have the same structure as
+        model inputs, a dictionary with keys `"token_ids"` and `"padding_mask"`.
+
+        Args:
+            inputs: A dictionary with two keys `"token_ids"` and
+                `"padding_mask"` and batched tensor values.
+            stop_token_ids: Tuple of id's of end token's to stop on. If all
+                sequences have produced a new stop token, generation
+                will stop.
+        """
+
+        token_ids, padding_mask, images, text_mask, vision_indices = (
+            inputs["token_ids"],
+            inputs["padding_mask"],
+            inputs.get("images", None),
+            inputs.get("text_mask", None),
+            inputs.get("vision_indices", None),
+        )
+        if not self.backbone.text_only_model:
+            if len(ops.shape(images)) == 3:
+                # Handle an unbatched image. Unlike `token_ids` and
+                # `padding_mask` this will not automatically be upranked.
+                images = ops.expand_dims(images, axis=0)
+            img_embeddings = self.backbone.vision_encoder(images)
+        else:
+            img_embeddings = None
+            text_mask = None
+            vision_indices = None
+
+        # Create and seed cache with a single forward pass.
+        hidden_states, cache = self._build_cache(
+            token_ids,
+            img_embeddings,
+            text_mask,
+            padding_mask,
+            vision_indices,
+        )
+
+        # Compute the lengths of all user inputted tokens ids.
+        row_lengths = ops.sum(ops.cast(padding_mask, "int32"), axis=-1)
+        # Start at the first index that has no user inputted id.
+        index = ops.min(row_lengths)
+
+        def next(prompt, cache, index):
+            # The cache index is the index of our previous token.
+            cache_update_index = index - 1
+            batch_size = ops.shape(prompt)[0]
+            prompt = ops.slice(prompt, [0, index - 1], [batch_size, 1])
+            logits, hidden_states, cache = self.call_with_cache(
+                token_ids=prompt,
+                cache=cache,
+                cache_update_index=cache_update_index,
+            )
+            return (
+                ops.squeeze(logits, axis=1),
+                ops.squeeze(hidden_states, axis=1),
+                cache,
+            )
+
+        token_ids = self.sampler(
+            next=next,
+            prompt=token_ids,
+            cache=cache,
+            index=index,
+            mask=padding_mask,
+            stop_token_ids=stop_token_ids,
+            hidden_states=hidden_states,
+            model=self,
+        )
+
+        # Compute an output padding mask with the token ids we updated.
+        if stop_token_ids is not None:
+            # Build a mask of `stop_token_ids` locations not in the original
+            # prompt (not in locations where `padding_mask` is True).
+            end_locations = any_equal(
+                token_ids, stop_token_ids, ops.logical_not(padding_mask)
+            )
+
+            end_locations = ops.cast(end_locations, "int32")
+            # Use cumsum to get ones in all locations after end_locations.
+            cumsum = ops.cast(ops.cumsum(end_locations, axis=-1), "int32")
+            overflow = cumsum - end_locations
+            # Our padding mask is the inverse of these overflow locations.
+            padding_mask = ops.logical_not(ops.cast(overflow, "bool"))
+        else:
+            # Without early stopping, all locations will have been updated.
+            padding_mask = ops.ones_like(token_ids, dtype="bool")
+        return {
+            "token_ids": token_ids,
+            "padding_mask": padding_mask,
+            "images": images,
+        }
+
+    def generate(
+        self,
+        inputs,
+        max_length=None,
+        stop_token_ids="auto",
+        strip_prompt=False,
+    ):
+        # If `auto`, add `<end_of_turn>` as a stop token too.
+        if self.preprocessor is None and stop_token_ids == "auto":
+            raise ValueError(
+                "A `preprocessor` must be attached to the model if "
+                '`stop_token_ids="auto"`. Currently `preprocessor=None`. To '
+                "call `generate()` with preprocessing detached, either pass "
+                "`stop_token_ids=None` to always generate until `max_length` "
+                "or pass a tuple of token ids that should terminate generation "
+                "as `stop_token_ids`."
+            )
+        elif stop_token_ids == "auto":
+            stop_token_ids = [
+                self.preprocessor.tokenizer.end_token_id,
+                self.preprocessor.tokenizer.token_to_id("<end_of_turn>"),
+            ]
+
+        return super().generate(
+            inputs,
+            max_length=max_length,
+            stop_token_ids=stop_token_ids,
+            strip_prompt=strip_prompt,
+        )