ai-edge-torch-nightly 0.3.0.dev20250114__py3-none-any.whl

ai_edge_torch/generative/layers/attention.py

@@ -0,0 +1,399 @@
+# Copyright 2024 The AI Edge Torch Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+
+"""Common building blocks for Attention layer."""
+
+from typing import Optional, Tuple, Union
+
+from ai_edge_torch.generative.layers import builder
+from ai_edge_torch.generative.layers import kv_cache as kv_utils
+from ai_edge_torch.generative.layers import lora as lora_utils
+from ai_edge_torch.generative.layers import scaled_dot_product_attention as sdpa
+import ai_edge_torch.generative.layers.model_config as cfg
+import ai_edge_torch.generative.layers.rotary_position_embedding as rotary_pos_emb
+import torch
+from torch import nn
+
+
+class TransformerBlock(nn.Module):
+
+  def __init__(
+      self,
+      config: cfg.TransformerBlockConfig,
+      model_config: cfg.ModelConfig,
+  ) -> None:
+    """Initialize an instance of the TransformerBlock.
+
+    Args:
+      config (cfg.TransformerBlockConfig): the configuration object for this
+        transformer block.
+      model_config (cfg.ModelConfig): the configuration object for the model
+        this transformer block belongs to.
+    """
+    super().__init__()
+    self.pre_atten_norm = builder.build_norm(
+        model_config.embedding_dim,
+        config.pre_attention_norm_config,
+    )
+    self.atten_func = CausalSelfAttention(
+        model_config.batch_size,
+        model_config.embedding_dim,
+        config.attn_config,
+        model_config.enable_hlfb,
+    )
+    self.post_atten_norm = builder.build_norm(
+        model_config.embedding_dim,
+        config.post_attention_norm_config,
+    )
+    self.ff = builder.build_ff(model_config.embedding_dim, config.ff_config)
+    self.config = config
+
+  def forward(
+      self,
+      x: torch.Tensor,
+      rope: Optional[Tuple[torch.Tensor, torch.Tensor]] = None,
+      mask: Optional[torch.Tensor] = None,
+      input_pos: Optional[torch.Tensor] = None,
+      kv_cache: kv_utils.KVCacheEntry = None,
+      lora: Optional[lora_utils.LoRAEntry] = None,
+  ) -> Union[torch.Tensor, Tuple[torch.Tensor, kv_utils.KVCacheEntry]]:
+    """Forward function of the TransformerBlock.
+
+    Args:
+      x (torch.Tensor): the input tensor.
+      rope (Tuple[torch.Tensor, torch.Tensor]): the input rope tensor.
+      mask (torch.Tensor): the optional mask tensor.
+      input_pos (torch.Tensor): the optional input position tensor.
+      kv_cache (KVCacheEntry): the optional kv cache entry.
+      lora (LoRAEntry): the optional lora entry.
+
+    Returns:
+      output activation from this transformer block, and updated kv cache (if
+      passed in).
+    """
+    kv = None
+    if self.config.parallel_residual:
+      x_norm = self.pre_atten_norm(x)
+      atten_func_out = self.atten_func(
+          x_norm, rope, mask, input_pos, kv_cache, lora
+      )
+      if kv_cache is None:
+        attn_out = atten_func_out
+      else:
+        attn_out, kv = atten_func_out
+      ff_out = self.ff(x_norm)
+      output = x + attn_out + ff_out
+    else:
+      x_norm = self.pre_atten_norm(x)
+      atten_func_out = self.atten_func(
+          x_norm, rope, mask, input_pos, kv_cache, lora
+      )
+      if kv_cache is None:
+        attn_out = atten_func_out
+      else:
+        attn_out, kv = atten_func_out
+      x = x + attn_out
+      x_norm = self.post_atten_norm(x)
+      output = x + self.ff(x_norm)
+
+    return output if kv is None else (output, kv)
+
+
+class CausalSelfAttention(nn.Module):
+
+  def __init__(
+      self,
+      batch_size: int,
+      dim: int,
+      config: cfg.AttentionConfig,
+      enable_hlfb: bool,
+  ) -> None:
+    """Initialize an instance of CausalSelfAttention.
+
+    Args:
+      batch_size (int): batch size of the input tensor.
+      dim (int): causal attention's input/output dimmension.
+      config (cfg.AttentionConfig): attention specific configurations.
+      enable_hlfb (bool): whether hlfb is enabled or not.
+    """
+    super().__init__()
+    self.kv_cache = None
+    self.batch_size = batch_size
+    qkv_shape = (
+        config.num_heads + 2 * config.num_query_groups
+    ) * config.head_dim
+    output_shape = config.num_heads * config.head_dim
+    # Key, query, value projections for all heads.
+    self.qkv_projection = nn.Linear(dim, qkv_shape, bias=config.qkv_use_bias)
+    self.output_projection = nn.Linear(
+        output_shape, dim, bias=config.output_proj_use_bias
+    )
+    self.query_norm = builder.build_norm(
+        config.head_dim, config.query_norm_config
+    )
+    self.key_norm = builder.build_norm(config.head_dim, config.key_norm_config)
+    self.config = config
+    self.enable_hlfb = enable_hlfb
+    self.sdpa_func = (
+        sdpa.scaled_dot_product_attention_with_hlfb
+        if enable_hlfb
+        else sdpa.scaled_dot_product_attention
+    )
+
+  def forward(
+      self,
+      x: torch.Tensor,
+      rope: Optional[Tuple[torch.Tensor, torch.Tensor]] = None,
+      mask: Optional[torch.Tensor] = None,
+      input_pos: Optional[torch.Tensor] = None,
+      kv_cache: Optional[kv_utils.KVCacheEntry] = None,
+      lora: Optional[lora_utils.LoRAEntry] = None,
+  ) -> Union[torch.Tensor, Tuple[torch.Tensor, kv_utils.KVCacheEntry]]:
+    """Forward function of the CausalSelfAttention layer, which can support
+
+       MQA, GQA and MHA.
+
+    Args:
+      x (torch.Tensor): the input tensor.
+      rope (Tuple[torch.Tensor, torch.Tensor]): the input rope tensor.
+      mask (torch.Tensor): the optional mask tensor.
+      input_pos (torch.Tensor): the optional input position tensor.
+      kv_cache (KVCacheEntry): the KV cache entry corresponding to this module.
+      lora (LoRAEntry): the optional lora entry.
+
+    Returns:
+      output activation from this self attention layer, and the updated
+        KV Cach Entry (if passed in).
+    """
+    # Batch size, sequence length, embedding dimensionality.
+    B, T, E = x.size()
+    assert B == self.batch_size, (
+        "batch size of input tensor must match with the batch size specified in"
+        " the model configuration."
+    )
+
+    qkv = self.qkv_projection(x)
+
+    # Assemble into a number of query groups to support MHA, MQA and GQA.
+    q_per_kv = self.config.num_heads // self.config.num_query_groups
+    # Each group has >=1 queries, 1 key, and 1 value.
+    if self.config.qkv_transpose_before_split:
+      qkv = qkv.view(B, T, -1, self.config.head_dim)
+      q, k, v = qkv.split(
+          (
+              q_per_kv * self.config.num_query_groups,
+              self.config.num_query_groups,
+              self.config.num_query_groups,
+          ),
+          dim=-2,
+      )
+    else:
+      qkv = qkv.view(B, T, self.config.num_query_groups, -1)
+      q, k, v = qkv.split(
+          (
+              q_per_kv * self.config.head_dim,
+              self.config.head_dim,
+              self.config.head_dim,
+          ),
+          dim=-1,
+      )
+
+    if lora is not None:
+      q += lora_utils.apply_lora(x, lora.attention.query, shape=q.shape)
+      k += lora_utils.apply_lora(x, lora.attention.key, shape=k.shape)
+      v += lora_utils.apply_lora(x, lora.attention.value, shape=v.shape)
+
+    q = self.query_norm(q)
+    k = self.key_norm(k)
+
+    q = q.reshape(B, T, -1, self.config.head_dim)
+    k = k.reshape(B, T, -1, self.config.head_dim)
+    v = v.reshape(B, T, -1, self.config.head_dim)
+
+    if rope is not None:
+      # Compute rotary positional embedding for query and key.
+      n_elem = int(self.config.rotary_percentage * self.config.head_dim)
+      cos, sin = rope
+      q, k = rotary_pos_emb.apply_rope_inline(q, k, cos, sin)
+
+    if kv_cache is not None:
+      kv_cache = kv_utils.update(kv_cache, input_pos, k, v)
+      k, v = kv_cache.k_cache, kv_cache.v_cache
+
+    sdpa_out = self.sdpa_func(
+        q,
+        k,
+        v,
+        self.config.head_dim,
+        mask=mask,
+        softcap=self.config.logit_softcap,
+    )
+    sdpa_out = sdpa_out.reshape(B, T, -1)
+
+    # Compute the output projection.
+    y = self.output_projection(sdpa_out)
+    if lora is not None:
+      y += lora_utils.apply_lora(sdpa_out, lora.attention.output)
+
+    return y if kv_cache is None else (y, kv_cache)
+
+
+class SelfAttention(CausalSelfAttention):
+  """Non-causal Self Attention module, which is equivalent to CausalSelfAttention without mask."""
+
+  def forward(
+      self,
+      x: torch.Tensor,
+      rope: Optional[Tuple[torch.Tensor, torch.Tensor]] = None,
+      input_pos: Optional[torch.Tensor] = None,
+      kv_cache: Optional[kv_utils.KVCacheEntry] = None,
+      lora: Optional[lora_utils.LoRAEntry] = None,
+  ) -> Union[torch.Tensor, Tuple[torch.Tensor, kv_utils.KVCacheEntry]]:
+    """Forward function of the SelfAttention layer, which can support MQA, GQA and MHA.
+
+    Args:
+      x (torch.Tensor): the input tensor.
+      rope (Tuple[torch.Tensor, torch.Tensor]): the input rope tensor.
+      input_pos (torch.Tensor): the optional input position tensor.
+      kv_cache (KVCacheEntry): the KV cache entry corresponding to this module.
+      lora (LoRAEntry): the optional lora entry.
+
+    Returns:
+      output activation from this self attention layer, and the updated
+        KV Cach Entry (if passed in).
+    """
+    B, T, _ = x.size()
+    assert (
+        kv_cache is None
+    ), "KV cache is not supported in non-causal SelfAttention."
+    return super().forward(
+        x,
+        rope=rope,
+        mask=torch.zeros((B, 1, T, T), dtype=torch.float32),
+        input_pos=input_pos,
+        lora=lora,
+    )
+
+
+class CrossAttention(nn.Module):
+
+  def __init__(
+      self,
+      batch_size: int,
+      query_dim: int,
+      cross_dim: int,
+      hidden_dim: int,
+      output_dim: int,
+      config: cfg.AttentionConfig,
+      enable_hlfb: bool,
+  ):
+    """Initialize an instance of CrossAttention.
+
+    Args:
+      batch_size (int): batch size of the input tensor.
+      query_dim (int): query tensor's dimension.
+      cross_dim (int): cross attention's dimensions, for key and value tensors.
+      hidden_dim (int): hidden dimension that q, k, v tensors project to.
+      output_dim (int): output tensor's dimension.
+      config (cfg.AttentionConfig): attention specific configurations.
+      enable_hlfb (bool): whether hlfb is enabled or not.
+    """
+    super().__init__()
+    self.config = config
+    self.n_heads = config.num_heads
+    self.q_projection = nn.Linear(
+        query_dim, hidden_dim, bias=config.qkv_use_bias
+    )
+    self.k_projection = nn.Linear(
+        cross_dim, hidden_dim, bias=config.qkv_use_bias
+    )
+    self.v_projection = nn.Linear(
+        cross_dim, hidden_dim, bias=config.qkv_use_bias
+    )
+    self.output_projection = nn.Linear(
+        hidden_dim, output_dim, bias=config.output_proj_use_bias
+    )
+
+    self.sdpa_func = (
+        sdpa.scaled_dot_product_attention_with_hlfb
+        if enable_hlfb
+        else sdpa.scaled_dot_product_attention
+    )
+
+  def forward(
+      self,
+      x: torch.Tensor,
+      y: torch.Tensor,
+      rope: Optional[Tuple[torch.Tensor, torch.Tensor]] = None,
+      mask: Optional[torch.Tensor] = None,
+      input_pos: Optional[torch.Tensor] = None,
+      kv_cache: Optional[kv_utils.KVCacheEntry] = None,
+      lora: Optional[lora_utils.LoRAEntry] = None,
+  ):
+    """Forward function of the CrossAttention layer.
+
+    Args:
+      x (torch.Tensor): the target tensor, with shape [B, target_seq_len, ...].
+      y (torch.Tensor): the source tensor, with shape [B, source_seq_len, ...].
+      rope (Tuple[torch.Tensor, torch.Tensor]): the optional input rope tensor.
+      mask (torch.Tensor): the optional mask tensor can be broadcaseted to shape
+        [B, n_heads, target_seq_len, source_seq_len].
+      input_pos (torch.Tensor): the optional input position tensor.
+      kv_cache (KVCacheEntry): the KV cache entry corresponding to this module.
+      lora (LoRAEntry): the optional lora entry.
+
+    Returns:
+      output activation from this cross attention layer.
+    """
+    batch_size = x.size()[0]
+    target_seq_len = x.size()[1]
+    source_seq_len = y.size()[1]
+
+    q = self.q_projection(x)
+    k = self.k_projection(y)
+    v = self.v_projection(y)
+
+    if lora is not None:
+      q += lora_utils.apply_lora(x, lora.attention.query, shape=q.shape)
+      k += lora_utils.apply_lora(x, lora.attention.key, shape=k.shape)
+      v += lora_utils.apply_lora(x, lora.attention.value, shape=v.shape)
+
+    interim_shape = (batch_size, -1, self.n_heads, self.config.head_dim)
+    q = q.view(interim_shape)
+    k = k.view(interim_shape)
+    v = v.view(interim_shape)
+
+    if rope is not None:
+      # Compute rotary positional embedding for query and key.
+      n_elem = int(self.config.rotary_percentage * self.config.head_dim)
+      cos, sin = rope
+      q, k = rotary_pos_emb.apply_rope_inline(q, k, cos, sin)
+
+    if kv_cache is not None:
+      kv_cache = kv_utils.update(kv_cache, input_pos, k, v)
+      k, v = kv_cache.k_cache, kv_cache.v_cache
+    if mask is None:
+      mask = torch.zeros(
+          (batch_size, 1, target_seq_len, source_seq_len), dtype=torch.float32
+      )
+    y = self.sdpa_func(q, k, v, self.config.head_dim, mask=mask)
+    y = y.reshape(batch_size, target_seq_len, -1)
+
+    # Compute the output projection.
+    y = self.output_projection(y)
+    if lora is not None:
+      y += lora_utils.apply_lora(y, lora.attention.output)
+
+    return y if kv_cache is None else (y, kv_cache)

