Implementation:Neuml Txtai Muvera

Knowledge Sources	Neuml_Txtai
Domains	Vector_Encoding, Retrieval
Last Updated	2026-02-09 17:00 GMT

Overview

The Muvera class implements the MUVERA algorithm for transforming multi-vector collections into fixed-dimensional single-vector encodings, enabling efficient retrieval with standard vector indexes.

Description

The Muvera class implements the algorithm described in the paper "Multi-Vector Retrieval via Fixed Dimensional Encodings." Multi-vector representations (such as those produced by ColBERT-style models where each token gets its own vector) are powerful but require specialized retrieval infrastructure. Muvera solves this by projecting multi-vector collections into a single fixed-dimensional vector through a combination of random hashing, dimensionality reduction via random projections, and repetition-based averaging. This allows multi-vector models to be used with standard single-vector ANN indexes while preserving much of the retrieval quality.

Usage

Use the Muvera class when you want to leverage multi-vector retrieval models (like ColBERT) but need to use standard single-vector similarity search infrastructure. It bridges the gap between the expressiveness of per-token embeddings and the efficiency of single-vector indexes. Configure it through txtai's pooling configuration when using multi-vector embedding models.

Code Reference

Source Location

• Repository: Neuml_Txtai
• File: src/python/txtai/models/pooling/muvera.py
• Lines: 1-164

Signature

class Muvera:
    def __init__(self, repetitions=20, hashes=5, projection=16, seed=42):
        """
        Creates a new Muvera instance.

        Args:
            repetitions: number of independent repetitions for averaging (default: 20)
            hashes: number of hash buckets for token assignment (default: 5)
            projection: target dimension for random projection per bucket (default: 16)
            seed: random seed for reproducibility (default: 42)
        """

    def __call__(self, data, category):
        """
        Transforms a multi-vector collection into a single fixed-dimensional vector.

        Args:
            data: multi-vector input, shape (n_tokens, embedding_dim)
            category: category identifier (e.g., 'query' or 'document')

        Returns:
            single fixed-dimensional vector encoding
        """

    def random(self, shape):
        """Generates a random projection matrix of the specified shape."""

    def reducer(self, vectors):
        """Reduces vectors via random projection to target dimension."""

Import

from txtai.models.pooling import Muvera

I/O Contract

Inputs

Name	Type	Required	Description
repetitions	int	No	Number of independent hash-and-project repetitions for robust averaging (default: 20)
hashes	int	No	Number of hash buckets each token is assigned to (default: 5)
projection	int	No	Target dimensionality for the random projection within each bucket (default: 16)
seed	int	No	Random seed for reproducible projections (default: 42)
data	numpy.ndarray	Yes (for __call__)	Multi-vector input of shape (n_tokens, embedding_dim) representing per-token embeddings
category	str	Yes (for __call__)	Category string such as 'query' or 'document', used to select appropriate projection parameters

Outputs

Name	Type	Description
vector	numpy.ndarray	Single fixed-dimensional vector of size (repetitions * hashes * projection,) encoding the multi-vector input

Usage Examples

Basic Usage

import numpy as np
from txtai.models.pooling import Muvera

# Create Muvera encoder with default settings
muvera = Muvera(repetitions=20, hashes=5, projection=16, seed=42)

# Simulate multi-vector output (e.g., 15 tokens, each 128-dimensional)
token_embeddings = np.random.rand(15, 128).astype(np.float32)

# Encode as a single fixed-dimensional vector
single_vector = muvera(token_embeddings, category="document")
print(f"Input: {token_embeddings.shape} -> Output: {single_vector.shape}")
# Input: (15, 128) -> Output: (1600,)  # 20 * 5 * 16 = 1600

With txtai Embeddings

from txtai.embeddings import Embeddings

# Configure embeddings with a multi-vector model and Muvera pooling
embeddings = Embeddings(
    path="colbert-model-name",
    method="pooling",
    pooling={
        "method": "muvera",
        "repetitions": 20,
        "hashes": 5,
        "projection": 16
    }
)

# Index documents - Muvera converts multi-vector to single-vector automatically
embeddings.index([
    "Multi-vector retrieval with efficient indexing",
    "Fixed dimensional encodings for scalable search",
    "Token-level embeddings aggregated into single vectors"
])

# Search uses standard single-vector similarity
results = embeddings.search("efficient multi-vector search", 2)
print(results)

Related Pages

• Principle:Neuml_Txtai_Multi_Vector_Encoding