llamaindex

LlamaIndex エキスパートスキル

LlamaIndex は、データを活用した LLM アプリケーションを構築するための、MIT ライセンスの Python フレームワークです。2026 年には、RAG インデックスライブラリから、統合された本番環境ランタイム（llama-deploy）、エージェントオーケストレーション（AgentWorkflow）、ナレッジグラフ構築（PropertyGraphIndex）、OpenTelemetry ネイティブの可観測性を備えた、イベント駆動型ワークフローフレームワークへと進化しました。

このフレームワークは、7 つのコアプリミティブを中心に構成されています。Reader（データローダー）、Document/Node（チャンク化されたコンテンツモデル）、Index（Node を扱うデータ構造）、Retriever（関連する Node の選択）、Query Engine（retriever ＋ 合成）、Agent（ツールを備えた LLM）、Workflow（イベント駆動型のオーケストレーション）です。

主な原則

これらの原則は、LlamaIndex を使って構築する際のあらゆる判断の基準となります。リファレンスガイドに進む前にお読みください。

1. 検索チャンクと合成チャンクを分離します。 効果的に検索できる埋め込み表現と、効果的に生成できるコンテキスト表現は異なります。このパターンには SentenceWindowNodeParser と MetadataReplacementNodePostProcessor を使用します。
2. 生成の前にリランキングします。 ハイブリッド検索 ＋ リランカーは、本番環境で RAG を運用するための最低限の構成です。
3. エージェントは Workflow です。 FunctionAgent と AgentWorkflow は、あらかじめ設定された Workflow です。独自の制御フローが必要な場合は、生の Workflow を使用します。
4. グラフは単なるベクトルストアではありません。 PropertyGraphIndex は、ベクトル類似度では提供できない構造的なパス探索を可能にします。検索品質を最大限に高めるには、両方を組み合わせます。
5. 同じプロセス内で評価します。 Span に紐づけられた評価により、出力と、その出力を生成した検索コンテキストとのつながりが保たれます。

どこから始めるか

パイプラインは Ingest から Deploy までの 9 つのフェーズで構成されています。既存の作業の途中から参加する場合は、該当する開始地点を見つけてください。

すでにあるもの...	開始するフェーズ	作業内容
何もない — 空のプロジェクト	Ingest	データ読み込みを設定してから、パイプライン全体を進めます
ディレクトリ内のドキュメント	Chunk	チャンク化戦略を選び、インデックスを構築します
動作するベクトルインデックス	Retrieve	ハイブリッド検索、リランキング、メタデータフィルターを追加します
強化が必要な既存の RAG パイプライン	Deploy	可観測性、llama-deploy、本番環境でのデバッグを追加します
品質を測定して改善する必要がある	Evaluate	評価器、ParamTuner、Span に紐づけられたスコアリングを設定します
何もない — フレームワークを比較中	フレームワーク選定ガイドを参照	パイプラインを始めるのではなく、まず適切なツールを選びます

パイプラインモード

タスクによって、必要な厳密さは異なります。作業範囲に合ったモードを選んでください。

モード	対象	実行するフェーズ	省略するもの
Quick	単一のクエリ、1 つのソース、調査	Ingest → Chunk → Index → Retrieve	リランキング、メタデータフィルター、可観測性、評価
Full	本番環境の RAG、複数のソース、コンプライアンス	Ingest → Chunk → Index → Retrieve → Agent/Workflow → Deploy → Evaluate	なし — すべてのフェーズを実行
Evaluate	ベンチマーク、リグレッションテスト	Ingest → Chunk → Index → Evaluate	Retrieve、Agent、Workflow、Deploy（オフラインで実行）
Graph	ナレッジグラフ構築	Ingest → Chunk → Graph → Retrieve	Agent、Workflow、Deploy（グラフインデックスから直接クエリ）

目安として、ユーザー向けにリリースする場合は Full モード、調査する場合は Quick モード、測定する場合は Evaluate モードを実行してください。

クイックリファレンス

