haystack

Haystack エキスパートスキル

Haystack（deepset 製）は、検索および NLP パイプラインを構築するための本番環境向けフレームワークです。中心となる抽象概念は Pipeline です。これは、型付きコンポーネントを明示的な接続で結んだ有向非巡回グラフです。LangChain の LCEL（パイプ演算子）や LlamaIndex のクエリエンジンとは異なり、Haystack のパイプラインは add_component と connect を使って事前に宣言するため、検証済みでデバッグしやすい DAG を構築できます。

コアパラダイム

from haystack import Pipeline
from haystack.components.embedders import SentenceTransformersTextEmbedder
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack.components.builders import PromptBuilder
from haystack.components.generators import OpenAIGenerator
from haystack.document_stores.in_memory import InMemoryDocumentStore

# Build a pipeline
document_store = InMemoryDocumentStore()
pipeline = Pipeline()
pipeline.add_component("embedder", SentenceTransformersTextEmbedder())
pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
pipeline.add_component("prompt_builder", PromptBuilder(template="Answer using: {{documents}}\n\nQuestion: {{question}}"))
pipeline.add_component("generator", OpenAIGenerator())

# Connect components
pipeline.connect("embedder.embedding", "retriever.query_embedding")
pipeline.connect("retriever.documents", "prompt_builder.documents")
pipeline.connect("prompt_builder", "generator")

# Run
result = pipeline.run({"embedder": {"text": "What is Haystack?"}, "prompt_builder": {"question": "What is Haystack?"}})

コア原則

1. パイプラインは検証済みの DAG です。 add_component + connect を使います。パイプラインの検証では実行前にエラーが検出されるため、開発中に活用してください。
2. コンポーネントには型があります。 各コンポーネントには入力／出力スロットがあります。接続するには型が一致している必要があります。これにより、実行時エラーを防げます。
3. PromptBuilder は Jinja2 を使用します。 テンプレートは f-string ではなく、Jinja2 文字列です。{{documents}}、{{query}}、{{question}} は変数のプレースホルダーです。
4. インデックス作成とクエリは別々のパイプラインです。 一方のパイプラインでドキュメントの読み込み、クリーニング、埋め込み、書き込みを行い、もう一方で検索と回答の生成を行います。両者は DocumentStore を共有します。
5. 評価もパイプラインです。 評価コンポーネントを追加して、忠実性、関連性、またはカスタム指標を測定します。

どこから始めるか

すでにあるもの	ここから始める
何もない — Haystack を試している	基本的なインデックス作成＋クエリのパイプラインを構築する
インデックスを作成するドキュメント	インデックス作成パイプラインを構築する（コンバーター、スプリッター、エンベッダー、ライター）
検索のユースケース	クエリパイプラインを構築する（エンベッダー、リトリーバー、プロンプト、ジェネレーター）
本番環境へのデプロイ	Hayhooks と評価パイプラインを追加する

クイックリファレンス

タスク	方法	リファレンス
インデックス作成パイプラインの構築	add_component -> connect -> run	references/pipeline-design.md
クエリパイプラインの構築	retriever -> prompt_builder -> generator	references/pipeline-design.md
ドキュメントストアの選択	InMemory（開発）、Elasticsearch/Pinecone（本番）	references/document-stores.md
埋め込み検索	SentenceTransformersTextEmbedder + EmbeddingRetriever	references/retrievers.md
ハイブリッド検索	BM25 + Embedding を並列実行し、DocumentJoiner を使用	references/retrievers.md
プロンプトテンプレート	PromptBuilder で Jinja2 を使用	references/pipeline-design.md
評価	DeepEvalEvaluator、SASEvaluator	references/evaluation.md
デプロイ	Hayhooks REST API	references/deployment.md

フレームワーク選択ガイド

シナリオ	選択するもの	理由
検索／NLP パイプライン	Haystack	パイプライン DAG モデルは、検索中心のワークロードにおいて最も成熟しています
クエリ対象のドキュメント／RAG	LlamaIndex	データの取り込みが主な基本機能です
チェーン／エージェントの構成	LangChain	汎用的なチェーン構築に適した LCEL パイプ演算子を備えています
コンパイル済みプロンプトプログラム	DSPy	指標に基づいてプロンプトを自動最適化します
ロールベースのマルチエージェント	CrewAI	より高水準のエージェント抽象化を提供します

リファレンスファイル

リファレンス	読み込むタイミング	ファイル
パイプライン設計	インデックス作成とクエリのパイプラインを構築するとき	references/pipeline-design.md
ドキュメントストア	ストアの選択と設定を行うとき	references/document-stores.md
リトリーバー	埋め込み、BM25、ハイブリッド検索について調べるとき	references/retrievers.md
検証監査	すべての API に関する主張の調査・検証を行うとき	references/validation-audit.md
ファイルコンバーター	複数形式のインデックス作成、YAML シリアル化、コンポーネントの種類について調べるとき	references/file-converters.md
評価	指標、評価器、パイプライン評価について調べるとき	references/evaluation.md
デプロイ	Hayhooks、コンテナ化、本番環境について調べるとき	references/deployment.md
FAQ とトラブルシューティング	よくあるエラーと解決方法を調べるとき	references/faq-and-troubleshooting.md

テンプレート

テンプレート	使用する場面	ファイル
インデックス作成パイプライン	読み込み、分割、埋め込み、ストアへの書き込み	templates/indexing-pipeline.py
クエリパイプライン	検索、プロンプトの作成、回答の生成	templates/query-pipeline.py
ハイブリッド RAG	BM25 と埋め込みを並列実行	templates/hybrid-rag.py

トラブルシューティング

症状	考えられる原因	解決方法	参照先
パイプラインの実行エラー	コンポーネントの接続の不一致	コンポーネントの入力／出力スロットの型を確認します	references/pipeline-design.md
ドキュメントが検索されない	ドキュメントストアが空	先にインデックス作成パイプラインを実行します	references/pipeline-design.md
プロンプトがレンダリングされない	Jinja2 テンプレート内の変数名が正しくない	{{variables}} がパイプラインの入力と一致しているか確認します	references/pipeline-design.md
検索が遅い	ANN ではなく全件スキャンを実行している	近似最近傍インデックスを設定します	references/retrievers.md
埋め込みの不一致	インデックス作成とクエリで異なるモデルを使用している	両方のパイプラインで同じモデルを使用します	references/retrievers.md
Hayhooks が起動しない	ポートの競合または設定の不足	ポートを確認し、オプションを確認するには --help を指定して実行します	references/deployment.md