<br />

<button value="stable" default="">See Stable</button> <button value="nightly">See Nightly</button>

<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/keras-team/keras/tree/v3.15.1/keras/src/layers/attention/grouped_query_attention.py#L16-L653) |

Grouped Query Attention layer.

Inherits From: [`Layer`](https://www.tensorflow.org/api_docs/python/tf/keras/Layer.md.txt), [`Operation`](https://www.tensorflow.org/api_docs/python/tf/keras/Operation.md.txt)

```python
tf.keras.layers.GroupQueryAttention(
    head_dim,
    num_query_heads,
    num_key_value_heads,
    dropout=0.0,
    use_bias=True,
    sliding_window=None,
    flash_attention=None,
    kernel_initializer='glorot_uniform',
    bias_initializer='zeros',
    kernel_regularizer=None,
    bias_regularizer=None,
    activity_regularizer=None,
    kernel_constraint=None,
    bias_constraint=None,
    use_gate=False,
    seed=None,
    **kwargs
)
```

This is an implementation of grouped-query attention introduced by
[Ainslie et al., 2023](https://arxiv.org/abs/2305.13245). Here
`num_key_value_heads` denotes number of groups, setting
`num_key_value_heads` to 1 is equivalent to multi-query attention, and
when `num_key_value_heads` is equal to `num_query_heads` it is equivalent
to multi-head attention.

This layer first projects `query`, `key`, and `value` tensors. Then, `key`
and `value` are repeated to match the number of heads of `query`.

Then, the `query` is scaled and dot-producted with `key` tensors. These are
softmaxed to obtain attention probabilities. The value tensors are then
interpolated by these probabilities and concatenated back to a single
tensor.

<br />

<br />

<br />

| ## Args ||
|---|---|
| `head_dim` | Size of each attention head. |
| `num_query_heads` | Number of query attention heads. |
| `num_key_value_heads` | Number of key and value attention heads. |
| `dropout` | Dropout probability. |
| `use_bias` | Boolean, whether the dense layers use bias vectors/matrices. |
| `sliding_window` | Optional positive integer. If set, restricts each query position to attend only to key positions within `sliding_window - 1` of itself (a symmetric band). Composes naturally with `use_causal_mask=True` to give the causal sliding window used by Mistral, Llama-3 long-context, and Phi-3. Defaults to `None` (full attention). |
| `flash_attention` | If `None`, the layer attempts to use flash attention for faster and more memory-efficient attention computations when possible. This behavior can be configured using [`keras.config.enable_flash_attention()`](https://www.tensorflow.org/api_docs/python/tf/keras/config/enable_flash_attention.md.txt) or [`keras.config.disable_flash_attention()`](https://www.tensorflow.org/api_docs/python/tf/keras/config/disable_flash_attention.md.txt). |
| `kernel_initializer` | Initializer for dense layer kernels. |
| `bias_initializer` | Initializer for dense layer biases. |
| `kernel_regularizer` | Regularizer for dense layer kernels. |
| `bias_regularizer` | Regularizer for dense layer biases. |
| `activity_regularizer` | Regularizer for dense layer activity. |
| `kernel_constraint` | Constraint for dense layer kernels. |
| `bias_constraint` | Constraint for dense layer kernels. |
| `use_gate` | Boolean, whether to apply a gated attention mechanism. When True, an additional gating branch is added based on the (Gated Attention for Large Language Models)\[https://arxiv.org/abs/2505.06708\]. It applies a sigmoid-activated linear projection to the query which then gates the attention output. This helps improve training stability and eliminates "attention sinks". |
| `seed` | Optional integer to seed the dropout layer. |

<br />

<br />

<br />

<br />

| ## Call arguments ||
|---|---|
| `query` | Query tensor of shape `(batch_dim, target_seq_len, feature_dim)`, where `batch_dim` is batch size, `target_seq_len` is the length of target sequence, and `feature_dim` is dimension of feature. |
| `value` | Value tensor of shape `(batch_dim, source_seq_len, feature_dim)`, where `batch_dim` is batch size, `source_seq_len` is the length of source sequence, and `feature_dim` is dimension of feature. |
| `key` | Optional key tensor of shape `(batch_dim, source_seq_len, feature_dim)`. If not given, will use `value` for both `key` and `value`, which is most common case. |
| `attention_mask` | A boolean mask of shape `(batch_dim, target_seq_len, source_seq_len)`, that prevents attention to certain positions. The boolean mask specifies which query elements can attend to which key elements, where 1 indicates attention and 0 indicates no attention. Broadcasting can happen for the missing batch dimensions and the head dimension. |
| `return_attention_scores` | A boolean to indicate whether the output should be `(attention_output, attention_scores)` if `True`, or `attention_output` if `False`. Defaults to `False`. |
| `training` | Python boolean indicating whether the layer should behave in training mode (adding dropout) or in inference mode (no dropout). Will go with either using the training mode of the parent layer/model or `False` (inference) if there is no parent layer. |
| `use_causal_mask` | A boolean to indicate whether to apply a causal mask to prevent tokens from attending to future tokens (e.g., used in a decoder Transformer). |

<br />

<br />

<br />

<br />

| ## Returns ||
|---|---|
| `attention_output` | Result of the computation, of shape `(batch_dim, target_seq_len, feature_dim)`, where `target_seq_len` is for target sequence length and `feature_dim` is the query input last dim. |
| `attention_scores` | (Optional) attention coefficients of shape `(batch_dim, num_query_heads, target_seq_len, source_seq_len)`. |

<br />

<br />

<br />

<br />

| ## Attributes ||
|---|---|
| `input` | Retrieves the input tensor(s) of a symbolic operation. <br /> Only returns the tensor(s) corresponding to the *first time* the operation was called. |
| `output` | Retrieves the output tensor(s) of a layer. <br /> Only returns the tensor(s) corresponding to the *first time* the operation was called. |

<br />

## Methods

### `from_config`

[View source](https://github.com/keras-team/keras/tree/v3.15.1/keras/src/ops/operation.py#L322-L362)

```python
@classmethod
from_config(
    config
)
```

Creates an operation from its config.

This method is the reverse of `get_config`, capable of instantiating the
same operation from the config dictionary.

> [!NOTE]
> **Note:** If you override this method, you might receive a serialized dtype config, which is a `dict`. You can deserialize it as follows:

```python
if "dtype" in config and isinstance(config["dtype"], dict):
    policy = dtype_policies.deserialize(config["dtype"])
```

<br />

<br />

<br />

| Args ||
|---|---|
| `config` | A Python dictionary, typically the output of `get_config`. |

<br />

<br />

<br />

<br />

| Returns ||
|---|---|
| An operation instance. ||

<br />