フェーズ	タスク	アプローチ	参照
取り込み	データを読み込む	SimpleDirectoryReader("./data").load_data()	references/architecture.md
チャンク化	ドキュメントをノードに解析する	SentenceSplitter(chunk_size=1024)	references/rag-strategies.md
インデックス作成	ベクトルインデックスを構築する	VectorStoreIndex.from_documents(docs)	references/rag-strategies.md
検索	ハイブリッド検索＋再ランキング	BM25Retriever + CohereRerank	references/rag-strategies.md
エージェント	マルチエージェントのオーケストレーション	AgentWorkflow(agents=[...])	references/agent-patterns.md
ワークフロー	イベント駆動型パイプライン	class MyFlow(Workflow): @step	references/workflows.md
グラフ	ナレッジグラフ	PropertyGraphIndex.from_documents(docs)	references/property-graph-index.md
評価	RAG の評価	FaithfulnessEvaluator().evaluate_response(...)	references/evaluation-observability.md
デプロイ	本番環境へのデプロイ	deploy_workflow(workflow=MyFlow())	references/production-deployment.md

このスキルを使用する場面

次のような場合は、いつでもこのスキルを読み込んでください。

• 企業データや個人データを対象とする RAG パイプラインを構築する
• LlamaIndex と LangChain、Haystack、DSPy を比較する
• 専門エージェント間のハンドオフを伴うマルチエージェントシステムを設計する
• 可観測性を備えた LLM アプリケーションを本番環境にデプロイする
• 非構造化ドキュメントからナレッジグラフを構築する
• よくある LlamaIndex の不具合（検索漏れ、ハンドオフのバグ、非同期処理の問題）をデバッグする

LlamaIndex を使用しない場面 — フレームワークの選択ガイド

このスキルは、フレームワークスキルのポートフォリオの一部です。適したフレームワークを選ぶ際は、次の選択表を使用してください。

シナリオ	選択するもの	理由
検索対象のドキュメントがある	LlamaIndex	データ取り込み、ハイブリッド検索、再ランキング、ナレッジグラフが標準機能として備わっています
オーケストレーションが必要なエージェントがある	LangGraph	ステートマシンのセマンティクス、タイムトラベルデバッグ、人間による介入のための一時停止が中核となる設計です
ツールをエージェントとしてラップしたい	PydanticAI	依存性注入を備えた型安全なエージェント定義と、LLM 呼び出しに対する最小限の抽象化が提供されます
PDF、SQL、Slack、200 以上のソースを対象とする、データ量の多い RAG	LlamaIndex	LlamaHub コネクター、ドキュメント向けの LlamaParse、標準搭載のハイブリッド検索を利用できます
チェックポイントを伴う複雑なマルチエージェントのステートマシン	LangGraph	グラフ構造を制御できます。スーパーバイザー、サブグラフ、階層型チーム、組み込みのチェックポインターに対応しています
データパイプラインより型安全性を重視する、エージェント中心のアプリ	PydanticAI	エージェントを Pydantic モデルとして定義し、DI と構造化出力を利用できます。データレイヤーは独自のコードで構成します
ドキュメント解析の品質が重要（表、グラフ、手書き文字）	LlamaIndex	LlamaParse はこの用途に特化して構築されています
本番環境向けの NLP 検索パイプライン	Haystack	パイプライン構成モデルが、検索に特化したワークロード向けにより成熟しています
最適化主導のプロンプトプログラミング	DSPy	コンパイル済みのプロンプトプログラムを使用します。検索パイプラインではありません

リファレンスファイル

リファレンス	読み込むタイミング	ファイル
コアアーキテクチャ	7 つのプリミティブ、Settings、データフローを理解するとき	references/architecture.md
RAG 戦略	基本から高度な RAG パイプラインを構築するとき	references/rag-strategies.md
エージェントパターン	AgentWorkflow でマルチエージェントをオーケストレーションするとき	references/agent-patterns.md
ワークフロー	イベント駆動のステップ構成と耐久性のある実行	references/workflows.md
本番環境とデプロイ	llama-deploy、デバッグ、障害モード	references/production-deployment.md
プロパティグラフインデックス	ナレッジグラフの構築とハイブリッド検索	references/property-graph-index.md
評価と可観測性	メトリクス、トレース、スパンに関連付けたスコアリング	references/evaluation-observability.md
統合エコシステム	ベクトルストア、LlamaHub、LlamaParse、エコシステム	references/integration-ecosystem.md
FAQ とトラブルシューティング	よくあるエラーとその修正方法	references/faq-and-troubleshooting.md
RAG の実践例	データ取り込みからデプロイまでの完全なエンドツーエンドパイプライン	references/example-rag-pipeline.md
評価ワークフロー	ParamTuner、評価器、バッチスコアリング、ベストプラクティス	references/evaluation-workflow.md

