GraphRAG 徹底解説 ─ 知識グラフを使う検索拡張生成の仕組みと実装

Baseline RAG:  文書 → フラットなチャンク群 → ベクトル距離で検索
GraphRAG:     文書 → 構造化された意味グラフ → グラフ探索＋コミュニティ要約で回答

Document 1 → [TextUnit 1] [TextUnit 2]
Document 2 → [TextUnit 3] [TextUnit 4]

TextUnit → LLM → サブグラフ（エンティティ群 + 関係性群）
                    ↓
          グローバルグラフにマージ（説明は配列で集約）

- .NET 10 SDK 以降
- Azure OpenAI または OpenAI の API キー
- Azure CLI（Azure OpenAI 使用時: az login で認証）

mkdir GraphRAGDemo
cd GraphRAGDemo
dotnet new console
dotnet add package Microsoft.Agents.AI
dotnet add package OpenAI
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity
dotnet add package System.ClientModel

// Models/KnowledgeGraph.cs
// https://github.com/microsoft/graphrag — Knowledge Model の C# 表現
 
/// <summary>テキストチャンク — GraphRAG の分析基本単位</summary>
public record TextUnit(string Id, string Text, string DocumentId);
 
/// <summary>エンティティ — ナレッジグラフのノード</summary>
public record Entity(
    string Id,
    string Title,
    string Type,        // "person", "organization", "location", "event", ...
    string Description,
    int CommunityId,
    float[] Embedding);
 
/// <summary>関係性 — ナレッジグラフのエッジ</summary>
public record Relationship(
    string SourceId,
    string TargetId,
    string Description,
    double Weight);
 
/// <summary>コミュニティ — Leiden アルゴリズムで検出されたクラスター</summary>
public record Community(
    int Id,
    string Title,
    int Level,
    string Report);    // LLM 生成のコミュニティレポート

// Agents/EntityExtractor.cs
// https://github.com/microsoft/agent-framework — Agent Framework の関数ツール機能を活用
 
using System.ComponentModel;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
 
public static class EntityExtractor
{
    /// <summary>
    /// TextUnit からエンティティと関係性を抽出する関数ツール。
    /// Agent Framework が自動的に JSON Schema を生成し、LLM の Function Calling で呼び出す。
    /// </summary>
    [Description("テキストからエンティティ（人物・組織・場所・概念）と関係性を抽出する")]
    public static string ExtractEntitiesAndRelationships(
        [Description("分析対象のテキストチャンク")] string textUnit,
        [Description("抽出対象のエンティティタイプ（カンマ区切り）")] string entityTypes = "person,organization,location,event,concept")
    {
        // この関数は LLM の Function Calling 経由で呼び出される。
        // 実際には、LLM からの構造化出力をパースして
        // エンティティと関係性のリストを返す。
        return $$"""
        {
            "entities": [
                {"title": "...", "type": "...", "description": "..."}
            ],
            "relationships": [
                {"source": "...", "target": "...", "description": "..."}
            ]
        }
        """;
    }
}

// Program.cs — エンティティ抽出エージェントの構成
// https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/02-agents/Agents/
 
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
 
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName =
    Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o";
 
