Haystack 深度拆解：LLM 应用框架的核心不是 Prompt 模板，而是类型化的图编排引擎

一个 26000 星的框架，最值钱的部分藏在类型系统里

Haystack 是 deepset 公司维护了 7 年的 LLM 应用框架，Apache 2.0 协议，GitHub 26K Stars。大部分人把它当成一个「带 Prompt 模板的 LangChain 替代品」，但读完源码后我发现，它真正的护城河根本不在 Prompt 管理上，而在一个端到端的类型化图编排引擎里。Haystack 用 @component 装饰器定义组件，每个组件的输入输出通过 @component.output_types 声明为带类型的 Socket。Pipeline 在构建时就会执行全链路类型校验——如果你把一个输出 List[Document] 的组件连到了一个期望 str 输入的组件上，它会在 pipeline.connect() 时就报错，而不是运行到一半才崩。

Pipeline 的核心：不重复造轮子，直接站在 networkx 的肩膀上

Haystack 的 Pipeline 引擎是建立在 networkx 的 DAG（有向无环图）之上的。它没有自己写一套拓扑排序或图序列化逻辑，而是直接利用 networkx 的成熟实现——这是一个非常务实的设计决策。Pipeline 的 run() 方法本质上是按拓扑顺序遍历图中的节点，每个节点接收上游输出、执行自己的逻辑、把结果传递给下游。因为底层是 networkx，Pipeline 可以被序列化、可视化、甚至做图论分析——这些能力都是「免费」获得的。这种「站在巨人肩膀上」的思路，恰恰是很多同类框架缺少的工程智慧。

Agent 的实现：一个有状态的 LLM 循环，用声明式 State Schema 解耦工具读写

Haystack 的 Agent 设计是我见过最干净的状态机实现之一。它把 Agent 建模为一个有状态的 LLM 循环，核心创新在于 State Schema 的声明式定义——你可以像定义 Pydantic Model 一样描述 Agent 的状态结构。Tool 通过 inputs_from_state 和 outputs_to_state 声明自己读写哪些状态字段，框架自动处理双向绑定。再加上 5 个生命周期钩子（类似 AOP 的切面），你可以在 Agent 决策循环的不同阶段插入自定义逻辑。同步和异步两套 API 共享相同的函数签名，在编译期就能保证一致性——没有「async 版本少了个参数」这种低级 Bug 的生存空间。

最深的一课：框架的核心竞争力是接口设计，不是算法

拆解 Haystack 的过程中，我越来越清晰地感受到一件事：Haystack 没有任何「独门算法」——它的 RAG、Agent、Pipeline 背后的技术原理都是公开的。但它的接口设计是顶级的。从 Component Socket 的类型校验，到 Agent State Schema 的声明式定义，到 Pipeline 的拓扑编排，整个框架提供了一种全链路类型安全的开发体验。你写的每一行代码都在一个强类型约束的上下文里，IDE 的自动补全和静态检查能帮你捕捉大部分错误。这听起来像是基础工程素养，但在 LLM 应用框架这个普遍「动态一时爽，运行时火葬场」的领域里，能做到这一点的框架寥寥无几。Haystack 用 7 年时间证明了：框架的价值不在于装了多少算法，而在于它如何让你安全、高效地把算法组合起来。