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.

Ajuste o desempenho do Loom

Cada ajuste desta página é uma configuração ou um campo de requisição. A referência de configuração informa o valor padrão e o significado de cada configuração. Quando um trade-off é medido, a página indica o comando que o mede.

Meça primeiro

Pergunta Comando Requer
p50 / p95 / p99 e RPS de uma op com concorrência N make bench OP=memory.search C=5 D=60 (scripts/ops/benchmark.py) um servidor em execução; as escritas vão para um namespace bench-…
Uma mudança de ranking ou de embedder prejudicou o recall? make bench-quick (uma fatia de um benchmark público de memória de longo prazo, com um juiz de respostas) provedores reais, OPENAI_API_KEY
Recall em relação à linha de base registrada make bench-quality-gate MIN_RECALL=… provedores reais
modo de busca × rerank × largura do pool make bench-matrix (escreve bench/MATRIX_RESULTS.md) um servidor em execução
Regressões de extração e de extração de grafo make bench-algorithm-gate um servidor em execução
Símbolo, chamadores, recall e custo em tokens do plano de código make bench-code-intel, make bench-code-legs um embedder real
O que mudou após um deploy loom deploy-delta (formatos do ledger e das instruções do ClickHouse em cada lado da troca) var/deployed.json

Aviso: um número de recall medido com o embedder fake não diz nada sobre a recuperação real. Por isso os quality gates ficam fora do CI. Execute-os contra um servidor com os provedores que você vai usar em produção e refaça a linha de base após qualquer mudança de embedder.

Para uma única requisição lenta, leia o cabeçalho Server-Timing (app vs ch) e as linhas de system.query_log antes de mexer em qualquer configuração (depuração). O custo por operação em todo o deployment é uma única consulta sobre log_comment:

SELECT splitByChar(' ', log_comment)[1] AS source,
       count() AS queries, sum(read_bytes) AS bytes, sum(query_duration_ms) AS ms
FROM system.query_log
WHERE type = 'QueryFinish' AND event_time > now() - INTERVAL 1 HOUR AND log_comment != ''
GROUP BY source ORDER BY ms DESC LIMIT 20;

O tráfego de benchmark logo após uma troca lê caches frios; espere antes de comparar a latência de um deploy com a do build anterior.

Ranking e limiares

memory.search ranqueia um conjunto de candidatos da primeira etapa e depois aplica termos de ranking e gates (recuperação e ranking). A maioria dos termos pode ser definida por deployment e sobrescrita por requisição, de modo que uma mudança possa ser testada em A/B primeiro em um único chamador.

