Implementation:Guardrails ai Guardrails Faiss

Knowledge Sources	Guardrails
Domains	Vector Database, Similarity Search
Last Updated	2026-02-14 00:00 GMT

Overview

Provides a concrete vector database implementation backed by Facebook's FAISS library for efficient similarity search.

Description

The Faiss class extends VectorDBBase to provide vector storage and similarity search using the FAISS (Facebook AI Similarity Search) library. It supports multiple index types and search methods:

Index Creation:

• new_flat_l2_index -- Creates an IndexFlatL2 (exact L2/Euclidean distance search) for a given vector dimensionality.
• new_flat_ip_index -- Creates an IndexFlatIP (exact inner product/cosine similarity search) for a given vector dimensionality.
• new_flat_l2_index_from_embedding -- Creates an L2 index pre-populated with an initial set of embedding vectors, inferring the dimensionality from the first vector.

Search Operations:

• similarity_search_vector -- Performs a k-nearest-neighbor search using index.search, returning the indices of the k most similar vectors.
• similarity_search_vector_with_threshold -- Performs a range search using index.range_search, returning indices of vectors within a distance threshold, sorted by distance and limited to k results.

Persistence:

• save -- Writes the FAISS index to disk using faiss.write_index.
• load -- Reads a FAISS index from disk using faiss.read_index and returns a new Faiss instance.

Vector Management:

• add_vectors -- Adds vectors to the index as a NumPy array via index.add.
• last_index -- Returns the total number of vectors in the index via index.ntotal.

The faiss library is an optional dependency; an ImportError is raised at construction time if it is not installed.

Usage

Use the Faiss class when you need efficient vector similarity search for validation scenarios such as checking semantic similarity, deduplication, or nearest-neighbor lookups. Choose the appropriate index type (L2 for Euclidean distance, IP for inner product) based on your embedding model and similarity metric requirements.

Code Reference

Source Location

• Repository: Guardrails
• File: guardrails/vectordb/faiss.py

Signature

class Faiss(VectorDBBase):
    def __init__(
        self,
        index: "Index",
        embedder: EmbeddingBase,
        path: Optional[str] = None,
    ) -> None: ...

    @classmethod
    def new_flat_l2_index(
        cls,
        vector_dim: int,
        embedder: EmbeddingBase,
        path: Optional[str] = None,
    ) -> "Faiss": ...

    @classmethod
    def new_flat_ip_index(
        cls,
        vector_dim: int,
        embedder: EmbeddingBase,
        path: Optional[str] = None,
    ) -> "Faiss": ...

    @classmethod
    def new_flat_l2_index_from_embedding(
        cls,
        embedding: List[List[float]],
        embedder: EmbeddingBase,
        path: Optional[str] = None,
    ) -> "Faiss": ...

    @classmethod
    def load(cls, path: str, embedder: EmbeddingBase) -> "Faiss": ...

    def save(self, path: Optional[str] = None) -> None: ...

    def similarity_search_vector(self, vector: List[float], k: int) -> List[int]: ...

    def similarity_search_vector_with_threshold(
        self, vector: List[float], k: int, threshold: float
    ) -> List[int]: ...

    def add_vectors(self, vectors: List[List[float]]) -> None: ...

    def last_index(self) -> int: ...

Import

from guardrails.vectordb.faiss import Faiss

I/O Contract

__init__

Parameter	Type	Description
index	faiss.Index	A pre-built FAISS index object
embedder	EmbeddingBase	Embedding model for text-to-vector conversion
path	Optional[str]	Optional path for persistence

Raises: ImportError if faiss is not installed.

new_flat_l2_index / new_flat_ip_index

Parameter	Type	Description
vector_dim	int	Dimensionality of the vectors to be indexed
embedder	EmbeddingBase	Embedding model instance
path	Optional[str]	Optional persistence path

Returns: Faiss -- A new instance with an empty FAISS index.

new_flat_l2_index_from_embedding

Parameter	Type	Description
embedding	List[List[float]]	Initial set of vectors to populate the index
embedder	EmbeddingBase	Embedding model instance
path	Optional[str]	Optional persistence path

Returns: Faiss -- A new instance with pre-populated vectors.

load

Parameter	Type	Description
path	str	File path to load the FAISS index from
embedder	EmbeddingBase	Embedding model instance

Returns: Faiss -- A new instance loaded from disk.

similarity_search_vector

Parameter	Type	Description
vector	List[float]	The query vector
k	int	Number of nearest neighbors to return

Returns: List[int] -- Indices of the k nearest vectors.

similarity_search_vector_with_threshold

Parameter	Type	Description
vector	List[float]	The query vector
k	int	Maximum number of results
threshold	float	Distance threshold for range search

Returns: List[int] -- Indices of vectors within the threshold, sorted by distance, limited to k.

add_vectors

Parameter	Type	Description
vectors	List[List[float]]	Vectors to add to the index

Returns: None

last_index

Returns: int -- Total number of vectors in the FAISS index (index.ntotal).

Usage Examples

from guardrails.vectordb.faiss import Faiss
from guardrails.embedding import EmbeddingBase

# Create an embedder (implementation-specific)
embedder = ...  # an EmbeddingBase instance

# Create a new L2 index for 128-dimensional vectors
db = Faiss.new_flat_l2_index(vector_dim=128, embedder=embedder)

# Add text data
db.add_texts(["Hello world", "Guardrails AI", "Vector similarity search"])

# Search by text
results = db.similarity_search("search query", k=2)
print(results)  # [index1, index2]

# Save to disk
db.save("/path/to/index.faiss")

# Load from disk
loaded_db = Faiss.load("/path/to/index.faiss", embedder=embedder)
print(loaded_db.last_index())  # 3

from guardrails.vectordb.faiss import Faiss

# Create from existing embeddings
embeddings = [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6], [0.7, 0.8, 0.9]]
db = Faiss.new_flat_l2_index_from_embedding(
    embedding=embeddings,
    embedder=embedder,
)

# Threshold-based search
results = db.similarity_search_vector_with_threshold(
    vector=[0.1, 0.2, 0.3],
    k=5,
    threshold=1.0,
)
print(results)  # indices of vectors within distance 1.0

Related Pages

• Guardrails_ai_Guardrails_VectorDBBase -- The abstract base class that Faiss implements
• Guardrails_ai_Guardrails_EmbeddingBase -- The embedding interface used for text-to-vector conversion