faiss

name	faiss
description	Facebook AI Similarity Search — ultra-fast vector similarity search for large-scale local embedding retrieval without a database server.
version	1.0.0
author	hermes-CCC (ported from Hermes Agent by NousResearch)
license	MIT
metadata	{"hermes":{"tags":["RAG","FAISS","Vector-Search","Embeddings","Local","Fast","Facebook"],"related_skills":["chroma","qdrant","pinecone"]}}

FAISS — Fast Vector Similarity Search

FAISS (Facebook AI Similarity Search) is a library for efficient similarity search over large collections of vectors. No server required — runs entirely in-process.

When to Use FAISS

• Millions of vectors, need maximum speed
• Can't run a server (embedded use case)
• Research / prototyping at scale
• Custom index types (HNSW, IVF, PQ)

Setup

pip install faiss-cpu        # CPU only
pip install faiss-gpu        # GPU (requires CUDA)
pip install sentence-transformers numpy

---

Basic Flat Index (Exact Search)

import faiss
import numpy as np
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("all-MiniLM-L6-v2")  # dim=384
DIM = 384

# Build index
documents = [
    "Python async programming",
    "Machine learning with PyTorch",
    "Docker container management",
    "GraphQL API design",
]

embeddings = model.encode(documents).astype(np.float32)

# Flat L2 index (exact, brute force)
index = faiss.IndexFlatL2(DIM)
index.add(embeddings)
print(f"Index size: {index.ntotal}")

# Search
query = "how to do async in Python?"
q_vec = model.encode([query]).astype(np.float32)

distances, indices = index.search(q_vec, k=3)
for i, idx in enumerate(indices[0]):
    print(f"[{distances[0][i]:.3f}] {documents[idx]}")

---

Cosine Similarity (Normalize first)

# For cosine similarity: normalize vectors, use IndexFlatIP (inner product)
def normalize(vecs):
    norms = np.linalg.norm(vecs, axis=1, keepdims=True)
    return vecs / np.maximum(norms, 1e-8)

embeddings_norm = normalize(embeddings.astype(np.float32))
index_cos = faiss.IndexFlatIP(DIM)
index_cos.add(embeddings_norm)

q_norm = normalize(model.encode([query]).astype(np.float32))
scores, indices = index_cos.search(q_norm, k=3)

---

IVF Index (Fast Approximate Search)

# For large datasets (>100k vectors)
N_CLUSTERS = 100  # sqrt(N) is a good heuristic

quantizer = faiss.IndexFlatL2(DIM)
index_ivf = faiss.IndexIVFFlat(quantizer, DIM, N_CLUSTERS)

# Must train before adding
index_ivf.train(embeddings)
index_ivf.add(embeddings)
index_ivf.nprobe = 10  # search 10 clusters (higher = more accurate, slower)

distances, indices = index_ivf.search(q_vec, k=5)

---

HNSW Index (Best Speed/Accuracy Tradeoff)

index_hnsw = faiss.IndexHNSWFlat(DIM, 32)  # 32 = M parameter
index_hnsw.add(embeddings)

distances, indices = index_hnsw.search(q_vec, k=5)

---

Save and Load Index

# Save
faiss.write_index(index, "my_index.faiss")

# Load
index = faiss.read_index("my_index.faiss")

---

With Metadata (store separately)

import pickle

# FAISS only stores vectors — store metadata separately
metadata = [{"id": i, "text": doc} for i, doc in enumerate(documents)]

# Save both
faiss.write_index(index, "vectors.faiss")
with open("metadata.pkl", "wb") as f:
    pickle.dump(metadata, f)

# Load and query
index = faiss.read_index("vectors.faiss")
with open("metadata.pkl", "rb") as f:
    metadata = pickle.load(f)

distances, indices = index.search(q_vec, k=3)
for idx in indices[0]:
    print(metadata[idx]["text"])

---

GPU Acceleration

res = faiss.StandardGpuResources()
index_gpu = faiss.index_cpu_to_gpu(res, 0, index)  # GPU 0
distances, indices = index_gpu.search(q_vec, k=5)

---

Index Selection Guide

Index	Size	Speed	Accuracy	Use Case
IndexFlatL2	Any	Slow	100%	<100k vectors, exact needed
IndexFlatIP	Any	Slow	100%	Cosine similarity
IndexIVFFlat	Large	Fast	~95%	100k–10M vectors
IndexHNSWFlat	Medium	Very fast	~99%	Best general choice
IndexIVFPQ	Huge	Fastest	~90%	Billions, memory-constrained