Ajuste Configuração (campo da requisição) Trade-off
Gates de similaridade LOOM_ADAPTIVE_THRESHOLDS (padrão: ativado) Ativado: os gates são derivados, na inicialização, da distribuição de cosseno do próprio embedder. Desativado: você controla os gates escalares abaixo.
Gates escalares (fallback) LOOM_MEMORY_SEARCH_MIN_SIMILARITY, LOOM_MEMORY_SEARCH_ABSTAIN_THRESHOLD, LOOM_MEMORY_SEARCH_HYDE_FALLBACK_THRESHOLD, LOOM_MEMORY_SEARCH_QUERY_REWRITE_THRESHOLD Ajustados para text-embedding-3-small; usados com embedders falsos, sonda com falha ou adaptatividade desativada.
Resultados abaixo do piso LOOM_MEMORY_SEARCH_FLOOR_MODE (floor_mode) readmit preenche top_k e marca com below_floor; ids_only preenche com corpos vazios; drop retorna menos resultados.
Conjunto de candidatos LOOM_MEMORY_SEARCH_POOL_MULTIPLIER_STANDARD, _RERANK, _DEEP, limitado por LOOM_MEMORY_SEARCH_MAX_POOL_TOP_K Um conjunto maior aumenta o recall e a entrada do rerank; custa linhas vetoriais lidas e tokens de rerank.
Pular o rerank LOOM_LLM_RERANK_SKIP_ABOVE (fallback quando o gate adaptativo não tem sonda) Pula a chamada de rerank quando o melhor resultado vetorial já é forte.
Cascata de fallback LOOM_MEMORY_SEARCH_FALLBACK_MAX_ROUNDS, _MAX_WALL_MS, _MAX_LLM_CALLS, _MAX_VECTOR_QUERIES Limita as novas tentativas que uma primeira passada fraca pode gastar (reescrita da consulta, HyDE).
Reforço LOOM_MEMORY_SEARCH_REINFORCEMENT_WEIGHT (reinforcement_weight), _HALF_LIFE_DAYS Quanto os acessos e os resultados positivos elevam uma linha; 0 desativa. Limitado abaixo da relevância.
Proveniência LOOM_MEMORY_SEARCH_TRUST_WEIGHT (padrão: 0) Um termo limitado que favorece fontes atestadas.
Recência LOOM_MEMORY_SEARCH_RECENCY_POOL_WEIGHT (recency_pool_weight) Reordena o conjunto em direção a linhas recentes em uma consulta com intenção de recência; 0 = desativado.
Perna lexical em consultas com formato de código rrf_adaptive_lexical (requisição), LOOM_MEMORY_RRF_CODE_SHAPE_LO / _HI Reduz o peso da perna lexical para consultas com formato de caminho ou de código sob RRF.
Modo padrão LOOM_MEMORY_SEARCH_DEFAULT_MODE (search_mode) Usado quando o chamador não informa nem um modo nem uma receita.
Duplicatas por chave LOOM_MEMORY_SEARCH_PER_KEY_CAP Linhas que uma chave pode contribuir para uma página.

Aviso: um limiar ajustado em um embedder está errado no seguinte. Com LOOM_ADAPTIVE_THRESHOLDS=false, ou com um embedder falso, execute o bench novamente (make bench-quick, make bench-quality-gate) após cada troca de embedder. calibration.get mostra qual camada produziu os gates em vigor para um namespace.

Leituras vetoriais

As colunas vetoriais são Array(BFloat16); onde enable_quantized_codec pode estar ativado, o migrator as cria codificadas (ClickHouse).

Ajuste Configuração Contrapartida
Varredura primeiro pelos códigos LOOM_VECTOR_SEARCH_QUANTIZED_CODES (padrão: ativado), LOOM_MEMORY_SEARCH_FACT_CODES_FIRST (auto) Lê os códigos quantizados e depois refaz a pontuação com precisão total. auto desativa essa opção enquanto memory_embeddings tiver partes de patch, caso em que a nova pontuação seria ignorada.
Busca excedente de códigos LOOM_VECTOR_SEARCH_QUANTIZED_FETCH_MULTIPLIER, LOOM_MEMORY_SEARCH_FACT_CODES_FETCH_MULTIPLIER Linhas mantidas pela distância dos códigos antes da nova pontuação. Um valor menor é mais barato e altera os melhores resultados com mais frequência.
Threads por instrução de fatos LOOM_MEMORY_SEARCH_FACT_LEG_MAX_THREADS (0 = sem fixação) Fixar limita a CPU e o pico de memória por instrução, ao custo de alguma latência.
Leituras de pares nas gravações em lote LOOM_MEMORY_BULK_PEER_READ (padrão: batched; per_fact) per_fact lê primeiro pelos códigos os pares de conflito e de atualização de valor de cada fato do lote, como memory.set faz: para namespaces grandes, em que a instrução de pares em lote falha com MEMORY_LIMIT_EXCEEDED (batched conflict candidates failed no log do servidor) e uma entrada é gravada sem verificação quando o fallback por fato também falha. Um par pode diferir quando as distâncias empatam.

Para mover uma tabela existente para um codec ou layout, use scripts/ops/vector_codec_rebuild.py (tabela gêmea, verificações de consistência e de recall, EXCHANGE; passos), nunca um ALTER em uma migração.

