Haystack は、LLM を活用した検索・質問応答システムを構築するための強力なフレームワークです。しかし、多くのクラスや関数、CLI コマンドが用意されているため、開発中に「あのクラスはどう使うんだっけ？」「CLI コマンドの書き方を忘れた」といった場面に遭遇することも少なくありません。

そこで本記事では、Haystack 開発で頻繁に使う主要クラス、関数、CLI コマンドを一枚のチートシートとしてまとめました。手元に置いておくことで、開発効率が格段に向上するでしょう。

主要クラス早見表

以下は Haystack で最もよく使用されるクラスの一覧です。

#	クラス名	用途	インポート元
1	Document	テキストデータの基本単位	haystack
2	Pipeline	コンポーネントを連結して処理フローを構築	haystack
3	InMemoryDocumentStore	メモリ内でドキュメントを保存	haystack.document_stores
4	ElasticsearchDocumentStore	Elasticsearch を使ったドキュメント保存	haystack.document_stores
5	FAISSDocumentStore	FAISS ベクトル検索用ストア	haystack.document_stores
6	BM25Retriever	キーワードベース検索	haystack.nodes
7	EmbeddingRetriever	埋め込みベクトルベース検索	haystack.nodes
8	PromptNode	LLM プロンプトを実行	haystack.nodes
9	PromptTemplate	プロンプトテンプレートを定義	haystack.nodes
10	AnswerParser	LLM 出力を解析	haystack.nodes

主要関数早見表

Haystack でよく使う関数とメソッドをまとめました。

#	関数・メソッド名	所属クラス	用途	主要引数
1	write_documents()	DocumentStore	ドキュメントを保存	documents: List[Document]
2	get_all_documents()	DocumentStore	全ドキュメントを取得	index: str
3	update_embeddings()	DocumentStore	埋め込みベクトルを更新	retriever: BaseRetriever
4	add_node()	Pipeline	ノードをパイプラインに追加	component, name, inputs
5	run()	Pipeline	パイプラインを実行	query: str, params: dict
6	retrieve()	Retriever	ドキュメントを検索	query: str, top_k: int
7	predict()	PromptNode	LLM で推論実行	query: str, documents: List
8	from_dict()	Pipeline	辞書からパイプラインを復元	data: dict
9	to_dict()	Pipeline	パイプラインを辞書に変換	なし
10	delete_documents()	DocumentStore	ドキュメントを削除	index: str, ids: List[str]

CLI コマンド早見表

Haystack の便利な CLI コマンドをまとめました。

#	コマンド	用途	オプション例
1	haystack run	パイプラインファイルを実行	haystack run pipeline.yml
2	haystack export	パイプラインを YAML にエクスポート	haystack export --path output.yml
3	haystack import	YAML からパイプラインをインポート	haystack import --path pipeline.yml
4	haystack validate	パイプライン構成を検証	haystack validate pipeline.yml
5	haystack list-nodes	利用可能なノード一覧を表示	haystack list-nodes
6	haystack rest-api	REST API サーバーを起動	haystack rest-api --port 8000
7	haystack ui	Web UI を起動	haystack ui --pipeline pipeline.yml
8	haystack benchmark	パイプラインのベンチマーク実行	haystack benchmark --config bench.yml

背景

Haystack は deepset 社が開発した、LLM と検索技術を統合するオープンソースフレームワークです。RAG（Retrieval-Augmented Generation）パターンの実装や、質問応答システムの構築に特化しており、多くの企業や研究機関で採用されています。

Haystack の設計思想は「パイプライン志向」にあります。ドキュメントの取得、埋め込みベクトルの生成、LLM による推論といった一連の処理を、ノード（Node）と呼ばれるコンポーネントで構成し、それらを連結してパイプラインを作ります。

以下の図は、Haystack における主要コンポーネントの関係性を示しています。

mermaidCopy codeflowchart TB
    user["開発者"] -->|構築| pipeline["Pipeline"]
    pipeline -->|追加| nodes["Nodes<br/>(Retriever, PromptNode など)"]
    nodes -->|アクセス| docstore["DocumentStore"]
    docstore -->|保存| docs["Documents"]
    pipeline -->|実行| result["検索結果 / 回答"]

図で理解できる要点:

• Pipeline が中心となり、複数の Node を連結する
• Node は DocumentStore にアクセスしてデータを取得・保存
• 開発者は Pipeline を構築・実行して結果を得る

このように、Haystack はモジュラーな設計で各機能が分離されているため、柔軟なカスタマイズが可能です。しかし、その分、覚えるべきクラスや関数、CLI コマンドが多くなります。