// エンティティ抽出エージェントを構成
AIAgent extractionAgent = new AzureOpenAIClient(
        new Uri(endpoint),
        new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsAIAgent(
        instructions: """
            あなたは知識グラフ構築の専門家です。
            与えられたテキストから、以下を JSON 形式で抽出してください:
            1. エンティティ: タイトル、タイプ（person/organization/location/event/concept）、説明
            2. 関係性: ソースエンティティ、ターゲットエンティティ、関係の説明
            重複するエンティティは同じタイトルで統一してください。
            """,
        tools: [AIFunctionFactory.Create(EntityExtractor.ExtractEntitiesAndRelationships)]);

// Services/CommunityDetector.cs
// 説明用の簡易コミュニティ検出器。完全な Leiden 実装ではない
 
/// <summary>
/// 説明用の簡易階層的コミュニティ検出。
/// GraphRAG では graspologic (Python) を使用するが、
/// この C# 例は説明用の簡易ローカル移動ヒューリスティックのみを示す。
/// </summary>
public class CommunityDetector
{
    /// <summary>
    /// グラフからコミュニティを検出し、各エンティティの CommunityId を設定する。
    /// </summary>
    /// <param name="entities">エンティティのリスト</param>
    /// <param name="relationships">関係性のリスト</param>
    /// <param name="maxCommunitySize">コミュニティの最大サイズ閾値</param>
    /// <returns>コミュニティのリスト</returns>
    public List<Community> DetectCommunities(
        List<Entity> entities,
        List<Relationship> relationships,
        int maxCommunitySize = 10)
    {
        // 1. 隣接リストを構築
        var adjacency = BuildAdjacencyList(entities, relationships);
 
        // 2. 初期化: 各ノードを独自のコミュニティに配置
        var assignments = entities.ToDictionary(e => e.Id, e => e.Id);
 
        // 3. 説明用のローカル移動ループ（実際の Leiden は modularity/CPM をより厳密に最適化）
        bool improved;
        do
        {
            improved = false;
            foreach (var entity in entities)
            {
                var bestCommunity = FindBestCommunity(
                    entity, adjacency, assignments);
                if (bestCommunity != assignments[entity.Id])
                {
                    assignments[entity.Id] = bestCommunity;
                    improved = true;
                }
            }
        } while (improved);
 
        // 4. コミュニティをグループ化し、各エンティティの CommunityId を設定して返却
        var groups = assignments.GroupBy(a => a.Value).ToList();
        var labels = groups.Select(g => g.Key).ToList();
        for (int i = 0; i < entities.Count; i++)
        {
            var communityId = labels.IndexOf(assignments[entities[i].Id]);
            entities[i] = entities[i] with { CommunityId = communityId };
        }
 
        return groups
            .Select((g, i) => new Community(
                Id: i,
                Title: $"Community {i}",
                Level: 0,
                Report: "")) // レポートは後続フェーズで生成
            .ToList();
    }
 
    private Dictionary<string, List<string>> BuildAdjacencyList(
        List<Entity> entities,
        List<Relationship> relationships)
    {
        var adj = entities.ToDictionary(e => e.Id, _ => new List<string>());
        foreach (var rel in relationships)
        {
            if (adj.ContainsKey(rel.SourceId))
                adj[rel.SourceId].Add(rel.TargetId);
            if (adj.ContainsKey(rel.TargetId))
                adj[rel.TargetId].Add(rel.SourceId);
        }
        return adj;
    }
 
    private string FindBestCommunity(
        Entity entity,
        Dictionary<string, List<string>> adjacency,
        Dictionary<string, string> assignments)
    {
        // 説明用スコア: 隣接コミュニティごとの隣接ノード数を数える
        var neighbors = adjacency.GetValueOrDefault(entity.Id) ?? [];
        var communityScores = neighbors
            .GroupBy(n => assignments.GetValueOrDefault(n, n))
            .ToDictionary(g => g.Key, g => (double)g.Count());
 
        return communityScores.Count > 0
            ? communityScores.MaxBy(kv => kv.Value).Key
            : assignments[entity.Id];
    }
}

// Services/CommunityReporter.cs
// https://github.com/microsoft/agent-framework — エージェントを使ったコミュニティ要約
 
public class CommunityReporter
{
    private readonly AIAgent _agent;
 
    public CommunityReporter(AIAgent agent)
    {
        _agent = agent;
    }
 
    /// <summary>
    /// コミュニティ内のエンティティと関係性から要約レポートを生成する。
    /// </summary>
    public async Task<string> GenerateReportAsync(
        Community community,
        List<Entity> entities,
        List<Relationship> relationships)
    {
        var context = BuildCommunityContext(entities, relationships);
 
        var session = await _agent.CreateSessionAsync();
        var response = await _agent.RunAsync(
            $"""
            以下のコミュニティのエンティティと関係性に基づいて、
            コミュニティレポートを生成してください。
 
            レポートには以下を含めてください:
            1. エグゼクティブサマリー（2-3文）
            2. 主要エンティティとその役割
            3. 重要な関係性
            4. 主要テーマ・傾向
 
            コミュニティデータ:
            {context}
            """,
            session);
 
        return response.Text;
    }
 
    private string BuildCommunityContext(
        List<Entity> entities,
        List<Relationship> relationships)
    {
        var sb = new System.Text.StringBuilder();
        sb.AppendLine("=== エンティティ ===");
        foreach (var e in entities)
            sb.AppendLine($"- {e.Title} ({e.Type}): {e.Description}");
 
        sb.AppendLine("\n=== 関係性 ===");
        foreach (var r in relationships)
            sb.AppendLine($"- {r.SourceId} → {r.TargetId}: {r.Description}");
 
        return sb.ToString();
    }
}

// Search/GlobalSearch.cs
// https://github.com/microsoft/graphrag — Global Search の C# 実装
 
public class GlobalSearch
{
    private readonly AIAgent _mapAgent;
    private readonly AIAgent _reduceAgent;
    private readonly int _maxTokensPerChunk;
 
    public GlobalSearch(
        AIAgent mapAgent,
        AIAgent reduceAgent,
        int maxTokensPerChunk = 2000)
    {
        _mapAgent = mapAgent;
        _reduceAgent = reduceAgent;
        _maxTokensPerChunk = maxTokensPerChunk;
    }
 
    /// <summary>
    /// コミュニティレポートを Map-Reduce で処理し、
    /// データセット全体に関する質問に回答する。
    /// </summary>
    public async Task<string> SearchAsync(
        string query,
        List<Community> communities)
    {
        // === Map ステージ ===
        // コミュニティレポートをチャンクに分割し、並列処理
        var reportChunks = ChunkReports(communities);
        var intermediateTasks = reportChunks.Select(chunk =>
            MapAsync(query, chunk));
        var intermediateResults = await Task.WhenAll(intermediateTasks);
 
        // === Reduce ステージ ===
        // 中間結果を集約して最終回答を生成
        var aggregated = intermediateResults
            .SelectMany(r => r.Points)
            .OrderByDescending(p => p.Score)
            .Take(20) // 上位 20 ポイントに絞る
            .ToList();
 
        return await ReduceAsync(query, aggregated);
    }
 
    private async Task<MapResult> MapAsync(
        string query, string reportChunk)
    {
        var session = await _mapAgent.CreateSessionAsync();
        var response = await _mapAgent.RunAsync(
            $"""
            以下のコミュニティレポートに基づいて、
            質問に関連するポイントを抽出し、
            各ポイントに 0-100 の重要度スコアを付けてください。
 
            質問: {query}
 
            レポート:
            {reportChunk}
            """,
            session);
 
        // 構造化出力をパース（簡略化）
        return ParseMapResult(response.Text);
    }
 
    private async Task<string> ReduceAsync(
        string query, List<ScoredPoint> points)
    {
        var context = string.Join("\n",
            points.Select(p => $"[Score: {p.Score}] {p.Text}"));
 
        var session = await _reduceAgent.CreateSessionAsync();
        var response = await _reduceAgent.RunAsync(
            $"""
            以下の情報ポイントに基づいて、質問に包括的に回答してください。
            各ポイントは元のデータセットから抽出された重要な情報です。
 
            質問: {query}
 
            情報ポイント:
            {context}
            """,
            session);
 
        return response.Text;
    }
 
    private List<string> ChunkReports(List<Community> communities)
    {
        // コミュニティレポートをトークン制限に基づいてチャンク化
        var chunks = new List<string>();
        var current = new System.Text.StringBuilder();
 
        foreach (var community in communities)
        {
            if (current.Length > _maxTokensPerChunk * 4) // おおよその文字数
            {
                chunks.Add(current.ToString());
                current.Clear();
            }
            current.AppendLine(community.Report);
        }
        if (current.Length > 0)
            chunks.Add(current.ToString());
 
        return chunks;
    }
 
    private MapResult ParseMapResult(string response)
        => new(new List<ScoredPoint>
        {
            new(response, 80) // 簡略化: 実際には構造化パースが必要
        });
}
 
public record MapResult(List<ScoredPoint> Points);
public record ScoredPoint(string Text, int Score);

// Search/LocalSearch.cs
// https://github.com/microsoft/graphrag — Local Search の C# 実装
 
public class LocalSearch
{
    private readonly AIAgent _agent;
    private readonly IVectorStore _vectorStore;
 
    public LocalSearch(AIAgent agent, IVectorStore vectorStore)
    {
        _agent = agent;
        _vectorStore = vectorStore;
    }
 
    /// <summary>
    /// 特定エンティティに関する質問に対して、
    /// 知識グラフの局所的な探索により回答する。
    /// </summary>
    public async Task<string> SearchAsync(
        string query,
        List<Entity> entities,
        List<Relationship> relationships,
        List<Community> communities,
        List<TextUnit> textUnits)
    {
        // 1. クエリに関連するエンティティをベクトル検索で特定
        var seedEntities = await _vectorStore.SearchAsync(
            query, topK: 5, collection: "entities");
 
        // 2. 知識グラフ上で近傍を探索
        var context = new SearchContext();
        foreach (var seed in seedEntities)
        {
            // 関連エンティティを収集
            var relatedRels = relationships
                .Where(r => r.SourceId == seed.Id || r.TargetId == seed.Id)
                .ToList();
            context.Relationships.AddRange(relatedRels);
 
            // 関連コミュニティレポートを収集
            var entity = entities.First(e => e.Id == seed.Id);
            var community = communities
                .FirstOrDefault(c => c.Id == entity.CommunityId);
            if (community != null)
                context.CommunityReports.Add(community.Report);
 
            // 関連 TextUnit を収集
            context.TextUnits.AddRange(
                textUnits.Where(tu => tu.Text.Contains(entity.Title)));
        }
 
        // 3. コンテキストを優先順位付けしてトークン予算内に収める
        var contextText = context.BuildContextString(maxTokens: 4000);
 
        // 4. LLM で回答生成
        var session = await _agent.CreateSessionAsync();
        var response = await _agent.RunAsync(
            $"""
            以下のコンテキスト情報に基づいて質問に回答してください。
            回答には可能な限り具体的な情報源を引用してください。
 
            質問: {query}
 
            コンテキスト:
            {contextText}
            """,
            session);
 
        return response.Text;
    }
}
 
public interface IVectorStore
{
    Task<List<Entity>> SearchAsync(
        string query, int topK, string collection);
}
 
public class SearchContext
{
    public List<Relationship> Relationships { get; } = [];
    public List<string> CommunityReports { get; } = [];
    public List<TextUnit> TextUnits { get; } = [];
 
    public string BuildContextString(int maxTokens)
    {
        var sb = new System.Text.StringBuilder();
 
        sb.AppendLine("=== コミュニティレポート ===");
        foreach (var report in CommunityReports.Take(3))
            sb.AppendLine(report);
 
        sb.AppendLine("\n=== 関係性 ===");
        foreach (var rel in Relationships.Take(10))
            sb.AppendLine($"- {rel.SourceId} → {rel.TargetId}: {rel.Description}");
 
        sb.AppendLine("\n=== ソーステキスト ===");
        foreach (var tu in TextUnits.Take(5))
            sb.AppendLine($"[{tu.Id}] {tu.Text[..Math.Min(200, tu.Text.Length)]}...");
 
        return sb.ToString();
    }
}

// Pipeline/GraphRAGPipeline.cs
// https://github.com/microsoft/agent-framework — ワークフローオーケストレーション
 
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
 
public class GraphRAGPipeline
{
    private readonly AIAgent _extractionAgent;
    private readonly AIAgent _summarizationAgent;
    private readonly CommunityDetector _communityDetector;
    private readonly CommunityReporter _communityReporter;
 
    public GraphRAGPipeline(string endpoint, string deploymentName)
    {
        var client = new AzureOpenAIClient(
            new Uri(endpoint),
            new DefaultAzureCredential());
 
        _extractionAgent = client
            .GetChatClient(deploymentName)
            .AsAIAgent(instructions: "エンティティと関係性を抽出する専門家エージェント");
 
        _summarizationAgent = client
            .GetChatClient(deploymentName)
            .AsAIAgent(instructions: "コミュニティレポートを生成する要約エージェント");
 
        _communityDetector = new CommunityDetector();
        _communityReporter = new CommunityReporter(_summarizationAgent);
    }
 
    /// <summary>
    /// GraphRAG インデキシングパイプラインを実行する。
    /// Phase 1〜5 を順に実行し、知識グラフインデックスを構築する。
    /// </summary>
    public async Task<KnowledgeGraphIndex> BuildIndexAsync(
        List<string> documents)
    {
        // Phase 1: TextUnit 分割
        var textUnits = ChunkDocuments(documents, chunkSize: 1200);
 
        // Phase 3: エンティティ・関係性抽出
        var (entities, relationships) =
            await ExtractGraphAsync(textUnits);
 
        // Phase 4: コミュニティ検出
        var communities = _communityDetector.DetectCommunities(
            entities, relationships);
 
        // Phase 5: コミュニティレポート生成
        for (var i = 0; i < communities.Count; i++)
        {
            var community = communities[i];
            var communityEntities = entities
                .Where(e => e.CommunityId == community.Id)
                .ToList();
            var communityRels = relationships
                .Where(r => communityEntities.Any(e => e.Id == r.SourceId))
                .ToList();
 
            var report = await _communityReporter.GenerateReportAsync(
                community, communityEntities, communityRels);
 
            // レポートを更新
            communities[i] = community with { Report = report };
        }
 
        return new KnowledgeGraphIndex(
            textUnits, entities, relationships, communities);
    }
 
    private List<TextUnit> ChunkDocuments(
        List<string> documents, int chunkSize)
    {
        var units = new List<TextUnit>();
        int unitId = 0;
        for (int docIdx = 0; docIdx < documents.Count; docIdx++)
        {
            var doc = documents[docIdx];
            // 簡易的な文字ベースのチャンキング
            // 実装では tiktoken などのトークナイザーを使う
            for (int i = 0; i < doc.Length; i += chunkSize)
            {
                var chunk = doc[i..Math.Min(i + chunkSize, doc.Length)];
                units.Add(new TextUnit(
                    $"tu-{unitId++}", chunk, $"doc-{docIdx}"));
            }
        }
        return units;
    }
 
    private async Task<(List<Entity>, List<Relationship>)>
        ExtractGraphAsync(List<TextUnit> textUnits)
    {
        var allEntities = new List<Entity>();
        var allRelationships = new List<Relationship>();
 
        foreach (var tu in textUnits)
        {
            var session = await _extractionAgent.CreateSessionAsync();
            var response = await _extractionAgent.RunAsync(
                $"""
                以下のテキストからエンティティと関係性を抽出してください。
                JSON 形式で出力してください。
 
                テキスト:
                {tu.Text}
                """,
                session);
 
            // レスポンスをパースしてエンティティ・関係性に変換
            // （実装の簡略化のため省略）
        }
 
        return (allEntities, allRelationships);
    }
}
 
public record KnowledgeGraphIndex(
    List<TextUnit> TextUnits,
    List<Entity> Entities,
    List<Relationship> Relationships,
    List<Community> Communities);

// Program.cs — 完全な使用例
 
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
var model = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
    ?? "gpt-4o";
 
// 1. インデキシングパイプラインを実行
var pipeline = new GraphRAGPipeline(endpoint, model);
var documents = new List<string>
{
    File.ReadAllText("data/document1.txt"),
    File.ReadAllText("data/document2.txt"),
};
 
var index = await pipeline.BuildIndexAsync(documents);
Console.WriteLine(
    $"Index built: {index.Entities.Count} entities, " +
    $"{index.Relationships.Count} relationships, " +
    $"{index.Communities.Count} communities");
 
// 2. Global Search — データセット全体のテーマを質問
var client = new AzureOpenAIClient(
    new Uri(endpoint), new DefaultAzureCredential());
var mapAgent = client.GetChatClient(model)
    .AsAIAgent(instructions: "情報ポイントを抽出し重要度スコアを付ける");
var reduceAgent = client.GetChatClient(model)
    .AsAIAgent(instructions: "情報ポイントを統合して包括的に回答する");
 
var globalSearch = new GlobalSearch(mapAgent, reduceAgent);
var globalAnswer = await globalSearch.SearchAsync(
    "このデータセットの主要テーマは何ですか？",
    index.Communities);
Console.WriteLine($"\n[Global Search]\n{globalAnswer}");
 
// 3. Local Search — 特定エンティティについて質問
// （IVectorStore の実装が必要）

# 自動プロンプトチューニングの実行
graphrag prompt-tune --root ./my-project

Standard GraphRAG: LLM ベースのインデキシング + 全レポートの事前生成（高コスト）
LazyGraphRAG:      NLP ベースのインデキシング、LLM 処理はすべてクエリ時に遅延実行（Microsoft Research の実験では、インデキシングコストはベクトル RAG と同等レベル、標準 GraphRAG の約 0.1% と報告）

# settings.yaml — 主要な設定パラメータ（graphrag init で生成）
completion_models:
  default_completion_model:
    model_provider: openai
    model: gpt-4o
    api_key: ${GRAPHRAG_API_KEY}
    # Azure OpenAI の場合
    # model_provider: azure
    # azure_deployment_name: your-deployment
    # api_base: https://your-resource.openai.azure.com
 
embedding_models:
  default_embedding_model:
    model_provider: openai
    model: text-embedding-3-small
    api_key: ${GRAPHRAG_API_KEY}
 
chunking:
  size: 1200          # TextUnit のチャンクサイズ（トークン数）
  overlap: 100        # チャンク間のオーバーラップ（トークン数）
 
extract_graph:
  max_gleanings: 1    # 追加抽出の回数（精度向上、コスト増）
  entity_types:       # 抽出するエンティティタイプ
    - person
    - organization
    - geo
    - event
 
community_reports:
  max_length: 2000    # レポートの最大長
 
cluster_graph:
  max_cluster_size: 10  # コミュニティの最大サイズ