Vanna.aiでText-to-SQLツールを構築する：自然言語でデータと対話する

Table of Contents

SQLのボトルネックを解消する

私は長年、優秀なデータチームが単純で繰り返しの多いリクエストに忙殺される様子を見てきました。これは典型的な摩擦点です。マーケティングマネージャーが「先月ベルリンで最も電子機器に支出した上位15人の顧客は誰か？」を知りたいと思っても、彼らはJOINとGROUP BYの違いすら知りません。その結果、チケットの山が築かれ、ステークホルダーは5分で済むクエリのために3日間も待たされることになります。

GPT-4のような汎用LLMは印象的ですが、複雑な実世界のスキーマでは躓いてしまいます。彼らは、user_idが請求テーブルのlegacy_idに対応していることや、「アクティブ」が直近14日以内のログインを意味することを理解していません。

ここでVanna.aiが状況を変えます。AIにプロンプトを投げるだけでなく、VannaはSQL専用に構築されたRAG（検索拡張生成）フレームワークを使用します。実際のスキーマ定義や過去の成功したクエリを検索し、AIに正確な回答に必要なコンテキストを提供します。

最近の中規模ECプラットフォームのプロジェクトでは、この構成を導入したところ、第1四半期に手動のレポーティングリクエストが58%減少しました。ここでは、そのシステムの設計図と、構築過程で得られた教訓を紹介します。

環境のセットアップ

Vannaは非常にモジュール化されています。10分程度のプロトタイプにはホスト型ティアを使用でき、厳格なデータプライバシーが必要な場合は完全なローカル環境にすることも可能です。プロフェッショナルな業務では、クリーンで再現性の高いバランスの取れたセットアップをお勧めします。

まずは専用の仮想環境から始めましょう。最新の非同期LLMラッパーをスムーズに扱うために、Python 3.10以降を推奨します。

# 標準的な環境セットアップ
python -m venv vanna-env
source vanna-env/bin/activate  # Windowsの場合: `vanna-env\Scripts\activate`

# コア依存関係のインストール
pip install vanna pandas
# ドライバーを選択: sqlite3, psycopg2-binary, または pymysql
pip install sqlite3

注意点として、VannaにはLLMプロバイダーごとに特定の拡張機能があります。Claude 3.5やGPT-4oを使用する場合は, ランタイムのインポートエラーを避けるために、ドキュメントに記載されている対応するパッケージ拡張機能を必ずインストールしてください。

エンジンルーム：AIのトレーニング

Vannaにおける主要な処理は、LLMではなくベクトルデータベース内で行われます。ここにDDL（データ定義言語）、ビジネスドキュメント、そして私が「ゴールデンSQL」と呼んでいる、100%正しいことが分かっているクエリを保存します。ユーザーが質問すると、Vannaはこれらのスニペットを取得して正確なプロンプトを作成します。

接続の初期化

このチュートリアルでは、デフォルトのVannaラッパーを使用します。エンタープライズ環境であれば、VannaDefaultをChromaDBや独自のAnthropicまたはOpenAI APIキーを使用するカスタムクラスに置き換えることになります。

import vanna as vn
from vanna.remote import VannaDefault

# vanna.ai/account からキーを取得してください
vn = VannaDefault(model='itfromzero-demo-v1', api_key='your_vanna_api_key')

# データソースに接続
vn.connect_to_sqlite('ecommerce_data.db')

高品質なメタデータの投入

精度は偶然生まれるものではありません。それは以下の3つのトレーニングレイヤーの成果です：

スケルトン (DDL): テーブル構造を定義します。
辞書 (ドキュメント): ビジネス定義を記述します。
例 (SQLサンプル): 最も重要なレイヤーです。複雑なロジックをどのように処理すべきかをAIに示します。

# 1. 構造を教える
vn.train(ddl="""
CREATE TABLE subscriptions (
    id UUID PRIMARY KEY,
    user_id UUID,
    monthly_price DECIMAL(12, 2),
    tier TEXT,
    is_active BOOLEAN
)
""")

# 2. 「人間」のコンテキストを追加する
vn.train(documentation="'tier'は 'Basic', 'Pro', または 'Enterprise' のいずれかです。アクティブユーザーは is_active=True である必要があります。")

# 3. ゴールデンSQLを提供する
vn.train(question="Proユーザーからの月次経常収益（MRR）はいくらですか？", 
         sql="SELECT SUM(monthly_price) FROM subscriptions WHERE tier = 'Pro' AND is_active = True")

手動入力の代わりに、毎週、使用頻度の高い上位20件のプロダクションクエリを取得してVannaにフィードバックするスクリプトを実行することをお勧めします。これにより、ビジネスロジックの進化に合わせてシステムが改善されるループが生まれます。

セキュリティとガードレール

AIにデータベース接続を渡すことには、本質的なリスクが伴います。決して管理者アカウントを使用しないでください。ビジネスチームが実際に必要とするテーブルにのみアクセスできる読み取り専用ユーザーを作成してください。AIにpassword_hashesやssn_numbersを見せたくない場合は、データベースユーザーからそれらのカラムを隠してください。

ハルシネーション（幻覚）は起こります。AIが存在しないtotal_profitカラムを捏造するかもしれません。このような場合は、プロンプトと戦うのではなく、トレーニングを修正してください。通常、それはドキュメントの一部やDDL定義が不足していることを意味します。

# 「暴走」クエリを防ぐためのシンプルなラッパー
def execute_safely(user_query):
    generated_sql = vn.generate_sql(user_query)
    
    # 基本的なセーフティチェック
    if not generated_sql.strip().upper().startswith("SELECT"):
        return "エラー: SELECTクエリのみが許可されています。"
        
    # 結果セットにハードリミットを適用
    if "LIMIT" not in generated_sql.upper():
        generated_sql += " LIMIT 50"
        
    return vn.run_sql(generated_sql)

最後に

Text-to-SQLを成功させることは、一度設定して終わりではなく、庭を手入れするようなものです。データベースの命名規則に一貫性がないと、AIは苦労します。しかし、Vanna.aiは、大規模なRAGパイプラインをゼロから構築することなく、その複雑さを管理するための最適なフレームワークを提供してくれます。

まずはスモールスタートしましょう。営業やマーケティングなど一つの部署を選び、シンプルなFlaskインターフェース（vanna.flask.VannaAdmin）へのアクセスを提供します。彼らのフィードバックからドキュメントの弱点がすぐに見つかり、真のセルフサービス型のデータ文化に向けて改善を繰り返すことができるようになります。