特に以下の要素を理解しておくことが重要です。

DocumentStore の種類と選び方

DocumentStore はドキュメントを保存・検索するための基盤です。用途に応じて適切なストアを選択する必要があります。

DocumentStore	特徴	適用シーン
InMemoryDocumentStore	メモリ上に保存、高速だが永続化なし	プロトタイプ、テスト
ElasticsearchDocumentStore	全文検索に強い	キーワード検索重視
FAISSDocumentStore	ベクトル検索に最適化	意味的類似検索
WeaviateDocumentStore	ベクトル検索 + メタデータフィルタ	複雑な検索条件

Retriever の種類と特性

Retriever はドキュメントを検索するコンポーネントです。検索方法によって使い分けます。

Retriever	検索方式	長所	短所
BM25Retriever	キーワードマッチング	高速、実装簡単	意味的類似性を捉えられない
EmbeddingRetriever	ベクトル類似度	意味的検索が可能	計算コスト高い
DensePassageRetriever	事前学習済み埋め込み	高精度	モデルサイズ大きい

課題

Haystack を使った開発では、以下のような課題に直面することがあります。

クラスや関数の多さによる迷い

Haystack には 100 以上のクラスと数百の関数が存在します。初学者はもちろん、経験者でも「どのクラスを使えばいいのか」「この関数の引数は何だったか」と迷うことが頻繁にあるでしょう。

公式ドキュメントは充実していますが、毎回検索するのは時間がかかります。開発のテンポが落ちてしまい、集中力も削がれてしまいますね。

CLI コマンドの記憶負担

Haystack は CLI ツールも提供していますが、コマンドやオプションの組み合わせを全て覚えるのは困難です。特に haystack rest-api や haystack benchmark など、たまにしか使わないコマンドは忘れがちでしょう。

以下の図は、開発中によくある「調べる → 実装 → また調べる」というサイクルを示しています。

mermaidCopy codestateDiagram-v2
    [*] --> coding["コーディング中"]
    coding --> forgot["使い方を忘れた"]
    forgot --> search["ドキュメント検索"]
    search --> understand["理解・確認"]
    understand --> coding
    coding --> complete["実装完了"]
    complete --> [*]

    note right of search
        時間ロスが発生
    end note

図で理解できる要点:

• 開発中に何度も「調べる」ステップが発生
• ドキュメント検索による時間ロスが積み重なる
• チートシートがあればこのサイクルを短縮可能

バージョン間の差異

Haystack は活発に開発されており、バージョンアップで API が変更されることもあります。古い記事やチュートリアルのコードが動かず、原因究明に時間を取られることもあるでしょう。

最新バージョンで推奨されるクラスや関数を把握しておくことが重要です。

パイプライン構築の試行錯誤

Pipeline の構築では、どの Node をどの順序で繋ぐかが重要になります。しかし、適切な組み合わせを見つけるには試行錯誤が必要で、その過程で何度もクラスや関数のリファレンスを確認することになるでしょう。

解決策

これらの課題を解決するために、チートシートが非常に有効です。頻繁に使うクラス、関数、CLI コマンドを一枚にまとめておくことで、以下のメリットが得られます。

即座の参照による開発速度向上

チートシートを手元に置いておけば、ドキュメントを開かずとも必要な情報にアクセスできます。「あのクラスの名前は何だったか」「この関数の引数は？」といった疑問を数秒で解決できるでしょう。

開発のリズムを崩さずに実装を進められるため、集中力を維持できます。

学習効率の向上

チートシートを眺めるだけでも、Haystack の全体像が把握できます。どんなクラスがあり、どんな機能を提供しているのかを俯瞰できるため、学習の道筋が見えやすくなるでしょう。

また、よく使うパターンを覚えやすくなり、自然と実装スピードも上がります。

チーム内での知識共有

チートシートをチーム内で共有することで、メンバー全員が同じ基準で開発できます。コードレビュー時にも共通の語彙として機能し、コミュニケーションがスムーズになるでしょう。

以下の図は、チートシート活用による開発フローの改善を示しています。

mermaidCopy codeflowchart LR
    task["開発タスク"] --> check["チートシート確認"]
    check --> impl["即座に実装"]
    impl --> done["完了"]

    task2["開発タスク"] -.->|従来| search2["ドキュメント検索"]
    search2 -.-> read["記事を読む"]
    read -.-> impl2["実装"]
    impl2 -.-> done2["完了"]

    style check fill:#90EE90
    style impl fill:#90EE90
    style search2 fill:#FFB6C6
    style read fill:#FFB6C6

