Pular para o conteúdo
AI Agent Eval Harness

ADR-0025: Provedor de reranking gerenciado e determinismo de avaliação

  • Status: Accepted
  • Data: 2026-06-08
  • Responsáveis pela decisão: Waldemar Szemat

Contexto e definição do problema

Seção intitulada “Contexto e definição do problema”

O pipeline de recuperação híbrida (ADR-0022) termina reavaliando o conjunto de candidatos fundidos com um reranker cross-encoder. Rodar esse cross-encoder localmente o torna o único custo dominante de um turno: no host de produção (Google Cloud Run, com uma alocação pequena de CPU e escala a zero), a medição por nó cabeada pelo stack de observabilidade (ADR-0006) registrou o reranker local como a esmagadora maioria da latência de um turno quente, e ele mantém um modelo grande residente em memória. Um enquadramento anterior tinha deixado os rerankers pagos de fora por motivos de custo; assim que o reranker local se tornou o defeito de latência principal, essa troca deixou de valer.

Duas perguntas decorrem disso. Primeira, qual reranker preserva - ou melhora - a qualidade de recuperação enquanto retira a inferência local do turno? Segunda, como o portão de avaliação (ADR-0003) se mantém determinístico uma vez que um reranker gerenciado e apoiado em rede passa a ficar no caminho de recuperação, sem jamais chamar uma API paga dentro do portão e detectando ao mesmo tempo a deriva do modelo do fornecedor?

Fatores de decisão

Seção intitulada “Fatores de decisão”
  • Trazer o turno quente de volta para baixo do orçamento de latência sem sacrificar a qualidade de recuperação; o rerank deve ser subsegundo e hospedado.
  • Paridade de ranking multilíngue: o demo serve en / es-419 / pt-BR, então o reranker deve classificar bem os pares consulta-documento fora do inglês.
  • $0 na escala do demo, sem surpresa de cota.
  • O portão de avaliação offline (ADR-0003) se mantém determinístico, offline e gratuito: nenhuma chamada ao vivo a uma API paga dentro do portão.
  • Reversível e seguro sob degradação, honrando o contrato de degradação elegante do pipeline híbrido (ADR-0022).

Opções consideradas

Seção intitulada “Opções consideradas”
  • Um reranker gerenciado fora da caixa (Voyage rerank-2.5), selecionado por turno (escolhida).
  • Manter o cross-encoder local e aceitar a latência dominante do turno quente.
  • Quantizar / compilar para ONNX o modelo local para acelerar a inferência em CPU.
  • Um fornecedor gerenciado diferente (por exemplo Cohere ou Jina) fora da caixa.

Resultado da decisão

Seção intitulada “Resultado da decisão”

Opção escolhida: transferir o reranking para um reranker gerenciado fora da caixa (Voyage rerank-2.5), resolvido por turno por um ajuste de fornecedor com três valores - automático (o padrão), gerenciado e local.

  • Resolução do fornecedor. O padrão automático se resolve para o reranker gerenciado quando há uma chave de API da Voyage presente, e para o cross-encoder local caso contrário. O demo implantado se resolve para o caminho gerenciado; uma cópia sem chave faz o rerank localmente. A produção nunca carrega o cross-encoder local, que é o que retira o peso do modelo residente que a transferência existe para remover.
  • Por que um modelo de qualidade gerenciado, e não o modelo local fora da caixa. O fornecedor gerenciado não oferece o cross-encoder local, pois distribui seus próprios modelos; hospedá-lo exigiria um terceiro fornecedor. O modelo gerenciado escolhido é multilíngue, com uma janela de contexto longa e latência hospedada subsegundo, de modo que a mudança baixa a latência sem baixar a qualidade.
  • Interface assíncrona. O reranking é uma interface assíncrona, então uma ida e volta hospedada não bloqueia o loop de eventos; o adaptador gerenciado reutiliza o padrão HTTP assíncrono de retentativa limitada e sem retentativa em erro de cliente já estabelecido para o embedder gerenciado (ADR-0004), e o reranker local é envolvido para apresentar a mesma superfície assíncrona. O resultado do ranking é idêntico em ambos; só o agendamento muda.
  • Degradação. Um não-sucesso gerenciado ou uma falha de transporte é levantado como um erro de rerank tipado, capturado no limite de recuperação e degradado para o ranking apenas-de-fusão - o mesmo caminho degradado que uma falha de carga local produz (ADR-0022). Uma queda do rerank nunca faz o turno falhar.
  • Custo. O reranker gerenciado é cobrado por token com uma ampla franquia gratuita; no volume de rerank por turno do demo, isso deixa o demo confortavelmente dentro da franquia gratuita ($0 na escala do demo), e além dela o custo marginal por turno é uma fração de centavo, medido no lado do servidor no livro de custos (ADR-0006).

Estratégia de determinismo da avaliação