テンプレートファイル

テンプレート	使用する場面	ファイル
基本的な RAG	単一ソースへのクエリ、使い始めるとき	templates/basic-rag.py
エージェント型 RAG	エージェントによるルーティングを伴う複数ソースのデータ	templates/agentic-rag.py
カスタムワークフロー	カスタム制御フロー、分岐ロジック	templates/custom-workflow.py
本番環境へのデプロイ	ワークフローをマイクロサービスとしてラップするとき	templates/production-deploy.py

スクリプト

スクリプト	目的	ファイル
check-setup	LlamaIndex のインストールと設定を確認する	scripts/check-setup.py

トラブルシューティング — 構造化された復旧ガイド

問題が発生した場合は、症状を探して復旧手順に従ってください。

検索と回答の品質

症状	考えられる原因	すぐにできる修正	恒久的な修正	リファレンス
回答の質が低い、または幻覚がある	ハイブリッド検索にリランカーがない	CohereRerank(top_n=5) を node_postprocessor として追加する	本番環境の RAG では必ずリランキングを行う	references/rag-strategies.md
明らかな内容を検索できない	デフォルトのチャンク分割で意味が損なわれている	SemanticSplitterNodeParser(breakpoint_percentile_threshold=95) に切り替える	ParamTuner でチャンクサイズを調整する	references/rag-strategies.md
別のテナントのデータが返される	メタデータフィルターがない	MetadataFilters(filters=[ExactMatchFilter(key="tenant_id", ...)]) を追加する	常にリトリーバーのレベルでメタデータフィルターを設定する	references/rag-strategies.md
特定の種類のクエリしかうまく処理できない	検索戦略が 1 つだけ	ハイブリッドリトリーバーで BM25 とベクトル検索を組み合わせる	クエリの種類に応じてルーティングする RouterQueryEngine を追加する	references/rag-strategies.md

エージェントとワークフローの障害

症状	考えられる原因	すぐにできる修正	恒久的な修正	リファレンス
ハンドオフ後、エージェントが応答せず待機する	AgentWorkflow のハンドオフのバグ	FunctionAgent.take_step を拡張して、最後のユーザーメッセージを再特定する	すべての本番環境のエージェントにハンドオフの修正を適用する	references/agent-patterns.md
ワークフローが実行されない	await を忘れている	w.run(...) とすべてのステップ呼び出しの前に await を追加する	すべてのステップメソッドは非同期コルーチン	references/workflows.md
ステップは実行されるが、結果が失われる	状態が永続化されていない	共有状態には ctx.store.edit_state() を使用する	ステップ間で保持されるのは ctx.store のみ	references/workflows.md
クラッシュによって進捗がすべて失われる	チェックポイントのスナップショットがない	ステップ完了時に Context.to_dict() を保存する	耐久性のあるワークフローでは明示的なチェックポイントが必要	references/workflows.md

デプロイとオブザーバビリティ

症状	考えられる原因	すぐにできる対処法	恒久的な対処法	参照先
llama-deploy のデプロイ後にリクエストがタイムアウトする	Redis が起動していない	redis-server を起動する	Redis は必須です。Redis がないとコントロールプレーンはルーティングを行いません	references/production-deployment.md
オブザーバビリティ UI にスパンが表示されない	インストルメンテーションの呼び出しが遅すぎる	ワークフローのインスタンス化より前に instrument() の呼び出しを移動する	Workflow オブジェクトを作成する前に、必ずインストルメンテーションを行ってください	references/production-deployment.md
誤ったデータが返される（テナント間の混在）	メタデータフィルターが設定されていない	すべてのリトリーバーにテナントフィルターを追加する	後処理ではなく、リトリーバーレベルでフィルタリングしてください	references/production-deployment.md

復旧ワークフロー

障害が発生した場合は、次のサイクルに従ってください。

1. 上の表から症状を特定する
2. すぐにできる対処法を実施する — これにより稼働を再開できます
3. 恒久的な対処法を実装する — 再発を防止します
4. 評価で検証する — 保留しておいたクエリセットに対して FaithfulnessEvaluator を実行します
5. 対処法を文書化する — 根本原因を references/faq-and-troubleshooting.md に追加します