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。它的定位是「編排框架」,而非「鏈式呼叫函式庫」。一句話總結:把「檢索—增強—生成」這條生產線標準化、視覺化、並推向 production-ready。
怎麼用
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 裡。
它的運作原理(架構)
三個核心抽象:
- Component:所有節點的基類。
@component裝飾器宣告輸入輸出,搭配 dataclass 風格的 dataclasses 定義,內建run()方法。 - Pipeline:DAG 容器。支援順序、條件分支(
add_branch),v2 還加入循環(Agent loop)。draw()直接輸出 Mermaid 圖,丟進 Obsidian 或 Notion 就能瀏覽。 - 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。
參考: