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.

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.json têm o formato {id, messages, expected}: frases que devem aparecer na chave ou no valor de alguma memória.
  • As linhas de graph_regressions.json têm o formato {id, messages, expected_triples: [{subject, relation, object}], as_of}.
  • Um campo _note nomeia 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 que code_intel_qa.jsonl tem pelo menos 30 linhas e exatamente os tipos symbol_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-dry ainda 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.py e code_intel_ka_slice.py gravam 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

  1. Não faça commit dele. Coloque-o em bench/datasets/ ou receba um caminho por flag. Se ele for baixado, adicione um caminho --fetch ou imprima o comando de download quando o arquivo estiver ausente, como faz o longmemeval.py.
  2. 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.
  3. Mantenha as categorias do próprio dataset como uma coluna e indique o subconjunto comparável, se as tabelas publicadas usarem um.
  4. Nomes de benchmarks públicos são aceitos em bench/, mas nunca como motivo de uma escolha em texto sob server/ (tests/unit/test_public_copy.py BENCHMARK_NAMES).
  5. Crie namespaces temporários com um prefixo de LOOM_NAMESPACE_BENCH_PREFIXES (server/settings/catalog.py; novos harnesses usam bench-), para que loom namespaces-gc e 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.md e, 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 formata bench/), pytest bench -q e 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.