RAG Híbrido com Trava Numérica
RAG · Postgres + pgvector · Busca textual · Fusão por posição · FastAPI · 22 testes
A pergunta de negócio
O atendimento de uma operadora de saúde responde às mesmas perguntas o dia inteiro. Quanto tempo tenho para recorrer de uma negativa? Quanto pago no pronto-socorro? Quantas teleconsultas são gratuitas? As respostas estão no manual do beneficiário, e um assistente consegue encontrá-las em segundos.
Ele precisa acertar uma coisa todas as vezes: o número. Uma coparticipação ou um prazo errado é o erro caro, porque o beneficiário age com base nele.
Duas coisas precisam valer. O assistente encontra o trecho certo mesmo quando o beneficiário usa palavras diferentes das do manual. E ele se recusa a responder quando está prestes a citar um número que o manual não contém.
Os dados
Um manual fictício de plano de saúde, em inglês, com 8 documentos: recursos, odontologia, urgência e emergência, maternidade, saúde mental, atendimento fora da rede, medicamentos e telessaúde. Ele é dividido em 21 trechos. É fictício de propósito. O repositório é público, e os documentos de uma operadora real não são meus para publicar. A estrutura é a que importa num manual real: limites, coparticipações e prazos.
O conjunto de teste tem 16 perguntas escritas com palavras diferentes das do manual: “ER” onde o texto diz “emergency room”, “therapy” onde diz “therapist”. Cada pergunta registra qual documento a responde, então dá para medir a busca com um número.
O método, e por que esse
Uma tabela do Postgres em vez de um banco vetorial. Cada trecho é uma linha com o texto, o embedding (pgvector, índice HNSW, distância de cosseno) e uma coluna de busca textual com índice próprio. Recarregar um documento é apagar e inserir numa única transação, então as duas buscas nunca veem versões diferentes dele. Para a maioria das empresas, isso significa nenhum sistema novo para manter, porque o Postgres já está lá.
Duas buscas, combinadas por posição. A busca vetorial encontra paráfrases. A busca textual encontra termos exatos, códigos e nomes. As notas das duas estão em escalas diferentes, então, em vez de calibrar um peso com 16 perguntas, elas são combinadas por Reciprocal Rank Fusion, que olha só a posição de cada trecho nas duas listas.
A trava falha fechada. Antes de uma resposta sair, cada número dela é conferido com os trechos recuperados ($1,500.00 e 1500 contam como o mesmo número). Se faltar algum, o serviço não devolve resposta, marca como bloqueada e diz qual número faltou. Para limites, coparticipações e prazos, ficar sem resposta custa menos do que receber uma errada.
Roda sem chave de API. Um respondedor extrativo simples, que escolhe a melhor frase dos trechos, permite rodar o fluxo inteiro e os testes sem internet. O Claude é quem responde de verdade quando há uma chave configurada. Na mesma linha, um embedding determinístico deixa os testes repetíveis, e a avaliação roda de novo com um modelo de embedding de verdade, o bge-small-en-v1.5.
Resultado
A busca é medida no CI a cada mudança, contra um banco Postgres 16 + pgvector de verdade. O número abaixo é o hit@1: a fração das 16 perguntas em que o documento certo vem em primeiro lugar.
| Embedding | Vetorial | Textual | Híbrida |
|---|---|---|---|
| Hashing simples (lexical) | 0,75 | 0,81 | 0,88 |
| bge-small-en-v1.5 | 1,00 | 0,81 | 1,00 |
Com um embedding fraco, a busca híbrida supera as duas, porque cada uma corrige erros da outra. Com um embedding bom, a busca vetorial já acerta as 16 e a híbrida mantém esse resultado. A busca textual sozinha erra as paráfrases. Dezesseis perguntas servem como teste de fumaça. O portão do CI (pelo menos 0,8 com os 3 primeiros trechos) está lá para pegar regressões quando o corte dos trechos, os índices ou a consulta mudam.
A trava, do jeito que os testes conferem. Pergunte “How long do I have to appeal a denied claim?” O manual diz 180 dias, a resposta diz 180 dias e cita o documento de recursos. Troque por um modelo que responde “You have 90 days to appeal” e o serviço retém a resposta e aponta o 90 como número sem fonte.
O repositório também declara os seus limites. Ainda não há reranker, a avaliação cobre a busca e não a qualidade da resposta, a busca textual está configurada só para inglês, e a trava não confere números escritos por extenso.
Aplicado aos seus documentos
Esse é o núcleo do piloto do Assistente de IA Confiável: os seus documentos ou tabelas no lugar do manual, 20 perguntas-teste aprovadas por você como critério de aceite, e a mesma regra de que nenhum número chega ao usuário sem ter sido encontrado na fonte.
O código
github.com/rhozon/rag-pgvector-hybrid
Com Docker e Python 3.12:
docker compose up -d
pip install -e ".[dev,embed]"
python -m rag.cli ingest data/handbook --reset
python -m rag.cli ask "How long do I have to appeal a denied claim?"
python -m rag.cli eval --k 1
pytest -vA configuração padrão não precisa de chave de API nem de download de modelo. A suíte tem 22 testes, incluindo os de Postgres, e roda a cada push junto com a avaliação da busca. O README lista as decisões de projeto, da escolha do índice ao motivo de a consulta textual ser um OU de termos.