図で理解できる要点:

• チートシートを使うと「確認 → 実装」が直結
• 従来の「検索 → 読む → 実装」より大幅に短縮
• 緑のフローが推奨される開発パス

カスタマイズ可能性

本記事で提供するチートシートは基本版ですが、自分のプロジェクトに合わせてカスタマイズできます。よく使うクラスだけを残したり、プロジェクト固有のヘルパー関数を追加したりすることで、より実用的なリファレンスになるでしょう。

具体例

それでは、実際に主要クラス、関数、CLI コマンドの使い方を具体例とともに見ていきましょう。

主要クラスの使い方

Document クラス

Document は Haystack におけるデータの基本単位です。テキストとメタデータを保持します。

Document の作成

typescriptCopy codefrom haystack import Document

# 基本的な Document の作成
doc = Document(
    content="Haystack は LLM アプリケーション構築フレームワークです。",
    meta={"source": "tutorial", "page": 1}
)

content にテキスト本文を、meta にメタデータを辞書形式で指定します。メタデータは検索時のフィルタリングに使えるため、適切に設定しておくと便利でしょう。

複数 Document の一括作成

typescriptCopy codefrom haystack import Document

# リストで複数の Document を作成
documents = [
    Document(content="RAG は検索拡張生成の略です。", meta={"category": "用語"}),
    Document(content="Pipeline はノードを連結します。", meta={"category": "概念"}),
    Document(content="Retriever はドキュメントを検索します。", meta={"category": "コンポーネント"})
]

リスト内包表記を使えば、大量のドキュメントも効率的に作成できます。

Pipeline クラス

Pipeline は複数のノードを連結して処理フローを構築するクラスです。

Pipeline の基本構築

typescriptCopy codefrom haystack import Pipeline
from haystack.document_stores import InMemoryDocumentStore
from haystack.nodes import BM25Retriever

# DocumentStore の初期化
document_store = InMemoryDocumentStore()

# Retriever の初期化
retriever = BM25Retriever(document_store=document_store)

まず DocumentStore と Retriever を準備します。InMemoryDocumentStore はメモリ上で動作するため、セットアップが簡単です。

ノードの追加

typescriptCopy code# Pipeline を作成
pipeline = Pipeline()

# ノードを追加
pipeline.add_node(
    component=retriever,
    name="Retriever",
    inputs=["Query"]
)

add_node() メソッドでノードをパイプラインに追加します。inputs で前段のノードを指定することで、処理の流れを定義できるでしょう。

Pipeline の実行

typescriptCopy code# クエリを実行
result = pipeline.run(
    query="Haystack とは何ですか？",
    params={"Retriever": {"top_k": 5}}
)

# 結果を取得
documents = result["documents"]
for doc in documents:
    print(doc.content)

run() メソッドでパイプラインを実行します。params で各ノードのパラメータを指定できます。

DocumentStore クラス群

DocumentStore はドキュメントの保存と検索を担当します。

InMemoryDocumentStore の使用

typescriptCopy codefrom haystack.document_stores import InMemoryDocumentStore
from haystack import Document

# DocumentStore の初期化
document_store = InMemoryDocumentStore()

# ドキュメントの書き込み
docs = [
    Document(content="Haystack はオープンソースです。"),
    Document(content="deepset 社が開発しています。")
]
document_store.write_documents(docs)

write_documents() でドキュメントを一括保存します。メモリ上に保持されるため、プログラム終了時にデータは消えます。

ElasticsearchDocumentStore の使用

typescriptCopy codefrom haystack.document_stores import ElasticsearchDocumentStore

# Elasticsearch に接続
document_store = ElasticsearchDocumentStore(
    host="localhost",
    port=9200,
    index="haystack_docs"
)

Elasticsearch を使う場合は、事前に Elasticsearch サーバーを起動しておく必要があります。index でインデックス名を指定しましょう。

ドキュメントの取得

typescriptCopy code# 全ドキュメントを取得
all_docs = document_store.get_all_documents()

# 件数を確認
print(f"保存されているドキュメント数: {len(all_docs)}")

get_all_documents() で保存されている全ドキュメントを取得できます。

Retriever クラス群

Retriever はドキュメントの検索を行います。

BM25Retriever の使用

typescriptCopy codefrom haystack.nodes import BM25Retriever

# BM25Retriever の初期化
retriever = BM25Retriever(document_store=document_store)

# 検索実行
results = retriever.retrieve(
    query="Haystack の特徴",
    top_k=3
)

# 結果を表示
for doc in results:
    print(f"スコア: {doc.score}, 内容: {doc.content}")

