Pular para conteúdo

As páginas sem tradução abrem em inglês e são identificadas como inglês.

Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.

Avaliar o Loom

Avalie a decisão que você precisa tomar, não cada harness do repositório. Este guia começa com um teste rápido do produto, sem custo, e depois passa para um teste de qualidade específico para a sua carga de trabalho. A suíte pública de benchmarks é a etapa final, para quando você precisa auditar ou reproduzir um resultado publicado.

Escolha uma avaliação

Decisão Dados Provedores Saída típica
O Loom é instalado e conecta corretamente? Quatro fatos de teste e um documento Os provedores falsos padrão são suficientes Um fato sobrevive a uma nova sessão; linhas de origem, histórico e auditoria aparecem no painel
A memória é útil para o nosso agente? 25–50 perguntas reais com chaves de memória esperadas Embedder real; LLM real para extração ou memory.ask recall@k, rank@1, abstenção, precisão das respostas, latência e custo
A inteligência de código é útil para o nosso repositório? Símbolos representativos, conjuntos de chamadores e perguntas no formato de issues Embedder real; repositório indexado definições exatas, F1 de chamadores, recall de arquivos, abstenção, tokens e latência
Conseguimos reproduzir um resultado publicado? O dataset público indicado e o artefato de resultado commitado Os modelos fixados ou substitutos documentados Uma execução comparável com a mesma fatia, o mesmo leitor, o mesmo juiz e o mesmo modo de busca

Não use o embedder falso (o .env de um checkout) nem o LLM falso para avaliar qualidade: eles existem para que a stack suba sem credenciais e para que os testes de integração sejam determinísticos. O embedder local da stack lançada recupera de verdade, então uma primeira olhada na busca é significativa com ele; avalie respostas e extração com um LLM real.

Antes de executar

Anote estas cinco coisas primeiro:

  1. Carga de trabalho. Os usuários, repositórios e tipos de pergunta que a decisão abrange.
  2. Linha de base. O que o mesmo usuário ou agente faz sem o Loom: contexto completo, grep, BM25, outro sistema de memória ou nenhuma recuperação.
  3. Limites de precisão. O recall, a acurácia das respostas ou o sucesso nas tarefas mínimos que você aceitará. A qualidade vem antes do custo.
  4. Limites de economia. Latência p95 máxima, tokens, custo de modelo, tempo de indexação e armazenamento.
  5. Instrumento. Commit do Loom, implantação do ClickHouse, modelos dos provedores, parâmetros dos modelos, hardware, versão do dataset e semente aleatória.

Registrar os limites com antecedência evita que uma métrica ou um recorte conveniente se torne o resultado depois da execução. Mantenha visíveis as falhas e as abstenções; relate os erros de requisição separadamente, em vez de contá-los ou descartá-los silenciosamente como falhas de recuperação.

1. Teste de fumaça do produto

Leva cerca de 15 minutos e comprova a conexão entre os componentes, a persistência e a visibilidade, não a qualidade semântica.

  1. Suba a stack local e confirme que /v1/health retorna status: ok.
  2. Escreva e busque um fato.
  3. Conecte um agente de código, diga a ele uma preferência duradoura, abra uma sessão nova e peça essa preferência.
  4. Corrija o fato e depois confirme que o painel mostra a origem e o histórico de versões dele.
  5. Execute loom demo com um documento e confirme que os chunks retornados citam esse documento (teste de fumaça com documento).

Considere o teste aprovado somente quando a nova sessão lembrar o fato, a correção substituir a resposta atual, uma pergunta não relacionada resultar em abstenção e o painel mostrar quem escreveu e o histórico. O resultado não diz nada sobre a recuperação em produção enquanto o health indicar fake_embedding ou fake_llm.

2. Avalie sua carga de trabalho

Configure provedores reais, redefina ou refaça o embedding dos dados se a largura do vetor mudou, e registre os modelos resolvidos a partir de /v1/health. Use um namespace isolado e mantenha os mesmos dados indexados para cada braço pareado.

Memória e RAG

Monte um conjunto de pelo menos 25–50 perguntas a partir de tarefas reais. Inclua:

  • fatos diretos, paráfrases, perguntas de vários saltos e atualizações sensíveis ao tempo;
  • perguntas cuja resposta deveria ter sido substituída;
  • perguntas plausíveis, mas sem resposta, para medir respostas falsas e abstenção;
  • distratores quase duplicados que diferem no valor que importa.

Para cada pergunta de memória com resposta, rotule o memory_key esperado antes de executar. Para RAG de documentos, rotule o documento e o chunk esperados, consulte knowledge.search e avalie esses identificadores com as mesmas métricas de recuperação. Meça a recuperação e a síntese separadamente:

  • Recuperação: recall@k, rank@1, MRR, taxa de falsos positivos e precisão/recall de abstenção.
  • Resposta: correção sob um único leitor e juiz fixos, mais a correção das citações.
  • Economia: latência p50/p95, tokens de entrada/saída, custo do modelo, custo de construção e linhas armazenadas.

