FAISS : a biblioteca por trás da pesquisa vectorielle

#Uma biblioteca, não uma base de dados

Costuma-se comparar o FAISS aos bancos de dados vetoriais como se fossem alternativas. São categorias diferentes. Um banco de dados vetorial é um serviço com API, armazenamento, filtragem e permissões. O FAISS é um componente: escrito em C++ com interfaces completas para Python e NumPy, ele recebe os vetores que você fornece, constrói um índice na memória e responde à pergunta “quais são os mais próximos deste?”. Vários bancos de dados vetoriais o utilizam, ou utilizam algo semelhante, internamente. O projeto é publicado sob a licença MIT, contava com mais de 41.000 estrelas no GitHub no fim de setembro de 2026, e seus autores indicam que alguns de seus métodos podem operar na escala de bilhões de vetores na memória principal de um único servidor.

A consequência prática é que escolher FAISS significa assumir todo o resto: salvar o índice no disco, recarregá-lo, manter o índice coerente com seus documentos, estabelecer a ligação entre a posição de um vetor e o texto de onde ele provém, e decidir o que acontece quando dois processos querem escrever ao mesmo tempo. Nada disso é fornecido por padrão; é uma escolha de arquitetura assumida, não um esquecimento do projeto.

#Os índices que importam

O conselho que economiza mais tempo: começar pela busca exata. Os índices aproximados existem para resolver um problema de escala; adotá-los antes de ter esse problema equivale a adquirir parâmetros para ajustar e uma métrica de recall para medir, em troca de milissegundos que ninguém percebeu. Na escala de um corpus local, a recuperação quase nunca é a etapa lenta — é a geração pelo modelo de linguagem que domina o tempo de resposta percebido pelo usuário final.

#O mínimo para começar em Python

1. 01
   Instalar a biblioteca

   pip install faiss-cpu instala o pacote oficial do PyPI (versão 1.15.1 no fim de setembro de 2026). Para a variante GPU, o projeto documenta uma instalação via conda: conda install -c pytorch -c nvidia -c conda-forge faiss-gpu=1.15.1.
2. 02
   Construir um índice exato

   index = faiss.IndexFlatL2(dimension) cria um índice de busca exata para vetores da dimensão do seu modelo de embedding.
3. 03
   Adicionar vetores

   index.add(vecteurs), onde vecteurs é um array NumPy de forma (n, dimension), com valores de ponto flutuante de 32 bits.
4. 04
   Consultar

   distances, indices = index.search(requete, k) retorna os k vizinhos mais próximos e suas distâncias; cabe a você associar indices aos trechos de texto originais.
5. 05
   Salvar e recarregar

   faiss.write_index(index, chemin) seguido de faiss.read_index(chemin) mantém o índice salvo em disco entre duas execuções, pois o FAISS não faz isso por conta própria.

#Escolher um índice com base no tamanho do corpus

O wiki oficial do projeto fornece referências precisas, expressas como strings para serem passadas à sua fábrica de índice (index_factory). Com menos de um milhão de vetores, IVF_K é suficiente, com K escolhido entre 4×√N e 16×√N de acordo com o número de vetores N, e um conjunto de treinamento composto por 30×K a 256×K vetores. Entre 1 e 10 milhões, a combinação recomendada é IVF65536_HNSW32, que utiliza HNSW para acelerar a atribuição aos clusters. Entre 10 e 100 milhões, IVF262144_HNSW32; acima disso, até um bilhão, IVF1048576_HNSW32 — nesse estágio, o treinamento torna-se consideravelmente mais lento e é geralmente executado em GPU enquanto o restante roda em CPU.

Para um corpus documental local — de alguns milhares a várias centenas de milhares de trechos de texto — esses indicadores confirmam principalmente que estamos longe do limiar em que um índice aproximado se torna necessário: um índice exato ou, no pior dos casos, um simples IVF_K cobrem quase todos os casos reais, e configurações com várias centenas de milhares de entradas de treinamento permanecem fora do alcance do uso documental comum.

#A memória em números

