Teste e compare de forma justa sistemas de busca que dão memória a agentes de IA

## Afirme só o que os resultados do teste realmente mostram Distinga afirmações sobre o sistema inteiro de afirmações sobre um recurso. Dizer que um sistema de recuperação completo é o melhor exige evidências sobre qualidade da recuperação, memória de contexto longo, calibração, confiabilidade, custo e comportamento operacional. Nenhum recurso ou teste de referência isolado pode comprovar isso. Ao avaliar um recurso, pergunte se ele oferece valor significativo aos usuários do sistema. Não gaste a avaliação tentando provar que um algoritmo proprietário supera outro quando a decisão de produto depende dos resultados para os usuários. Antes de executar um experimento, escreva a afirmação, a unidade de análise, o efeito esperado, o limite de decisão e as condições em que o resultado não poderia ser generalizado. Rejeite conclusões cujo alcance seja maior que a população, a carga de trabalho, o mecanismo ou a configuração testados. ## Escolha separadamente o banco de dados e a fonte dentro dele Modele o roteamento do conhecimento em dois eixos independentes: - o corpus ou banco de dados que controla o armazenamento e a política de acesso; - a fonte ou coleção dentro desse corpus. Resolva os dois eixos por uma cadeia de precedência explícita, como entrada por chamada, permissão autenticada, contexto de sessão, marcador do repositório, configuração do usuário e valor padrão. Registre os valores resolvidos em cada consulta para possibilitar o diagnóstico de roteamentos incorretos silenciosos. Considere chamadores remotos ou voltados a agentes como não confiáveis, a menos que a confiança tenha sido estabelecida explicitamente. Aplique o escopo da fonte a todos os caminhos de leitura por uma única função auxiliar compartilhada; não monte filtros manualmente em consultas individuais. Valide os identificadores antes de usá-los em junções ou na construção de chaves e defina a unicidade sobre a chave completa com escopo de fonte. ## Compare os modos de busca com todos os ajustes juntos Defina modos nomeados como conjuntos coerentes de política de cache, orçamento de tokens, expansão de consulta, recuperação relacional, ponderação de intenção e limite de resultados. Resolva a configuração por uma cadeia determinística, com substituições por chamada acima da configuração de implantação e uma alternativa documentada. Compare os modos como escolhas completas voltadas ao usuário, em vez de selecionar apenas um ajuste favorável. Informe o valor ativo e a origem de cada ajuste. Aplique a resolução do modo no caminho de busca compartilhado de nível mais baixo para que consultas de produção e repetições de avaliação executem o mesmo comportamento. Quando um novo ramo de recuperação se aplicar somente a um tipo de consulta reconhecido, torne seu comportamento determinístico e não execute nenhuma ação nos demais casos. Ofereça uma substituição por consulta para experimentos controlados sem alterar o padrão de todo o sistema. ## Estime o custo com níveis de uso reais Calcule o custo posterior com base no volume de consultas, nos tokens de contexto entregues, no preço de entrada do modelo, nas chamadas de expansão e na taxa de acerto do cache. Mostre pelo menos níveis de uso leve, típico e intenso para que os leitores possam dimensionar o resultado sem extrapolar a partir de uma única consulta. Separe o custo isolado por consulta do gasto real de um ciclo de agente. Cache de instruções, acertos do cache de recuperação, mudanças de prefixo e chamadas repetidas de ferramentas podem alterar substancialmente o total realizado. Indique quais economias foram medidas, quais foram presumidas e quais foram excluídas. Avalie o modo e o modelo posterior como um par. Um contexto superdimensionado pode sobrecarregar um modelo de baixa capacidade, enquanto um orçamento restritivo demais pode deixar um modelo caro sem informação suficiente. Prefira combinações naturais e destaque incompatibilidades como modos de falha distintos, em vez de classificar apenas pelo custo. ## Decida o que medir e como julgar antes de testar Para cada métrica relatada, publique uma definição em linguagem simples ao lado do resultado legível por máquina. Use um glossário canônico para termos como precisão em um ponto de corte, ganho descontado, classificação recíproca, sobreposição, calibração, latência e custo. Antes de coletar resultados, especifique os conjuntos de dados, a seleção de amostras, a direção esperada, as métricas principais, as ameaças à validade e as regras de exclusão. Em comparações pareadas, use um método de reamostragem pareada e corrija comparações múltiplas ao testar várias métricas ou variantes. Preserve resumos legíveis por pessoas e metadados estruturados. Não adicione campos improvisados de glossário ao lado de valores individuais; anexe um único bloco consistente de metadados por resposta para que as ferramentas posteriores possam interpretá-lo de forma confiável. ## Faça com que qualquer pessoa possa repetir os testes de encaminhamento de perguntas Separe os casos de treinamento dos casos reservados para avaliação. Pontue com critérios estritos e também com critérios flexíveis documentados explicitamente quando uma variação de formato puder ocultar um roteamento semanticamente correto, mas não altere os critérios depois de ver os resultados reservados. Para cada execução entre modelos, armazene um comprovante que vincule o identificador do modelo, o hash do padrão de instruções, o hash dos casos, a revisão do ambiente de teste, o carimbo de data e hora e a versão de pontuação. Preserve as previsões brutas para que a lógica de pontuação possa ser melhorada ou auditada sem pagar para executar o modelo novamente. Use ablações para identificar sinais essenciais. Retire uma cláusula de roteamento, uma camada de hierarquia ou um campo de contexto por vez e compare com o mesmo conjunto reservado. Uma queda de desempenho sustenta uma afirmação causal de projeto; uma anedota não pareada de antes e depois não sustenta. ## Evite que resultados salvos (cache) se misturem entre ajustes Inclua na chave de cache todas as entradas que alterem o comportamento: escopo da fonte, ajustes do modo, limite de resultados, estado de expansão, ramos e profundidade de recuperação, provedor de representações vetoriais, coluna ou modelo de representação e qualquer indicador de recurso que altere a classificação. Versione o contrato da chave de cache. Quando a semântica mudar, aumente a versão para que as linhas antigas fiquem inacessíveis por uma falha normal de cache, em vez de serem interpretadas com a nova configuração. Teste o isolamento entre modos, fontes e provedores, além do isolamento entre recuperação relacional ativada e desativada. Execute testes de paridade em todos os mecanismos de armazenamento compatíveis, pois um mecanismo incorporado pode ocultar comportamentos de codificação ou de tipos que aparecem somente em um banco de dados de produção. ## Proteja dados privados e explique correções de segurança sem revelar pontos fracos Armazene os registros de avaliação na área de auditoria do projeto, nunca no corpus privado ativo de um usuário. Use nomes e organizações fictícios em casos, exemplos, relatórios, notas de versão e discussões públicas. Substitua consultas que revelem relacionamentos por marcadores genéricos. Descreva as correções de segurança de forma funcional em materiais públicos. Explique o mecanismo de proteção e a ação necessária ao operador sem publicar uma lista organizada de registros confidenciais, o período de exposição ou o caminho mais simples de sondagem de sistemas não corrigidos. Mantenha a análise detalhada da exposição em evidências de revisão com acesso restrito. Antes de publicar, pergunte se alguém sem contexto anterior poderia deduzir relacionamentos privados ou atacar diretamente uma implantação antiga; em caso afirmativo, generalize o texto. ## Mantenha os documentos de pesquisa atuais e curtos com verificações automáticas Use uma estrutura de documentação em camadas: - uma orientação sempre carregada que contenha o objetivo da pesquisa, o modelo de roteamento, a arquitetura e as invariantes transversais; - documentos de referência do estado atual carregados apenas para o subsistema relevante; - um registro de alterações e um histórico de versões para o comportamento passado. Não acrescente uma narrativa versão por versão às referências do estado atual. Atualize a entrada existente para refletir a nova realidade e mantenha os detalhes históricos no controle de versões e no registro de alterações. Aplique na integração contínua limites de tamanho, marcadores históricos proibidos, atualidade do glossário gerado e atualidade do conjunto de documentação. Uma regra em texto sem proteção automatizada não é uma restrição duradoura. ## Guarde toda a saída e os ajustes de cada execução Escreva o progresso em um canal separado dos resultados de dados. Mantenha os nomes das fases estáveis, torne o progresso estruturado uma opção explícita e garanta que operações longas emitam sinais de atividade sem corromper resultados legíveis por máquina. Em testes e avaliações, capture o resultado completo em um arquivo antes de exibir o final ou um resumo filtrado. Registre o código de saída do comando original antes de executar qualquer visualizador. Nunca canalize uma verificação de qualidade diretamente por um comando que trunque conteúdo, pois o encadeamento pode informar o sucesso do visualizador enquanto descarta os detalhes da falha real. Cada execução deve preservar a configuração, o modo resolvido, a identidade do conjunto de dados, os hashes, as métricas, o custo, os avisos, o estado de saída e os carimbos de data e hora. Um resultado só serve para decisões quando outra pessoa revisora consegue reconstruir o que foi executado e distinguir fatos medidos de suposições.