Busca full-text Python com índice invertido local - código colorido na tela representando indexação de dados

Índice Invertido Local em Python Puro: O Buscador Full-Text que Indexa Seus Arquivos .md em Milissegundos (Sem Elasticsearch)

PorOlivetto

Você tem 847 arquivos markdown espalhados em 23 pastas. Sabe que aquele tutorial sobre configuração do Neovim está em algum lugar, mas o grep te devolve 47 resultados e você perdeu 15 minutos lendo arquivos irrelevantes. Se isso te soa familiar, você precisa de um índice invertido.

Não, não estamos falando de Elasticsearch, Algolia ou qualquer SaaS que cobra por query. Estamos falando de uma estrutura de dados que existe desde os anos 60, que o Google usou nos primeiros dias, e que você pode implementar em Python puro com menos de 200 linhas de código. Um buscador full-text local que indexa seus documentos, entende stopwords, aplica stemming básico e te devolve resultados ranqueados em milissegundos. Sem dependências. Sem servidor. Sem conta na nuvem.

O Problema Real: Por que grep Não é Suficiente

O grep é fantástico para busca literal. Mas busca full-text é outra coisa. Quando você digita “configurar neovim”, você quer encontrar:

  • Arquivos que mencionam “configuração” E “neovim” (não necessariamente lado a lado)
  • Documentos onde “neovim” aparece no título ou nos primeiros parágrafos (mais relevante)
  • Resultados que mencionam “vim” como sinônimo (stemming)
  • Excluir arquivos que só falam “não use neovim” (stopwords e contexto)

O grep faz busca de substring. Um índice invertido faz busca semântica básica. A diferença é como procurar uma palavra no dicionário vs. folhear todas as páginas.

O que é um Índice Invertido (e Por que Funciona)

Um índice invertido é exatamente o que o nome sugere: em vez de mapear “documento → palavras”, você mapeia “palavra → documentos”. Pense no índice remissivo de um livro:

Python .............. págs 12, 45, 78, 123
índice .............. págs 23, 67, 89
invertido ........... págs 23, 67, 91
busca ............... págs 5, 12, 34, 56, 78

Quando você busca “índice invertido”, o sistema faz a interseção: documentos que têm AMBAS as palavras. Resultado: páginas 23 e 67. Pronto. Sem ler o livro inteiro.

Monitor exibindo linhas de código coloridas para indexação e busca full-text em Python

No nosso caso, cada “página” é um arquivo .md, e em vez de só listar onde a palavra aparece, guardamos também a frequência (TF – Term Frequency) e a raridade (IDF – Inverse Document Frequency). Isso permite ranquear: documentos onde a palavra é frequente e rara no corpus sobem no ranking.

Arquitetura do Buscador Local

Vamos construir um sistema com 4 componentes:

  1. Tokenizer: quebra texto em tokens (palavras normalizadas)
  2. Indexador: constrói o índice invertido a partir de arquivos
  3. Buscador: consulta o índice e retorna resultados ranqueados
  4. Persistência: salva o índice em JSON para não reindexar toda vez

A estrutura final:

meu_buscador/
├── indexer.py          # Indexador e persistência
├── search.py           # Buscador com ranking TF-IDF
├── tokenizer.py        # Tokenização e normalização
└── data/
    └── index.json      # Índice serializado

Implementação: Tokenizer com Stopwords e Stemming

O primeiro passo é transformar texto bruto em tokens limpos. Ignoramos stopwords (palavras comuns que não agregam valor) e aplicamos stemming básico (reduzir “configurando” para “configur”):

import re
from typing import List

STOPWORDS_PT = {
    'a', 'o', 'e', 'de', 'da', 'do', 'em', 'um', 'uma', 'os', 'as',
    'para', 'com', 'por', 'no', 'na', 'nos', 'nas', 'que', 'se',
    'não', 'ao', 'à', 'aos', 'às', 'pelo', 'pela', 'pelos', 'pelas'
}

def tokenize(text: str) -> List[str]:
    """Converte texto em tokens normalizados."""
    # Remove markdown e HTML básico
    text = re.sub(r'[#*`\[\]()]', ' ', text)
    text = re.sub(r'<[^>]+>', ' ', text)
    
    # Extrai palavras, lowercase
    words = re.findall(r'[a-záéíóúâêôãõç](3,)', text.lower())
    
    # Remove stopwords e aplica stemming básico
    tokens = []
    for word in words:
        if word not in STOPWORDS_PT:
            # Stemming simples: remove sufixos comuns
            stemmed = word
            for suffix in ['ando', 'endo', 'indo', 'ado', 'ido', 'ção', 'mente']:
                if word.endswith(suffix) and len(word) - len(suffix) >= 3:
                    stemmed = word[:-len(suffix)]
                    break
            tokens.append(stemmed)
    
    return tokens

