tpu-inference 0.11.1.dev202511220812__py3-none-any.whl → 0.13.2.dev20251230__py3-none-any.whl

tests/kernels/mla_v1_test.py

@@ -1,3 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
 import jax
 import jax.numpy as jnp
 import numpy as np
@@ -42,6 +56,7 @@ class MlaRaggedPagedAttentionKernelTest(jtu.JaxTestCase):
 
         padded_r_dim = align_to(r_dim, 128)
         padded_lkv_dim = align_to(lkv_dim, 128)
+        padded_kv_dim = padded_lkv_dim + padded_r_dim
         packing = get_dtype_packing(kv_dtype)
         q_lens = [s[0] for s in seq_lens]
         kv_lens_list = [s[1] for s in seq_lens]
@@ -69,13 +84,10 @@ class MlaRaggedPagedAttentionKernelTest(jtu.JaxTestCase):
         new_kv_c = gen_random((total_q_len, lkv_dim), kv_dtype)
         new_k_pe = gen_random((total_q_len, r_dim), kv_dtype)
 
-        cache_kv_c = gen_random(
-            (total_num_pages, page_size // packing, packing, padded_lkv_dim),
+        cache_kv = gen_random(
+            (total_num_pages, page_size // packing, packing, padded_kv_dim),
             kv_dtype,
         )
-        cache_k_pe = gen_random(
-            (total_num_pages, page_size // packing, packing, padded_r_dim),
-            kv_dtype)
         kv_lens = jnp.array(kv_lens_list, dtype=jnp.int32)
         page_indices = jnp.array(page_indices_list, dtype=jnp.int32)
         cu_q_lens = jnp.array(cu_q_lens_list, dtype=jnp.int32)
@@ -84,14 +96,13 @@ class MlaRaggedPagedAttentionKernelTest(jtu.JaxTestCase):
         ql_nope_for_kernel = ql_nope.copy()
         q_pe_for_kernel = q_pe.copy()
 
-        expected_out, expected_updated_kv_c, expeceted_updated_k_pe = (
+        expected_out, expected_updated_kv = (
             mla.ref_mla_ragged_paged_attention(
                 ql_nope,
                 q_pe,
                 new_kv_c,
                 new_k_pe,
-                cache_kv_c.copy(),
-                cache_k_pe.copy(),
+                cache_kv.copy(),
                 kv_lens,
                 page_indices,
                 cu_q_lens,
@@ -101,50 +112,141 @@ class MlaRaggedPagedAttentionKernelTest(jtu.JaxTestCase):
                 soft_cap=soft_cap,
             ))
 
-        kernel_out, kernel_updated_kv_c, kernel_updated_k_pe = (
-            mla.mla_ragged_paged_attention(
-                ql_nope_for_kernel,
-                q_pe_for_kernel,
-                new_kv_c,
-                new_k_pe,
-                cache_kv_c.copy(),
-                cache_k_pe.copy(),
-                kv_lens,
-                page_indices,
-                cu_q_lens,
-                distribution,
-                sm_scale=sm_scale,
-                sliding_window=sliding_window,
-                soft_cap=soft_cap,
-                num_kv_pages_per_block=num_kv_pages_per_block,
-                num_queries_per_block=num_queries_per_block,
-                vmem_limit_bytes=vmem_limit_bytes,
-            ))
+        kernel_out, kernel_updated_kv = (mla.mla_ragged_paged_attention(
+            ql_nope_for_kernel,
+            q_pe_for_kernel,
+            new_kv_c,
+            new_k_pe,
+            cache_kv.copy(),
+            kv_lens,
+            page_indices,
+            cu_q_lens,
+            distribution,
+            sm_scale=sm_scale,
+            sliding_window=sliding_window,
+            soft_cap=soft_cap,
+            num_kv_pages_per_block=num_kv_pages_per_block,
+            num_queries_per_block=num_queries_per_block,
+            vmem_limit_bytes=vmem_limit_bytes,
+        ))
 
         self.assertEqual(expected_out.shape,
                          (total_q_len, num_heads, padded_lkv_dim))
         self.assertEqual(
-            expected_updated_kv_c.shape,
-            (total_num_pages, page_size // packing, packing, padded_lkv_dim),
-        )
-        self.assertEqual(
-            expeceted_updated_k_pe.shape,
-            (total_num_pages, page_size // packing, packing, padded_r_dim),
+            expected_updated_kv.shape,
+            (total_num_pages, page_size // packing, packing, padded_kv_dim),
         )
         self.assertEqual(expected_out.dtype, kv_dtype)
-        self.assertEqual(expected_updated_kv_c.dtype, kv_dtype)
-        self.assertEqual(expeceted_updated_k_pe.dtype, kv_dtype)
+        self.assertEqual(expected_updated_kv.dtype, kv_dtype)
 
         self.assertAllClose(expected_out, kernel_out, atol=0.2, rtol=0.2)
-        self.assertAllClose(expected_updated_kv_c,
-                            kernel_updated_kv_c,
-                            atol=0.2,
-                            rtol=0.2)
-        self.assertAllClose(expeceted_updated_k_pe,
-                            kernel_updated_k_pe,
+        self.assertAllClose(expected_updated_kv,
+                            kernel_updated_kv,
                             atol=0.2,
                             rtol=0.2)
 
+    def test_update_kv_cache(self):
+        lkv_dim = 4
+        r_dim = 4
+        padded_lkv_dim = align_to(lkv_dim, 128)
+        padded_r_dim = align_to(r_dim, 128)
+        kv_dtype = jnp.bfloat16
+        new_kv_c = jnp.arange(16, dtype=kv_dtype).reshape((4, lkv_dim))
+        new_k_pe = (jnp.arange(16, dtype=kv_dtype).reshape((4, r_dim)) + 100)
+        total_num_pages = 2
+        page_size = 4
+        cache_kv_shape = mla.get_kv_cache_shape(
+            total_num_pages,
+            page_size,
+            padded_lkv_dim + padded_r_dim,
+            kv_dtype,
+        )
+        cache_kv = jnp.zeros(cache_kv_shape, dtype=kv_dtype)
+
+        # two sequences, first with 3 tokens, second with 1 token
+        kv_lens = jnp.array([3, 1], dtype=jnp.int32)
+        # first seq uses page 0, second uses page 1
+        page_indices = jnp.array([0, -1, 1, -1], dtype=jnp.int32)
+        # three tokens for first seq, one for second
+        cu_q_lens = jnp.array([0, 3, 4], dtype=jnp.int32)
+        distribution = jnp.array([0, 0, 2], dtype=jnp.int32)
+
+        # manually compute the expected cache
+        padded_new_kv_c = jnp.pad(new_kv_c,
+                                  ((0, 0), (0, padded_lkv_dim - lkv_dim)),
+                                  constant_values=0)
+        padded_new_k_pe = jnp.pad(new_k_pe,
+                                  ((0, 0), (0, padded_r_dim - r_dim)),
+                                  constant_values=0)
+
+        expected_cache = cache_kv
+        # First sequence
+        # token 0
+        page_idx, row, col = 0, 0, 0
+        expected_cache = expected_cache.at[page_idx, row,
+                                           col, :padded_lkv_dim].set(
+                                               padded_new_kv_c[0])
+        expected_cache = expected_cache.at[page_idx, row, col,
+                                           padded_lkv_dim:padded_lkv_dim +
+                                           padded_r_dim].set(
+                                               padded_new_k_pe[0])
+        # token 1
+        page_idx, row, col = 0, 0, 1
+        expected_cache = expected_cache.at[page_idx, row,
+                                           col, :padded_lkv_dim].set(
+                                               padded_new_kv_c[1])
+        expected_cache = expected_cache.at[page_idx, row, col,
+                                           padded_lkv_dim:padded_lkv_dim +
+                                           padded_r_dim].set(
+                                               padded_new_k_pe[1])
+        # token 2
+        page_idx, row, col = 0, 1, 0
+        expected_cache = expected_cache.at[page_idx, row,
+                                           col, :padded_lkv_dim].set(
+                                               padded_new_kv_c[2])
+        expected_cache = expected_cache.at[page_idx, row, col,
+                                           padded_lkv_dim:padded_lkv_dim +
+                                           padded_r_dim].set(
+                                               padded_new_k_pe[2])
+
+        # Second sequence
+        # token 0
+        page_idx, row, col = 1, 0, 0
+        expected_cache = expected_cache.at[page_idx, row,
+                                           col, :padded_lkv_dim].set(
+                                               padded_new_kv_c[3])
+        expected_cache = expected_cache.at[page_idx, row, col,
+                                           padded_lkv_dim:padded_lkv_dim +
+                                           padded_r_dim].set(
+                                               padded_new_k_pe[3])
+
+        updated_cache = mla.update_kv_cache(
+            new_kv_c,
+            new_k_pe,
+            cache_kv,
+            kv_lens,
+            page_indices,
+            cu_q_lens,
+            distribution,
+        )
+
+        self.assertAllClose(updated_cache, expected_cache)
+
+    def test_get_kv_cache_shape(self):
+        total_num_pages = 10
+        page_size = 16
+        lkv_dim = 128
+        kv_dtype = jnp.bfloat16
+        # The calculation for the expected shape is as follows:
+        # kv_packing is determined by the dtype, which is 2 for bfloat16.
+        # The second dimension is page_size / kv_packing = 16 / 2 = 8
+        # The third dimension is kv_packing = 2
+        # The fourth dimension is lkv_dim aligned to 128, which is 128
+        expected_shape = (10, 8, 2, 128)
+        self.assertEqual(
+            mla.get_kv_cache_shape(total_num_pages, page_size, lkv_dim,
+                                   kv_dtype), expected_shape)
+
     def test_ragged_paged_attention_basic(self):
         dtype = jnp.bfloat16
         seq_lens = [(192, 328), (128, 180), (64, 255)]

tests/kernels/quantized_matmul_kernel_test.py

@@ -1,7 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
 
-import functools
-
 import jax
 import jax.numpy as jnp
 from absl.testing import absltest, parameterized
@@ -10,6 +8,7 @@ from jax._src import test_util as jtu
 from tpu_inference.kernels.quantized_matmul import (kernel, tuned_block_sizes,
                                                     util)
 
+xla_quantized_matmul = kernel.xla_quantized_matmul
 quantized_matmul_kernel = kernel.quantized_matmul_kernel
 quantize_tensor = util.quantize_tensor
 get_tuned_block_sizes = tuned_block_sizes.get_tuned_block_sizes
@@ -17,37 +16,6 @@ get_tuned_block_sizes = tuned_block_sizes.get_tuned_block_sizes
 jax.config.parse_flags_with_absl()
 
 
-@functools.partial(jax.jit, static_argnames=["quantize_activation"])
-def reference_quantized_matmul(
-    x: jax.Array,
-    w_q: jax.Array,
-    w_scale: jax.Array,
-    quantize_activation=True,
-):
-    if quantize_activation:
-        acc_dtype = jnp.float32
-        if quantize_activation and jnp.issubdtype(w_q.dtype, jnp.integer):
-            acc_dtype = jnp.int32
-
-        x_q, x_scale = quantize_tensor(x, w_q.dtype)
-        out = jax.lax.dot_general(
-            x_q,
-            w_q,
-            dimension_numbers=(((1, ), (1, )), ((), ())),
-            preferred_element_type=acc_dtype,
-        ).astype(jnp.float32)
-        out *= x_scale
-    else:
-        out = jax.lax.dot_general(
-            x,
-            w_q,
-            dimension_numbers=(((1, ), (1, )), ((), ())),
-            preferred_element_type=jnp.float32,
-        )
-    out *= jnp.expand_dims(w_scale, 0)
-    return out.astype(x.dtype)
-
-
 @jtu.with_config(jax_numpy_dtype_promotion="standard")
 class QuantizedMatmulKernelTest(jtu.JaxTestCase):
 
@@ -94,7 +62,7 @@ class QuantizedMatmulKernelTest(jtu.JaxTestCase):
             x_q_dtype=x_q_dtype,
             tuned_value=tuned_value,
         )
-        expected = reference_quantized_matmul(
+        expected = xla_quantized_matmul(
             x, w_q, w_scale, quantize_activation=quantize_activation)
 
         self.assertAllClose(output,

tests/kernels/ragged_kv_cache_update_v2_test.py

@@ -1,3 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
 import jax
 import jax.numpy as jnp
 import numpy as np

tests/kernels/ragged_paged_attention_kernel_v2_test.py

@@ -1,3 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
 import random
 
 import jax

tests/kernels/ragged_paged_attention_kernel_v3_hd64_test.py

@@ -1,3 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
 import jax
 import jax.numpy as jnp
 import numpy as np
@@ -176,7 +190,9 @@ class RaggedPagedAttentionHeadDim64KernelTest(jtu.JaxTestCase):
         )
         output = output[:cu_q_lens[distribution[-1]]]
 
-        dtype_bits = dtypes.bit_width(jnp.dtype(kv_dtype))
+        dtype_bits = (dtypes.bit_width(jnp.dtype(kv_dtype)) if hasattr(
+            dtypes, "bit_width") else dtypes.itemsize_bits(
+                jnp.dtype(kv_dtype)))
         tols = {
             32: 0.15,
             16: 0.2,

tests/kernels/ragged_paged_attention_kernel_v3_test.py

@@ -1,3 +1,17 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
 import jax
 import jax.numpy as jnp
 import numpy as np
@@ -162,7 +176,9 @@ class RaggedPagedAttentionKernelTest(jtu.JaxTestCase):
         )
         output = output[:cu_q_lens[distribution[-1]]]
 
-        dtype_bits = dtypes.bit_width(jnp.dtype(kv_dtype))
+        dtype_bits = (dtypes.bit_width(jnp.dtype(kv_dtype)) if hasattr(
+            dtypes, "bit_width") else dtypes.itemsize_bits(
+                jnp.dtype(kv_dtype)))
         tols = {
             32: 0.15,
             16: 0.2,

tests/layers/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2025 Google LLC
+#
+# 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.

tests/layers/common/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2025 Google LLC
+#
+# 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.

tests/layers/common/test_attention_interface.py

@@ -0,0 +1,156 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
+from unittest.mock import MagicMock
+
+import jax
+import jax.numpy as jnp
+import numpy as np
+import pytest
+from jax.sharding import Mesh
+
+from tpu_inference.layers.common.attention_interface import attention
+from tpu_inference.layers.common.attention_metadata import AttentionMetadata
+from tpu_inference.runner.kv_cache import get_kv_cache_shape_with_mesh
+
+# ---- Test Configuration & Constants ----
+
+# Total number of tokens across all sequences in the batch
+TOTAL_TOKENS = 10
+# Number of sequences in the batch
+NUM_SEQS = 2
+# Padded maximum number of sequences
+MAX_NUM_SEQS = 4
+# Number of attention heads (Query)
+NUM_HEADS = 8
+# Number of attention heads (Key/Value) - for Grouped-Query Attention
+NUM_KV_HEADS = 4
+# Total number of blocks in the KV cache
+NUM_BLOCKS = 32
+# Number of tokens per block
+BLOCK_SIZE = 16
+# Maximum number of blocks a single sequence can occupy
+MAX_BLOCKS_PER_SEQ = 8
+
+
+@pytest.fixture
+def mesh():
+    """Provides a mock 1D JAX mesh for testing."""
+    # Create a mesh with available devices, useful for running on CPU/GPU/TPU
+    # For this test, it will likely be a single CPU device.
+    devices = np.array(jax.local_devices()[:1])
+    if not devices.any():
+        # Add a mock device if no devices are present (e.g., in a CI environment)
+        devices = np.array([jax.devices("cpu")[0]])
+    return Mesh(devices.reshape((-1, 1, 1)), ("data", "attn_dp", "model"))
+
+
+# ---- Test for `attention` ----
+
+
+def _test_attention(monkeypatch, mesh, head_dim, use_sinks=False):
+    """
+    Tests the main `attention` function.
+
+    Verifies that:
+    1. It calls the `sharded_ragged_paged_attention` kernel with correct metadata.
+    2. The final outputs (kv_cache and attention output) have the correct shapes.
+    """
+    # 1. Arrange
+
+    # Create input tensors
+    q_dtype = jnp.float32
+    kv_dtype = jnp.float32
+    q = jnp.ones((TOTAL_TOKENS, NUM_HEADS, head_dim), dtype=q_dtype)
+    k = jnp.ones((TOTAL_TOKENS, NUM_KV_HEADS, head_dim), dtype=kv_dtype)
+    v = jnp.ones((TOTAL_TOKENS, NUM_KV_HEADS, head_dim), dtype=kv_dtype)
+    sinks = jnp.ones((NUM_HEADS, ), dtype=jnp.float32) if use_sinks else None
+
+    kv_cache_shape = get_kv_cache_shape_with_mesh(
+        mesh,
+        NUM_BLOCKS,
+        BLOCK_SIZE,
+        NUM_KV_HEADS,
+        head_dim,
+        kv_dtype,
+    )
+    kv_cache = jnp.zeros(kv_cache_shape, dtype=kv_dtype)
+
+    # Mock ragged_paged_attention to return a tensor of the correct shape
+    mock_paged_attn_kernel = MagicMock(return_value=(jnp.ones(
+        (TOTAL_TOKENS, NUM_HEADS, head_dim)), kv_cache), )
+
+    if head_dim == 64:
+        monkeypatch.setattr(
+            "tpu_inference.layers.common.attention_interface.ragged_paged_attention_hd64",
+            mock_paged_attn_kernel,
+        )
+    else:
+        monkeypatch.setattr(
+            "tpu_inference.layers.common.attention_interface.ragged_paged_attention",
+            mock_paged_attn_kernel,
+        )
+
+    # Create AttentionMetadata
+    attention_metadata = AttentionMetadata(
+        input_positions=jnp.arange(TOTAL_TOKENS, dtype=jnp.int32),
+        block_tables=jnp.zeros((MAX_NUM_SEQS * MAX_BLOCKS_PER_SEQ, ),
+                               dtype=jnp.int32),
+        seq_lens=jnp.array([5, 5, 0, 0], dtype=jnp.int32),
+        query_start_loc=jnp.array([0, 5, 10, 10, 10], dtype=jnp.int32),
+        request_distribution=jnp.array([0, 0, NUM_SEQS], dtype=jnp.int32),
+    )
+
+    # 2. Act
+    final_kv_cache, output = attention(
+        kv_cache=kv_cache,
+        q=q,
+        k=k,
+        v=v,
+        attention_metadata=attention_metadata,
+        mesh=mesh,
+        head_dim_original=head_dim,
+        sinks=sinks,
+    )
+
+    # 3. Assert
+    # Check that both mocked kernels were called
+    mock_paged_attn_kernel.assert_called_once()
+
+    # Check output shapes
+    assert final_kv_cache.shape == kv_cache.shape
+    assert output.shape == q.shape
+
+    # Check that the output is the one from our mock
+    assert jnp.all(output == 1.0)
+
+
+def test_attention(monkeypatch, mesh):
+    _test_attention(monkeypatch, mesh, 128)
+
+
+def test_attention_hd64(monkeypatch, mesh):
+    _test_attention(monkeypatch, mesh, 64)
+
+
+def test_attention_sink(monkeypatch, mesh):
+    _test_attention(monkeypatch, mesh, 64, True)
+
+
+def test_attention_sink_no_64_raises_error(monkeypatch, mesh):
+    with pytest.raises(
+            NotImplementedError,
+            match="Attention sink support is only available when head_dim==64"
+    ):
+        _test_attention(monkeypatch, mesh, 128, True)