Controllable-RAG-Agent: 決定論的グラフでRAGの質問分解を制御する
This repository provides an advanced Retrieval-Augmented Generation (RAG) solution for complex question answering. It uses sophisticated graph based algorithm to handle the tasks.
ひと目でわかる
- これは何？
- 単純な類似度検索では解けない複合質問に対し、LangGraphベースの決定論的グラフで計画と実行を制御するJupyter Notebook集。READMEとリポジトリ構成から読み取れる設計と制約を整理する。
- 誰に向いている？
- 複数文書をまたぐ多段推論を、LLMの自由な計画に任せずグラフ構造で固定したいチームに向く。単発のFAQ検索で足りる用途や、低レイテンシを優先する用途には過剰で、ノートブックをそのまま本番に置く前提も現実的でない。
- 商用利用できる？
- できます。Apache-2.0 は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。直近 1 日以内に新しいコミットがあります。
- 何の言語で書かれている？
- 主に Jupyter Notebook です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
単純な類似度検索が落ちる質問をどう扱うか
このリポジトリが対象にするのは、意味的類似度による検索では答えに到達しにくい複合質問である。READMEは「complex questions that simple semantic similarity-based retrieval cannot solve」と述べ、単一の検索クエリで関連チャンクを取ってLLMに渡す方式の限界を出発点に置いている。想定読者は、自前のデータセットに対して非自明な問いを投げ、根拠をデータ内に限定したい開発者だ。READMEの表現では「non-trivial questions from your own data」となる。
特徴として挙げられているのは、決定論的グラフ、制御可能な自律エージェント、ハルシネーション防止、多段推論、適応的計画、Ragasによる性能評価の6点である。このうち実装の骨格を成すのは決定論的グラフで、READMEはこれをエージェントの「brain」と位置づける。計画の生成そのものをLLMに丸投げするのではなく、グラフのノードとして固定された手順の中にLLM呼び出しを埋め込む発想だと読める。
PDFを章に割り、要約と引用の両方をベクトル化する
READMEのHow It Worksは処理を段階的に列挙している。PDFの読み込みと章単位への分割、テキストの前処理、LLMによる章ごとの要約生成、引用が必要な質問に備えたBook Quotes Databaseの作成、そして本文と章要約をベクトルストアへエンコードする段階が並ぶ。
ここで注目したいのは、本文と要約という粒度の異なる2種類のインデックスを用意している点だ。要約は広い問いに対して文脈を圧縮して渡す役割を担い、引用データベースは「本の一節をそのまま示せ」という種類の要求に応える役割を担う。検索対象を一つに絞らず、質問の性質に応じて参照先を切り替える設計になっている。ただしREADMEの記述はこの段階までで、各ベクトルストアの具体的なバックエンドやチャンクサイズ、埋め込みモデルの指定までは示されていない。実装の細部はノートブック本体を読む必要がある。
graphs/final_graph_schema.jpegが示すノード構成
アーキテクチャの全体像はgraphs/final_graph_schema.jpegという図で示される。READMEの本文はこの図を参照するだけで、ノード名やエッジの条件を文章では列挙していない。したがって、どのノードが計画立案を担い、どのノードが検索結果の妥当性を判定し、どの条件でループが継続または終了するのかは、図とノートブックを開いて確認するほかない。
リポジトリのトピックにlanggraphとlangchainが含まれることから、グラフの実行基盤はLangGraphであると推測できる。状態を持つノードを明示的に接続するLangGraphのモデルは、「適応的計画」と「多段推論」というREADMEの主張と整合する。計画を一度作って終わりにせず、得られた情報に応じて次の一手を更新する挙動を、グラフの分岐として表現しているという読み方だ。ただしこれはトピックと図からの推論であり、READMEがノードの動作を明文化しているわけではない。採用判断の前に図を実際に開くべき箇所である。
動かすまでに読むべきファイルと設定
主言語はJupyter Notebookで、リポジトリの中心はノートブック群である。READMEにはインストール手順、requirements.txtの内容、環境変数のキー名、CLIコマンドのいずれも記載されていない。トピックにopenaiが含まれるためOpenAI系のAPIキーが必要と見られるが、変数名がOPENAI_API_KEYなのか別名なのかは与えられた材料からは確定できない。
確実に言えるのは、ノートブックを上から順に実行し、データ投入からグラフ実行、評価までを一つの流れとして体験する形式だという点だ。評価にはRagasメトリクスを使うとREADMEが明記している。設定値を外部ファイルで管理する構成なのか、ノートブック内のセルに直接書く構成なのかも判別できない。パッケージ名や依存バージョンを知りたい場合は、ノートブック内のインストールセルを読むのが最短になる。ここはドキュメントとして薄い部分であり、そのまま本番構成に移すには不足がある。
ハルシネーション防止の主張と、その裏にある制約
READMEはハルシネーション防止を主要な特徴として挙げ、「Ensures answers are solely based on provided data」と書く。回答の根拠を投入したデータに限定するという主張である。ただしこの種の保証は、検索が正しいチャンクを返し、要約段階で情報が失われていないことを前提にする。章単位の要約を経由する構成では、要約時に落ちた細部は後段の推論から参照できない。
もう一つの制約は決定論的グラフという設計自体にある。ノードの並びが固定されているということは、想定外の質問パターンに対しては、LLMの判断で経路を動的に組み替える仕組みよりも適応力が低くなる。READMEは「Adaptive Planning」も挙げているため、グラフ内に計画更新の余地はあると読めるが、その適応はあくまでグラフが許容する範囲に収まる。自由形式の調査タスクや、事前に構造化できない探索的な問いには向かない。
代替となるアプローチとの違い
同じ著者によるRAG_Techniquesリポジトリは、多数のRAG技法を個別に解説する構成をとる。Controllable-RAG-Agentが複合質問を解くための一つの完成形としてグラフを組み上げているのに対し、RAG_Techniquesは検索、再ランク、チャンク設計といった部品を比較検討するためのカタログである。どちらを読むかは、既に方針が決まっていて実装パターンが欲しいのか、技法そのものを選定したいのかで変わる。
エージェント実装の選択肢としては、LangGraphのグラフを自分で設計し、検索ツールをノードに接続する素朴な構成も考えられる。このリポジトリとの差は、PDFの章分割から要約、引用データベース、ベクトルストア、Ragas評価までの流れが一つの参照実装として通しで示されている点にある。逆に言えば、既に自前のインジェスト経路と評価基盤を持っているチームにとっては、グラフ構造の部分だけを抜き出して読む方が効率がよい。
ライセンスと保守の見通し
ライセンスはApache-2.0で、リポジトリはアーカイブされておらず、最終更新は2026年9月9日である。Apache-2.0は商用利用を含む利用と改変を許容し、特許条項と変更表示の義務を伴う。ノートブックを自社製品に組み込む場合、著作権表示とライセンス文の保持が必要になる。具体的な条項の解釈は法務の領域であり、ここでは踏み込まない。
保守コストの観点で材料から言えるのは限られる。リリースタグは取得されておらず、バージョン番号に基づく依存固定の指針は示されていない。READMEの相当部分が著者の書籍、コース、ニュースレターへの案内に割かれており、APIリファレンスや変更履歴の類は見当たらない。結果として、依存ライブラリの破壊的変更が入った場合に、どの版へ固定すべきかをリポジトリ側の情報だけでは判断しにくい。ノートブックを出発点に使い、依存は自前で固定する前提で临むのが現実的である。
編集部の結論
複数文書をまたぐ多段推論を、LLMの自由な計画に任せずグラフ構造で固定したいチームに向く。単発のFAQ検索で足りる用途や、低レイテンシを優先する用途には過剰で、ノートブックをそのまま本番に置く前提も現実的でない。導入前に確認すべきは、graphs/final_graph_schema.jpegのノード構成が自データの質問パターンに写せるか、Ragas評価を回すための正解データを用意できるか、そしてOpenAI依存の呼び出し回数とコストを許容できるかである。
コミュニティノート