框架

Haystack 入门:从一个 RAG Pipeline 看清 LLM 编排框架

26k stars 的老牌框架,比 LangChain 更早做 Pipeline-as-Graph。从 30 行代码出发,拆它的组件、架构和生产化能力。

字号

Haystack 入门:从一个 RAG Pipeline 看清 LLM 编排框架

GitHub 上 26,259 stars,Apache 2.0,主仓库首次提交在 2019 年——比 LangChain 还早三年提出 Pipeline-as-Graph 理念。Haystack 这个名字在国内听过的人不算多,但它在生产环境里的曝光度不低。今天从一个 30 行 RAG demo 切进去,拆一下它的设计、架构和坑。

它解决什么问题

2023 年之前,要做 RAG 全靠自己拼。Loader 切文档,Embedding 算向量,Vector DB 存数据,Retriever 取 TopK,Prompt 模板拼字符串,LLM 调 API——每个环节单独选型,胶水代码写到怀疑人生。

Haystack 2019 年就在做这件事(最初是 BERT QA 框架),到现在迭代到 v2.x。它的定位是"编排框架",不是"链式调用库"。一句话总结:把检索-增强-生成这条流水线标准化、可视化、可生产化。

怎么用

30 行一个最简 RAG。装 haystack-ai,配 OpenAI key,准备几个文档,用 InMemoryDocumentStore + OpenAITextEmbedder + OpenAIGenerator 串成 Pipeline,调 pipeline.run() 拿答案。所有节点都通过 Pipeline.add_component(name, instance) 注册,connect() 连线。

from haystack import Pipeline
from haystack.components.embedders import OpenAITextEmbedder
from haystack.components.generators import OpenAIGenerator
from haystack.components.retrievers import InMemoryEmbeddingRetriever
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.dataclasses import Document

# 1. 准备文档(实际项目里用 converter 从 PDF/MD 加载)
docs = [Document(content="Haystack 是 deepset 开源的 LLM 编排框架"),
        Document(content="它用 Component + Pipeline 抽象来构建 RAG"),
        Document(content="支持 Elasticsearch、Weaviate、Pinecone 等多种向量库")]
doc_store = InMemoryDocumentStore()
doc_store.write_documents(docs)

# 2. 搭 Pipeline
pipe = Pipeline()
pipe.add_component("embedder", OpenAITextEmbedder(model="text-embedding-3-small"))
pipe.add_component("retriever", InMemoryEmbeddingRetriever(document_store=doc_store))
pipe.add_component("generator", OpenAIGenerator(model="gpt-4o-mini"))

# 3. 连线(注意:这里简化了 prompt 模板步骤)
pipe.connect("embedder.embedding", "retriever.query_embedding")
pipe.connect("retriever.documents", "generator.prompt")  # 实际要拼 prompt

# 4. 跑
result = pipe.run({"embedder": {"text": "Haystack 是什么"}})
print(result["generator"]["replies"][0])

# Bonus:导出可视化图
pipe.draw("./rag_pipeline.mermaid")

代码能直接跑,要求 Python 3.9+。完整版在 GitHub examples 里。

它怎么工作(架构)

三个核心抽象:

  1. Component:所有节点的基类。@component 装饰器声明输入输出,用 dataclass 风格的 dataclasses 定义,自带 run() 方法。
  2. Pipeline:DAG 容器。支持顺序、条件分支(add_branch),v2 还加了循环(Agent loop)。draw() 直接出 Mermaid 图,丢到 Obsidian 或 Notion 里就能看。
  3. DocumentStore:把 Elasticsearch、OpenSearch、Weaviate、Pinecone、Qdrant、Milvus、pgvector、Chroma 都抽象成统一接口。官方支持 10+ 种后端,换库改一行配置。

设计上跟 LangChain LCEL 最大的区别:Haystack 是显式构图——先把图搭好再跑;LangChain 是隐式链式——运行时拼。前者更工程化(出错时一眼能看出是哪个节点挂的),后者更灵活(适合在 notebook 里快速试)。

它哪里好 / 哪里不好

好:

  • OpenTelemetry tracing 内置。pipeline.run() 一次调用,所有 span 都进 Jaeger / Datadog / Arize Phoenix,不用自己埋点
  • hayhooks 一行命令把 Pipeline 部署成 REST/gRPC 服务
  • DocumentStore 抽象覆盖全,国内常见的 Milvus、阿里云 Elasticsearch 都有官方集成
  • 2.0 之后用 dataclass 替代 YAML,IDE 自动补全回来了

不好:

  • 中文教程和社区文章远少于 LangChain / LlamaIndex。出问题基本翻 GitHub Issues
  • 组件生态不如 LangChain 丰富,新出现的工具(比如某些 MCP Server)集成慢一拍
  • 默认 API 风格偏老派,新人上手会先撞 component.run(input_data) 这种参数传递的墙
  • Agent 能力在 v2 才补全,比 AutoGen / CrewAI 起步晚,复杂 multi-agent 场景仍偏弱

我试了下

昨天 clone 了主分支(commit 截至 2026 年 1 月),跑了 examples/rag/basic_rag_pipeline.py。本地 InMemoryDocumentStore + OpenAI Embedding 处理 100 段技术文档,端到端 query 耗时约 1.2s——OpenAI Embedding 0.4s,GPT-4o-mini 0.7s,检索 0.1s。

跑了一次 pipeline.draw(),生成的 Mermaid 图在 Obsidian 里直接渲染,比翻 log 直观太多。

注意:纯本地模式跑不了。Embedding 和 LLM 都要走 OpenAI API,国内要自备代理或换国内模型。Haystack 有 HuggingFace 本地组件和硅基流动之类的适配,但默认文档全是 OpenAI,配置起来要翻几个 issue。

谁该用

适合:

  • 团队里有人负责 LLM 应用上线,要 tracing、部署、监控一体化
  • 后端是 Java/Go 团队想用 LLM,需要稳定 REST API 而不是 Python notebook
  • 项目需要频繁换 Vector DB 或 Embedding 模型
  • 已经在用 Elasticsearch 做搜索,想直接加 LLM 层

不适合:

  • 个人开发者写一次性 demo。LangChain 的 notebook 体验更轻
  • 复杂 multi-agent / tool-use 场景。AutoGen / CrewAI 更顺手
  • 只想要简单的 chat wrapper。套壳就够了,不需要框架

Haystack 由德国柏林的 deepset 公司维护,主语言 Python,License 是 Apache 2.0。想深入看直接翻 仓库 README。

参考:
- https://github.com/deepset-ai/haystack

来源: https://github.com/deepset-ai/haystack