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.
Adicionando um caso, conjunto de dados ou suíte de benchmark
Os conjuntos versionados são pequenos (tamanhos dos conjuntos), então um novo caso é a forma mais barata de melhorar a suíte. Leia primeiro o cabeçalho ou o _comment do arquivo: a maioria explica como o gold foi construído e o que uma nova linha precisa satisfazer.
Adicionar um caso a um conjunto existente
QA de memória (bench/datasets/synthetic_memory_qa.json)
Acrescente uma pergunta a uma conversa, ou uma conversa inteira:
{
"conversation_id": "06-billing",
"conversation": [{ "role": "user", "content": "Our invoices go out on the 3rd of each month." }],
"questions": [{ "question": "When do invoices go out?", "gold_keys": ["invoice", "3rd"] }]
}
Um acerto é qualquer memory_key ou trecho retornado que contenha uma string gold (sem diferenciar maiúsculas de minúsculas, com underscores tratados como espaços). Escolha palavras gold que uma memória correta deve conter e que uma memória errada dificilmente conterá. Mantenha o caso sintético: sem texto de terceiros e sem pessoas reais.
Isso move a linha de base. O limite de 0.80 do gate foi registrado com este arquivo. Execute o gate em uma implantação real antes e depois, e atualize MIN_RECALL no Makefile se o valor mudar. Testes: tests/unit/test_bench_quality_gate.py, bench/test_quality.py.
Regressões de extração e de grafo
- As linhas de
bench/fixtures/extraction_regressions.jsontêm o formato{id, messages, expected}: frases que devem aparecer na chave ou no valor de alguma memória. - As linhas de
graph_regressions.jsontêm o formato{id, messages, expected_triples: [{subject, relation, object}], as_of}. - Um campo
_notenomeia a classe da falha; o harness o ignora.
tests/unit/test_algorithm_gate_assets.py verifica se toda linha tem mensagens e uma expectativa não vazia. Execute make bench-algorithm-gate com um LLM de extração real para ver o caso passar.
QA do plano de código (bench/fixtures/code_intel_qa*.jsonl)
Um objeto JSON por linha; linhas // são comentários:
{"id": "co037", "type": "conceptual", "query": "where are part merges scheduled", "gold": {"paths": ["src/Storages/MergeTree/MergeTreeBackgroundExecutor"]}}
{"id": "sd011", "type": "symbol_def", "query": "IColumn::insert", "gold": {"qualified_name": "DB::IColumn::insert", "path_prefix": "src/Columns/"}}
{"id": "ab011", "type": "abstain_probe", "query": "kubernetes ingress annotation for sticky sessions", "gold": {}}
O gold de cada tipo está na docstring de bench/code_intel_qa.py (callers usa expected_callers, hub usa path_prefix e symbols). Os caminhos são prefixos sem a extensão. Os campos opcionais lane, facets e namespace roteiam e fatiam a linha.
- Verifique o gold em um índice ativo antes de ele passar a valer no gate: execute uma vez sem limites mínimos, leia as divergências e corrija o gold.
- Um abstain probe deve tratar de código que não está no repositório.
- Mantenha o conjunto de tipos do arquivo principal.
bench/test_code_intel_qa.py(test_fixture_loads_and_validates) verifica quecode_intel_qa.jsonltem pelo menos 30 linhas e exatamente os tipossymbol_def,callers,conceptual,abstain_probe. Linhas de hub, histórico e conjunto de testes vão em seus próprios arquivos de lane. make bench-code-intel-dryainda deve passar: cada lane atinge seu teto sob uma recuperação sintética perfeita.- As lanes mineradas são regeneradas, não editadas à mão:
code_intel_mine_prs.pyecode_intel_ka_slice.pygravam o arquivo e as contagens do cabeçalho.
Lições do agente de código (bench/fixtures/coding_agent_qa.json)
Acrescente a lessons (uma linha de memória identificada por memory_key) e a questions (question, question_type da taxonomia, gold_keys e, opcionalmente, fix_reuse). Toda gold key deve nomear uma chave de lição real: caso contrário, bench/test_coding_agent_qa.py (test_load_corpus_rejects_dangling_gold_key) falha. --dry ainda deve passar.
Tarefas de planejamento de ops (bench/fixtures/op_planning_tasks.jsonl)
Uma tarefa contém id, class (instruction_type, structure), prompt, um plano gold (ferramenta, argumentos obrigatórios, argumentos literais) e assertions sobre o armazenamento. tests/unit/test_op_planning_bench.py (test_every_gold_tool_and_required_arg_exists_on_the_surface) falha quando uma ferramenta ou um argumento gold deixa de existir na superfície do MCP. Uma tarefa cuja op foi aposentada vai para op_planning_tasks_retired.jsonl em vez de ser excluída.
Tarefas de avaliação de skill
Um briefing em bench/skill_eval/tasks/ tem front matter (task, namespace, agent, traps), nomeia um namespace skill-eval-… no corpo e termina dizendo que o namespace será auditado. O mesmo corpo é um caso de claude plugin eval em integrations/claude-code-plugin/evals/loom-memory/<task>/prompt.md, idêntico byte a byte após o front matter. tests/unit/test_skill_eval.py verifica as três regras e fixa a lista de tarefas, então uma nova tarefa também atualiza esse teste. Veja avaliação de skill.
Integrar um novo dataset
- Não faça commit dele. Coloque-o em
bench/datasets/ou receba um caminho por flag. Se ele for baixado, adicione um caminho--fetchou imprima o comando de download quando o arquivo estiver ausente, como faz olongmemeval.py. - Registre a procedência na docstring do harness: origem, nomes dos arquivos, número de itens e a licença declarada pelo dataset. Adicione uma linha em conjuntos de dados.
- Mantenha as categorias do próprio dataset como uma coluna e indique o subconjunto comparável, se as tabelas publicadas usarem um.
- Nomes de benchmarks públicos são aceitos em
bench/, mas nunca como motivo de uma escolha em texto sobserver/(tests/unit/test_public_copy.pyBENCHMARK_NAMES). - Crie namespaces temporários com um prefixo de
LOOM_NAMESPACE_BENCH_PREFIXES(server/settings/catalog.py; novos harnesses usambench-), para queloom namespaces-gce o GC de namespaces encontrem o que uma execução abortada deixar para trás.
Escrever um novo harness
Todo harness segue este formato:
| Regra | Como |
|---|---|
| Script independente | argparse, --base-url, --token (padrão LOOM_API_KEY), --out; executável como PYTHONPATH=$PWD python bench/<name>.py e como módulo |
| Política HTTP compartilhada | Envie as requisições por bench/_http.py (post_json / apost_json): token Bearer, esperas em 429, novas tentativas limitadas em 5xx, erros que carregam o corpo da resposta |
| A docstring é o manual | O que mede, o que não mede, conjunto de dados, custo e um comando de execução |
| Núcleo de pontuação puro | Funções de pontuação acima do caminho em execução real, importáveis sem um servidor, com um teste unitário (bench/test_<name>.py ou tests/unit/test_bench_<name>.py) |
Um modo --dry ou de autoteste |
Exercita o avaliador com entrada sintética, sem servidor e sem gasto |
| Leituras de avaliação | Primeiro, mescle measurement_fields("memory.search") / ("memory.ask") de bench/_gate.py nos corpos das requisições; ofereça --credit |
| Namespaces descartáveis e registrados | register_bench_namespace + remember_bench_namespace antes da primeira escrita, o trabalho dentro de erase_on_exit e uma flag --keep-namespaces (bench/bench_namespaces.py) |
| Escopo fixo | Envie namespace_scope: "this" nas leituras |
| Com julgamento? Use o gate compartilhado | add_gate_arguments(parser) para --repeats, --gate*, --credit, --judge-calibration; gate_from_args para o veredito; fixe os modelos de leitor e de juiz e avise sobre substituições. tests/unit/test_bench_gate_help_renders.py mostra por que um % solto no texto de ajuda quebra o --help |
| Registre o instrumento | Embedder, LLM, provedor e build_commit de /v1/health junto aos números (veja run_metadata em quality.py) |
| Separe falhas de erros de recuperação | Conte e imprima os erros de requisição; não os pontue como erros de recuperação |
| Comparações pareadas | Deltas por item com paired_bootstrap usando uma chave de cluster; libere com base no limite inferior |
Depois:
- adicione um item à seção adequada de
bench/README.mde, se ele responder a uma pergunta comum, uma linha na tabela "When to run what"; - adicione um alvo no Makefile apenas para um gate que alguém execute rotineiramente, com seus limites mínimos como variáveis substituíveis;
- execute
make format(o ruff formatabench/),pytest bench -qe o lint de texto:
.venv/bin/python -m pytest tests/unit/test_public_copy.py tests/unit/test_bench_namespaces.py -q
O lint de texto verifica bench/: sem nomes de produtos, pessoas, hosts internos ou namespaces, citações de artigos ou referências a registros de decisão em código, comentários ou fixtures.
Relacionados
- Metodologia: o que o gate e o bootstrap calculam.
- Execução: comandos e saídas.
- Testes: as suítes de testes unitários e de integração.