📚 Indexação: chunking, embeddings e BM25 híbrido

Chunking é a primeira e mais consequente decisão. Chunk muito grande (>2000 tokens) dilui relevância — embedding fica genérico. Chunk muito pequeno (<100 tokens) perde contexto. Default robusto: 500 tokens com overlap de 10-20%, cortando em fronteira semântica (parágrafo, fim de sentença). Recursive splitter (LangChain) ou SemanticChunker (LlamaIndex) implementam isso bem.

def chunk_by_paragraph(text: str, target=500, overlap=50) -> list[str]:
    paras = text.split('\n\n')
    chunks, current = [], ''
    for p in paras:
        if len(current) + len(p) > target:
            chunks.append(current)
            current = current[-overlap:] + '\n\n' + p  # overlap
        else:
            current += '\n\n' + p
    chunks.append(current)
    return chunks

Embeddings densos mapeiam texto em vetor (768-3072 dimensões) onde proximidade vetorial ≈ similaridade semântica. Modelos canônicos: BGE-large (open), OpenAI text-embedding-3-large, Cohere embed-v3. Capturam paráfrase ('automóvel' ≈ 'carro') que BM25 sozinho perde.

from sentence_transformers import SentenceTransformer
model = SentenceTransformer('BAAI/bge-large-en-v1.5')

chunks = ['o carro é vermelho', 'o automóvel é vermelho', 'o gato dorme']
vectors = model.encode(chunks, normalize_embeddings=True)

# vectors[0] @ vectors[1] ~ 0.92 (similar)
# vectors[0] @ vectors[2] ~ 0.15 (não relacionado)

BM25 é probabilístico, baseado em TF-IDF. Não usa ML, mas é excelente em match exato: números, IDs, nomes próprios, acrônimos — coisas que embeddings densos costumam errar. Em queries factuais ('quem é Liu et al. 2023?'), BM25 frequentemente bate dense retrieval sozinho.

from rank_bm25 import BM25Okapi
tokenized = [doc.lower().split() for doc in corpus]
bm25 = BM25Okapi(tokenized)

query = 'Liu 2023 lost in middle'.lower().split()
scores = bm25.get_scores(query)
top10 = sorted(zip(corpus, scores), key=lambda x: -x[1])[:10]

Híbrido roda BM25 + dense em paralelo, depois funde via Reciprocal Rank Fusion (RRF). RRF combina rankings sem precisar normalizar scores: score = Σ 1/(k + rank_i) com k=60. Em benchmark BEIR, híbrido bate cada método sozinho consistentemente.

def rrf(rankings: list[list[int]], k: int = 60) -> list[int]:
    scores = {}
    for ranking in rankings:
        for rank, doc_id in enumerate(ranking):
            scores[doc_id] = scores.get(doc_id, 0) + 1 / (k + rank)
    return [d for d, _ in sorted(scores.items(), key=lambda x: -x[1])]

top_bm25  = bm25_search(query, top_k=50)
top_dense = vector_search(query, top_k=50)
top_hybrid = rrf([top_bm25, top_dense])[:20]

Vector stores fazem ANN (approximate nearest neighbor) com algoritmos como HNSW (hierarchical navigable small world) ou IVF. Em 100k documentos, cosine similarity exato é O(n) — inviável em produção. ANN entrega ~99% de recall em <5ms. Para começar: FAISS em memória ou pgvector em Postgres existente. Cloud: Qdrant, Pinecone, Weaviate.

Retrieval só por similaridade semântica é ingênuo. Em corpus heterogêneo, você quer filtros: 'eventos de 2024' não deve trazer chunks de 2019, mesmo que semanticamente similares. Vector stores modernos suportam metadata filters (pre-filter ou post-filter). Pre-filter (Qdrant, pgvector) é mais eficiente; post-filter (FAISS) força recuperar mais e descartar.

from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchValue

client.search(
    collection_name='docs',
    query_vector=q,
    query_filter=Filter(must=[
        FieldCondition(key='year', range={'gte': 2024}),
        FieldCondition(key='lang', match=MatchValue(value='pt')),
    ]),
    limit=10,
)