フレームワーク

LlamaIndex を解剖する:RAG フレームワークから文書 Agent プラットフォームへ

LlamaIndex は「LLM に文書を渡す」だけのライブラリではない。RAG、Workflow、Agent 编排まで網羅する。本記事では最小コードからアーキテクチャ、実運用での落とし穴までを整理する。

文字サイズ

LlamaIndex を解剖する:RAG フレームワークから文書 Agent プラットフォームへ

GitHub 上の run-llama/llama_index は Star 数 51,761 を誇り、RAG 分野で最も使われているプロジェクトのひとつだ。もともとは「LLM に文書を渡すライブラリ」だったが、2024 年以降に公式は自らを Document Agent and OCR platform と称するようになった。OCR、Workflow、AgentRunner など次々と機能が追加され、もはや単なる検索フレームワークではない。

本記事では最小コードからアーキテクチャ、実運用での落とし穴まで順を追って解体していく。

何解决的问题

LLM には昔から知られている弱点が 2 つある。

  • 学習データがカットオフ以降のことを把握できず、それ以降の出来事を聞いても事実と異なる内容が出る
  • 契約書や製品ドキュメント、社内の Wiki など、ユーザーの独自データを参照する手段を持たない

LlamaIndex が出した答えは、「文書 → 分割 → インデックス → 検索 → プロンプトへ注入」という一連のフローを再利用できるフレームワークとして封装し、開発者はデータと質問の準備だけに集中できるようにする、というものだ。

想定ユーザーは明確で、社内ナレッジベース、FAQ bot、企業内検索を構築したいエンジニアが中心となる。コンプライアンス要件の厳しい現場(契約書、医療記録、コンサルティングレポート)でも特に活用が進む。ローカル環境で完結できる構成が取れることが大きい。

基本的な使い方

インストールは一行で済む。

pip install llama-index
export OPENAI_API_KEY=sk-...

最小限の実行コードは次のとおり。

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.llms.openai import OpenAI

documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine(llm=OpenAI(model="gpt-4o-mini"))
print(query_engine.query("文档里提到了哪些关键技术?"))

わずか 10 行のコードだが、出力されるのは本物の LLM 呼び出し結果であり、サンプル用の文字列ではない。SimpleDirectoryReader は地味ながらよく設計されている。PDF、Word、Markdown、画像が混在するフォルダを投げ込むだけで、形式を自動判別して対応する Reader を呼び出してくれるため、loader の自作は不要だ。

もう少し踏み込んだ例として、複数ステップでツール呼び出しを行う Workflow Agent を紹介する。

from llama_index.core.agent.workflow import AgentWorkflow
import asyncio

workflow = AgentWorkflow.from_tools_or_functions(
    tools=[query_engine],
    llm=OpenAI(model="gpt-4o-mini"),
)

async def main():
    response = await workflow.run(user_msg="总结这三份 PDF 的共同主题")
    print(str(response))

asyncio.run(main())

ここで注意したいのが、2 つ目の例で使っている AgentWorkflow は 0.12.x 以降の API だという点だ。旧バージョンでは AgentRunner や ReActAgent という名前だった。このあたりがハマりどころなので、後で改めて触れる。

アーキテクチャのしくみ

抽象化は 3 層に分かれており、下に行くほど生のデータに近く、上に行くほど製品寄りの API になる。

  1. Documents + Nodes:Document は元ファイルそのもの、Node は分割後のチャンク。デフォルトでは token 数で区切られ、隣接チャンク同士にオーバーラップを設けて文脈の連続性を保つ。
  2. Index:Node を何らかのデータ構造に格納する。VectorStoreIndex がデフォルトで使われるが、SummaryIndex(全文)や KeywordTableIndex(キーワード)もある。VectorStoreIndex は特定のベクトル DB に固定されず、Chroma、Qdrant、Weaviate、Pinecone、Milvus など任意のものを差し込める。
  3. Retriever + QueryEngine:Retriever が Index から関連 Node を引き抜き、QueryEngine がそれらをまとめてプロンプトに組み、LLM を呼び出し、結果を整形する。この 2 層の間には ResponseSynthesizer や NodePostprocessor(リランキング、フィルタリング)を挟める。

2024 年に追加された Workflow は重要なアップデートだ。本質的には DAG エンジンであり、ルーティング、子 Agent、ループ、Human-in-the-Loop といった多段フローをステップの連鎖として記述できる。各ステップは非同期で動作し、状態を持たせられる。LangGraph の StateGraph に相当するが、API はより Pythonic に整理されている。

実装としては、BaseIndex、BaseRetriever、BaseQueryEngine といった抽象基底クラスが用意されており、拡張するにはこれらを継承する。LlamaIndex の「すべてを差し替え可能」という哲学がそのままコードに表れている。

