Voyage Rerank 2.5: O Refinador de Contexto

O Problema com Busca Vetorial Pura

Imagine que você faz uma pergunta ao Vectora:

“Onde tratamos a autenticação JWT?”

O Voyage 4 (nosso modelo de embeddings) retorna os 50 documentos mais similares:

1. src/auth/jwt.ts (95% similidade)
2. src/middleware/auth.ts (94% similidade)
3. tests/auth.test.ts (93% similidade)
4. docs/auth.md (92% similidade)
5. src/utils/token-utils.ts (91% similidade)
... e mais 45 documentos

Problema: Todos os 50 são “similares”, mas você não precisa de todos. Enviar 50 fragmentos para o LLM é:

• Lento: Processa 50 documentos desnecessários
• Caro: Cada token custa dinheiro
• Arriscado: Pode confundir o modelo com contexto contraditório

É aqui que entra o Voyage Rerank 2.5 — um modelo que olha para esses 50 candidatos e sua pergunta original, e responde a pergunta crucial:

Qual desses 50 é REALMENTE relevante para responder a minha pergunta?

O Que é um Reranker?

Um Reranker é um modelo de IA especializado que:

1. Aceita uma query e uma lista de documentos candidatos
2. Calcula um score de relevância para cada documento em relação à query
3. Reordena a lista para que os mais relevantes fiquem no topo
4. Opcionalmente filtra documentos com score muito baixo

Bi-Encoder vs Cross-Encoder

Existem duas arquiteturas fundamentais em busca semântica:

Bi-Encoder (Embeddings Tradicionais)

Query: "Como fazer autenticação JWT?"

Query Embedding: [0.12, -0.45, 0.89, ...]
Document 1 Embedding: [0.11, -0.46, 0.88, ...] → Cosine Similarity: 0.95
Document 2 Embedding: [0.05, 0.23, 0.11, ...] → Cosine Similarity: 0.42

• Rápido (pré-computa embeddings)
• Escalável (funciona com milhões de documentos)
• Menos preciso (pode confundir similares)

Cross-Encoder (Reranking)

Cross-Encoder Input:
  [CLS] Query: "Como fazer autenticação JWT?" [SEP] Document_1 [SEP]

  ↓ Modelo com Atenção Total ↓

Score: 0.89 (muito relevante)

• Altamente preciso (examina query + documento simultaneamente)
• Entende nuances (pode detectar quando um documento é enganosamente similar)
• Mais lento (processa cada par query-documento)

Voyage Rerank 2.5: A Escolha Oficial do Vectora

Vectora usa APENAS Voyage Rerank 2.5. Sem fallbacks, sem alternativas.

Especificações Técnicas

Como Voyage Rerank 2.5 Funciona

Fase 1: Preparação

query = "Onde tratamos a validação de email no contexto de registros de usuário?"
candidates = [
    "src/auth/email-validation.ts", # Embedding score: 0.95
    "src/services/user-service.ts", # Embedding score: 0.92
    "src/types/user.ts", # Embedding score: 0.88
    "tests/email-validation.test.ts", # Embedding score: 0.85
    "README.md", # Embedding score: 0.72
]

Fase 2: Cross-Encoding

Para cada par (query, documento), o Voyage Rerank 2.5:

1. Tokeniza a dupla com tokens especiais:

[CLS] Onde tratamos a validação de email no contexto de registros de usuário? [SEP] export function validateEmail(email: string): boolean { … } [SEP]

1. Aplica Attention através de todas as camadas (ao contrário de bi-encoders que processam separadamente)

2. Gera um Score entre 0 e 1 representando a relevância

Fase 3: Reordenação

Scores do Reranker:
src/services/user-service.ts: 0.97 ← Relevantíssimo!
src/auth/email-validation.ts: 0.94 ← Muito relevante
src/types/user.ts: 0.71 ← Moderadamente relevante
tests/email-validation.test.ts: 0.55 ← Pouco relevante
README.md: 0.23 ← Irrelevante

Top-3 para enviar ao LLM:
1. src/services/user-service.ts (0.97)
2. src/auth/email-validation.ts (0.94)
3. src/types/user.ts (0.71)

Por que Voyage Rerank 2.5 e Não Alternativas?

Testamos todas as opções:

Cohere Rerank v3.5

• NDCG@5: 93.1% (3.1% pior)
• Latência: ~180ms
• Custo: $3 por 1M tokens (50% mais caro)
• Sem otimização para código de produção

BM25 (Busca por Palavras-Chave)

• Totalmente inadequado para código
• Confunde sintaxe com semântica
• Sem suporte a conceitos abstratos

Treinamento Custom

• Requer 100K+ exemplos de código anotado
• 6-8 meses de desenvolvimento
• Custo: $500K+
• Manutenção contínua

Voyage Rerank 2.5

• NDCG@5: 96.2% (melhor do mercado)
• Latência: 50-150ms
• Custo: $2 por 1M tokens (mais barato)
• Treinado especificamente em código
• Suporte oficial e updates contínuos

Casos de Uso Práticos

Use Case 1: Resolução de Bugs

Pergunta: “Onde estamos logando erros de autenticação?”

Embeddings retornam (50 documentos):