Seção intitulada “Estratégia de determinismo da avaliação”

O caminho de recuperação agora contém um reranker apoiado em rede. O determinismo no portão é preservado por camadas, não confiando no fornecedor:

  1. O portão offline não tem store. O portão canônico de pull-request roda um LLM substituto sem nenhum armazenamento vetorial cabeado, então o nó de recuperação nem sequer está no grafo e nenhum reranker - local ou gerenciado
    • é jamais chamado dentro do portão. O “gerenciado-desligado” no portão é estrutural, não um sinalizador que possa ser esquecido.
  2. A avaliação com store fixa o reranker local. Quando uma execução de avaliação de fato cabeia um store (execuções de qualidade de recuperação e de integração), ela constrói o reranker local para que o ranking pontuado seja determinístico e offline. Nenhuma execução com portão emite jamais uma chamada gerenciada ao vivo.
  3. Reprodução gravada e paridade ao vivo não bloqueante (especificada, condicionada a chave). Para uma pontuação de fidelidade de produção, uma chave de avaliação separada grava respostas gerenciadas reais em cassetes que a avaliação com store reproduz de forma determinística, junto a uma execução agendada de paridade ao vivo não bloqueante que chama o serviço real para detectar cedo a deriva do modelo do fornecedor. As chamadas ao vivo ficam fora de toda execução com portão. Esta camada é especificada aqui e provisionada fora da máquina do desenvolvedor.

Confirmação

Seção intitulada “Confirmação”
  • O portão offline se mantém verde e livre de qualquer chamada ao reranker gerenciado.
  • Os testes unitários exercitam ambos os fornecedores por meio de um transporte HTTP simulado - incluindo as variantes do envelope de resposta e o caminho de erro tipado em erro de cliente - e a resolução de fornecedor.
  • A verificação ao vivo no host de produção confirma que o turno quente cai abaixo do alvo e que o componente de rerank do trace reflete a latência fora da caixa (ADR-0006).

Consequências

Seção intitulada “Consequências”

Positivas

Seção intitulada “Positivas”
  • O rerank local dominante sai do turno; o turno quente cumpre seu alvo de latência com um ranking multilíngue igual ou melhor.
  • A produção deixa de carregar o peso do reranker em memória, o que habilita um reajuste de memória à parte.
  • A interface assíncrona desbloqueia turnos concorrentes: o caminho de recuperação não bloqueia mais o loop de eventos durante a inferência local.

Negativas

Seção intitulada “Negativas”
  • A produção ganha uma dependência de rede do reranker gerenciado para o caminho de rerank completo, mitigada pelo contrato de degradação apenas-de-fusão e pela reversibilidade completa ao caminho local.
  • A camada de reprodução / paridade ao vivo de fidelidade de produção precisa de uma chave de avaliação separada, então roda fora da máquina do desenvolvedor.

Neutras

Seção intitulada “Neutras”
  • O ajuste de fornecedor e o nome do modelo gerenciado se somam à superfície de configuração.
  • O cross-encoder local segue sendo o reranker suportado offline e de avaliação; ele não é mais carregado em produção, não é removido.

Prós e contras das opções

Seção intitulada “Prós e contras das opções”

Um reranker gerenciado fora da caixa (escolhida)

Seção intitulada “Um reranker gerenciado fora da caixa (escolhida)”
  • Bom, porque retira a inferência local dominante do turno e traz o turno quente para baixo do orçamento.
  • Bom, porque o modelo escolhido é multilíngue e hospedado subsegundo, então a latência cai sem uma troca de qualidade.
  • Bom, porque se mantém em $0 na escala do demo com a franquia gratuita do fornecedor.
  • Ruim, porque introduz uma dependência de rede em produção, aceita porque o pipeline se degrada para apenas-de-fusão em qualquer queda do rerank.

Manter o cross-encoder local

Seção intitulada “Manter o cross-encoder local”
  • Bom, porque não tem dependência de rede nem fornecedor.
  • Ruim, porque é a única latência dominante de um turno quente e mantém um modelo grande residente em memória.

Quantizar / compilar para ONNX o modelo local

Seção intitulada “Quantizar / compilar para ONNX o modelo local”
  • Bom, porque mantém o rerank na caixa sem fornecedor.
  • Ruim, porque a inferência em CPU de um cross-encoder grande se mantém muito acima do alvo subsegundo mesmo quantizada, e adiciona um caminho de compilação em tempo de build para manter.

Um fornecedor gerenciado diferente

Seção intitulada “Um fornecedor gerenciado diferente”
  • Bom, porque é o mesmo movimento arquitetural para um reranker hospedado.
  • Ruim, porque não oferece uma vantagem decisiva de qualidade ou custo aqui e ainda assim introduz um segundo fornecedor de reranking.

Mais informações

Seção intitulada “Mais informações”