フレームワーク

Haystack入門:30行のRAGコードで読むLLMオーケストレーションフレームワーク

GitHubで26k stars、Apache 2.0、2019年生まれの老舗フレームワーク。LangChainより3年早くPipeline-as-Graphを提唱した Haystack の設計とアーキテクチャを、最小デモから解剖する。

文字サイズ

GitHub上で26,259 stars、Apache 2.0、最初のコミットは2019年——LangChainより3年早くPipeline-as-Graphの構想を打ち出した。国内では知名度は高くないが、プロダクション環境での採用実績は少なくない。今回は30行のRAGデモを切り口に、設計思想とアーキテクチャ、そして運用上のハマりどころを見ていく。

何の課題を解決するのか

2023年以前、RAGを自前で組み上げるのは至難の業だった。Loaderで文書を分割し、Embeddingでベクトルを計算し、Vector DBに格納し、RetrieverでTopKを取得し、Promptテンプレートで文字列を組み立て、LLMのAPIを叩く——各工程を個別に選定し、グルーコードで繋ぐ羽目になる。

Haystackは2019年からこの問題に取り組んでいる(当初はBERT QAフレームワーク)。現在はv2.xまで成熟した。立ち位置は「チェーン呼び出しライブラリ」ではなく「オーケストレーションフレームワーク」。一言でまとめると、Retrieval-Augmented-Generationのパイプラインを標準化・可視化・本番運用可能な形に整えるツールだ。

使い方

30行で最小のRAGを実装する。haystack-aiをインストールし、OpenAIのAPIキーを設定、ドキュメントを準備、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])

# おまけ:可視化グラフの出力
pipe.draw("./rag_pipeline.mermaid")

Python 3.9+でそのまま動く。完全版はGitHub examplesにある。

内部構造(アーキテクチャ)

3つのコア抽象がある。

  1. Component:全ノードの基底クラス。@componentデコレータで入出力を宣言し、dataclassスタイルで定義する。標準でrun()メソッドを備える。
  2. Pipeline:DAGコンテナ。順次実行に加え、条件分岐(add_branch)に対応し、v2ではループ(Agent loop)も追加された。draw()で直接Mermaid形式の図を出力でき、ObsidianやNotionに貼り付ければ可視化できる。
  3. DocumentStore:Elasticsearch、OpenSearch、Weaviate、Pinecone、Qdrant、Milvus、pgvector、Chromaを統一インターフェースで抽象化する。公式で10以上のバックエンドをサポートし、切り替えは設定1行で済む。

LangChain LCELとの最大の違いは、Haystackが明示的にグラフを構築する点にある——先にグラフを組んでから実行する。LangChainは暗黙的にチェーンを繋ぐ——実行時に組み立てる。前者は工学的で、エラー時にどのノードで詰まったか一目で分かる。後者は柔軟で、notebookでの素早い試行に向く。

強みと弱み

強み:

  • OpenTelemetry tracingが組み込まれている。pipeline.run()を1回呼ぶだけで、全spanがJaeger / Datadog / Arize Phoenixに流れる。独自計装は不要。
  • hayhooksコマンド1行でPipelineをREST/gRPCサービスとしてデプロイできる。
  • DocumentStoreの抽象が網羅的で、国内でも利用の多いMilvusやAlibaba Cloud Elasticsearch向けの公式インテグレーションが揃っている。
  • v2.0以降はYAMLからdataclassに移行し、IDEの自動補完が復活した。

弱み:

  • 日本語・中国語圏の tutorialsやコミュニティ記事がLangChain / LlamaIndexと比べて圧倒的に少ない。問題発生時はGitHub Issuesを漁ることになる。
  • コンポーネントエコシステムの拡充速度はLangChainに劣る。MCP Serverなど新しいツールの統合は後れを取りがち。
  • APIスタイルがやや旧来的で、初心者はcomponent.run(input_data)のような引数渡し方式でまずつまずく。
  • Agent機能はv2でようやく整ったが、AutoGen / CrewAIより着手が遅く、複雑なmulti-agentシナリオでは力不足感が残る。

実際に試してみた

昨日メインブランチ(2026年1月時点)をcloneし、examples/rag/basic_rag_pipeline.pyを実行した。ローカル環境のInMemoryDocumentStore + OpenAI Embeddingで技術ドキュメント100件を処理したところ、エンドツーエンドのクエリ所要時間は約1.2秒——OpenAI Embedding 0.4秒、GPT-4o-mini 0.7秒、Retrieval 0.1秒という内訳だった。

pipeline.draw()も実行してみたが、出力されたMermaid図はObsidianでそのままレンダリングされ、ログを追うより遥かに直感的だった。

注意点として、完全ローカル動作は不可能。EmbeddingもLLMもOpenAI API経由となり、国内からはプロキシの準備か国内モデルへの差し替えが必須。HaystackにはHuggingFaceローカルコンポーネントやSiliconFlow対応のアダプタも存在するが、デフォルトのドキュメントはOpenAI前提なので、設定にはGitHub Issuesをいくつか参照する必要がある。

どんな人に向くか

向いているケース:

  • チーム内にLLMアプリの本番運用担当がいて、tracing・デプロイ・監視を一括で揃えたい
  • バックエンドがJava/Go中心のチームで、Python notebookではなく安定したREST APIでLLMを叩きたい
  • Vector DBやEmbeddingモデルを頻繁に切り替えるプロジェクト
  • すでにElasticsearchで全文検索を運用しており、LLMレイヤーを追加したい

向かないケース:

  • 個人開発者が使い捨てのデモを書く程度なら、LangChainのnotebook体験のほうが手軽
  • multi-agent / tool-useの複雑な構成を組むなら、AutoGen / CrewAIのほうが扱いやすい
  • シンプルなchatラッパーが欲しいだけなら、フレームワークを持ち出すまでもない

Haystackはベルリンのdeepset社がメンテナンスしており、主要言語はPython、ライセンスはApache 2.0。詳細はリポジトリのREADMEを参照のこと。

参考:

出典: https://github.com/deepset-ai/haystack