SQLエージェントにビジネスルールを付与する知識層構築ガイド

問題概要

AI エージェントがデータベースに接続して「アクティブ顧客は何人？」と質問すると、ステータス列が “active” のレコード数を即座に返しますが、実際の「アクティブ顧客」は「過去90日以内に有料注文をした顧客」を意味します。このビジネスルールはデータベース内に存在せず、Wiki やダッシュボード、DBT モデル、担当者の頭の中にしかありません。そのためエージェントは正しい答えを導き出せません。

LiveSQLBench ベンチマーク

LiveSQLBench は 18 個のデータベースと 270 件の質問からなる公開ベンチマークです。各データベースはスキーマ、カラム説明、ビジネスルールという 3 つのファイルで提供され、質問文はビジネス用語で記述されています。ルールが別ファイルにあるため、エージェントはスキーマだけでは正解できません。ベンチマーク上で最高性能のシステムでも正答率は 48％に留まります。

知識層（OKF）とは

本稿では「知識層」と呼ばれるアプローチを紹介します。スキーマ、カラム説明、ビジネスルールをまとめて OKF バンドル（Markdown ファイル群）として保存し、エージェントが必要な情報だけを検索・参照できるようにします。これにより、プロンプトに全情報を詰め込むコストや、スキーマだけで推測させる誤りを回避できます。

手順概要

シリーズは 4 部構成です。

第 1 部：問題提示と最初のバンドル作成（本稿）
第 2 部：Python スクリプトで全 18 データベースから自動的に OKF バンドルを生成
第 3 部：Docker 上でベンチマークを走らせ、知識層を利用したエージェントを実装
第 4 部：スキーマのみ、全文プロンプト、知識層検索、知識層検索の 4 パターンで精度・トークン消費・コストを比較

プロジェクトセットアップ

Python 3.11 以上と Git が必要です。macOS と Windows 向けのチュートリアルに従い、プロジェクトフォルダーを作成し、data/ と bundles/ を空状態で配置します。

データ取得

LiveSQLBench の最小版「Base‑Lite」（18 データベース、270 質問）を data/ 配下にダウンロードします。各データベースは *_schema.txt、*_column_meaning_base.json、*_kb.jsonl の 3 ファイルで構成され、質問は別途 livesqlbench_data.jsonl に格納されています。

コンセプトファイル作成

例として「disaster」データベースの「Resource Utilization Ratio」質問に対応する 3 つの Markdown ファイルを作ります。

テーブル概念（bundles/disaster/tables/distributionhubs.md） – スキーマとカラム説明を統合し、テーブルの概要・生成者・ソースを FrontMatter に記載。
計算ルール概念（bundles/disaster/knowledge/resource-utilization-ratio.md） – ビジネスルール 10 の式を平易な数式で示し、使用カラムへのリンクを追加。
分類ルール概念（bundles/disaster/knowledge/resource-utilization-classification.md） – ビジネスルール 50 の分類表を掲載し、依存関係（Rule 10）への双方向リンクを設定。

インデックスファイル

エージェントが必要な情報だけを選択できるよう、フォルダーごとに index.md を作成します。

ルートインデックス（bundles/disaster/index.md） – 各サブフォルダーへのリンクと概要。
テーブルインデックス（bundles/disaster/tables/index.md） – テーブル概念の一覧。
知識インデックス（bundles/disaster/knowledge/index.md） – 計算ルールとビジネスルールのカテゴリ別一覧。

インデックスはエージェントが最初に読むメニューとなり、質問に関連する概念へ効率的に辿り着く道筋を提供します。

今後のステップ

次回は Python スクリプトで全 18 データベースから自動的に OKF バンドルを生成し、Docker 環境でベンチマークを走らせながら、知識層を活用したエージェントの実装と評価を行います。

元記事: https://dev.to/lakhan_malviya_09d3c6dbcb/build-a-knowledge-layer-for-sql-agents-with-okf-part-2-2c34