Pinterest Medic：AI Agent自动诊断Spark故障的工程实践

在大型数据平台团队中，为依赖底层基础设施的合作团队提供高质量支持，往往是一场没有终点的战斗。Spark 作业失败、分布式系统排障、优先级取舍——这些日常挑战消耗着工程师大量的时间与精力。Pinterest 的 Staff Engineer Dražko Profirović 在 AI Engineer 大会上分享了他们的解法：Medic for Apache Spark，一款基于智能体（Agent）的自动化诊断工具。

本文将梳理 Medic 从原型到多智能体架构的演进历程，以及团队在这一过程中沉淀出的关键工程经验。

为什么要构建 Medic

数据平台团队的支持轮值有两个绕不开的痛点。其一是排障门槛高：troubleshooting Spark 乃至任何分布式系统本身就极其困难，对刚接触框架的新人尤其不友好。其二是优先级模糊：是先帮一个团队修复失败的作业，还是先解除另一个团队临近 deadline 的阻塞？作为人类工程师，不得不在有限时间内艰难取舍。

而 LLM 恰好能打破这一约束——它可以按需横向扩展知识与能力。Pinterest 对诊断工具的愿景很朴素：用户只需问一句「这个作业为什么失败？」，就能得到一份深度研究报告，其中包含失败根因的证据链，以及基于作业上下文的修复建议。更进一步，这个 Agent 必须部署在用户实际工作的所有触点上，比如 Slack 和 Airflow UI。

从原型到瓶颈：单一 ReAct Agent 的困境

团队的起点是通过 Model Context Protocol（MCP） 暴露数据资源，将它们连接到 LLM。MCP 是 Anthropic 于 2024 年底推出的开放协议标准，旨在统一 LLM 与外部数据源、工具之间的连接方式——其核心思想类似于 USB-C 接口的标准化理念：不同的数据系统只需实现一套 MCP Server 接口，便可被任何支持 MCP Client 的 LLM 应用调用。在 Pinterest 的场景中，MCP 使得 Spark 作业元数据、日志、指标等分布式数据资源能以统一接口暴露给 LLM，避免了为每个数据源单独开发集成代码的重复劳动。这样便可在启用 MCP 工具的对话中，让模型直接对 Spark 作业进行推理。方案在实践中可行，但高度依赖人类操作员精心编写的 prompt。

随后团队扩展原型，构建了一个单一的推理与行动（ReAct）Agent。ReAct（Reasoning + Acting）是由 Google 研究团队于 2022 年提出的 LLM Agent 范式，其核心是让模型在「思考」与「行动」之间交替迭代：模型先输出推理链（Thought），再调用外部工具（Action），根据工具返回结果继续推理，直至得出答案。这种范式在开放式问题上表现出色，但当单一 Agent 需要承载复杂任务时，推理链会变得冗长，上下文窗口压力剧增，且难以通过 prompt 工程精确控制执行路径。这个 Agent 被赋予一条包罗万象的 prompt，其中定义了解决问题的方法论、报告的结构化输出方式，以及常见失败模式的示例。凭借这些能力，Medic 开始向 Beta 用户开放试用。

但早期试用暴露了大量缺陷：

• Prompt 调优难以为继：单条 prompt 要承担所有职责，在一处增加细节往往会劣化另一处的行为。
• 响应质量不稳定：分析时而肤浅，时而冗长。
• 缺乏控制手段：难以让 Agent 保持在正轨上。
• 频繁触及上下文窗口上限：生产作业的巨量日志输出会迅速吞噬 token，导致推理中断。
• 测试策略薄弱：端到端测试依赖生产环境的手工验证，而生产数据会被清理，测试结果如同轶事，无法确认新改动是否破坏了此前的成果。

用可观测性与可测试性夯实工程地基

面对这些问题，团队首先投资于可观测性与可测试性。他们采用 OpenTelemetry 将追踪数据推送至 LangFuse，通过瀑布图的形式审视 Agent 的执行步骤，从而定位低质量响应的成因。OpenTelemetry 是 CNCF 孵化的开源可观测性框架，提供统一的追踪（Tracing）、指标（Metrics）和日志（Logs）采集标准，已成为云原生系统可观测性的事实规范；LangFuse 则是专为 LLM 应用设计的开源可观测性平台，支持对 Agent 的每次 LLM 调用、工具调用进行细粒度追踪，并以瀑布图形式呈现调用链路。将两者结合，团队可以像调试传统微服务一样审视 Agent 的执行轨迹，定位是哪一步的推理或工具调用导致了质量下降——这是将 AI 系统工程化的关键基础设施。

更关键的是构建了端到端测试框架。其原理相当简洁：

• 录制模式（Record）：Agent 调用真实的下游系统，工具响应被捕获为 fixtures（测试夹具），保存到文件系统并作为代码提交。
• 回放模式（Playback）：Agent 面向 fixtures 而非生产数据运行，执行分析并生成报告。