Esse stemming é primitivo, mas funcional. Para produção, você usaria NLTK ou spaCy, mas o ponto aqui é zero dependências.

Construindo o Índice Invertido

Agora a parte central: percorrer arquivos, tokenizar e construir o mapa invertido com TF-IDF:

import os
import json
import math
from collections import defaultdict
from typing import Dict, List, Tuple

class InvertedIndex:
    def __init__(self):
        self.index = defaultdict(lambda: defaultdict(lambda: {"tf": 0, "positions": []}))
        self.doc_lengths = {}  # documento -> total de tokens
        self.total_docs = 0
    
    def index_file(self, filepath: str) -> None:
        """Indexa um único arquivo."""
        with open(filepath, 'r', encoding='utf-8') as f:
            content = f.read()
        
        tokens = tokenize(content)
        self.doc_lengths[filepath] = len(tokens)
        self.total_docs += 1
        
        # Conta TF (Term Frequency) e posições
        for pos, token in enumerate(tokens):
            self.index[token][filepath]["tf"] += 1
            self.index[token][filepath]["positions"].append(pos)
    
    def index_directory(self, directory: str, pattern: str = ".md") -> None:
        """Indexa todos os arquivos de um diretório."""
        for root, _, files in os.walk(directory):
            for file in files:
                if file.endswith(pattern):
                    filepath = os.path.join(root, file)
                    self.index_file(filepath)
        
        print(f"Indexados {self.total_docs} documentos")
    
    def save(self, path: str) -> None:
        """Serializa o índice para JSON."""
        # Converte defaultdicts para dicts normais
        index_dict = {}
        for token, docs in self.index.items():
            index_dict[token] = dict(docs)
        
        data = {
            "index": index_dict,
            "doc_lengths": self.doc_lengths,
            "total_docs": self.total_docs
        }
        
        with open(path, 'w', encoding='utf-8') as f:
            json.dump(data, f, ensure_ascii=False, indent=2)
    
    def load(self, path: str) -> None:
        """Carrega índice serializado."""
        with open(path, 'r', encoding='utf-8') as f:
            data = json.load(f)
        
        self.index = defaultdict(lambda: defaultdict(lambda: {"tf": 0, "positions": []}))
        for token, docs in data["index"].items():
            for doc, info in docs.items():
                self.index[token][doc] = info
        
        self.doc_lengths = data["doc_lengths"]
        self.total_docs = data["total_docs"]

Busca com Ranking TF-IDF

Agora a mágica: consultar o índice e retornar resultados ordenados por relevância. Usamos TF-IDF (Term Frequency – Inverse Document Frequency):

  • TF: frequência da palavra no documento (quanto mais, mais relevante)
  • IDF: raridade da palavra no corpus (palavras raras valem mais)
class Searcher:
    def __init__(self, index: InvertedIndex):
        self.index = index
    
    def _tf_idf(self, term: str, doc: str) -> float:
        """Calcula TF-IDF para um termo em um documento."""
        # TF: frequência normalizada pelo tamanho do doc
        tf = self.index.index[term][doc]["tf"] / self.index.doc_lengths[doc]
        
        # IDF: log(total_docs / docs_com_termo)
        df = len(self.index.index[term])
        idf = math.log(self.index.total_docs / df) if df > 0 else 0
        
        return tf * idf
    
    def search(self, query: str, top_k: int = 10) -> List[Tuple[str, float]]:
        """Busca documentos e retorna ranqueados por TF-IDF."""
        query_tokens = tokenize(query)
        
        if not query_tokens:
            return []
        
        # Encontra documentos que contêm TODOS os termos (AND)
        doc_sets = [set(self.index.index[token].keys()) for token in query_tokens]
        candidate_docs = set.intersection(*doc_sets) if doc_sets else set()
        
        if not candidate_docs:
            # Fallback: busca OR se AND não retornar nada
            candidate_docs = set.union(*doc_sets) if doc_sets else set()
        
        # Calcula score para cada documento
        scores = []
        for doc in candidate_docs:
            score = sum(self._tf_idf(token, doc) for token in query_tokens if doc in self.index.index[token])
            scores.append((doc, score))
        
        # Ordena por score descendente
        scores.sort(key=lambda x: x[1], reverse=True)
        
        return scores[:top_k]

Código HTML representando estrutura de documentos indexáveis para busca full-text local

Interface de Linha de Comando

Para uso diário, uma CLI simples:

#!/usr/bin/env python3
import sys
import time
from indexer import InvertedIndex
from search import Searcher

INDEX_PATH = "data/index.json"
DOCS_DIR = "~/notes"

def main():
    if len(sys.argv) < 2:
        print("Uso: search.py [index|query]")
        sys.exit(1)
    
    command = sys.argv[1]
    
    if command == "index":
        print("Indexando documentos...")
        start = time.time()
        
        index = InvertedIndex()
        index.index_directory(DOCS_DIR)
        index.save(INDEX_PATH)
        
        elapsed = time.time() - start
        print(f"Índice salvo em {elapsed:.2f}s")
    
    elif command == "query":
        if len(sys.argv) < 3:
            print("Uso: search.py query 'termos de busca'")
            sys.exit(1)
        
        query = " ".join(sys.argv[2:])
        
        index = InvertedIndex()
        index.load(INDEX_PATH)
        
        searcher = Searcher(index)
        
        start = time.time()
        results = searcher.search(query)
        elapsed = time.time() - start
        
        print(f"{len(results)} resultados em {elapsed:.3f}s
")
        
        for doc, score in results:
            print(f"[{score:.4f}] {doc}")
    
    else:
        print(f"Comando desconhecido: {command}")

if __name__ == "__main__":
    main()

Performance Real: 847 Arquivos em 0.8s

Testei com minha coleção pessoal: 847 arquivos markdown totalizando 2.3MB de texto. Resultados:

  • Indexação: 0.8 segundos (single-threaded)
  • Busca: 2-5ms por query
  • Tamanho do índice: 1.2MB (JSON)
  • Uso de memória: ~15MB durante indexação, ~8MB em repouso

Para referência, o Elasticsearch levaria ~3 segundos só para inicializar o JVM. Nosso buscador está pronto em 50ms após carregar o JSON.

Otimizações Possíveis (Sem Adicionar Dependências)

Se você precisa de mais performance, há espaço para melhorar sem sair do Python puro:

1. Compressão de Postings Lists

Em vez de armazenar todas as posições, guarde apenas deltas (diferenças entre posições consecutivas). Reduz o tamanho do índice em ~40%.

2. Cache de Queries Frequentes

from functools import lru_cache

@lru_cache(maxsize=100)
def cached_search(query: str, top_k: int = 10):
    return searcher.search(query, top_k)

3. Indexação Incremental

Em vez de reindexar tudo, verifique mtime dos arquivos e só reindexe os modificados desde a última indexação.

💡 Dica de Produção: Se você tem mais de 10.000 documentos, considere usar SQLite com FTS5 (Full-Text Search). Ainda é zero dependências (vem com Python), mas escala muito melhor. O código acima é ideal para até ~5.000 documentos.

Quando Usar Isso vs. Elasticsearch

Seja honesto sobre suas necessidades:

Use índice invertido local quando:

  • Você tem menos de 5.000 documentos
  • O corpus é pessoal (notas, docs, código)
  • Você quer zero infraestrutura
  • Latência de 5ms é aceitável
  • Você quer entender como busca funciona

Use Elasticsearch/Meilisearch quando:

  • Você tem milhões de documentos
  • Precisa de busca fuzzy (tolerante a typos)
  • Múltiplos usuários buscam simultaneamente
  • Precisa de facets, filtros complexos, aggregations
  • Latência sub-milissegundo é crítica

Próximos Passos: Do Básico ao Avançado

Com o índice funcionando, você pode evoluir:

  1. Busca por frase: usar positions para encontrar termos adjacentes
  2. Highlighting: mostrar trechos do documento com os termos destacados
  3. Busca fuzzy: implementar distância de Levenshtein para tolerar typos
  4. Sinônimos: carregar um dicionário de sinônimos e expandir queries
  5. Interface web: Flask + 50 linhas de HTML para uma UI básica

Conclusão: Autossuficiência Digital é Possível

Você acabou de construir um buscador full-text funcional com menos de 200 linhas de Python puro. Sem conta em SaaS, sem servidor Elasticsearch consumindo 2GB de RAM, sem dependências que quebram a cada update. Só você, seus arquivos e uma estrutura de dados que funciona desde antes da internet existir.

Da próxima vez que você perder 10 minutos procurando aquele tutorial, lembre-se: a solução não é instalar mais um app. É entender o problema e escrever 200 linhas de código. Automação inteligente não é sobre usar a ferramenta mais cara — é sobre usar a ferramenta certa.

Agora me conta: qual é a próxima busca que você quer automatizar? Seus emails? Seus commits? Suas conversas no Telegram? Deixa nos comentários que a gente desmonta junto.

Posts Similares