Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Armazenamento de Vetores com FAISS

Aula 12 de 18 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. FAISS: Pesquisa de Vetores de Alto Desempenho
  2. Criar o Seu Primeiro Índice
  3. Escolher o Tipo de Índice Correto
  4. Consultar o Índice
  5. Mudar para Similaridade de Cosseno
  6. Quando o Corpus Se Torna Massivo
  7. Pontos-chave

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
  • IndexFlatL2 para corpora pequenos (menos de 100 mil vetores), pesquisa exata
  • IndexIVFFlat para corpora grandes, pesquisa aproximada mas rápida
  • Normalize os vetores e use IndexFlatIP para similaridade de cosseno
  • Guarde o índice em disco com faiss.write_index para evitar reconstruções