Vector Store con FAISS
In questa pagina
FAISS: Ricerca Vettoriale ad Alte Prestazioni
Hai calcolato e salvato i tuoi embedding, ma una matrice NumPy non è un motore di ricerca: confrontare una query con 100.000 vettori usando un ciclo Python richiederebbe diversi secondi per domanda. FAISS (Facebook AI Similarity Search) risolve esattamente questo problema. Questa libreria open-source di Meta è progettata per la ricerca di similarità su grandi insiemi di vettori; è veloce, efficiente in termini di memoria e funziona altrettanto bene con poche centinaia di vettori come con milioni. L’installazione richiede un solo comando. faiss-cpu è sufficiente nella stragrande maggioranza dei casi; faiss-gpu è giustificato solo per volumi in cui il calcolo diventa il collo di bottiglia.
# pip install faiss-cpu
# or faiss-gpu for GPU acceleration
import faiss
import numpy as np
Crea il tuo primo indice
L’indice più semplice è IndexFlatL2, che esegue una ricerca esaustiva utilizzando la distanza L2 (euclidea). “Esaustiva” significa che confronta effettivamente la query con ogni vettore memorizzato: nessuna approssimazione, quindi nessun risultato perso. Lo inizializzi con la dimensione del vettore—1024 per mistral-embed, un valore che leggi direttamente dalla forma della matrice invece di codificarlo manualmente. La conversione in float32 non è opzionale: FAISS rifiuta il float64 prodotto di default da NumPy, e dimenticare questo dettaglio è il primo errore che ogni principiante incontra.
# Assume our embeddings are a NumPy matrix
# embeddings.shape = (n_chunks, 1024)
# Create the index
dimension = embeddings.shape[1] # 1024 for mistral-embed
index = faiss.IndexFlatL2(dimension)
# Add the vectors
index.add(embeddings.astype(np.float32)) # FAISS requires float32
print(f"Index created: {index.ntotal} vectors of dimension {dimension}")
Scegliere il tipo di indice giusto
FAISS non offre un singolo indice, ma una famiglia di essi, e la scelta implica un compromesso tra accuratezza e velocità. I primi due, IndexFlatL2 e IndexFlatIP, sono esatti: differiscono solo per la metrica utilizzata, distanza euclidea per uno, prodotto scalare per l’altro. IndexIVFFlat cambia la logica partizionando lo spazio in cluster e cercando solo quelli più promettenti, il che accelera significativamente la ricerca al costo di una leggera perdita di recall—e richiede un addestramento preliminare sui tuoi dati. Infine, IndexHNSWFlat costruisce un grafo dei vicini e si dimostra molto veloce durante le query, con il parametro 32 che imposta qui il numero di vicini mantenuti per nodo.
dimension = 1024
# 1. IndexFlatL2: Exact search, L2 distance
# Most accurate, but slowest for large volumes
index_flat_l2 = faiss.IndexFlatL2(dimension)
# 2. IndexFlatIP: Exact search, dot product (inner product)
# Use with normalized vectors for cosine similarity
index_flat_ip = faiss.IndexFlatIP(dimension)
# 3. IndexIVFFlat: Approximate search with partitioning
# Faster for large volumes, slight loss of accuracy
nlist = 100 # Number of partitions (clusters)
quantizer = faiss.IndexFlatL2(dimension)
index_ivf = faiss.IndexIVFFlat(quantizer, dimension, nlist)
# Requires training before use:
# index_ivf.train(embeddings)
# index_ivf.add(embeddings)
# 4. IndexHNSWFlat: Neighbor graph (very fast search)
index_hnsw = faiss.IndexHNSWFlat(dimension, 32) # 32 = number of neighbors
Interrogare l’indice
La ricerca avviene in tre passaggi. Innanzitutto, codifica la domanda dell’utente con lo stesso modello del corpus: una query codificata da un modello diverso produrrebbe distanze prive di senso. FAISS restituisce quindi due array paralleli: le distanze e gli indici dei k vicini più prossimi. Questi indici sono posizioni nella tua lista di chunk: è qui che la disciplina della lezione precedente paga, poiché l’allineamento tra la matrice e i metadati è ciò che ti permette di risalire al testo e alla sua fonte. Il test if idx >= 0 copre il caso in cui l’indice contenga meno di k vettori, nel qual caso FAISS riempie gli spazi mancanti con -1.
from mistralai.client import Mistral
client = Mistral(api_key=api_key)
def search_index(query, index, chunks, k=5):
"""Search for chunks closest to a query."""
# 1. Encode the query
response = client.embeddings.create(
model="mistral-embed",
inputs=[query],
)
query_vector = np.array([response.data[0].embedding], dtype=np.float32)
# 2. Search in FAISS
distances, indices = index.search(query_vector, k)
# 3. Format results
results = []
for i, (dist, idx) in enumerate(zip(distances[0], indices[0])):
if idx >= 0: # FAISS returns -1 if not enough results
results.append({
"rank": i + 1,
"distance": float(dist),
"text": chunks[idx]["text"],
"source": chunks[idx].get("source", ""),
})
return results
# Example search
results = search_index("How does RAG work?", index, chunks)
for r in results:
print(f" #{r['rank']} (dist: {r['distance']:.4f}) [{r['source']}]")
print(f" {r['text'][:100]}...")
Passare alla similarità del coseno
FAISS non offre un indice “coseno” esplicito, ma l’algebra fornisce un equivalente gratuito: per vettori con norma 1, il prodotto scalare è il coseno. Devi semplicemente dividere ogni vettore per la sua norma, quindi usare IndexFlatIP. Questo cambiamento è tutt’altro che teorico: la distanza L2 è sensibile alla lunghezza del vettore, quindi un chunk molto lungo può finire artificialmente lontano da una query breve anche se i loro argomenti corrispondono. Il coseno misura solo l’orientamento, quindi il significato, ed è generalmente ciò che vuoi confrontare.
def create_cosine_index(embeddings):
"""Create a FAISS index with cosine similarity."""
# Normalize vectors (L2 norm = 1)
norms = np.linalg.norm(embeddings, axis=1, keepdims=True)
normalized = (embeddings / norms).astype(np.float32)
# Use IndexFlatIP (dot product = cosine for normalized vectors)
dimension = normalized.shape[1]
index = faiss.IndexFlatIP(dimension)
index.add(normalized)
return index
cosine_index = create_cosine_index(embeddings)
Come per gli embedding, l’indice persiste su disco. faiss.write_index produce un file binario che faiss.read_index ricarica così com’è, incluse le strutture interne—cosa che conta soprattutto per gli indici addestrati, dove la ricostruzione dovrebbe altrimenti essere rifatta.
# Save
faiss.write_index(index, "rag_faiss.index")
print("FAISS index saved")
# Load
index_loaded = faiss.read_index("rag_faiss.index")
print(f"Index loaded: {index_loaded.ntotal} vectors")
Quando il corpus diventa massiccio
A partire da alcune centinaia di migliaia di vettori, la ricerca esaustiva diventa troppo lenta e l’indice IVF (Inverted File) diventa necessario. Il suo ciclo di vita include un passaggio che gli indici piatti non hanno: l’addestramento, che analizza la distribuzione dei tuoi dati per posizionare i centroidi di partizione nlist. Segue l’aggiunta dei vettori, quindi la sintonizzazione di nprobe, la manopola che decide quante partizioni verranno esplorate per query. Aumentare nprobe migliora la recall e rallenta la ricerca; questo è il parametro che regolerai misurando, su un insieme rappresentativo di domande, il punto in cui i risultati smettono di migliorare.
def create_ivf_index(embeddings, nlist=100, nprobe=10):
"""Create an IVF index for large volumes."""
dimension = embeddings.shape[1]
data = embeddings.astype(np.float32)
# Create the quantizer and IVF index
quantizer = faiss.IndexFlatL2(dimension)
index = faiss.IndexIVFFlat(quantizer, dimension, nlist)
# Train the index (required for IVF)
print("Training index...")
index.train(data)
# Add the vectors
index.add(data)
# Number of partitions to explore during search
index.nprobe = nprobe # Higher = more accurate, slower
print(f"IVF index created: {index.ntotal} vectors, {nlist} partitions")
return index
# For 100K+ vectors
# large_index = create_ivf_index(embeddings, nlist=256, nprobe=20)
Punti chiave
- FAISS è lo standard per la ricerca vettoriale veloce
IndexFlatL2per piccoli corpus (sotto i 100k vettori), ricerca esattaIndexIVFFlatper grandi corpus, ricerca approssimata ma veloce- Normalizza i vettori e usa
IndexFlatIPper la similarità del coseno - Salva l’indice su disco con
faiss.write_indexper evitare di ricostruirlo