번역되지 않은 페이지는 영어로 열리며 영어로 표시됩니다.
이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.
백그라운드 워커 추가
워커는 server/workers/registry.py(_WORKERS)의 한 행과 패스 함수 하나를 가진 모듈로 구성됩니다. enabled_workers()는 활성화된 행을 WorkerSpec으로 변환하고, WorkerSupervisor(server/workers/supervisor.py)는 각 워커를 실행하고, 시간을 측정하고, 백오프를 적용하고, 종료 처리를 합니다. 생성된 워커 레퍼런스에서 모든 행을 확인할 수 있습니다.
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. 패스 작성하기
server/<domain>/workers/<name>.py에 async def run_pass()를 만듭니다. 슈퍼바이저는 이 함수를 간격마다 한 번 호출하고 반환값은 버립니다. 작은 예시는 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
패스 규약은 다음과 같습니다.
- 멱등성과 제한된 작업량. 패스는 마감 시간에 취소될 수도 있고, 크래시 후 다시 실행될 수도 있으며, 배포 후 다른 색상에서 실행될 수도 있습니다. 제한된 양의 작업만 수행하고 나머지는 다음 패스에 남겨 두세요.
- 마감 시간. 기본값은
min(4 × interval, 900 s)이며 최소 60 s입니다(default_max_pass_seconds). 마감 시간을 넘긴 패스는 취소되며 실패로 집계됩니다. 더 오래 걸리는 패스에는 해당 행에max_pass_seconds또는max_pass_setting을 설정하세요. - 실패. 예외가 발생하면 패스가 실패합니다. 슈퍼바이저는 지수 백오프(1 s에서 시작해 60 s까지 두 배씩 증가)로 재시도하며, 연속 3회 실패하면 워커를
degraded로 표시합니다. 마감 시간에 중단된 패스나, 간격이 마감 시간보다 긴 워커(일간 및 주간 패스)는 전체 간격만큼 기다립니다(failure_hold_seconds). 그래서 재시도가 같은 데이터베이스 시간을 다시 소모하지 않습니다. - 부분 실패. 패스 자체는 실패시키지 않고 일부 단계만 실패하는 경우
pass_context.note_failure(exc, what)를 호출합니다. 이 호출은 연속 실패 횟수에 반영되며loom.worker.partial_failures{worker}에 표시됩니다. - 유휴. 처리할 것이 없었던 패스는
pass_context.mark_idle()을 호출합니다. 그러면 슈퍼바이저는idle_interval_seconds만큼 대기합니다. - 커서. 페이징하는 워커는
pass_context.resume_cursor()로 커서를 읽고, 멈춘 지점에서pass_context.set_cursor(value)를 호출합니다. 커서는 해당 패스의loom.worker_status행에 저장되므로 프로세스를 재시작해도 이어서 실행됩니다. - 광범위한
except에는 이유를 적습니다.# noqa: BLE001 — <what must not fail>
2. 쿼리 출처 지정하기
supervisor는 모든 패스에 태그를 붙입니다.
- ClickHouse 쿼리는
log_commentworker.<name>을 가집니다(server/workers/status.py의set_worker_identity). - 프로바이더 스팬은
loom.operation=worker.<name>을 가집니다. - 패스는 백그라운드 트래픽 클래스(
bind_background)에서 실행됩니다. - 패스의 LLM 및 임베더 사용 비용은 하나의 원장 행
worker.<name>.pass에 기록됩니다.
supervisor 밖에서 도는 루프(태스크, 스레드, CLI 루프)는 스스로 태그를 지정해야 합니다. 그렇지 않으면 해당 쿼리가 untagged:<module>.<function>으로 기록됩니다.
from server.core.ch import set_query_tag
set_query_tag("worker.my_loop")
3. 설정 추가하기
server/settings/catalog.py에서 해당 영역의 섹션(Memory, Code, Tracker 등)에 스위치와 실행 주기를 추가합니다. 각 주석은 생성되는 설정 레퍼런스에서 해당 행의 설명 텍스트가 됩니다.
# 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
워커가 자격 증명을 필요로 하거나, 외부 제공자에 비용을 지출하거나, 운영자가 직접 선택해 사용하는 플레인을 담당한다면 기본값을 off로 설정합니다. 기본값이 on인 워커는 노트북을 포함한 모든 스택에서 실행됩니다.
4. 레지스트리 행 추가
(
_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",
),
)
_Worker 필드 |
의미 |
|---|---|
name |
워커의 이름입니다. 로그 태그, 원장 operation, 상태 행에 쓰입니다. |
module |
전체 모듈 경로입니다. 워커가 활성화된 경우에만 import되므로 부팅이 빠르게 유지되고 선택적 의존성은 선택 사항으로 남습니다. |
enabled |
워커를 켜는 설정 플래그입니다. None이면 항상 켜집니다. |
interval |
주기를 초 단위로 담고 있는 설정 필드입니다. |
pass_attr |
패스 함수의 이름입니다(기본값 run_pass). |
also_requires |
워커에 필요한 두 번째 설정 플래그입니다(읽는 원장, 제공하는 플레인). 꺼져 있으면 워커도 꺼집니다. |
idle_interval |
유휴 패스 이후의 대기 시간을 담는 설정 필드입니다. |
max_pass_seconds, max_pass_setting |
패스 제한 시간입니다. 고정값을 쓰거나 설정에서 읽습니다. |
first_pass_due |
모듈 속성입니다. 시작할 때 한 번 호출되는 비동기 검사이며, True이면 부팅 지연 이후가 아니라 지금 첫 패스를 실행합니다. |
owned_tables |
True: 모듈이 OWNED_TABLES와 due_scope를 export합니다. 범위 내 네임스페이스에 대해 소유 테이블에 행이 없으면 첫 패스가 실행 대상이 됩니다. |
부팅 지연. 첫 패스 훅이 없으면 첫 패스는 crc32(name) % interval만큼 기다립니다. 그러면 몇 시간만 살아 있는 프로세스에서 하루 주기 워커는 한 번도 실행되지 않을 수 있으므로, 워커가 채우는 대상을 선언하세요.
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
이는 server/tracker/workers/embed.py의 선언입니다. 검사는 테이블당 쿼리 한 번이며 FIRST_PASS_DUE_TIMEOUT_SECONDS로 제한됩니다. 읽을 수 없는 테이블은 실행 대상으로 간주됩니다.
5. 실행 위치 이해하기
배포당 하나의 supervisor. server/workers/leader.py는 ClickHouse를 통해 모든 컨테이너와 호스트에 걸쳐 하나의 프로세스를 선출합니다. 이때 Keeper 락 테이블 loom._migration_lock의 workers_supervisor 키를 사용합니다. 리더는 LOOM_SUPERVISOR_LEASE_TTL_S / 6마다 임대를 갱신합니다. 임대를 잃은 리더는 자신의 워커를 중지합니다. 리더가 종료되면 LOOM_SUPERVISOR_LEASE_TTL_S(기본값 30초)가 지난 뒤 다른 프로세스가 이를 이어받습니다.
LOOM_BACKGROUND_WORKERS |
효과 |
|---|---|
auto (기본값) |
임대를 얻기 위해 경쟁하고, 임대를 보유하는 동안 supervisor를 실행합니다. 배포 환경 밖(LOOM_DEPLOYMENT 없음)에서는 off입니다. |
on |
항상 supervisor를 실행합니다. |
off |
웹만 실행합니다. |
모든 레플리카를 auto로 실행하세요. 어떤 레플리카든 리더가 될 수 있습니다. make server 또는 iso 서버는 on으로 설정하지 않으면 워커를 실행하지 않습니다.
두 복사본이 잠시 겹칠 수 있습니다. 리더는 갱신 없이 T/2가 지나면 워커를 중지하며, 이는 다른 프로세스가 T에 이어받기 전입니다. 그러나 이미 전송된 구문은 그대로 반영되며, on 프로세스는 임대를 가져가지 않습니다. 두 번째 복사본이 해를 끼치지 않도록 만드세요. 멱등 쓰기, 임대 기반 클레임, 저장소에 보관하는 커서가 그 방법입니다. LLM에 비용을 쓰는 워커는 두 복사본이 실행되는 동안 비용이 두 배가 됩니다.
배치 사이에서 중단하기. 오래 도는 루프는 쓰기를 수행하는 배치마다 앞서 pass_context.check_stop()을 호출합니다. 이 호출은 패스가 중지되었거나 임대가 만료되면 PassStopped를 발생시키며, asyncio.to_thread에서 실행 중인 작업에도 전달됩니다. PassBudget.exhausted()는 이를 대신 호출해 줍니다.
롤링 업그레이드. 이전 빌드는 실행 중인 최신 빌드에 임대를 양보합니다(장애와 복구 참고). 이전 리더는 중지될 때 임대를 해제하고, 더 새로운 프로세스가 다음 라운드에서 몇 초 안에 이를 가져갑니다.
6. 테스트에 고정하기
-
레지스트리 스냅샷.
tests/unit/test_worker_registry_snapshot.py는 세 가지 설정 프로필(defaults,all_on,production)에서 워커 목록을 만들고, 모든WorkerSpec필드를tests/unit/snapshots/worker_registry.json과 비교합니다. 의도한 변경일 때만 다시 생성하세요.LOOM_UPDATE_WORKER_SNAPSHOT=1 python -m pytest tests/unit/test_worker_registry_snapshot.pyproduction에서 해당 워커를 실행해야 한다면, 이 테스트의
_PRODUCTION_FLAGS에 워커의 플래그를 추가하세요.
- 일치 검사.
tests/unit/test_worker_registry_parity.py는 모든 플래그를 켠 상태에서worker_meta()(/v1/admin/workers.status가 렌더링하는 내용)와enabled_workers()가 동일한 집합을 나열하는지 확인합니다. - 패스 자체. 단위 테스트에서 스텁 리포지토리 또는 로컬 ClickHouse를 대상으로
run_pass()를 호출합니다. 감독되는 패스 밖에서는pass_context호출이 로그만 남깁니다. - 생성된 문서.
python scripts/codegen/docs_reference.py는 워커 레퍼런스를 다시 생성합니다. 이 문서가 최신이 아니면make lint가 실패합니다.
7. 실행 확인
/v1/admin/workers.status는 이 프로세스의 레지스트리와 워커별 최신loom.worker_status행을 병합하므로, 웹 티어에서 workers 컨테이너에서 실행 중인 워커를 확인할 수 있습니다./v1/health?include=workers는 워커별 상태와workers_leader를 보고합니다. 이 값은 응답하는 프로세스가 잠금을 보유하고 있는지와 그 이유를 나타냅니다.loom.worker.consecutive_failures{worker}와loom.worker.partial_failures{worker}에 알림을 설정하세요 (모니터링).