retrieve() メソッドで検索を実行します。top_k で取得する件数を指定できます。

EmbeddingRetriever の使用

typescriptCopy codefrom haystack.nodes import EmbeddingRetriever

# EmbeddingRetriever の初期化
retriever = EmbeddingRetriever(
    document_store=document_store,
    embedding_model="sentence-transformers/all-MiniLM-L6-v2"
)

EmbeddingRetriever を使う場合は、まず埋め込みベクトルを生成する必要があります。

埋め込みベクトルの更新

typescriptCopy code# ドキュメントに埋め込みベクトルを追加
document_store.update_embeddings(retriever=retriever)

# 検索実行
results = retriever.retrieve(
    query="LLM フレームワーク",
    top_k=3
)

update_embeddings() で全ドキュメントに埋め込みベクトルを付与します。初回のみ実行すれば OK です。

PromptNode クラス

PromptNode は LLM を使った推論を実行します。

PromptNode の基本使用

typescriptCopy codefrom haystack.nodes import PromptNode, PromptTemplate

# PromptTemplate の定義
template = PromptTemplate(
    prompt="以下の質問に答えてください。\n質問: {query}\n回答:",
    output_parser=None
)

まずプロンプトテンプレートを定義します。{query} の部分が実行時に置き換わります。

LLM の設定と実行

typescriptCopy code# PromptNode の初期化
prompt_node = PromptNode(
    model_name_or_path="gpt-3.5-turbo",
    api_key="your-api-key-here",
    default_prompt_template=template
)

# 推論実行
result = prompt_node.predict(
    query="Haystack の主な機能は何ですか？"
)

print(result)

predict() メソッドで LLM に問い合わせます。API キーは環境変数で管理することを推奨します。

主要関数の使い方

write_documents()

ドキュメントを DocumentStore に保存する関数です。

基本的な使い方

typescriptCopy codefrom haystack import Document

# ドキュメントリストを作成
docs = [
    Document(content="内容1"),
    Document(content="内容2"),
    Document(content="内容3")
]

# 書き込み
document_store.write_documents(documents=docs)

リスト形式でドキュメントを渡すだけで、一括保存できます。

重複チェックオプション

typescriptCopy code# 重複を避けて書き込み
document_store.write_documents(
    documents=docs,
    duplicate_documents="skip"
)

duplicate_documents パラメータで重複時の動作を制御できます。skip、overwrite、fail が選択可能です。

retrieve()

Retriever を使ってドキュメントを検索します。

基本的な検索

typescriptCopy code# 検索実行
results = retriever.retrieve(
    query="検索キーワード",
    top_k=5
)

top_k で取得件数を指定します。デフォルトは 10 件です。

フィルタを使った検索

typescriptCopy code# メタデータでフィルタリング
results = retriever.retrieve(
    query="検索キーワード",
    top_k=5,
    filters={"category": ["用語", "概念"]}
)

filters パラメータでメタデータによる絞り込みができます。複数の値を指定すると OR 条件になります。

add_node()

Pipeline にノードを追加する関数です。

単純な追加

typescriptCopy codepipeline.add_node(
  (component = retriever),
  (name = 'MyRetriever'),
  (inputs = ['Query'])
);

inputs に ["Query"] を指定すると、パイプラインの開始点になります。

複数ノードの連結

typescriptCopy code# Retriever を追加
pipeline.add_node(
    component=retriever,
    name="Retriever",
    inputs=["Query"]
)

# PromptNode を追加
pipeline.add_node(
    component=prompt_node,
    name="PromptNode",
    inputs=["Retriever"]
)

2 つ目以降のノードは、前のノードの名前を inputs に指定することで連結されます。

run()

Pipeline を実行する関数です。

基本的な実行

typescriptCopy coderesult = pipeline.run((query = '質問内容'));

query パラメータに検索クエリや質問を指定します。

パラメータの詳細指定

typescriptCopy coderesult = pipeline.run(
  (query = '質問内容'),
  (params = {
    Retriever: { top_k: 10 },
    PromptNode: { temperature: 0.7 },
  })
);

params で各ノードに個別のパラメータを渡せます。ノード名をキーとした辞書形式で指定しましょう。

CLI コマンドの実践例

haystack run

パイプライン定義ファイルを実行します。

基本的な実行

bashCopy code# YAML ファイルからパイプラインを実行
haystack run pipeline.yml

pipeline.yml には Pipeline の構成が記述されています。

クエリを指定して実行

bashCopy code# クエリパラメータを指定
haystack run pipeline.yml --query "Haystack とは？"