ai_edge_torch/generative/layers/attention_utils.py

@@ -0,0 +1,210 @@
+# Copyright 2024 The AI Edge Torch Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+# Common utility functions used with attention module.
+
+import math
+from typing import Tuple
+
+import torch
+
+
+def build_rope_cache(
+    size: int,
+    dim: int,
+    base: int = 10000,
+    condense_ratio: int = 1,
+    dtype: torch.dtype = torch.float32,
+    device: torch.device = None,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+  """Precomputes Rotary Positional Embeddings.
+
+  Precompute Rotary Positional Embedding Sin and Cos values for quick lookup
+  during the inference.
+
+  Args:
+      size (int): The size of the built cache.
+      dim (int): Each sequence's dimmension.
+      base (int, optional): Rope base value. Defaults to 10000.
+      condense_ratio (int, optional): The ratio by which sequence indicies are
+        condensed. Defaults to 1.
+      dtype (torch.dtype, optional): Output tensor's data type. Defaults to
+        torch.float32.
+      device (torch.device, optional): Output tensor's data type. Defaults to
+        None in which case "cpu" is used.
+
+  Returns:
+      Tuple[torch.Tensor, torch.Tensor]: Rope's Cosine and Sine waves.
+  """
+  if device is None:
+    device = torch.device('cpu')
+  theta = 1.0 / (base ** (torch.arange(0, dim, 2).float() / dim))
+  seq_idx = torch.arange(size) / condense_ratio
+  idx_theta = torch.outer(seq_idx, theta)
+  cos = torch.cos(idx_theta).to(dtype=dtype, device=device)
+  sin = torch.sin(idx_theta).to(dtype=dtype, device=device)
+  return cos, sin
+
+
+def build_causal_mask_cache(
+    size: int,
+    dtype: torch.dtype = torch.float32,
+    device: torch.device = None,
+) -> torch.Tensor:
+  """Build a cache for causal attention mask.
+
+  Args:
+      size (int): The size of the built mask cache.
+      dtype (torch.dtype, optional): Output tensor's data type. Defaults to
+        torch.float32.
+      device (torch.device, optional): Output tensor's data type. Defaults to
+        None in which case "cpu" is used.
+
+  Returns:
+      torch.Tensor: Causal attention mask.
+  """
+
+  if device is None:
+    device = torch.device('cpu')
+  mask = torch.full((size, size), float('-inf'), dtype=dtype, device=device)
+  return torch.triu(mask, diagonal=1).unsqueeze(0).unsqueeze(0)
+
+
+def build_sliding_window_mask_cache(
+    size: int,
+    window_size: int,
+    dtype: torch.dtype = torch.float32,
+    device: torch.device = None,
+) -> torch.Tensor:
+  """Build a cache for a sliding window mask.
+
+  Args:
+      size (int): The size of the built mask cache.
+      window_size (int): The window size that is "seen" by a token.
+      dtype (torch.dtype, optional): Output tensor's data type. Defaults to
+        torch.float32.
+      device (torch.device, optional): Output tensor's data type. Defaults to
+        None in which case "cpu" is used.
+
+  Returns:
+      torch.Tensor: Causal attention mask.
+  """
+
+  mask = build_causal_mask_cache(size, dtype, device)
+  all_ones = torch.ones_like(mask)
+  window_size = min(size, window_size)
+  sliding_mask = torch.triu(all_ones, -1 * window_size + 1) * torch.tril(
+      all_ones, window_size - 1
+  )
+  return torch.where(sliding_mask == 1, mask, float('-inf'))
+
+
+def relative_position_bucket(
+    relative_position: torch.Tensor,
+    bidirectional: bool,
+    num_buckets: int,
+    max_distance: int,
+) -> torch.Tensor:
+  """Adapted from Mesh Tensorflow:
+
+  https://github.com/tensorflow/mesh/blob/0cb87fe07da627bf0b7e60475d59f95ed6b5be3d/mesh_tensorflow/transformer/transformer_layers.py#L593
+
+  Translate relative position to a bucket number for relative attention. The
+  relative position is defined as
+  memory_position - query_position, i.e. the distance in tokens from the
+  attending position to the attended-to
+  position. If bidirectional=False, then positive relative positions are
+  invalid. We use smaller buckets for
+  small absolute relative_position and larger buckets for larger absolute
+  relative_positions. All relative
+  positions >=max_distance map to the same bucket. All relative positions
+  <=-max_distance map to the same bucket.
+  This should allow for more graceful generalization to longer sequences than
+  the model has been trained on
+
+  Args:
+      relative_position: an int32 Tensor
+      bidirectional: a boolean - whether the attention is bidirectional
+      num_buckets: an integer for number of buckets.
+      max_distance: an integer for max distance.
+
+  Returns:
+      a Tensor with the same shape as relative_position, containing int32 values
+      in the range [0, num_buckets)
+  """
+  relative_buckets = 0
+  if bidirectional:
+    num_buckets //= 2
+    relative_buckets += (relative_position > 0).to(torch.long) * num_buckets
+    relative_position = torch.abs(relative_position)
+  else:
+    relative_position = -torch.min(
+        relative_position, torch.zeros_like(relative_position)
+    )
+  # now relative_position is in the range [0, inf)
+
+  # half of the buckets are for exact increments in positions
+  max_exact = num_buckets // 2
+  is_small = relative_position < max_exact
+
+  # The other half of the buckets are for logarithmically bigger bins in
+  # positions up to max_distance
+  relative_position_if_large = max_exact + (
+      torch.log(relative_position.float() / max_exact)
+      / math.log(max_distance / max_exact)
+      * (num_buckets - max_exact)
+  ).to(torch.long)
+  relative_position_if_large = torch.min(
+      relative_position_if_large,
+      torch.full_like(relative_position_if_large, num_buckets - 1),
+  )
+
+  relative_buckets += torch.where(
+      is_small, relative_position, relative_position_if_large
+  )
+  return relative_buckets
+
+
+def build_relative_position_buckets(
+    query_length: int,
+    key_length: int,
+    bidirectional: bool = True,
+    num_buckets: int = 32,
+    max_distance: int = 128,
+) -> torch.Tensor:
+  """Relative position buckets for computing bias.
+
+  Args:
+    query_length: an integer of length of current query tensor.
+    key_length: an integer of length of current key tensor.
+    bidirectional: a boolean - whether the attention is bidirectional, default
+      is True.
+    num_buckets: an integer for number of buckets, default is 32.
+    max_distance: an integer for max distance, default is 128.
+
+  Returns:
+    A torch.Tensor of computed relative position buckets.
+  """
+  context_position = torch.arange(query_length, dtype=torch.long)[:, None]
+  memory_position = torch.arange(key_length, dtype=torch.long)[None, :]
+  relative_position = (
+      memory_position - context_position
+  )  # shape (query_length, key_length)
+  rel_pos_bucket = relative_position_bucket(
+      relative_position,  # shape (query_length, key_length)
+      bidirectional=bidirectional,
+      num_buckets=num_buckets,
+      max_distance=max_distance,
+  )
+  return rel_pos_bucket.unsqueeze(0).unsqueeze(0)