コードをKG化する7ステップと6ツール比較

「Knowledge Graph実践ガイド」の第4章と第9章を書いていて、私は同じ落とし穴に3回落ちました。第4章はNeo4j公式の7ステップでナレッジグラフ構築を整理する章、第9章はコードKGツール6本を並べて比較する章です。別々に書いていると、7ステップの絵は綺麗に描けます。ところがコードKGツールの側から逆に眺めた瞬間、7ステップのStep 3・Step 5・Step 7に見えない段差が残っているのに気づきました。

この記事は、その両章を書きながら私が気づいた3つの段差と、6つのツールがそれぞれ7ステップのどこを埋めているかの当てはめノートです。実装ノートではありません。私が本を書きながら本の中で行き止まったポイントを、読者に先に地図として渡す種類のメモです。

7ステップの骨格 — Neo4j公式版をそのまま書き写す

第4章では、Neo4j公式ドキュメントの構築フレームワークを次の7ステップで整理しています。

この整理は間違っていません。私が書いた第4章のまとめもこの表と同じ形をしています。問題は、コードをKG化する側から見ると、この7ステップに書いていない工程が3箇所あることです。書いた本人がそう言うのだから間違いないと思っています。

段差1: Step 3の設計図を書く前に、AST抽出の粒度が刺さる

Step 3「オントロジー/スキーマ設計」は、ノードラベルとエッジタイプを紙に描く工程です。第4章では Service API Developer Repository みたいな綺麗なラベルで例示しています。

ところがコードKGの世界では、この設計図を描く前にAST抽出器がどこまで細かく取れるかが先に決まっています。Tree-sitterで関数呼び出しを抽出するとき、CALLS を「クラス.メソッド」で1本立てるか、「モジュール.関数」で立てるか、「引数の型解決込み」で立てるかは、抽出器の設定側で決まる話です。

第8章では、Tree-sitterを19以上のプログラミング言語に対応するASTパーサとして紹介しています。「19以上」と幅を持たせているのは、Tree-sitter本体は多数の言語文法を公式・コミュニティで抱えていて、実装側がそのうちどれをバインドするかで対応言語数が変わるためです。第9章のツール比較表を見ると、実装側で選ばれる言語数は10〜19に絞られています。設計図の粒度は、抽出器がその言語で何を取れるかに強く縛られる、というのはここに現れる縛りです。

つまり、Step 3の紙で描いた美しい CALLS エッジは、Step 5の抽出フェーズで「該当ツールがこの言語で動的呼び出しを取れるか」で一度砕かれます。第4章の例では EXPOSES: Service -> API みたいな粒度で書けますが、コードKGでは Tree-sitter の対応言語ごとにこのラベルの実体が変わります。

参考: 静的解析ベースの抽出がどこまで漏らすかは、静的解析コードKGが落とす61%の動的呼び出し で ISSTA 2024 の実測を追いました。動的呼び出しの取りこぼしは、Step 3で書けない現実の代表例です。

段差2: Step 5でLLM抽出に飛びつくと、Step 3に戻ってくる

Step 5「データの取り込み・変換」で、非構造化データからLLMで抽出する例が第4章に載っています。テキストからエンティティと関係をJSONで返してもらう、あのパターンです。

コードKGでも同じことをやりたくなります。README・docstring・コミットメッセージから設計意図を抽出できれば、Step 3の設計図が事後的に補強されるからです。第8章で紹介した2パス処理(Pass 1: ローカルAST / Pass 2: LLMセマンティック)はまさにこの形です。

私が第9章のツール比較で気になったのは、Graphify が エッジ分類 EXTRACTED / INFERRED / AMBIGUOUS と信頼度スコアをエッジ属性として持っている点でした。「LLMが推測したエッジ」と「ASTから確定したエッジ」を混ぜず、属性で区別する設計です。これがない Step 5 実装は、機械的な事実とLLMの推測を同じノードグラフに入れてしまい、Step 6のクエリ側で「どのエッジを信じてよいか」の話に戻ります。

7ステップは「確からしさの層」を分けていません。私が第4章を書いていたときの油断はここでした。LLM抽出の便利さで濁ったエッジと、AST由来の確定エッジは、Step 3の設計図に「信頼度」プロパティを持つ話として最初から書いておかないと、後から泣きます。 第9章を書き終わってから第4章に戻って追記したのはこの段落だった、と正直に告白しておきます。

