添加后台 worker
本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.
worker 是 server/workers/registry.py(_WORKERS)中的一行,加上一个带有单个 pass 函数的模块。enabled_workers() 会把已启用的行转换为 WorkerSpec,WorkerSupervisor(server/workers/supervisor.py)负责运行、计时、退避和排空每个 worker。自动生成的 worker 参考列出了每一行。
1. 编写 pass
创建 server/<domain>/workers/<name>.py,其中包含一个 async def run_pass()。supervisor 每隔一个间隔调用它一次,并丢弃其返回值。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
pass 的约定:
- 幂等且有界。 pass 可能在截止时间被取消,在崩溃后重新运行,或在部署后于另一种颜色的实例上运行。每次只做有限量的工作,其余留给下一次 pass。
- 截止时间。 默认值为
min(4 × interval, 900 s),下限为 60 s(default_max_pass_seconds)。超过截止时间的 pass 会被取消,并计为一次失败。若某个 pass 需要更长时间,请在该行上设置max_pass_seconds或max_pass_setting。 - 失败。 异常会使 pass 失败。supervisor 以指数退避重试(从 1 s 起翻倍,直至 60 s),连续失败 3 次后将该 worker 标记为
degraded。在截止时间被中断的 pass,或间隔超过其截止时间的 worker(每日和每周的 pass),会等待完整的间隔(failure_hold_seconds),这样重试就不会再次消耗同样的数据库时间。 - 部分失败。 某个分支失败但并未使整个 pass 失败时,调用
pass_context.note_failure(exc, what)。它会计入连续失败次数,并显示在loom.worker.partial_failures{worker}中。 - 空闲。 没有发现任何工作的 pass 调用
pass_context.mark_idle()。随后 supervisor 会休眠idle_interval_seconds。 - 游标。 分页处理的 worker 读取
pass_context.resume_cursor(),并在停下的位置调用pass_context.set_cursor(value)。游标存储在该 pass 的loom.worker_status行上,因此重启后的进程可以接着处理。 - 宽泛的
except要说明原因:# noqa: BLE001 — <what must not fail>。
2. 标记其查询归属
supervisor 会为每一轮执行打上标记:
- ClickHouse 查询携带
log_commentworker.<name>(见server/workers/status.py中的set_worker_identity); - provider span 携带
loom.operation=worker.<name>; - 该轮执行在后台流量类别中运行(
bind_background); - 其 LLM 和 embedder 的开销会记入同一条账本记录
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
如果 worker 需要凭据、会在提供商上产生费用,或者服务于需要运维人员主动启用的平面,则将其默认设为关闭。默认开启的 worker 会在每个部署环境中运行,包括笔记本电脑。
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 |
worker 的名称:日志标签、账本操作、状态行。 |
module |
完整的模块路径。仅在 worker 启用时才导入,因此启动保持快速,可选依赖也保持可选。 |
enabled |
用于开启该 worker 的设置标志;None = 始终开启。 |
interval |
保存执行周期(以秒为单位)的设置字段。 |
pass_attr |
pass 函数的名称(默认为 run_pass)。 |
also_requires |
worker 所需的第二个设置标志(它读取的账本、它服务的平面);关闭 → 该 worker 关闭。 |
idle_interval |
空闲 pass 之后休眠时长的设置字段。 |
max_pass_seconds, max_pass_setting |
pass 的截止时间,可固定指定,也可从设置中读取。 |
first_pass_due |
模块属性:启动时询问一次的异步检查;返回 True 则立即运行第一次 pass,而不是等到启动错峰之后。 |
owned_tables |
True:模块导出 OWNED_TABLES 和 due_scope;当某个自有表在范围内的命名空间中没有对应行时,第一次 pass 即到期。 |
启动错峰。 如果没有第一次 pass 的钩子,第一次 pass 会等待 crc32(name) % interval。这样一来,在只存活数小时的进程上,每日运行的 worker 可能永远不会运行,因此请声明它负责填充的内容:
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 续约一次;失去租约的持有者会停止它的 worker;持有者退出后,另一个进程会在 LOOM_SUPERVISOR_LEASE_TTL_S(默认 30 秒)之后接管。
LOOM_BACKGROUND_WORKERS |
效果 |
|---|---|
auto(默认) |
竞争租约;持有租约期间运行 supervisor。在部署之外(没有 LOOM_DEPLOYMENT)时为 off。 |
on |
始终运行 supervisor。 |
off |
只运行 Web。 |
让每个副本都以 auto 运行:任何一个都可能成为 leader。make server 或 iso server 除非设置为 on,否则不会运行任何 worker。
两个副本可能短暂重叠。 持有者在 T/2 内没有续约时会停止它的 worker,早于其他进程在 T 时接管,但它已经发出的语句仍会生效,而且 on 进程不会获取租约。要让第二个副本无害:使用幂等写入、带租约的认领、保存在存储中的游标。调用 LLM 的 worker 在两个副本同时运行期间,开销会翻倍。
在批次之间停止。 长循环在写入每个批次之前调用 pass_context.check_stop()。一旦该轮次被停止或租约过期,它就会抛出 PassStopped,这也会影响在 asyncio.to_thread 中运行的工作。PassBudget.exhausted() 会替你调用它。
滚动升级。 较旧的构建会把租约让给仍在运行的较新构建(参见故障与恢复)。旧的 leader 在停止时释放租约,较新的进程会在下一轮(几秒内)接管。
6. 在测试中固定行为
-
Registry 快照。
tests/unit/test_worker_registry_snapshot.py在三种设置配置(defaults、all_on、production)下构建 worker 列表,并将每个WorkerSpec字段与tests/unit/snapshots/worker_registry.json进行比较。仅在有意变更时才重新生成快照:LOOM_UPDATE_WORKER_SNAPSHOT=1 python -m pytest tests/unit/test_worker_registry_snapshot.py如果 production 应运行该 worker,请将其标志添加到该测试中的
_PRODUCTION_FLAGS。 -
一致性。
tests/unit/test_worker_registry_parity.py检查在所有标志开启时,worker_meta()(/v1/admin/workers.status所渲染的内容)与enabled_workers()列出的集合相同。 -
pass 本身。 单元测试针对桩仓库(stub repository)或本地 ClickHouse 调用
run_pass()。在受监督的 pass 之外,pass_context的调用只会记录日志。 -
生成的文档。
python scripts/codegen/docs_reference.py会重新生成 workers 参考文档;在文档过期时,make lint会失败。
7. 检查是否运行
/v1/admin/workers.status会将本进程的注册表与每个 worker 最新的loom.worker_status行合并,因此 Web 层可以显示在 workers 容器中运行的 worker。/v1/health?include=workers会报告每个 worker 的状态以及workers_leader:即应答的进程是否持有锁,以及原因。- 对
loom.worker.consecutive_failures{worker}和loom.worker.partial_failures{worker}设置告警(监控)。