【次世代RAG】Microsoft「GraphRAG」超入門！Pythonでナレッジグラフを自動構築し複雑な社内文書に答える検索AI構築ガイド

はじめに：従来のRAG（Naive RAG）が抱える限界

社内文書やマニュアルをLLM（大規模言語モデル）に読み込ませて高度な質問応答を行う仕組みとして、「RAG」（Retrieval-Augmented Generation）は広く普及しました。しかし、一般的なベクトルデータベースを利用した従来のRAG（いわゆる「Naive RAG」）には、実務運用においていくつかの大きな壁が存在します。

それは、以下のような「ドキュメント全体を俯瞰・要約しなければ答えられない質問」や「複数の情報にまたがる抽象的な関連性の把握」が非常に苦手であるという点です。

「この業務マニュアル全体を通じて、セキュリティに関する脆弱性はどこに集約されていますか？」
「プロジェクトAとプロジェクトBの共通の課題は何ですか？」

従来のRAGは、テキストを数行〜数十行の断片（チャンク）に分割し、質問文に「ベクトルが類似している断片」のみを検索してLLMに渡します。そのため、文書全体に分散している情報をまとめ上げたり、複雑な人間関係や組織構造を俯瞰して整理したりするようなクエリ（Global Queries）には対応できないのです。

この課題をブレイクスルーするためにMicrosoft Researchが開発したのが、次世代のRAG手法である「GraphRAG」です。

Microsoftが提唱する「GraphRAG」とは？

Microsoft GraphRAG GitHub は、LLMを用いて入力ドキュメントからナレッジグラフ（構造化された知識グラフ）を自動的に構築する画期的なフレームワークです。

ナレッジグラフとは、情報の中に登場する「エンティティ」（人、組織、場所、概念など）を「ノード」とし、それらの関係性を「エッジ」で結んだネットワーク状のデータ構造です。GraphRAGは、このネットワーク構造を自動構築するだけでなく、グラフ理論を応用してノードを「コミュニティ」に自動分割し、それぞれのコミュニティごとにLLMが階層的な要約を事前生成します。

これにより、ミクロな特定情報の検索だけでなく、マクロなドキュメント全体の要約や、多角的な情報のマッピングが可能になりました。公式ドキュメントは GraphRAG Official Documentation から確認できます。

GraphRAGの核となる「2つの検索モード」

GraphRAGでは、ユーザーの質問の性質に合わせて、以下の「2つのクエリエンジン」を使い分けることができます。

1. ローカル検索（Local Search）

特定の「エンティティ」（例：特定の製品、特定の人物など）に関する具体的な質問に適しています。質問に関連するナレッジグラフ内のノードを特定し、その周辺の関係性や関連ドキュメント、エンティティのメタ情報を統合して回答を生成します。ミクロな絞り込み検索に強みを発揮します。

2. グローバル検索（Global Search）

ドキュメント群全体にまたがる「全体的なテーマ」や「抽象的な問い」に適しています。事前に自動生成された各コミュニティの要約群をマクロに検索し、全体像を合成して回答を出力します。従来のRAGが最も苦手としていた「要約」や「全体把握」を驚くほどの精度で実現します。

GraphRAGをPython環境で構築・実行する手順

それでは、実際にPython環境を使用して、独自のテキストデータからナレッジグラフを構築・検索するまでのステップを解説します。

1. 動作環境の準備とインストール

Python 3.10〜3.12の環境を用意し、専用の作業ディレクトリを作成してライブラリをインストールします。

# 作業ディレクトリの作成
mkdir graphrag-demo && cd graphrag-demo

# 仮想環境の作成と有効化
python -m venv .venv
source .venv/bin/activate  # Windowsの場合は .venv\Scripts\activate

# graphragのインストール
pip install graphrag

2. ワークスペースの初期化

次に、GraphRAGのインデックス作成に必要な設定ファイルなどを自動生成するために初期化コマンドを実行します。

python -m graphrag.index --init --root .

実行すると、カレントディレクトリに以下のファイルが生成されます。

.env（環境変数・APIキーの設定）
settings.yaml（インデックス構築およびクエリの詳細設定）
prompts/（エンティティ抽出などで使われるプロンプトのテンプレート）

3. APIキーとモデルの設定

まず、.env ファイルを開き、お手持ちのOpenAIのAPIキーを記述します。

GRAPHRAG_API_KEY=sk-proj-************************

次に、settings.yaml をテキストエディタで開き、使用するLLMを設定します。標準では gpt-4o や gpt-4o-mini が指定されています。ナレッジグラフの構築は大量のトークンを消費するため、最初はコストパフォーマンスに優れた gpt-4o-mini を選択することを強く推奨します。

llm:
  api_key: !env ${GRAPHRAG_API_KEY}
  type: openai_chat
  model: gpt-4o-mini
  model_supports_json: true

4. ソースデータの配置

検索対象としたい任意のテキストデータを input ディレクトリに格納します。ここでは、サンプルとして input フォルダを作成し、社内規約やプロジェクトドキュメント（テキストファイル）を保存します。