随后，测试套件依据预先编写的离线评估（offline evals）为报告打分。例如，一条 eval 会检查建议修复项是否超过三条——若 Agent 给出过多修复建议，评分就会降低，以此控制最终报告的冗余度。这套机制让团队得以用量化指标衡量质量，而非依赖直觉，并在扩大测试覆盖的同时确保改进不会引入回归。

深挖日志与指标：提升信噪比

有了测试保障，团队开始深入优化对日志的处理。日志噪声极大，许多异常其实是良性的，因此单纯聚焦最后一个异常并不可靠。最初的正则启发式过滤方案扩展性差，团队转而构建了异常分类流水线。

核心思路是：学习哪些异常常出现在成功作业中，将它们视为可能的「红鲱鱼」（干扰项）并过滤。Agent 会对异常进行指纹识别与聚类，再根据内容相关性以及相对于作业终止时间的近因性进行排序。此后 Agent 不再直接消费日志，而是通过两个 MCP 工具操作：获取 top-k 截断异常，或获取特定异常的完整日志。这显著提升了信噪比，降低了 LLM 被误导性异常「锚定」的风险。

对于指标，挑战同样在于上下文窗口。原始时序数据对长时运行的生产作业极不友好，且 token 效率低下。

Pinterest 的做法颇具巧思：在一个隔离的子 Agent 中完成指标分析。他们将原始时序数据转换为图表，拼接成一张总览图（外观类似 Grafana 仪表盘，但附带了如最小/最大值标注等有用信息），再将这张图片附加到 LLM 对话中，让模型推理数据中的模式。

采用图片的最大优势在于：无论 Spark 作业运行多久，都能保证固定的输入 token 数量。子 Agent 能识别出诸如执行器数量骤降至零、长时间停滞或瓶颈等异常信号，将发现总结后返回给父 Agent，从而始终保持上下文窗口的健康。

多智能体架构：控制力的质变

Medic 演进的最后一步，是将单一 ReAct Agent 重构为多智能体架构，底层基于 LangGraph 的 deep agent 库。LangGraph 是 LangChain 团队开发的有状态多智能体编排框架，其核心抽象是将 Agent 工作流建模为有向图（DAG 或含环图），节点代表 Agent 或处理步骤，边代表控制流或数据流——相比线性的 Chain 模式，LangGraph 原生支持循环推理、条件分支和并行执行，尤其适合需要多 Agent 协作的复杂任务。Pinterest 采用的 deep agent 库是在 LangGraph 之上的进一步封装，内置了任务待办列表（todo list）和虚拟文件系统等「脚手架」工具，使 Agent 在长任务执行中能维持状态连贯性，避免「迷失方向」。每个 Agent 拥有专属的 prompt 和一组 MCP 工具子集，这种设计哲学与 Claude Code、Codex 等编程工具的体验一脉相承。

重构后，团队终于能将臃肿的单一 prompt 拆解为专职角色，各 Agent 职责清晰、便于独立维护与聚焦测试。一个意外收获是：扩展项目范围变得像新增一条 prompt 一样简单，团队正是借此让 Medic 额外支持了 Spark SQL 作业的优化。

完整的诊断工作流

整个工作流的运转如下：

1. 用户请求进入系统，意图被分类为「简单问答」或「深度诊断」。
2. 若为深度诊断，Triage Agent 判断 Spark 作业的生命周期状态；若确认失败，则调用工具生成一组失败假设。
3. 每条假设由研究 Agent 并行调查，收集证据加以验证，并返回置信度评分与根因。
4. Supervisor 选出置信度最高的根因，调用 Healer Agent，基于摄入向量数据库的运维手册（runbooks）给出修复方案。向量数据库通过将文本语义编码为高维向量支持基于语义相似度的快速检索，是检索增强生成（RAG）架构的核心组件——Healer Agent 以根因描述为查询向量检索最相关的修复手册片段，再由 LLM 结合作业上下文生成具体建议，既避免了将全量手册塞入上下文窗口的 token 浪费，又确保修复建议有明确的知识出处。
5. 最终由 Supervisor 组装格式规范的报告。

成效与工程启示

多智能体架构被证明极为有效，为系统行为提供了最强的控制力，日志处理的改进也大幅减少了错误根因的产生。值得一提的是，团队曾尝试用 LangGraph 的 workflows 让 Agent 更具确定性，但相较于 ReAct 范式，这种方式显得过于脆弱——这是一个反直觉却重要的工程判断。

展望未来，Pinterest 正在实验从历史会话中吸收用户反馈以自动改进 Agent，并看到了将这一模式推广到 Flink、Trino 等其他分布式系统的广阔空间。

Medic for Apache Spark 的案例，为「AI Agent 落地生产级基础设施运维」提供了一份扎实的工程范本：真正的价值不在于炫目的模型能力，而在于可观测性、可测试性与架构解耦这些工程基本功的持续打磨。

核心要点