Haystack

一句话定位

deepset 出品的 production-ready RAG & Agent 编排框架：核心是一套声明式 DAG Pipeline——任何标了 @component 的类（retriever / embedder / generator / ranker / agent…）都有类型化的 input/output sockets，用 add_component() + connect() 按数据流接成图，引擎按拓扑序（支持环路/分支）驱动执行；Agent 只是其中一个特殊 component，内部跑 LLM↔ToolInvoker 的 ReAct 式循环。强调 “context engineering”：检索、路由、记忆、生成全部透明可追踪、可序列化、可热插拔模型厂商。

设计理念 / 顶层架构

Haystack 的世界观是 “一切皆 Component，编排即 DAG”，与 single-agent ReAct 框架（如 connectonion）的 “agent 是一等公民” 相反——这里 Pipeline（图）才是一等公民，Agent 是图里的一个节点。核心设计取舍：

• Component 契约（鸭子类型 + 元类）：@component 装饰器（haystack/core/component/component.py:644 的 component = _Component()）通过 ComponentMeta 元类（component.py:187）在实例化时用 inspect.signature 解析 run() 的形参类型生成 InputSocket，用 @component.output_types(...) 装饰器（component.py:534）声明 OutputSocket。唯一硬性契约：必须有 run() 且返回 Mapping。
• 声明式 DAG + 类型检查连线：Pipeline 内部是 networkx.MultiDiGraph（haystack/core/pipeline/base.py:112）。connect("retriever", "prompt_builder.documents")（base.py:441）在连线时就校验 sender 的 output socket 类型与 receiver 的 input socket 类型是否兼容，类型不匹配直接报错。执行引擎用拓扑序+优先级队列调度；若图含环（如 Agent 自反馈、retry）则走 networkx.condensation 处理强连通分量（base.py:1289），故 Pipeline 支持 loop/branch，不只是纯 DAG。
• RAG 是头等场景：components/ 下按职责切分目录——retrievers/、embedders/、rankers/、readers/、converters/、preprocessors/、writers/、generators/、builders/（PromptBuilder）、routers/、joiners/、evaluators/。一条标准 RAG = Retriever→PromptBuilder→ChatGenerator→AnswerBuilder 用 connect() 串起来。
• 模型/厂商无关：Generator 与 Retriever 都是协议（Protocol）。ChatGenerator（haystack/components/generators/chat/types/protocol.py:10）只要求 run(messages) -> dict；OpenAI/Azure/HuggingFace 等是核心包内置，其余厂商（Anthropic/Cohere/Bedrock/Mistral…）在 haystack-core-integrations 仓库，换厂商=换一个 component 实例。
• 可序列化是一等需求：component 的 __init__ 参数必须 JSON-serializable，Pipeline.to_dict()/from_dict()（base.py:150/177）+ dumps()/loads()（base.py:264/287，默认 YAML marshaller）让整条 pipeline 能存成 YAML 并复原——这也是 Hayhooks 把 pipeline 暴露成 REST/MCP 的基础。
• 入口 API：from haystack import Pipeline, component, Document（haystack/__init__.py）；Agent 在 haystack.components.agents.Agent。

最小示例（取自 Pipeline.run docstring，haystack/core/pipeline/pipeline.py:127）：

from haystack import Pipeline, Document
from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
from haystack.dataclasses import ChatMessage
from haystack.document_stores.in_memory import InMemoryDocumentStore

document_store = InMemoryDocumentStore()
document_store.write_documents([
    Document(content="My name is Jean and I live in Paris."),
    Document(content="My name is Mark and I live in Berlin."),
])

template = [ChatMessage.from_user(
    "Given these documents, answer the question.\n"
    "Documents:\n{% for doc in documents %}{{ doc.content }}\n{% endfor %}\n"
    "Question: {{question}}\nAnswer:"
)]

rag = Pipeline()                                              # 声明式 DAG
rag.add_component("retriever", InMemoryBM25Retriever(document_store=document_store))
rag.add_component("prompt_builder", ChatPromptBuilder(template=template))
rag.add_component("llm", OpenAIChatGenerator())
rag.connect("retriever", "prompt_builder.documents")          # 类型化连线（连线即校验）
rag.connect("prompt_builder", "llm")

question = "Who lives in Paris?"
result = rag.run({"retriever": {"query": question}, "prompt_builder": {"question": question}})
print(result["llm"]["replies"][0].text)                       # Jean lives in Paris

组件实现（横向逐项）

设计权衡与特性

• “图编排” vs “agent 编排”：与 connectonion/Swarm 等 “agent 是中心、循环是核心” 的框架根本不同——Haystack 把 DAG 当一等公民，Agent 只是图里一个会内部循环的节点。好处是透明可控、可静态校验类型、可序列化成 YAML 部署；代价是写法更 “工程化”（要手工 add_component+connect），不如两行起一个 agent 那样轻。
• 连线即类型检查：connect() 在装配期就比对 socket 类型（base.py:441），把 “上游输出对不上下游输入” 这类错误从运行时提前到构建时——这是声明式 DAG 相对命令式 agent 循环的硬优势。
• RAG 第一公民：检索/嵌入/重排/读取/写入/转换/预处理被拆成独立可组合 component，配合 DocumentStore 协议，换向量库/换 embedding 模型/插一个 ranker 都只是改一个节点。Context engineering（检索→排序→过滤→拼装→路由全透明）是其相对 “黑盒 RAG” 框架的核心差异。
• Protocol 而非继承：Generator/Retriever/DocumentStore 都是 typing.Protocol，模型/厂商/存储无关性靠鸭子类型达成，换厂商=换 component 实例，不改 pipeline 结构。
• 支持环与分支：虽名为 DAG，引擎实际经 networkx.condensation 支持带环图（base.py:1289），故 retry、self-correction、Agent 反馈回路都能在 pipeline 层表达；AsyncPipeline 还能并行无依赖分支。
• 生产化外置：核心库不含 server；REST/MCP 暴露交给独立的 Hayhooks，企业版（Enterprise Platform）补 observability/治理/协作——核心库保持精简。
• multi-agent 是 “涌现” 而非 “内建”：没有专门的 multi-agent 调度器，多 agent 协作靠 “Agent 也是 component” 复用 DAG 或 agent-as-tool，灵活但需自己设计编排拓扑。
• 待确认/注意：①版本为 2.31.0-rc0(VERSION.txt) 的 release candidate，部分 API 可能仍在演进；②绝大多数第三方厂商集成不在本仓库（在 haystack-core-integrations），本笔记仅覆盖核心包内置的 OpenAI/Azure/HF；③Tool 的 function 必须是同步函数（tool.py:105 显式拒绝 async）。

关联

• component-taxonomy · context-engineering · tool-use · state-persistence
• 同范式(RAG/声明式 pipeline)：component-taxonomy · 对比 single-agent：connectonion
• 源码：agents-example/haystack/