3.8.2 · BM25 e busca híbrida

Onde a busca semântica falha em SAP

As oito primeiras linhas são a razão de este módulo existir para a Wayon. Um assistente de documentação SAP que só tenha busca semântica falha na consulta mais frequente que o consultor faz: colar um código de erro e perguntar o que é.

E não é que a semântica erre por pouco. Ela pode devolver, com alta similaridade, o trecho sobre ME 084 — parecidíssimo em forma, e resposta errada.

Busca híbrida

from rank_bm25 import BM25Okapi
import numpy as np

# Índice lexical
bm25 = BM25Okapi([p.lower().split() for p in pedacos])

def buscar_hibrido(pergunta, k=20):
    # Semântico
    q = vo.embed([pergunta], model="voyage-4", input_type="query").embeddings[0]
    sem = np.dot(vetores, q)

    # Lexical
    lex = bm25.get_scores(pergunta.lower().split())

    # Normalizar cada lista para 0–1 antes de somar: as escalas não são comparáveis
    def norm(x):
        x = np.asarray(x, dtype=float)
        return (x - x.min()) / (x.max() - x.min() + 1e-9)

    combinado = 0.5 * norm(sem) + 0.5 * norm(lex)
    return [pedacos[i] for i in np.argsort(combinado)[-k:][::-1]]

O detalhe que quebra implementações apressadas: as duas pontuações não são comparáveis em escala. Similaridade de cosseno vive entre −1 e 1; BM25 não tem teto. Somar direto faz o BM25 dominar. Normalizar antes é obrigatório.

O peso 0,5 / 0,5 é ponto de partida. Em acervo SAP, carregado de identificadores, subir o peso do BM25 costuma ajudar — e isso se mede, com o dataset e o grader do módulo 3.6, não se estima.

Contextual retrieval

PROMPT_CONTEXTO = """<documento>
{documento}
</documento>

Aqui está o trecho que queremos situar dentro do documento acima:

<trecho>
{trecho}
</trecho>

Escreva uma frase curta (50 a 100 tokens) situando este trecho no documento, para
melhorar a recuperação em busca. Responda apenas com a frase."""


def contextualizar(documento: str, trecho: str) -> str:
    r = client.messages.create(
        model="claude-haiku-4-5",     # tarefa simples, volume alto: modelo barato
        max_tokens=150,
        messages=[{"role": "user",
                   "content": PROMPT_CONTEXTO.format(documento=documento, trecho=trecho)}],
    )
    contexto = next(b.text for b in r.content if b.type == "text")
    return f"{contexto.strip()}\n\n{trecho}"

Isso roda uma vez por pedaço, na indexação — não a cada consulta. Ainda assim, é uma chamada por pedaço: num acervo de 20 mil pedaços, são 20 mil chamadas. Duas coisas tornam isso viável:

• Modelo barato. É tarefa simples; Haiku 4.5 dá conta.
• Prompt caching. O documento inteiro é o mesmo para todos os pedaços dele — cachear o documento e variar só o trecho é exatamente o padrão da aula 3.7.4. Sem isso, você reenvia o documento inteiro uma vez por pedaço.

Os ganhos, medidos

Esses números são de uma medição publicada pela Anthropic, em corpus dela — não são garantia para o acervo do Meridiano. Servem para dimensionar o esforço: cada estágio acrescenta trabalho e custo, e o retorno é conhecido em ordem de grandeza. Se o seu pipeline já está bom o suficiente para o caso, parar antes é uma decisão legítima.

Reranking

resultados = vo.rerank(
    query=pergunta,
    documents=candidatos,      # os 20 da busca híbrida
    model="rerank-2.5",
    top_k=5,
)
melhores = [r.document for r in resultados.results]

O reranker vê a pergunta e o pedaço juntos, o que a busca vetorial não faz — ela compara vetores calculados separadamente. Por isso ele é mais preciso e mais caro: roda só sobre os candidatos que a busca já filtrou.

A alternativa que reduz o pipeline

Modelos de embedding contextualizado (voyage-context-4, 120 mil tokens de contexto) produzem o vetor do pedaço já considerando o documento inteiro, através de contextualized_embed() em vez de embed(). Isso elimina a etapa de gerar contexto com o Claude:

Menos peça, menos coisa para manter, menos coisa para quebrar. Vale medir os dois no seu acervo — mas comece pelo mais simples.

Regra Wayon Assistente de documentação técnica entregue a cliente SAP roda busca híbrida, nunca só semântica. Código de erro, nota SAP, transação, tabela e número de documento são a consulta mais frequente do consultor, e são exatamente onde a busca semântica falha. A escolha dos pesos entre lexical e semântico é medida com o dataset do módulo 3.6, não estimada — e o número medido vai na proposta, como na aula 3.6.5.

📖 Contextual Retrieval · Embeddings · Prompt caching — aula 3.7.4