mkdir -p input

※ input ディレクトリ内に、複数の .txt または .md ファイルを配置してください。

5. インデックス（ナレッジグラフ）の自動構築

準備が整ったら、インデックス構築プロセスを開始します。この処理により、LLMがファイルを読み込み、エンティティの抽出、関係性の定義、コミュニティ要約作成までを一気通貫で実行します。

python -m graphrag.index --root .

注意：ドキュメントの量に応じてLLMのAPIコールが大量に発生します。数分〜数十分かかる場合がありますので、処理が完了するまでお待ちください。処理結果は output ディレクトリに保存されます。

PythonコードからGraphRAGを実行する

インデックスの構築が完了したら、Pythonスクリプトから検索エンジンを呼び出し、実際に回答を得てみましょう。以下のコードは、GraphRAGの検索機能をPythonスクリプトから呼び出すシンプルな実装例です。

import asyncio
import os
from pandas import DataFrame
from graphrag.query.cli import run_global_search, run_local_search

# ディレクトリパスの設定
INPUT_DIR = "./output"
# 最新の実行バッチのパスを自動で設定する必要があります
# 実際の実装では、output内の最新タイムスタンプフォルダのParquetファイルを指定します

async def query_graphrag():
    # グローバル検索の実行例
    # ドキュメント全体に関するマクロな質問
    print("--- グローバル検索の実行中 ---")
    query = "このドキュメントに登場する主要な登場人物と、彼らの共通の課題をまとめてください。"
    
    # 簡易的にCLIインターフェースをPythonから叩く構成例
    # 実際の実装は、APIドキュメントを参照して検索エンジンオブジェクトを初期化して使用します
    
if __name__ == "__main__":
    # コマンドラインからも直接以下のコマンドで検索が可能です
    # python -m graphrag.query --root . --method global "ドキュメントの要約をしてください"
    pass

コマンドラインから最も手軽にテストするには、以下のコマンドを実行します。

# グローバル検索による全体の要約
python -m graphrag.query --root . --method global "このドキュメントが扱っている最も重要なトピックを3点に要約してください。"

# ローカル検索による特定情報のピンポイント抽出
python -m graphrag.query --root . --method local "特定のプロジェクトAのリーダーは誰ですか？"

よくあるエラーとトラブルシューティング

GraphRAGを実際に動かしてみると、いくつかの代表的なエラーに遭遇することがあります。実務で立ち往生しないための解決策を提示します。

1. OpenAI APIの「Rate Limit（レートリミット）」エラー（429エラー）

原因： GraphRAGは複数の文書を非同期かつ超高速で処理するため、短時間に数千〜数万のトークンをAPIに送信します。そのため、OpenAIの「TPM」（Tokens Per Minute）や「RPM」（Requests Per Minute）の制限に引っかかりやすくなります。

解決策： settings.yaml ファイルの llm セクションにある並列リクエスト制限およびスロットリングの設定を調整します。

llm:
  # 並列数を下げて負荷を減らす（デフォルトは16など）
  concurrent_requests: 4
  # リトライの間隔やリトライ最大回数を調整する
  max_retries: 10

2. インデックス作成後のクエリ時に「ファイルが見つからない」と怒られる

原因：ナレッジグラフのインデックス生成ステップ（graphrag.index）が途中でクラッシュしている、あるいは出力先パスが正しく参照できていない場合に発生します。
解決策： output/ ディレクトリ配下に、生成された成果物（.parquet ファイル群など）が格納されているか確認してください。途中でエラー終了している場合は、APIキーの不足や入力テキストが空、あるいは文字コードが UTF-8 以外になっている可能性があります。テキストファイルのエンコーディングを今一度確認してください。

他のAIフレームワークとの連携と発展性

GraphRAGによって生成された「整理された回答」や「関係性のデータ」は、そのままユーザーに提示するだけでなく、他の自律型AIエージェントと組み合わせることで真価を発揮します。

例えば、構造化された確実なデータを元にしてシステムを動かす場合、Pydantic AI を利用した型安全なRAGシステムへ統合したり、複雑なタスクの分岐・評価を行うために LangGraph を用いたマルチエージェントに回答パーツとしてGraphRAGの検索結果を組み込んだりするアプローチがトレンドとなっています。

これにより、「全体の構造をGraphRAGが把握し、詳細なアクションをマルチエージェントが実行する」という、極めて実用的で賢い社内AIアシスタントの構築が実現します。

まとめ

Microsoftの「GraphRAG」は、従来のベクトルDBだけでは限界があった「全体の要約」「関係性の俯瞰」というRAG開発の難所を、ナレッジグラフの自動構築というアプローチで見事に突破しました。

チャンク単位の類似度検索にとどまらない、マクロなコンテキストの理解
コミュニティ検出を用いた、多階層なサマリーの自動生成
gpt-4o-mini などを活用することで、個人や中小規模の開発でも実用可能

複雑な社内文書や大量の仕様書をインテリジェントに検索するシステムを目指すなら、ぜひ本記事を参考にGraphRAGの導入にチャレンジしてみてください！