Newshot

用 Go 和 spooler.sh 构建可靠的 LLM 调查流水线

Translation(model translation, not the source's own text)

使用 Spooler 的故障处理流水线

一只准备调查故障的毛茸茸的狗
一只准备调查故障的毛茸茸的狗

大家好!可能有些人已经知道,我最近发布了 spooler.sh —— 一个简单的托管消息队列。

在本文中,我想向大家展示,构建具有清晰一致性和持久性保证的流水线可以有多么简单。

我们要构建的项目很小,但非常契合当下的趋势:涉及 LLM。

我们将构建一个分布式智能体 AI 集群,它能够在有限或无人工监督的情况下执行多步操作来调查……

实际上,我们将构建一个简单的程序,根据队列积压情况来启动和关闭 worker。这些 worker 会从队列中拉取故障事件,并让 LLM 来调查它们。

认识一下这只毛茸茸的家伙

构建我在本文中要描述的这个工具花了几天时间,但后来我意识到它已经具备了相当不错的形态,可能值得作为独立的工具与世界分享,而不仅仅是一个展示示例。

所以我把它叫做 Pagedog —— 一个与“watchdog”押韵的有趣名字,但这里的“page”指的是来自寻呼机的页面。它是用 Go 写的,下面的代码片段也是如此,不过设计上并不依赖任何特定语言。

对于从未值过班的人来说,page 就是唤醒当前值班人员的告警:某个监控系统认定必须有人来看一看。pager 则是发送它的工具,PagerDuty、incident.io 和 Alertmanager 都是如此。

设计

一侧,我们有一个用于可观测性栈的 webhook 处理器 —— 它接收来自 Prometheus Alertmanager、incident.io、PagerDuty 或任何你想集成的系统的 page。

在我见过的许多实现中,包括我自己构建的系统和与其他工程师讨论过的方法,传入的 page 通常会在进一步处理之前存储在某处。另一方面,有些实现根本不存储它,而是直接立即处理。

后一种方法的风险在于你可能会丢失 page,同时还可能浪费计算资源和 LLM token。取决于你的可观测性栈及其重试行为,page 可能永远不会再次到达,或者到达得太晚。

所以我们在本文中要做的是将 page 存储到消息队列中 —— 具体来说,是一个 Spooler 队列(多么巧妙的巧合!)。这为我们提供了关于持久性和投递的有用保证。

一旦我们收到 page 并将其作为故障事件存储到队列中,这就是我们项目的一半了。另一半是从队列中把它拉回来,喂给我们选择的 LLM —— 我们让 LLM 分析该故障事件并调查可能出了什么问题。

当然,我们还需要让它能够访问我们的一些基础设施可观测性工具。否则,它除了重新表述故障事件的描述之外做不了什么。所以我们让 LLM 访问我们的指标、日志以及我们想提供的其他任何东西。


        Alertmanager   |   webhook  ┌────────────────┐      ┌────────────────┐
 incident.io    |  --------> │ pagedog server │ ───▶ │ incident queue │
 ...            |            └────────────────┘      └────────────────┘
                |                                            │
                |                                            ▼
 MCPs           |            +----------------+      ┌────────────────┐
 Prometheus     |  <-------> |      LLMs      | <--> │ pagedog worker │
 ...            |            +----------------+      └────────────────┘
                |                                            │
                |                                            ▼
 Slack          |            ┌────────────────┐      ┌────────────────┐
 incident.io    |  ◀──────── │ pagedog server │ ◀─── │  report queue  │
 ...            |            └────────────────┘      └────────────────┘
      

所承诺的特性

本文标题:用 spooler.sh 在 Go 中构建可靠的 LLM 调查流水线

正文: 这个设计带来了以下好处;下面的章节会逐一说明:

  • 一旦寻呼器收到我们返回的 200 OK,页面就再也不会丢失
  • 同一个页面被发送两次,只会产生一次调查
  • 在调查中途崩溃的 worker 会被替换,其对应的事件会被重新投递
  • 报告一旦写入,在送往下一阶段的途中就不会丢失
  • 每个下游目标都会收到每一份报告,至少一次

Webhook

webhook 服务器是这里最简单的部分。它为每个来源提供一个路由,例如 /webhook/alertmanager,而 handler 可以是任何能把 HTTP 请求转换为事件的东西:


        type IncidentSource interface {
	Handle(*http.Request) ([]pagedog.Incident, error)
}
      

每个来源首先会确认这个页面确实来自它对应的寻呼器:一个 bearer Authorization token、对请求体的签名,或者该来源规范提供的其他任何方式。

然后它从负载中读出事件,并把它们向上传递到调用栈,以便发送到 incidents 队列:这是我们系统中承载输入的“边缘”队列。只有当每一次发送都成功之后,它才返回 200 OK,确认输入已经进入且已持久化:


        incs, err := src.Handle(req)
if errors.Is(err, ErrForbidden) {
	http.Error(res, "", http.StatusForbidden)
	return
}
if err != nil {
	http.Error(res, "failed parsing body", http.StatusBadRequest)
	return
}
for _, inc := range incs {
	if err := s.enqueue(req.Context(), inc); err != nil {
		// The source may retry the whole notification: the queue
		// deduplicates what was sent already.
		http.Error(res, "failed sending job", http.StatusBadGateway)
		return
	}
}
// 200 OK.
      

这个顺序就是这一部分关于持久化的全部要点:只有当事件已经进入队列之后,寻呼器才会听到“收到了”,否则就会重试。我们通过状态码来告诉它:寻呼器在收到 5xx 时会重试,在收到 4xx 时会放弃,所以坏 token 或我们无法解析的负载会得到 403 或 400,重试也无法解决;而发送失败会得到 502,这样寻呼器就会再试一次。

这里体现了 Spooler 的第一个特性:去重。每个事件都有一个由来源从页面推导出的 key(对于 Alertmanager,就是告警的 fingerprint 加上它开始触发的时间),并告知队列按它去重:


        incidents := spooler.Queue[pagedog.Incident]{
	Client: client,
	Spool:  "default",
	Queue:  "incidents",
	Dedup: func(inc pagedog.Incident) string {
		return inc.Key
	},
}
      

在队列的去重窗口内(这是队列的一个设置,时长从数秒到数分钟不等),用同一个 key 进行的第二次发送不会成为第二条消息:重复的页面或重试的页面只会产生一次调查。在窗口之后重复的页面——就像 Alertmanager 对几小时后仍在触发的告警所做的那样——则是一条新消息和一次全新的调查,这是有意为之:到那时情况很可能已经发生了变化。

上面的 Spool 字段,用 SQL 的话说就是一个数据库:一个隔离单元,容纳着它的各个队列,拥有自己的 write-ahead log、I/O 和限制,因此一个 spool 永远不会拖慢另一个。每个账户一开始都有一个名为 default 的 spool,而对 Pagedog 来说这一个就足够了。

Workers

一旦事件进入队列,我们就需要某种东西把它进一步推向流水线的下游:我们需要启动 worker 来做这件事。

在 Pagedog 中,worker 有意被设计成一个相当模糊的概念:实际的执行机制隐藏在一个 runtime 接口之后:


        type Runtime interface {
	Stats(context.Context) (Stats, error)
	Launch(context.Context) (Worker, error)
	Shutdown(context.Context, Worker) error
}
      

runtime 的实现可以是从进程内运行的 goroutine,到在你的平台上运行的独立容器或 pod,再到 serverless 平台上的函数。这个接口让我们能够把这些执行细节与系统的其余部分隔离开来,并接入任何计算资源。

该启动多少?

文章标题:用 spooler.sh 在 Go 中构建可靠的 LLM 调查流水线

正文: 为了判断何时需要再启动一个 worker,Pagedog 会检查 Spooler 队列中的几个简单指标:incidents 队列中当前可见的消息数——也就是等待被接收的消息数——以及已被 worker 处理中的消息数——也就是处于 pending 状态的消息数。

两者之和给出了一个估计值:理想情况下需要运行多少个 worker 来处理所有可用的 incident。运行中的 worker 数量受配置限制:


        func desired(q QueueStats, minWorkers, maxWorkers int) int {
	want := int(q.Pending + q.Visible)
	want = min(want, maxWorkers)
	want = max(want, minWorkers)
	return want
}
      

desired() 由运行时 reconciler 循环调用:它会定期将运行中的 worker 数量与期望值进行比较,并启动或关闭差值数量的 worker。

排查 incident

worker 本身非常简单。它从 incidents 队列中拉取消息,其中每条消息代表一个需要调查的 incident。

对于每个 incident,worker 通过其 API 与配置好的 LLM 通信:


        type Model interface {
	Complete(context.Context, CompleteRequest) (CompleteResult, error)
}
type CompleteRequest struct {
	// Messages is the conversation so far: the task text, model replies
	// and tool output.
	Messages []Message

// Tools holds the specs of the tools the model may call.
	Tools []ToolSpec
}
      
LLM API 是无状态的,因此每次调用都要携带完整对话。同时我们还会发送工具的规格:名称、描述以及输入的 schema。模型要么以文本作答,要么请求调用其中一个工具。在后一种情况下,我们的代码会运行该工具,将其输出追加到对话中,然后再次询问模型。如此反复,直到模型仅以文本作答——那就是报告。每一次往返称为一个 turn,而由于每个 turn 都会重新发送对话,turn 数就是调查的成本所在。

如你所见,我们把可用工具的规格传给 LLM,让它在调查中自行使用——例如,获取 incident 前后的日志,或读取日志活动中涉及的源代码。

如今许多系统都有可以满足这些需求的 MCP server。Pagedog 有一个通用的 MCP 工具实现可以连接这些 server,同时也内置了与 Prometheus 和 Loki 的直接集成。

MCP,即 Model Context Protocol,是驱动模型的程序与为其提供工具的 server 之间的协议。server 列出其工具,每个工具都有名称、描述和输入的 JSON schema,并在被请求时运行工具、返回文本。该列表的形状与下面的 ToolSpec 相同,因此 Pagedog 可以在不知道 MCP server 工具具体功能的情况下,将其交给模型。

内置工具是只读查询,而对于 MCP,模型只能获得你列出的工具——该列表是必需的,因此不会有任何东西因遗漏而被默认授予。模型对你基础设施的触达范围,完全取决于你允许的范围。

添加新工具需要实现 Tool 接口并在配置中接入:


        // Tool is something the model may call.
type Tool interface {
	// Spec describes the tool to the model.
	Spec() ToolSpec

// Call runs the tool on the model's input, which the model shaped after
	// Spec's schema. The text goes back to the model; so does an error.
	Call(ctx context.Context, input []byte) (string, error)
}
      

ToolSpec 定义了输入的结构,这样模型就知道该工具期望什么。

对话中的初始消息——即 worker 交给模型的任务——是由模板结合 incident 字段渲染出的文本。默认的模板很短:


        You are the on-call engineer. Investigate the incident below and write a short
report in Markdown: what happened, the evidence you found in the metrics and
the logs, the likely cause, and what to do next.

文章标题:用 spooler.sh 在 Go 中构建可靠的 LLM 调查流水线

正文:
事件开始于 {{.StartedAt}};现在是 {{.Now}}。查看从开始前十五分钟到现在的窗口,并以 RFC 3339 格式给工具提供时间。

事件,如其来源所报告的那样:
---
{{.Raw}}
---
      

当模型停止调用工具后,返回的是任务所要求形状的 Markdown:发生了什么、证据、可能的原因以及下一步该做什么。

取决于你希望调查深入的程度,所有这些都需要一段时间。而这正是 Spooler 的第二个特性发挥作用的地方。

租约与重试

Spooler 将消息租给消费者。这意味着当 worker 收到一条消息时,它不会立即将其从队列中移除:相反,worker 在处理该消息期间持有它的租约。租约可以过期,此时消息要么被重新投递给另一个 worker,要么在重试预算耗尽时进入失败状态(该预算是队列的 maxRetries 设置)。

接收循环非常简单:


        for ctx.Err() == nil {
	m, ok, err := client.Recv(ctx, spooler.RecvRequest{
		Spool:       spool,
		Queue:       queue,
		WaitSeconds: new(1), // Wait up to one second for a message.
	})
	if err != nil {
		return err
	}
	if !ok {
		// No visible messages within the second: repeat.
		continue
	}
	process(ctx, m)
}
      

由于 LLM 调查可能需要一些时间,worker 会定期续订消息租约,以免丢失它。如果 worker 在调查中途崩溃,租约最终会过期,另一个 worker 可以接手同一条消息并重试。

续订失败会取消调查的上下文:消息现在属于别人了,正在进行的调查应该停止:


        for {
	select {
	case <-ctx.Done():
		return
	case <-time.After(time.Until(expiresAt) / 3 * 2):
		// Renew at two thirds of the lease, leaving a third as a
		// margin for a slow request.
	}
	res, err := client.Renew(ctx, spooler.RenewRequest{
		Spool: spool,
		Lease: lease.token,
	})
	if err != nil {
		cancel() // Cancel investigation context.
		break
	}
	expiresAt = res.LeaseExpiresAt
}
      

一旦调查完成,worker 会以以下方式之一对租用的消息进行结算:

  • 成功时确认(ack)它,这会将其从队列中移除
  • 否定确认(nack)它以消耗一次重试并使其被重新投递
  • 释放它以将其退回队列而不消耗重试(当 worker 关闭时)
  • 使其失败以将其置于失败状态,直到人工介入(编码问题、版本不匹配等)
  • 丢弃它以将其完全删除

在代码中,调查返回它想要的结算——也就是我们稍后会讲到的 ack-and-send。在失败的情况下,结算由错误决定。res 是接收到的消息,sub 是一个上下文,它在关闭后仍能存活足够长的时间以完成结算:


        settle, err := investigate(ctx, item)
switch {
case errors.Is(err, ErrDiscard):
	settle = r.discard

case errors.Is(err, ErrFail):
	settle = r.fail

case err != nil && ctx.Err() != nil:
	// A shutdown or a lost lease is not the message's fault: a release
	// spends no retry.
	settle = r.release

case err != nil:
	settle = r.nack
}
_ = settle(sub, res.Lease)
      

报告

一旦模型完成调查,我们就有了一个报告。现在我们需要决定如何处理它。Pagedog 将报告存储在消息队列之外:消息队列实际上并不打算用作文档的永久存储。它的内容是动态的,而且队列通常对单条消息中可存储的数据量有限制,Spooler 也不例外。

因此我们在技术栈中引入另一个组件,上图中没有显示,它位于 worker 旁边——一个报告存储:


        // ReportStore 用于持久化事件报告,以便之后检索。
type ReportStore interface {
	// Store 将事件的报告按其 key 保存,并返回其
	// URI。同一事件再次存储会覆盖此前存储的内容。
	Store(ctx context.Context, inc Incident, r Report) (*url.URL, error)

// Load 返回 Store() 保存在 u 处的报告。
	Load(ctx context.Context, u *url.URL) (Report, error)
}
      

目前 Pagedog 有两种报告存储后端:本地文件系统(如果你希望全部运行在单台机器上),以及 GitHub issues——每份报告会变成你自己的某个仓库中的一个 issue,同一事件再次上报时会更新其对应的 issue。

与之前的所有接口一样,用 S3 或其他分布式存储系统来扩展这个接口应当是很直接的。

报告存储完成后,我们向另一个 Spooler 队列——reports——放入一条新消息,用于通知处理。该消息包含的是对已存储报告的引用,而非报告本身。

这就引出了我最喜欢的设计部分之一。

原子化的 ack-and-send

这是第三个、也是特别有用的一个 Spooler 特性,我想请你注意它:正是它让构建流水线变得容易。

Spooler 提供了一个名为 ack-and-send 的 API。它在一个原子操作中确认一个队列中的消息,并向另一个队列发送一条新消息。

在我们的场景中,我们确认 incidents 队列中的原始事件消息,并向 reports 队列发送一条包含报告引用的新消息。如果该操作失败,事件消息不会被确认,报告消息也不会被添加。如果成功,两项变更都会被提交。

为什么原子性很重要?没有它,我们就必须为事件确认和报告发送选择一个顺序:先确认再发送:中间崩溃会丢失报告,事件也随之丢失先发送再确认:中间崩溃会让事件保持租约状态,它会被重新投递,我们会再次调查它,付两次模型的费用并发送第二份报告。通常的解决办法是 outbox 表或幂等键,也就是我们自己要维护更多状态。ack-and-send 把它变成了队列的问题。

为什么原子性很重要?没有它,我们就必须为事件确认和报告发送选择一个顺序:

  • 先确认再发送:中间崩溃会丢失报告,事件也随之丢失
  • 先发送再确认:中间崩溃会让事件保持租约状态,它会被重新投递,我们会再次调查它,付两次模型的费用并发送第二份报告。

通常的解决办法是 outbox 表或幂等键,也就是我们自己要维护更多状态。ack-and-send 把它变成了队列的问题。

这正是我希望 Spooler 让使用者轻松获得的那种一致性特性。在 Pagedog 中,它被封装进一个 Pipe(一种抽象,将来我可能会把它加入 spooler/x 子包以便复用):它从一个队列接收类型为 A 的消息,把每条消息转成 B,再把 B 放入另一个队列。worker 的全部工作就是这个函数(此处省略了任务模板化部分):


        pipe := &spooler.Pipe[pagedog.Incident, pagedog.Report]{
	Client: client,
	Spool:  "default",
	Input:  "incidents",
	Output: "reports",
}
err := pipe.Pump(ctx,
	func(ctx context.Context, inc pagedog.Incident) (r pagedog.Report, err error) {
		res, err := agent.Do(ctx, ai.DoRequest{
			Task:     task(inc), // Task text rendered.
			MaxTurns: maxTurns,  // Limit roundtrips with LLM.
		})
		if err != nil {
			return r, err
		}
		u, err := reportStore.Store(ctx, inc, pagedog.Report{
			Text: res.Output,
		})
		if err != nil {
			return r, err
		}
		return pagedog.Report{
			Incident:  inc,
			ReportURI: u,
		}, nil
	},
)
      

当回调函数成功时,Pump 通过 ack-and-send 结算该消息。

报告报告

文章标题:用 spooler.sh 在 Go 中构建可靠的 LLM 调查流水线

正文: 一旦报告已经存储、新消息已经放入 reports 队列,就只剩下一个环节了:把调查结果通知给某个人。目前,这发生在 Pagedog 主进程内部的一个独立 goroutine 中,它消费 reports 队列的方式,与 workers 处理 incidents 队列的方式大致相同。

它租用一条消息,从存储中加载对应的报告,然后尝试把它投递到你在配置中指定的所有目标。这些目标可能是 Slack 频道、PagerDuty incident 上的一条备注、incident.io incident 的一次更新,或者任何其他你想集成的地方。

一旦报告成功投递到所有已配置的目标,Pagedog 就会确认(ack)这条消息。

如果任何一个目标拒绝接收,消息就会被否认(nack),并在稍后重新返回——而且会再次发往所有目标,包括那些已经收到过报告的目标。也就是说,这里的投递对每个目标而言是 at-least-once:一个 Slack 频道可能会两次看到同一份报告,但不会有任何目标漏掉它。这就是不在任何地方保存按目标维度的状态的代价。

这一次,我们不需要原子的 ack-and-send——一个 incident 会经历三个状态:queued、reported 和 notified,而这是最后一个状态,在这个状态下,一次简单的 ack 就足以把消息从队列中移除。

就是这样。

运行 Pagedog

以上这一切现在都以一个 MIT 许可的开源项目形式提供,名为 Pagedog。仓库在 examples/docker 下附带了一个 docker compose 演示,其中包含 Prometheus、Alertmanager 和 Loki,围绕着一个你可以故意弄坏的小型 HTTP 服务器;在 examples/k8s 下还有一个单清单的 Kubernetes 部署。

最近,本地内存版 Spooler 镜像已经可以免费在你自己的基础设施中用于你自己的目的,无论是开发还是生产,这意味着你无须成为托管 Spooler 服务的订阅者,也能使用 Pagedog。

它把队列保存在内存中,所以重启丢失的就是那几分钟内正在处理中的内容——而仍在触发的告警会随着下一次 Alertmanager repeat 再次回来。报告存放在队列之外,因此已经写入的内容不会丢失。

当然,如果你需要,仍然可以选择更强的持久性或更大的规模——你随时可以订阅托管 Spooler 服务的某个层级,它提供持久且可复制的队列。

结论

这就是 Pagedog。

这是一个相对简单的项目,但我认为它相当好地展示了如何用 Spooler 构建有用、可靠的处理流水线,而不会给应用引入过多复杂性。

在 Pagedog 中,一条消息只有两个阶段——incidents 和 reports,但你可以很容易地在两者之间增加更多阶段,同时保持接线简单、状态转换原子。

队列负责消息投递、租约、重试以及阶段之间的原子转换,让我们可以专注于真正的应用逻辑。

我希望这能让你对 Spooler 如何融入你自己的基础设施项目有一个有用的了解。

如果你觉得 Pagedog 有用,欢迎试用它、探索代码,或者用你自己的 runtime、调查工具和通知目标来扩展它——非常欢迎 PR!

后记

最后还有一点值得提:这个设计其实并没有什么特别针对 incident 的地方。

我选择 incident 调查,是因为这是我熟悉、也是很多人熟悉的领域。但同样的架构几乎可以应用于任何工作流,无论是否由 LLM 驱动,尤其是当你希望以分布式方式运行它,而不是从你的笔记本电脑上编排一切的时候。

想象一个 GitHub issue 描述了一些要做的工作。一个 worker 把它捡起来,在代码库上启动一个 agent;它打开的 pull request 落到下一个队列,在那里另一个 worker 评审它,并可能安排进一步的工作。每个阶段都运行在自己的机器上,有自己的扩缩容和重试。

但核心依然不变——运行时 reconciler 循环与任务队列语义。

LLM agent 不必是运行在你笔记本电脑上的进程,agent 工作流也不必存在于单个长期运行的进程里。这里的要点是:剥去那些流行术语之后,从一种形态切换到另一种形态并不需要太多工作:借助消息队列和相对简单的 worker,你可以搭建分布式流水线,让各个步骤耗时、失败、重试,并把工作交接给下一阶段。Pagedog 只是用这种模式能构建出的一个例子,而 Spooler 是让这些阶段之间的协调变得可靠的一种方式。

感谢阅读!

References

  • docs.spooler.sh
  • modelcontextprotocol.io

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by Lobsters
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