Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Vector Store con FAISS

Lezione 12 di 18 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. FAISS: Ricerca Vettoriale ad Alte Prestazioni
  2. Crea il tuo primo indice
  3. Scegliere il tipo di indice giusto
  4. Interrogare l’indice
  5. Passare alla similarità del coseno
  6. Quando il corpus diventa massiccio
  7. Punti chiave

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
  • IndexFlatL2 per piccoli corpus (sotto i 100k vettori), ricerca esatta
  • IndexIVFFlat per grandi corpus, ricerca approssimata ma veloce
  • Normalizza i vettori e usa IndexFlatIP per la similarità del coseno
  • Salva l’indice su disco con faiss.write_index per evitare di ricostruirlo