Las páginas sin traducir se abren en inglés y se indican como inglés.
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Añadir un worker en segundo plano
Un worker es una fila en server/workers/registry.py (_WORKERS) más un módulo con una función de pasada. enabled_workers() convierte las filas habilitadas en WorkerSpecs, y WorkerSupervisor (server/workers/supervisor.py) ejecuta, mide el tiempo, aplica retroceso y drena cada uno. La referencia de workers generada enumera cada fila.
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. Escribir el pass
Crea server/<domain>/workers/<name>.py con un async def run_pass(). El supervisor lo llama una vez por intervalo y descarta el valor de retorno. Un ejemplo pequeño es 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
El contrato del pass:
- Idempotente y acotado. Un pass puede cancelarse al llegar a su plazo, volver a ejecutarse tras una caída o ejecutarse en el otro color después de un despliegue. Haz una cantidad acotada de trabajo y deja el resto para el siguiente pass.
- Plazo. El valor por defecto es
min(4 × interval, 900 s), con un mínimo de 60 s (default_max_pass_seconds). Un pass que lo supera se cancela y cuenta como un fallo. Definemax_pass_secondsomax_pass_settingen la fila para un pass más largo. - Fallos. Una excepción hace fallar el pass. El supervisor reintenta con backoff exponencial (de 1 s, duplicándose hasta 60 s) y marca el worker como
degradedtras 3 fallos consecutivos. Un pass cortado en su plazo, o un worker cuyo intervalo supera su plazo (los pass diarios y semanales), espera el intervalo completo (failure_hold_seconds), de modo que un reintento no gaste otra vez el mismo tiempo de base de datos. - Fallos parciales. Una parte que falla sin hacer fallar el pass llama a
pass_context.note_failure(exc, what). Cuenta para la racha y aparece enloom.worker.partial_failures{worker}. - Inactivo. Un pass que no encontró nada llama a
pass_context.mark_idle(). Entonces el supervisor esperaidle_interval_seconds. - Cursor. Un worker que pagina lee
pass_context.resume_cursor()y llama apass_context.set_cursor(value)donde se detuvo. El cursor se guarda en la filaloom.worker_statusdel pass, así que un proceso reiniciado continúa desde ahí. - Un
exceptamplio explica por qué:# noqa: BLE001 — <what must not fail>.
2. Atribuir sus consultas
El supervisor etiqueta cada pasada:
- Las consultas a ClickHouse llevan
log_commentworker.<name>(set_worker_identityenserver/workers/status.py); - los spans del proveedor llevan
loom.operation=worker.<name>; - la pasada se ejecuta en la clase de tráfico en segundo plano (
bind_background); - el gasto de LLM y del embedder queda en una sola fila del libro de registro,
worker.<name>.pass.
Un bucle fuera del supervisor (una tarea, un hilo, un bucle de CLI) se etiqueta a sí mismo; de lo contrario, sus consultas se registran como untagged:<module>.<function>:
from server.core.ch import set_query_tag
set_query_tag("worker.my_loop")
3. Agregar sus ajustes
Agrega el interruptor y la cadencia a la sección del área en server/settings/catalog.py (Memory, Code, Tracker, …). Cada comentario se convierte en el texto de la fila en la referencia de configuración generada.
# 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
Deja un worker desactivado por defecto cuando necesita credenciales, genera costos en un proveedor o atiende un plano que un operador activa por decisión propia. Los workers activados por defecto se ejecutan en todas las instalaciones, incluido un portátil.
4. Añadir la fila del 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 |
El nombre del worker: la etiqueta del log, la operación del ledger, la fila de estado. |
module |
La ruta completa del módulo. Solo se importa cuando el worker está habilitado, de modo que el arranque sigue siendo rápido y las dependencias opcionales siguen siendo opcionales. |
enabled |
El flag de configuración que lo activa; None = siempre activo. |
interval |
El campo de configuración que contiene la cadencia en segundos. |
pass_attr |
El nombre de la función de pasada (por defecto run_pass). |
also_requires |
Un segundo flag de configuración que el worker necesita (el ledger que lee, el plano al que sirve); si está desactivado, el worker queda desactivado. |
idle_interval |
Campo de configuración para la espera tras una pasada inactiva. |
max_pass_seconds, max_pass_setting |
El plazo límite de la pasada, fijo o leído de un ajuste. |
first_pass_due |
Un atributo del módulo: una comprobación asíncrona que se consulta una vez al inicio; True ejecuta la primera pasada de inmediato en lugar de esperar al escalonado de arranque. |
owned_tables |
True: el módulo exporta OWNED_TABLES y due_scope; la primera pasada corresponde cuando una tabla propia no tiene fila para un espacio de nombres dentro del alcance. |
Escalonado de arranque. Sin un hook de primera pasada, la primera pasada espera crc32(name) % interval. Un worker diario en procesos que viven unas pocas horas podría no ejecutarse nunca, así que declara qué rellena:
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
Esa es la declaración de server/tracker/workers/embed.py. La comprobación es una sentencia por tabla, acotada por FIRST_PASS_DUE_TIMEOUT_SECONDS. Una tabla ilegible se considera pendiente.
5. Entender dónde se ejecuta
Un supervisor por despliegue. server/workers/leader.py elige un único proceso entre todos los contenedores y hosts a través de ClickHouse: la clave workers_supervisor en la tabla de bloqueo de Keeper loom._migration_lock. El titular renueva cada LOOM_SUPERVISOR_LEASE_TTL_S / 6; un titular que pierde el lease detiene sus workers; cuando el titular muere, otro proceso toma el relevo tras LOOM_SUPERVISOR_LEASE_TTL_S (por defecto 30 s).
LOOM_BACKGROUND_WORKERS |
Efecto |
|---|---|
auto (por defecto) |
Compite por el lease; ejecuta el supervisor mientras lo mantiene. Fuera del despliegue (sin LOOM_DEPLOYMENT), off. |
on |
Ejecuta siempre el supervisor. |
off |
Solo web. |
Ejecuta cada réplica en auto: cualquiera de ellas puede convertirse en líder. Un servidor de make server o un servidor iso no ejecuta workers a menos que se configure on.
Dos copias pueden solaparse brevemente. Un titular detiene sus workers en T/2 sin una renovación, antes de que otro proceso pueda tomar el relevo en T, pero una sentencia que ya envió igualmente se aplica, y un proceso on no toma ningún lease. Haz que una segunda copia sea inofensiva: escrituras idempotentes, reclamaciones con lease, cursores en el almacén. Un worker que gasta en un LLM duplica su gasto mientras hay dos copias en ejecución.
Detenerse entre lotes. Un bucle largo llama a pass_context.check_stop() antes de cada lote que escribe. Lanza PassStopped cuando la pasada se detuvo o el lease quedó obsoleto, lo que también alcanza al trabajo que se ejecuta en asyncio.to_thread. PassBudget.exhausted() lo llama por ti.
Actualizaciones progresivas. Una compilación más antigua cede el lease a una compilación más nueva que esté activa (consulta Fallos y recuperación). El líder antiguo libera el lease cuando se detiene, y un proceso más nuevo lo toma en su siguiente ronda, en cuestión de segundos.
6. Fíjalo en las pruebas
-
Snapshot del registro.
tests/unit/test_worker_registry_snapshot.pyconstruye la lista de workers con tres perfiles de configuración (defaults,all_on,production) y compara cada campo deWorkerSpeccontests/unit/snapshots/worker_registry.json. Regenéralo solo cuando el cambio sea intencional:LOOM_UPDATE_WORKER_SNAPSHOT=1 python -m pytest tests/unit/test_worker_registry_snapshot.pySi production debe ejecutar el worker, añade su flag a
_PRODUCTION_FLAGSen esa prueba.
- Paridad.
tests/unit/test_worker_registry_parity.pycomprueba queworker_meta()(lo que muestra/v1/admin/workers.status) yenabled_workers()listan el mismo conjunto con todos los flags activados. - El pase en sí. Una prueba unitaria llama a
run_pass()contra un repositorio stub o un ClickHouse local. Fuera de un pase supervisado, las llamadas apass_contextsolo registran logs. - Documentación generada.
python scripts/codegen/docs_reference.pyregenera la referencia de workers;make lintfalla mientras esté desactualizada.
7. Comprueba que funciona
/v1/admin/workers.statuscombina el registro de este proceso con la última fila deloom.worker_statuspor cada worker, de modo que el nivel web muestra los workers que se ejecutan en el contenedor de workers./v1/health?include=workersinforma del estado de cada worker y deworkers_leader: si el proceso que responde tiene el bloqueo, y por qué.- Configura alertas sobre
loom.worker.consecutive_failures{worker}yloom.worker.partial_failures{worker}(monitorización).