Um vetor de 1.024 dimensões em ponto flutuante de 32 bits ocupa aproximadamente 4 KB. Um milhão de vetores, então, é cerca de 4 GB, antes mesmo da estrutura de índice. Para um índice HNSW, especificamente, o wiki oficial fornece a fórmula (d×4 + M×2×4) em bytes por vetor, onde d é a dimensão e M o número de ligações por vetor (entre 4 e 64: mais ligações, mais precisão, mais memória). Essa aritmética define a maioria das arquiteturas: é por isso que a compressão existe e é por isso que uma máquina que hospeda também um modelo de linguagem tem menos margem do que se imagina.

Quanto à compressão, a quantização de produto (PQ) codifica cada vetor em M bytes, normalmente no máximo 64 — acima disso, a quantização escalar (SQ) costuma ser tão precisa quanto a PQ e mais rápida. Quando a qualidade da compressão realmente importa, o guia oficial recomenda adicionar uma transformação OPQ antes da quantização: ela primeiro reduz a dimensão do vetor por meio de uma transformação linear que o torna mais fácil de comprimir e depois aplica a quantização de produto ao resultado. É uma etapa adicional de cálculo durante a indexação, mas reduz a perda de precisão em comparação com a quantização de produto direta, mantendo o mesmo tamanho de código. RaBitQ, a opção de compressão máxima, chega a cerca de (d/8 + 8) bytes por vetor, mantendo apenas um bit por dimensão, ao custo de uma etapa de rotação aleatória necessária para manter uma precisão adequada; existem variantes com vários bits por dimensão para recuperar um pouco de precisão em troca de um pouco mais de armazenamento.

#A função ausente que decide tudo

As perguntas reais têm condições: apenas os documentos desse cliente, apenas após essa data, apenas o que essa pessoa tem direito de ler. O FAISS não possui nenhuma noção de metadados. A solução alternativa habitual — recuperar mais resultados do que o necessário e depois filtrar em Python — falha de uma maneira específica: se os cinquenta melhores resultados pertencerem todos a outro departamento, a filtragem não deixa nenhum resultado, e seu assistente afirma não ter encontrado nenhuma informação, em vez de dizer que não encontrou nenhuma que você possa ver.

A filtragem por permissões, em especial, não deve ser implementada após a recuperação. Esse é o argumento prático mais forte a favor de um sistema que filtra durante a busca: um banco de dados vetorial, ou vetores no PostgreSQL, em que a filtragem é feita com uma cláusula WHERE.

• pgvector: filtrar durante a busca, em SQL
• Qdrant: o serviço dedicado
• Milvus: o banco de dados vetorial para grandes volumes
• Cadeia RAG completa
• O kit RAG local QuelLLM
• Fonte: repositório oficial FAISS no GitHub
• Fonte: guia oficial de escolha de índice
• Fonte: início rápido FAISS em Python

#Quando FAISS é a escolha certa

Uma aplicação de um único processo

Que carrega um índice ao iniciar e o consulta: uma ferramenta de desktop, um processamento em lote, um caderno de anotações.

Corpus fixo

Reconstruído conforme um cronograma, em vez de ser atualizado continuamente.

Nenhum filtro por usuário

Ou uma filtragem tão pouco granular que um índice por categoria ainda seja razoável.

Uma latência crítica

Quando o custo de uma ida e volta pela rede até um banco de dados é exatamente o que você deseja eliminar, por exemplo, em uma ferramenta embarcada sem conexão garantida.

Fora desses casos, o serviço que evitamos instalar geralmente custa menos, ao longo do tempo, do que o código de persistência, filtragem e concorrência que acabamos tendo que reescrever por conta própria à medida que o projeto cresce.

Um último ponto útil antes de decidir: vários bancos de dados vetoriais que você encontrará em outros contextos não substituem o FAISS por mágica; eles o encapsulam ou se inspiram nas mesmas famílias de índices (IVF, HNSW, quantização de produto), oferecendo uma API de rede, um sistema de persistência gerenciado e um mecanismo de filtragem. Entender o FAISS equivale, portanto, a entender boa parte do funcionamento interno dos próprios bancos de dados vetoriais — um desvio útil mesmo que o projeto final use Qdrant ou Milvus em vez de usar o FAISS diretamente, porque os mesmos compromissos entre memória e precisão aparecem com outros nomes de parâmetros.

#FAQ