Conexões e prazos do ClickHouse

Ajuste Configuração Compromisso
Tamanho do pool LOOM_CH_POOL_MAXSIZE (padrão 64 por processo) Dimensione conforme a concorrência de requisições esperada mais os workers, mais as conexões que os inserts em lote mantêm durante a espera; o padrão do próprio driver se esgota sob escritas em massa.
Inserts em lote LOOM_CH_BATCHED_INSERTS (padrão ativado), LOOM_CH_BATCHED_INSERT_WAIT_MIN_MS (10), LOOM_CH_BATCHED_INSERT_WAIT_MAX_MS (50), LOOM_CH_BATCHED_INSERT_BACKGROUND_WAIT_MAX_MS (200) Inserts concorrentes compartilham uma parte, com até a latência da janela cada um; um insert isolado espera o mínimo; cada insert em espera mantém uma conexão do pool, então o pool cresce com a taxa de escrita (inserts em lote).
Espera pelo pool LOOM_CH_POOL_WAIT_MS (padrão 500) Após esse tempo, a requisição falha rapidamente com 503 OVERLOADED em vez de entrar na fila; 0 = sem limite.
Keep-alive LOOM_CH_KEEPALIVE_TIMEOUT (padrão 5 s) Deve ficar abaixo do corte por inatividade do balanceador de carga, para que o Loom feche a conexão do pool primeiro.
Prazos de instrução LOOM_CH_TIMEOUT_READ_S, LOOM_CH_TIMEOUT_WRITE_S, LOOM_CH_TIMEOUT_DDL_S Aplicados como max_execution_time e como um limite no cliente que libera o slot do pool; 0 = sem limite para essa classe.
Prioridade por classe de tráfego LOOM_CH_SETTINGS_BY_TRAFFIC_CLASS (JSON) priority e max_threads por classe (production, interactive, bench, background), para que benchmarks e workers cedam vez às leituras de produção.
Read-your-writes LOOM_CH_READ_YOUR_WRITES, LOOM_CH_READ_YOUR_WRITES_WINDOW_S Leituras sequencialmente consistentes após uma escrita; tem custo em serviços replicados e não faz nada em um único nó.
Orçamentos de operação LOOM_LATENCY_BUDGET_MULTIPLIER Multiplica o budget_p99_ms de cada op; um salto WAN até o ClickHouse precisa de cerca de 20. Os orçamentos apenas geram eventos budget.violated; não interrompem requisições.

A capacidade web é LOOM_WEB_WORKERS por contêiner vezes o número de contêineres; o limitador de taxa divide seus limites pelas réplicas ativas que ele conta em loom.instances, nunca menos que LOOM_REPLICA_COUNT (réplicas).

Provedores

Alavanca Configuração Compromisso
Limite do embedding da consulta LOOM_MEMORY_SEARCH_EMBED_BOUND_S, LOOM_MEMORY_SEARCH_EMBED_BOUND_RETRIES Limite por tentativa para o embedding da consulta; depois das novas tentativas, a busca responde 503 EMBED_TIMEOUT.
Grafia da consulta LOOM_MEMORY_SEARCH_QUERY_SPELLING_MAX_WORDS Uma consulta com no máximo essa quantidade de palavras lê o namespace uma vez, junto ao embedding, para gerar o embedding de suas palavras em minúsculas na grafia do corpus: 100–300 ms para um namespace de 40k linhas, reaproveitado por um minuto; 0 = desativado.
Caches de embedding da consulta LOOM_EMBEDDING_CACHE_SIZE, LOOM_EMBEDDING_CACHE_TTL_S, LOOM_EMBEDDING_CACHE_SHARED, LOOM_EMBEDDING_CACHE_SHARED_MAX_CHARS Um LRU por processo na frente de um loom.embedding_cache compartilhado; consultas repetidas dispensam a chamada ao provedor.
Cache de respostas do LLM por classe LOOM_LLM_POLICY_BY_TRAFFIC_CLASS (JSON) Faz cache das respostas do LLM (ativado por padrão para bench) e pode impedir que uma classe use a camada forte ou intermediária.
Modelo de fallback LOOM_LLM_FALLBACK_MODEL Responde quando o primário continua indisponível após as novas tentativas, em vez de fazer a op falhar.
Limite de gasto LOOM_DEFAULT_DAILY_COST_CAP_USD (por namespace daily_cost_cap_usd) Acima do limite, os workers baseados em LLM ignoram o namespace e memory.ask se abstém com budget_capped; leituras e escritas simples continuam.

