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.
Adicionar um worker em segundo plano
Um worker é uma linha em server/workers/registry.py (_WORKERS) mais um módulo com uma função de passagem. enabled_workers() transforma as linhas habilitadas em WorkerSpecs, e o WorkerSupervisor (server/workers/supervisor.py) executa, mede o tempo, aplica backoff e drena cada um. A referência de workers gerada lista todas as linhas.
flowchart LR
S["settings<br/><name>_enabled, <name>_interval_seconds"] --> R["_Worker row<br/>in _WORKERS"]
R --> E["enabled_workers()<br/>WorkerSpec"]
L["leader.py<br/>supervisor lock"] --> V["WorkerSupervisor"]
E --> V
V --> P["run_pass()<br/>server/<domain>/workers/<name>.py"]
V --> W["loom.worker_status<br/>/v1/admin/workers.status"]
1. Escreva o pass
Crie server/<domain>/workers/<name>.py com um async def run_pass(). O supervisor o chama uma vez por intervalo e descarta o valor de retorno. Um exemplo pequeno é server/tasks/workers/lease_sweep.py:
from server.workers import pass_context
from server.workers.status import record_pass
async def run_pass() -> SweepResult:
from server.tasks.app.sweep import sweep_once
with record_pass("task_lease_sweep") as rec:
counts = await sweep_once()
rec.outcome = dict(counts)
result = SweepResult(**counts)
if result.total == 0:
pass_context.mark_idle()
else:
log.info("task_lease_sweep: expired=%d ...", result.expired)
return result
O contrato do pass:
- Idempotente e limitado. Um pass pode ser cancelado no seu prazo, executado novamente após uma falha ou executado na outra cor após um deploy. Faça uma quantidade limitada de trabalho e deixe o restante para o próximo pass.
- Prazo. O padrão é
min(4 × interval, 900 s), com piso de 60 s (default_max_pass_seconds). Um pass que ultrapassa o prazo é cancelado e conta como falha. Definamax_pass_secondsoumax_pass_settingna linha para um pass mais longo. - Falhas. Uma exceção faz o pass falhar. O supervisor tenta novamente com backoff exponencial (de 1 s, dobrando até 60 s) e marca o worker como
degradedapós 3 falhas consecutivas. Um pass interrompido no prazo, ou um worker cujo intervalo excede o prazo (passes diários e semanais), espera o intervalo inteiro (failure_hold_seconds), para que uma nova tentativa não gaste o mesmo tempo de banco de dados novamente. - Falhas parciais. Uma etapa que falha sem fazer o pass falhar chama
pass_context.note_failure(exc, what). Ela conta para a sequência de falhas e aparece emloom.worker.partial_failures{worker}. - Ocioso. Um pass que não encontrou nada chama
pass_context.mark_idle(). O supervisor então esperaidle_interval_seconds. - Cursor. Um worker que percorre páginas lê
pass_context.resume_cursor()e chamapass_context.set_cursor(value)onde parou. O cursor é armazenado na linhaloom.worker_statusdo pass, de modo que um processo reiniciado retoma de onde parou. - Um
exceptamplo diz o porquê:# noqa: BLE001 — <what must not fail>.
2. Atribua as consultas dela
O supervisor marca cada execução:
- as consultas ao ClickHouse carregam
log_commentworker.<name>(set_worker_identityemserver/workers/status.py); - os spans do provedor carregam
loom.operation=worker.<name>; - a execução roda na classe de tráfego em segundo plano (
bind_background); - o gasto de LLM e de embedder cai em uma única linha do ledger,
worker.<name>.pass.
Um loop fora do supervisor (uma task, uma thread, um loop de CLI) deve se marcar sozinho; caso contrário, suas consultas são registradas como untagged:<module>.<function>:
from server.core.ch import set_query_tag
set_query_tag("worker.my_loop")
3. Adicione as configurações
Adicione o interruptor e a cadência à seção da área em server/settings/catalog.py (Memory, Code, Tracker, …). Cada comentário se torna o texto da linha na referência de configuração gerada.
# Lease sweeper: return expired leases to todo, resume deferred tasks at
# resume_at, escalate stale triage. One read per pass.
task_lease_sweep_enabled: bool = True
# Seconds between passes while there is work.
task_lease_sweep_interval_seconds: int = 60
# Seconds between passes that found nothing.
task_lease_sweep_idle_interval_seconds: int = 300
Deixe um worker desativado por padrão quando ele precisa de credenciais, gera custo em um provedor ou atende um plano que o operador ativa por escolha própria. Workers ativados por padrão rodam em todas as stacks, inclusive em um laptop.
4. Adicione a linha no registro
(
_Worker(
"task_lease_sweep",
"server.tasks.workers.lease_sweep",
"task_lease_sweep_enabled",
"task_lease_sweep_interval_seconds",
idle_interval="task_lease_sweep_idle_interval_seconds",
),
)
Campo de _Worker |
Significado |
|---|---|
name |
O nome do worker: a tag de log, a operação do ledger, a linha de status. |
module |
O caminho completo do módulo. Só é importado quando o worker está habilitado, para que o boot continue rápido e as dependências opcionais continuem opcionais. |
enabled |
O flag de configuração que o liga; None = sempre ligado. |
interval |
O campo de configuração que guarda a cadência em segundos. |
pass_attr |
O nome da função de passada (padrão run_pass). |
also_requires |
Um segundo flag de configuração de que o worker precisa (o ledger que ele lê, o plano que ele atende); desligado → o worker fica desligado. |
idle_interval |
Campo de configuração para a espera após uma passada ociosa. |
max_pass_seconds, max_pass_setting |
O prazo da passada, fixo ou lido de uma configuração. |
first_pass_due |
Um atributo do módulo: uma verificação assíncrona consultada uma vez na inicialização; True executa a primeira passada agora, em vez de após o escalonamento do boot. |
owned_tables |
True: o módulo exporta OWNED_TABLES e due_scope; a primeira passada é devida quando uma tabela própria não tem linha para um namespace no escopo. |
Escalonamento do boot. Sem um hook de primeira passada, a primeira passada espera crc32(name) % interval. Um worker diário em processos que vivem algumas horas pode, assim, nunca executar, então declare o que ele preenche:
from server.workers.first_pass import OwnedTable
OWNED_TABLES = (OwnedTable("loom.qa_item_embeddings", namespace_column="namespace"),)
def due_scope() -> list[tuple[str, str]]: ... # the (org, namespace) pairs this worker fills
Essa é a declaração de server/tracker/workers/embed.py. A verificação é uma instrução por tabela, limitada por FIRST_PASS_DUE_TIMEOUT_SECONDS. Uma tabela ilegível conta como devida.
5. Entenda onde ele roda
Um supervisor por deployment. server/workers/leader.py elege um único processo entre todos os containers e hosts por meio do ClickHouse: a chave workers_supervisor na tabela de lock do Keeper loom._migration_lock. Quem detém o lease o renova a cada LOOM_SUPERVISOR_LEASE_TTL_S / 6; um detentor que perde o lease interrompe seus workers; quando o detentor morre, outro processo assume após LOOM_SUPERVISOR_LEASE_TTL_S (padrão 30 s).
LOOM_BACKGROUND_WORKERS |
Efeito |
|---|---|
auto (padrão) |
Disputa o lease; executa o supervisor enquanto o detém. Fora do deployment (sem LOOM_DEPLOYMENT), equivale a off. |
on |
Sempre executa o supervisor. |
off |
Somente web. |
Execute todas as réplicas em auto: qualquer uma delas pode se tornar a líder. Um servidor make server ou iso não executa workers, a menos que defina on.
Duas cópias podem se sobrepor brevemente. Um detentor interrompe seus workers em T/2 sem uma renovação, antes que outro processo possa assumir em T, mas uma instrução que ele já enviou ainda é aplicada, e um processo on não obtém lease. Torne inofensiva uma segunda cópia: escritas idempotentes, claims com lease, cursores no armazenamento. Um worker que gasta com um LLM dobra seu gasto enquanto duas cópias estão em execução.
Pare entre lotes. Um loop longo chama pass_context.check_stop() antes de cada lote que grava. Ele levanta PassStopped quando a passagem foi interrompida ou o lease ficou obsoleto, o que também alcança o trabalho executado em asyncio.to_thread. PassBudget.exhausted() o chama por você.
Upgrades graduais. Um build mais antigo cede o lease a um build mais novo ativo (veja Falha e recuperação). O líder antigo libera o lease ao parar, e um processo mais novo o assume na rodada seguinte, em poucos segundos.
6. Fixe o comportamento nos testes
-
Snapshot do registry.
tests/unit/test_worker_registry_snapshot.pymonta a lista de workers em três perfis de configuração (defaults,all_on,production) e compara cada campo deWorkerSpeccomtests/unit/snapshots/worker_registry.json. Regenere o snapshot apenas quando a mudança for intencional:LOOM_UPDATE_WORKER_SNAPSHOT=1 python -m pytest tests/unit/test_worker_registry_snapshot.pySe o worker deve rodar em produção, adicione a flag dele a
_PRODUCTION_FLAGSnesse teste.
- Paridade.
tests/unit/test_worker_registry_parity.pyverifica queworker_meta()(o que/v1/admin/workers.statusexibe) eenabled_workers()listam o mesmo conjunto com todas as flags ativadas. - A própria passagem. Um teste unitário chama
run_pass()contra um repositório stub ou um ClickHouse local. Fora de uma passagem supervisionada, as chamadas depass_contextapenas registram log. - Documentação gerada.
python scripts/codegen/docs_reference.pyregenera a referência de workers;make lintfalha enquanto ela estiver desatualizada.
7. Verifique se está funcionando
/v1/admin/workers.statuscombina o registro deste processo com a linha mais recente deloom.worker_statuspor worker, de modo que a camada web mostra os workers em execução no contêiner de workers./v1/health?include=workersinforma o status de cada worker eworkers_leader: se o processo que respondeu detém o lock e por quê.- Configure alertas para
loom.worker.consecutive_failures{worker}eloom.worker.partial_failures{worker}(monitoramento).