Armazenamento de Vetores com FAISS
Nesta página
FAISS: Pesquisa de Vetores de Alto Desempenho
Já calculou e guardou os seus embeddings, mas uma matriz NumPy não é um motor de busca: comparar uma consulta a 100.000 vetores usando um ciclo em Python levaria vários segundos por pergunta. O FAISS (Facebook AI Similarity Search) resolve exatamente este problema. Esta biblioteca de código aberto da Meta foi desenhada para pesquisa de similaridade em grandes conjuntos de vetores; é rápida, eficiente em memória e funciona tão bem com algumas centenas de vetores como com milhões. A instalação requer apenas um comando. O faiss-cpu é suficiente na vasta maioria dos casos; o faiss-gpu só se justifica para volumes onde o cálculo se torna o gargalo.
# pip install faiss-cpu
# or faiss-gpu for GPU acceleration
import faiss
import numpy as np
Criar o Seu Primeiro Índice
O índice mais simples é o IndexFlatL2, que realiza uma pesquisa exaustiva usando a distância L2 (Euclidiana). “Exaustiva” significa que compara efetivamente a consulta a todos os vetores armazenados: sem aproximação, logo sem resultados perdidos. Inicializa-o com a dimensão do vetor — 1024 para o mistral-embed, um valor que lê diretamente da forma da matriz em vez de o codificar rigidamente. A conversão para float32 não é opcional: o FAISS rejeita o float64 que o NumPy produz por predefinição, e esquecer este detalhe é o primeiro erro que todos os iniciantes cometem.
# 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}")
Escolher o Tipo de Índice Correto
O FAISS não oferece um único índice, mas uma família deles, e a escolha envolve um compromisso entre precisão e velocidade. Os dois primeiros, IndexFlatL2 e IndexFlatIP, são exatos: diferem apenas na métrica utilizada, distância euclidiana para um, produto escalar para o outro. O IndexIVFFlat altera a lógica ao particionar o espaço em clusters e pesquisar apenas os mais promissores, o que acelera significativamente a pesquisa ao custo de uma ligeira perda de recall — e exige treino prévio nos seus dados. Por fim, o IndexHNSWFlat constrói um grafo de vizinhos e revela-se muito rápido durante as consultas, sendo que o parâmetro 32 define aqui o número de vizinhos retidos por nó.
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
Consultar o Índice
A pesquisa ocorre em três passos. Primeiro, codifique a pergunta do utilizador com o mesmo modelo que o do corpus — uma consulta codificada por um modelo diferente produziria distâncias sem sentido. O FAISS devolve depois dois vetores paralelos: as distâncias e os índices dos k vizinhos mais próximos. Estes índices são posições na sua lista de fragmentos: é aqui que a disciplina da lição anterior compensa, já que o alinhamento entre a matriz e os metadados é o que lhe permite rastrear o texto e a sua origem. O teste if idx >= 0 cobre o caso em que o índice contém menos de k vetores, situação em que o FAISS preenche os lugares em falta com -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]}...")
Mudar para Similaridade de Cosseno
O FAISS não oferece um índice “cosseno” explícito, mas a álgebra fornece um equivalente gratuito: para vetores com norma 1, o produto escalar é o cosseno. Basta dividir cada vetor pela sua norma e usar o IndexFlatIP. Esta alteração está longe de ser teórica: a distância L2 é sensível ao comprimento do vetor, pelo que um fragmento muito longo pode acabar artificialmente distante de uma consulta curta, mesmo que os tópicos coincidam. O cosseno mede apenas a orientação, logo o significado, e é geralmente isso que deseja comparar.
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)
Tal como com os embeddings, o índice persiste em disco. O faiss.write_index produz um ficheiro binário que o faiss.read_index recarrega tal qual, incluindo as estruturas internas — o que é crucial para índices treinados, onde a reconstrução teria de ser refeita caso contrário.
# 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 o Corpus Se Torna Massivo
A partir de várias centenas de milhares de vetores, a pesquisa exaustiva torna-se demasiado lenta e o índice IVF (Inverted File) torna-se necessário. O seu ciclo de vida inclui um passo que os índices planos não têm: o treino, que analisa a distribuição dos seus dados para posicionar os centróides das partições nlist. Segue-se a adição dos vetores e depois o ajuste do nprobe, o controlo que decide quantas partições serão exploradas por consulta. Aumentar o nprobe melhora o recall e desacelera a pesquisa; este é o parâmetro que ajustará medindo, num conjunto representativo de perguntas, o ponto em que os resultados deixam de melhorar.
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)
Pontos-chave
- O FAISS é o padrão para pesquisa rápida de vetores
IndexFlatL2para corpora pequenos (menos de 100 mil vetores), pesquisa exataIndexIVFFlatpara corpora grandes, pesquisa aproximada mas rápida- Normalize os vetores e use
IndexFlatIPpara similaridade de cosseno - Guarde o índice em disco com
faiss.write_indexpara evitar reconstruções