Para um corpus de memória existente, salve um dataset JSON com este formato (o harness fornecido tem como alvo memory.search; use um avaliador equivalente para knowledge.search):

{
  "org": "acme",
  "namespace": "support-eval",
  "questions": [{ "query": "When can we deploy?", "gold_keys": ["deploy_window"] }]
}

Em seguida, execute a recuperação sem alterar o corpus:

export PYTHONPATH=$PWD LOOM_API_KEY=<token>
.venv/bin/python bench/retrieval_recall.py \
  --dataset /path/to/retrieval_qa.json --base-url http://localhost:7777 \
  --top-k 10 --out /tmp/loom-retrieval.csv

Defina --min-recall e --min-mrr somente a partir dos seus critérios pré-registrados. Use memory.ask ou o seu leitor de produção nas mesmas perguntas para medir a acurácia das respostas; o recall e a acurácia das respostas são medições diferentes.

Inteligência de código

Indexe um repositório parecido com os seus repositórios de produção. Não comece apenas com o repositório no qual o Loom foi ajustado. Rotule:

  • definições com o arquivo esperado e o símbolo qualificado;
  • chamadores com o conjunto completo esperado de chamadores;
  • perguntas conceituais e no formato de issues com arquivos aceitáveis no top 5 e no top 10;
  • perguntas fora do repositório que devem resultar em abstenção;
  • os testes ou dependentes esperados de uma consulta de impacto.

Execute o relatório de aceitação do agente de código em um repositório indexado:

export PYTHONPATH=$PWD
.venv/bin/python bench/acceptance/code_agent.py \
  --base-url http://localhost:7777 --token-file /path/to/token \
  --namespace <code-namespace>

O fixture embutido tem como alvo o ClickHouse e é útil para verificar uma implantação. Para uma decisão de produto, substitua-o ou amplie-o com suas perguntas rotuladas e compare as mesmas tarefas do agente usando apenas as ferramentas comuns do repositório. Informe primeiro o sucesso da tarefa, depois turnos, tokens, custo e tempo total. A sobrecarga do schema de ferramentas depende do cliente, então registre se ele adia as definições das ferramentas MCP.

Mantenha a comparação justa

  • Use o mesmo modelo, prompt, snapshot de dados e ordem das perguntas nos braços pareados.
  • Mantenha o custo de extração/construção do índice separado do custo por pergunta e, em seguida, informe o número de perguntas necessárias para amortizar a construção.
  • Desative o aprendizado a partir das leituras de avaliação (auto_touch: false, reinforce: false) para que uma consulta anterior não melhore uma posterior.
  • Informe o tamanho da amostra, os resultados por categoria e a incerteza. Não promova uma pequena amostra de teste rápido a uma afirmação geral.
  • Salve as saídas por pergunta, incluindo erros e falhas, e não apenas as pontuações agregadas.

3. Auditar ou reproduzir os resultados publicados

O README é um placar, não o registro de evidências. Para cada número publicado:

  1. Abra a seção correspondente em Resultados dos benchmarks.
  2. Inspecione o artefato commitado em bench/results/.
  3. Confirme o recorte do dataset, o commit do Loom, os modelos, o leitor, o juiz, o modo de busca e a seed.
  4. Execute o comando de reprodução exato da seção do resultado.
  5. Interprete a diferença usando a metodologia, incluindo a calibração do juiz, os intervalos de bootstrap e os vieses conhecidos.

Nem todos os conjuntos de dados de terceiros são redistribuídos por este repositório. A origem e a licença de cada um estão listadas em conjuntos de dados. As execuções públicas completas podem levar horas e gerar cobranças dos provedores; comece pelo recorte de teste rápido documentado e depois execute o protocolo completo antes de publicar uma comparação.

O que publicar

Publique um resultado no README somente quando ele for representativo, compreensível em uma linha e respaldado por um artefato commitado e por um comando de reprodução. Coloque a tabela completa de categorias, os modelos, os prompts, a incerteza, os custos, a análise de falhas e as limitações no registro de resultados. Coloque as regras estáveis de avaliação na metodologia, e os comandos e a obtenção dos datasets em execução.

Toda afirmação pública deve informar:

  • a tarefa e o tamanho da amostra;
  • a métrica e se ela mede recuperação, qualidade da resposta ou sucesso de ponta a ponta;
  • o baseline e o delta pareado, quando existir;
  • os modelos e o juiz, ou que nenhum juiz LLM foi usado;
  • a incerteza ou a granularidade da mudança de uma única pergunta;
  • o custo de construção e o custo de consulta, separadamente;
  • o artefato commitado e o comando exato de reprodução;
  • os achados negativos relevantes e onde o resultado não se generaliza.

Não publique todos os números disponíveis no README. Um placar longo esconde a decisão de produto, incentiva comparações inválidas entre benchmarks e dificulta a identificação de afirmações desatualizadas. O README deve levar os leitores até as evidências; a documentação deve conter as evidências.

Próximos passos