Escolha do embedder

Embedder (LOOM_EMBEDDING_MODEL) Compromisso
text-embedding-3-large, gemini-embedding-001 Padrão de 3072 dimensões do Loom; qualidade e custo ainda precisam ser medidos nos seus dados.
text-embedding-3-small Opção de vetor mais estreito, de 1536; mudar a largura exige gerar os embeddings novamente.
local, local:bge-small, local:bge-base, local:minilm Embedding em CPU no próprio processo, sem chamada ao provedor nem chave; troca qualidade por latência e custo.
fake-ngram-3072 N-gramas de caracteres na largura padrão, apenas para testes e integração; os números de recall não significam nada.

Trocar o embedder muda o espaço vetorial: defina LOOM_EMBEDDING_DIM de acordo, execute loom reembed e, com limiares adaptativos ativados, deixe a sondagem de inicialização recalibrar. Execute make bench-quick antes e depois; o mesmo vale para LOOM_LLM_MODEL, com o qual os prompts de extração são calibrados.

Workers e lotes

Todo worker tem um interruptor *_ENABLED e uma cadência *_INTERVAL_SECONDS, e muitos têm uma pausa *_IDLE_INTERVAL_SECONDS após uma passagem que não encontrou nada (referência de workers). Intervalos menores reduzem o atraso do trabalho em segundo plano ao custo de mais varreduras; o intervalo ocioso mantém uma fila vazia barata.

Worker Ajustes
embedding_worker LOOM_EMBEDDING_WORKER_INTERVAL_SECONDS, _IDLE_INTERVAL_SECONDS; LOOM_EMBEDDING_WORKER_ORPHAN_FULL_SCAN_SECONDS / _ORPHAN_RECENT_SECONDS limitam o anti-join de órfãos.
extraction_queue LOOM_EXTRACTION_QUEUE_INTERVAL_SECONDS, _MAX_BATCHES_PER_PASS, _NAMESPACE_CONCURRENCY, _LEASE_SECONDS; LOOM_EXTRACTION_DEFER_AGENTS adia set_from_messages para os agentes listados, de modo que a requisição retorna antes da extração.
memory_expiry_sweep LOOM_MEMORY_EXPIRY_SWEEP_BATCH_SIZE.
task_lease_sweep LOOM_TASK_LEASE_SWEEP_INTERVAL_SECONDS, _IDLE_INTERVAL_SECONDS.

Os workers rodam na classe de tráfego background, então LOOM_CH_SETTINGS_BY_TRAFFIC_CLASS também limita a prioridade e as threads deles no ClickHouse. Execute exatamente um processo de workers: uma segunda cópia de um worker baseado em LLM dobra suas varreduras e seu gasto. Os workers de ingestão e da camada do compilador do plano de código têm seus próprios ajustes (operações do índice de código).

Ajustes no lado do cliente

Alguns dos maiores ganhos estão na própria requisição:

  • Peça menos corpos: bodies e body_budget_tokens em memory.search, token_budget em context.pack e code.search.
  • Carregue o contexto uma vez por tarefa (context.pack) em vez de fazer uma busca a cada passo.
  • Use retrieval_budget para escolher um perfil de busca mais barato ou mais profundo a cada chamada.
  • Repita operações idempotentes com um header Idempotency-Key (os SDKs geram um): uma repetição retorna a resposta armazenada em vez de executar a operação novamente.

Relacionados