Microsoft GraphRAG や LightRAG、HippoRAG 2 のような直近の実装も、抽出フェーズの品質チューニングに大半のドキュメントを割いています。エンティティ抽出の粒度合わせは、graphrag prompt-tune のような Auto Tuning が公式に用意されるくらい、一発では収束しません。「Step 5で初めてStep 3の設計不足に気づく」のが、7ステップに書かれていない周回の姿です。

段差3: Step 7の「運用」に、コミット履歴の時間軸が入っていない

Step 7「運用と拡張」は、鮮度管理・品質監視・スキーマ進化・アクセス制御の4項目で整理されています。この4項目、いずれも一般的な情報グラフの運用としては十分です。

コードKGでは、ここに5つ目の軸「履歴」が乗ります。ソースコードは日々変わります。「昨日は動いていた payment.py:refund の呼び出し先が、今日は消えている」を扱わないと、コードKGのクエリは即座に嘘になります。第9章のツール比較で CodeLayers が「ファイル保存時に150msデバウンスで自動再解析」を強みに挙げているのは、この時間軸の話です。

第9章で紹介した6ツールのうち、再解析の設計が読み取れる5つをこの軸で並べ直すと、扱いがはっきり分かれます。

• リアルタイム再解析派: CodeLayers(VS Code、ファイル保存トリガー)、CodeGraphContext(ディレクトリ監視)
• オンデマンド再解析派: GitNexus(コマンド発火)、code-review-graph(PR差分ベース)
• バッチ再解析派: Graphify(2パス手動)

Step 7の「鮮度管理」は、この3層のどれを採るかを決めるステップとして読み直すべきでした。7ステップの表には収まりきらない工程です。第4章では紙面の都合で1行に押し込みましたが、実装するなら独立した設計判断です。

6ツールを7ステップに当ててみる

第9章で並べた6ツールを、7ステップのどこを主に埋めているかで当てはめると次のようになります。

「7ステップのどこを埋めているか」の列を足しただけで、選び方の解像度が変わります。Step 3の設計を強くやりたいなら Graphify のエッジ分類、Step 7の運用まで一気に含めたいなら CodeGraphContext か Understand Anything に寄ります。ここが第9章の比較表に足りなかった1列でした。

ベクトルRAGとの対比は1段落だけ

コードに対して、なぜベクトルRAGではなくKGが向くのか。1段落だけ書きます。ベクトルRAGは「意味が似た断片」を返しますが、コードで欲しいのは「この関数を変更したら壊れるのはどこか」であって、意味の類似ではなく構造の到達可能性です。関数呼び出しは推移的に辿れる関係で、KGで MATCH path = ... を書ける形の問いです。ベクトル検索でこの問いに答えると、埋め込みが近いだけで実は呼び出されていない場所が混ざります。ここが分岐点であって、優劣ではありません。

深追いは他の記事に譲ります。GraphRAGを選んだあとのRDFかプロパティグラフかの分岐は GraphRAGはRDFかプロパティグラフか3問 に、企業導入時の分岐は GraphRAG企業導入で詰まる3つの壁 にそれぞれ分けて書きました。

まとめ

第4章の7ステップは、コードKG構築の骨格として正確です。ただ、第9章のツール6本を並べ直しながら第4章を読み返すと、7ステップの表に収まりきらない3つの段差が残ります。

• 段差1: Step 3の設計図が、AST抽出器の粒度に縛られる
• 段差2: Step 5のLLM抽出が、Step 3に信頼度プロパティを追加させる
• 段差3: Step 7の「運用」に、履歴・再解析の時間軸が抜けている

書いていて、私は第4章の表を7列で描いた自分に、あとから8列目・9列目を書き足す作業を繰り返しました。書籍の紙面の都合ではありますが、実装に踏み出す読者はこの追加列を最初から意識するほうが楽です。7ステップを飛ばして手を動かすのではなく、7ステップの間と外側にある段差を先に見ておく話です。

コードKGの7ステップと6ツールの詳細比較、それぞれのツールが本番で何をどう扱うかの内訳は、Knowledge Graph実践ガイド の第4章・第8章・第9章に収録しています。