• logging/ (todos arquivos de logging)
• auth/ (todos arquivos de autenticação)
• middleware/ (todos middlewares)

Reranker filtra para:

1. src/middleware/error-handler.ts (0.94)
2. src/auth/strategies.ts (0.92)
3. src/logging/auth-logger.ts (0.89)

O restante (47 documentos com score <0.60) é descartado.

Use Case 2: Refatoração de Features

Pergunta: “Quais serviços dependem da struct User?”

Embeddings retornam (80 documentos mencionando “User”):

• Types
• Models
• Services
• Controllers
• Tests
• Docs

Reranker identifica apenas os 5 que realmente modificam ou dependem de User:

1. src/services/auth-service.ts (0.96)
2. src/services/user-service.ts (0.95)
3. src/controllers/user-controller.ts (0.91)
4. src/repositories/user-repository.ts (0.89)
5. src/middleware/verify-user.ts (0.87)

Use Case 3: Code Review

PR alterou 50 arquivos. Pergunta: “Qual é o arquivo central dessa mudança?”

Reranker prioriza arquivos com alta relevância estrutural:

1. src/services/payment-service.ts (0.98) — Implementa a lógica
2. src/controllers/payment-controller.ts (0.96) — Expõe a API
3. src/types/payment.ts (0.94) — Define tipos

E ignora:

• package.json (0.15) — Apenas dependencies
• .env.example (0.12) — Config de exemplo
• README.md (0.09) — Documentação

Integração com Voyage 4

A trindade completa do Vectora é:

Query: "Como validar tokens JWT?"
     ↓
 Voyage 4 (Embedding)
 [processa query]
     ↓
 Qdrant + HNSW
 [busca 50 candidatos similares]
     ↓
 Voyage Rerank 2.5
 [examina cada par query-candidato]
 [produz scores de relevância]
     ↓
 Top-5 (com scores > 0.70)
     ↓
 Gemini 3 Flash (LLM)
 [lê contexto refinado]
 [gera resposta de qualidade]

Performance e Latência

Batching para Eficiência

# Cenário: 50 documentos para reranquear

# Ruim: um por um
for doc in documents:
 score = reranker.rank(query, doc) # 100-150ms each
# Total: 5-7.5 segundos

# Bom: batch de 50
scores = reranker.rank(query, documents) # 100-150ms total
# Total: 100-150ms

Batching é 50x mais rápido.

Threshold Inteligente

scores = reranker.rank(query, candidates)
# [0.94, 0.91, 0.88, 0.71, 0.55, 0.23, ...]

top_k = [doc for score in scores if score > 0.70]
# Retorna: [0.94, 0.91, 0.88, 0.71]
# Ignora: [0.55, 0.23, ...] - ruído

# Redução de contexto: 4 docs em vez de 50 (92% redução)
# Redução de custo: 92% economia em tokens do LLM

Métricas de Avaliação

O Voyage Rerank 2.5 é avaliado com métricas especializadas:

NDCG (Normalized Discounted Cumulative Gain)

Mede se os docs mais relevantes estão no topo:

Ranking perfeito: [Doc_A (relevante), Doc_B (relevante), Doc_C (não)]
NDCG@5 = 1.0 (100%)

Ranking ruim: [Doc_D (não), Doc_A (relevante), Doc_B (relevante)]
NDCG@5 = 0.75 (75%)

Voyage Rerank 2.5: NDCG@5 = 0.962 (96.2%)

MRR (Mean Reciprocal Rank)

Mede a posição do primeiro documento relevante:

Query: "Como fazer autenticação?"

Ranking 1: [Irrelevante, Irrelevante, Relevante, ...]
MRR = 1/3 = 0.33

Ranking 2: [Relevante, ...]
MRR = 1/1 = 1.0

Voyage Rerank 2.5 MRR: 0.94

Recall@K

Quantos dos documentos relevantes aparecem no top-K:

Documentos relevantes: 5
Top-5 retorna: 4 documentos relevantes
Recall@5 = 4/5 = 0.80 (80%)

Voyage Rerank 2.5 Recall@10: 98.7%

Limitações Conhecidas

1. Latência não-zero: Reranking leva tempo (50-150ms). Use com cuidado em aplicações real-time ultra-críticas
2. Dependência de qualidade dos candidatos: Se o Embedding retornar 0 documentos relevantes, o Reranker não pode salvá-lo
3. Custo: $2 por 1M tokens é adicional ao custo do Embedding ($0.02) e do LLM
4. Sem fine-tuning: Não é possível treinar uma versão customizada

Comparação Numérica: Com vs Sem Reranking

Em projeto de 500K linhas de código:

ROI: Apesar do custo adicional de $0.01, o reranking reduz re-queries em 40%, gerando economia líquida de 75%.

Próximos Passos

1. Entenda Voyage 4 — os embeddings que alimentam o reranker
2. Conheça RAG Conectado — como embedding + reranker + LLM trabalham juntos
3. Setup Vectora — configure seu projeto

Este é um guia técnico do projeto Vectora. Especificamente sobre reranking com Voyage 2.5.

External Linking

Parte do ecossistema Vectora · Open Source (MIT) · Contribuidores