--query オプションで実行時のクエリを指定できます。

haystack rest-api

REST API サーバーを起動します。

API サーバーの起動

bashCopy code# デフォルトポート (8000) で起動
haystack rest-api

ブラウザで http:​/​​/​localhost:8000​/​docs にアクセスすると、API ドキュメントが表示されます。

ポート番号の指定

bashCopy code# カスタムポートで起動
haystack rest-api --port 9000 --pipeline pipeline.yml

--port でポート番号を、--pipeline でパイプライン定義ファイルを指定できます。

haystack export

Pipeline を YAML 形式にエクスポートします。

Pipeline のエクスポート

bashCopy code# 現在の Pipeline を YAML に出力
haystack export --path exported_pipeline.yml

Python で構築した Pipeline を YAML として保存できます。チーム共有やバージョン管理に便利でしょう。

haystack validate

パイプライン定義ファイルの妥当性を検証します。

検証の実行

bashCopy code# YAML ファイルを検証
haystack validate pipeline.yml

構文エラーや設定ミスがあれば、エラーメッセージが表示されます。

詳細モードでの検証

bashCopy code# 詳細情報を出力
haystack validate pipeline.yml --verbose

--verbose オプションで、より詳しい検証結果が得られます。

haystack list-nodes

利用可能なノードの一覧を表示します。

ノード一覧の表示

bashCopy code# 全ノードをリスト表示
haystack list-nodes

Retriever、Reader、Generator など、カテゴリ別にノードが表示されます。

特定カテゴリのみ表示

bashCopy code# Retriever のみ表示
haystack list-nodes --category Retriever

--category オプションで絞り込みができます。

haystack ui

Web UI を起動します。

UI の起動

bashCopy code# デフォルト設定で UI を起動
haystack ui

ブラウザが自動的に開き、GUI で Pipeline を操作できます。

パイプラインを指定して起動

bashCopy code# 特定の Pipeline を読み込んで起動
haystack ui --pipeline my_pipeline.yml --port 8080

--pipeline で読み込むパイプラインを指定できます。

以下の図は、CLI コマンドの典型的な使用フローを示しています。

mermaidCopy codesequenceDiagram
    participant dev as 開発者
    participant cli as Haystack CLI
    participant file as pipeline.yml
    participant server as API Server

    dev->>cli: haystack validate pipeline.yml
    cli->>file: 構文チェック
    file-->>cli: OK
    cli-->>dev: 検証成功

    dev->>cli: haystack rest-api --pipeline pipeline.yml
    cli->>file: 読み込み
    cli->>server: サーバー起動
    server-->>dev: http://localhost:8000

    dev->>server: API リクエスト
    server-->>dev: レスポンス

図で理解できる要点:

• まず validate でパイプラインの妥当性を確認
• 問題なければ rest-api でサーバーを起動
• API 経由でパイプラインを利用可能

まとめ

本記事では、Haystack 開発で頻繁に使用する主要クラス、関数、CLI コマンドをチートシート形式でまとめました。

主要クラスでは、Document、Pipeline、各種 DocumentStore、Retriever、PromptNode など、Haystack の中核を成すコンポーネントを紹介しました。これらを組み合わせることで、柔軟な検索・質問応答システムを構築できます。

主要関数では、write_documents()、retrieve()、add_node()、run() といった、日常的に使う関数の使い方を具体例とともに解説しました。引数の指定方法やオプションを理解しておくことで、開発がスムーズになるでしょう。

CLI コマンドでは、haystack run、haystack rest-api、haystack validate など、開発やデプロイで役立つコマンドを紹介しました。これらを活用することで、Python コードを書かずとも多くの操作が可能になります。

チートシートを手元に置いておくことで、ドキュメントを何度も開く手間が省け、開発効率が格段に向上します。また、チーム内で共有すれば、共通の知識基盤として機能し、コミュニケーションもスムーズになるでしょう。

本記事の内容をベースに、ぜひ自分のプロジェクトに合わせたカスタムチートシートを作成してみてください。よく使うパターンや独自のヘルパー関数を追加することで、さらに実用的なリファレンスになります。

Haystack は非常に強力なフレームワークですが、その全機能を使いこなすには時間がかかります。しかし、頻繁に使うクラスや関数を押さえておけば、大半のユースケースに対応できるはずです。

このチートシートが、あなたの Haystack 開発の良きパートナーとなることを願っています。

関連リンク

• Haystack 公式サイト
• Haystack GitHub リポジトリ
• Haystack ドキュメント
• Haystack チュートリアル
• deepset 社公式ブログ
• Haystack Discord コミュニティ