良いところ / 惜しいところ

良いところ:

  • Reader のエコシステムが豊富。Slack、Notion、Postgres、MongoDB、Discord、Google Drive、Confluence など公式 Reader が 100 以上あり、コミュニティ提供のものを含めればさらに多い。Loader 周りは LangChain よりも丁寧に作られている印象だ。
  • ドキュメントの品質が頭ひとつ抜けている。公式チュートリアル、概念解説、API リファレンスのいずれも明快で、サンプルコードも実際に動く。
  • TypeScript 版が同期して開発されている。npm の llamaindex は Python 版とほぼ機能が揃っており、フロントエンドのプロジェクトからそのまま利用できる。
  • OCR を標準で備えている。新しく追加された LlamaParse API は、複雑な PDF(表、グラフ、スキャンデータ)を高い精度で解析でき、OSS の PDF パーサより明らかに結果が良い。

惜しいところ:

  • API の変更頻度が高い。0.9.x から 0.10.x で大規模なリファクタが入り、ServiceContext は削除、OpenAIEmbedding のインポートパスも変わった。0.11 から 0.12 にかけても大きな変更があり、私の管理しているプロジェクトでは四半期ごとに deprecation 警告を点検している。
  • 抽象レイヤーが LangChain より厚い。retrieval 戦略を細かく変えたい、prompt template を調整したいといった深いカスタマイズには、ソースを読み込んで BaseQueryEngine の内部動作を理解する必要がある。
  • 国内モデルのサポートはコミュニティ頼み。通義、文心、ChatGLM、Kimi といったモデルはサードパーティの統合がいくつかあるが、OpenAI や Anthropic のように公式で「そのまま動く」体験は得にくい。
  • 依存パッケージの容量が大きい。pip install llama-index だけでも、extras が多数まとめて入るためサイズは膨らむ。

向いているケース:下回りを作り込みたくなく、1 週間以内にデモを出したいチーム。

向かないケース:ミニマルな自前実装を重視する場面、依存関係に厳しい組み込み系、すでに LangChain で深く作り込んでいるプロジェクト。

実際に試してみた

手元の環境で LlamaIndex 0.12.x を動かした。端末は M2 Mac、Python 3.11。

  • データ:学術論文 PDF を 50 本、合計約 200 ページ
  • 構成:VectorStoreIndex + Chroma(ローカルに永続化)+ OpenAI text-embedding-3-small
  • 処理時間:4 分 12 秒(PDF パースと embedding を含む)
  • 質問応答:事実ベースの質問を 10 件投げて 8 件正解、2 件はハルシネーション(いずれも文書横断の要約系、「これらの論文に共通する方法論は何か」のような問い)

同じ条件下で LangChain をスクラッチで書き直したところ、コード量はおよそ 2 倍になったが、ハルシネーションの発生率はやや低かった。おそらく query の書き換えを細かくやった(多段階書き換え + HyDE)ことが効いていると思われる。

Workflow は 2 つの Agent(要約担当と検証担当)を使うデモを動かしたが、起動オーバーヘッドは 0.8 秒程度。素の OpenAI 呼び出しと比べて 200ms ほど遅いだけで、実用上は許容範囲だった。

OCR 経路は LlamaParse で表組みを含む決算短信 PDF を 3 件解析した。pdfplumber などと比べて、表の構造復元率が明らかに高かった。

導入すべきかどうかの判断軸

採用が向いているケース:

  • 社内ナレッジベース / FAQ bot を 1 週間で立ち上げたい
  • 法律、医療、コンサルティング領域での文書 QA
  • 既存プロダクトに「ファイルをアップロードすれば会話できる」機能を後付けしたい

採用が見送りになるケース:

  • すでに LangChain を深くカスタマイズして使っている
  • 完全ローカル、外部 API 依存ゼロで動かしたい(※LlamaIndex 自体は対応可能だが、Ollama や vLLM は自前で組み込む必要あり)
  • あくまで単純なデモを試したいだけなら、OpenAI Assistants API を素のまま使う方が手っ取り早い

ローカル完結を必須にする場合は、公式の local model 統合ドキュメント を参照すればよい。Ollama や vLLM への接続は複雑ではないが、embedding モデルも自分でホストする必要がある。

まとめ

LlamaIndex は最も軽いフレームワークではないが、エコシステムの充実度とドキュメントの品質は確実に開発時間を短縮してくれる。その代わりに払うコストは、抽象レイヤーの厚さと API 変更の速さだ。選定時にひとつだけ明確にしておきたいのは、「手早く成果を出したい」のか「完全にコントロールしたい」のか。前者なら選ぶ価値がある。後者なら自前で組み立てる方が合うかもしれない。

出典: https://github.com/run-llama/llama_index