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:
- Carga de trabalho. Os usuários, repositórios e tipos de pergunta que a decisão abrange.
- 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.
- 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.
- Limites de economia. Latência p95 máxima, tokens, custo de modelo, tempo de indexação e armazenamento.
- 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.
- Suba a stack local e confirme que
/v1/healthretornastatus: ok. - Escreva e busque um fato.
- Conecte um agente de código, diga a ele uma preferência duradoura, abra uma sessão nova e peça essa preferência.
- Corrija o fato e depois confirme que o painel mostra a origem e o histórico de versões dele.
- Execute
loom democom 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:
- Abra a seção correspondente em Resultados dos benchmarks.
- Inspecione o artefato commitado em
bench/results/. - Confirme o recorte do dataset, o commit do Loom, os modelos, o leitor, o juiz, o modo de busca e a seed.
- Execute o comando de reprodução exato da seção do resultado.
- 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
- Cobertura dos benchmarks: o que tem medição pública, o que tem apenas um harness e o que ainda não tem evidência pública.
- Visão geral dos benchmarks: escolha um harness pelo sinal que ele mede.
- Executando benchmarks: provedores, tokens, comandos e datasets.
- Metodologia dos benchmarks: regras de comparação e limitações.
- Resultados dos benchmarks: medições e artefatos commitados.