このドキュメントでは、データ エージェント アプリケーションの構築で QueryData の精度を高めることができるコンテキストを作成して最適化する方法について説明します。Gemini CLI の DB コンテキスト拡充拡張機能を使用すると、コンテキスト セットの作成と最適化を自動化する一連のデベロッパー ツールにアクセスできます。
コンテキスト セットの詳細については、コンテキスト セットの概要をご覧ください。この拡張機能は、次の順序でコンテキスト セットの作成と最適化を自動化します。
- アプリケーションを理解する: データベース スキーマ、アプリケーション コード、ビジネス要件などのアーティファクトを取り込んで、データ エージェントの基本的なビジネス ロジックを確立します。
- データセットを作成する: 代表的な自然言語の質問と想定される SQL の回答を含む評価データセットをキュレートします。このベースライン データセットを確立することは、パフォーマンスを測定し、時間の経過に伴う改善を追跡するために不可欠です。
- 初期コンテキストを生成する: データベース スキーマとオプションのアプリケーション アーティファクトから直接導出されたベースライン コンテキスト セットを自動的に生成して、クイック スタートとして使用します。
- コンテキストを反復的に最適化する: データセットを評価して、特定のクエリが失敗する理由を特定します。Gemini は自動推論を使用して、ターゲット コンテキストの更新を提案し、精度を繰り返し高めます。
この拡張機能は堅牢な自動ワークフローを提供しますが、ニーズに合わせて調整することもできます。自動化をバイパスして、より詳細なレベルでコンテキストを作成して挿入できます。専用の生成コマンドを使用して、高品質のテンプレート、ファセット、値検索クエリの作成を制御します。
始める前に
エージェントを作成する前に、次の前提条件を満たす必要があります。
必要なサービスを有効にする
プロジェクトで次のサービスを有効にします。AlloyDB for PostgreSQL クラスタ、インスタンス、データベースを準備する
既存の AlloyDB クラスタとインスタンスにアクセスできることを確認するか、新しいクラスタとインスタンスを作成します。このチュートリアルでは、AlloyDB インスタンスにデータベースが必要です。詳細については、データベースを作成するをご覧ください。
必要なロールと権限
- データベース レベルで Identity and Access Management（IAM）ユーザーまたはサービス アカウントをクラスタに追加します。詳細については、データベース ユーザーを管理するをご覧ください。
- プロジェクト レベルで IAM ユーザーに
alloydb.databaseUser、serviceusage.serviceUsageConsumer、geminidataanalytics.queryDataUserのロールを付与します。詳細については、プロジェクトの IAM ポリシー バインディングを追加するをご覧ください。
AlloyDB for PostgreSQL インスタンスに executesql 権限を付与する
AlloyDB for PostgreSQL インスタンスに executesql 権限を付与し、data_api_access インスタンス設定を値 ALLOW_DATA_API に設定するには、次の curl コマンドを使用します。
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://alloydb.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=dataApiAccess \
-d '{
"dataApiAccess": "ENABLED",
}'
PROJECT_ID: 実際の Google Cloud プロジェクト ID。LOCATION: AlloyDB クラスタが配置されているリージョン。CLUSTER_ID: AlloyDB クラスタの ID。INSTANCE_ID: AlloyDB インスタンスの ID。
環境を準備する
コンテキスト セット ファイルは、任意のローカル開発環境または IDE から作成できます。環境を準備するには、次の手順を行います。
- Gemini CLI をインストールする
- DB コンテキスト拡充拡張機能をインストールする
- データベース接続を設定する
Gemini CLI をインストールする
Gemini CLI をインストールするには、Gemini CLI の使用を開始するをご覧ください。
DB コンテキスト拡充拡張機能をインストールする
DB コンテキスト拡充拡張機能により、構造化されたコンテキスト セットを生成して反復処理するためのインタラクティブなガイド付きワークフローが提供されます。
DB コンテキスト拡充拡張機能をインストールする方法の詳細については、DB コンテキスト拡充拡張機能をご覧ください。
DB コンテキスト拡充拡張機能をインストールする手順は次のとおりです。
DB コンテキスト拡充 Gemini CLI 拡張機能をインストールします。
gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment（省略可）DB コンテキスト拡充拡張機能を更新します。
インストールされている拡張機能のバージョンを確認するには、次のコマンドを実行します。
gemini extensions listバージョンが
0.5.0以降であることを確認します。DB コンテキスト拡充拡張機能を更新するには、次のコマンドを実行します。gemini extensions update mcp-db-context-enrichmentDB コンテキスト拡充拡張機能を更新するか、
GEMINI_API_KEYを置き換えるには、次のコマンドを実行します。gemini extensions config mcp-db-context-enrichment GEMINI_API_KEYGEMINI_API_KEY は、実際の Gemini API キーに置き換えます。
データベース接続を設定する
この拡張機能では、スキーマを取得するためのデータベース接続と、生成された SQL コンテキストの構文を検証する機能が必要です。拡張機能がデータベースを操作できるようにするには、認証情報を構成し、データベース接続構成を定義します。
アプリケーションのデフォルト認証情報を構成する
アプリケーションのデフォルト認証情報（ADC）を構成して、次の 2 つのメイン コンポーネントにユーザー認証情報を提供します。
- Toolbox MCP サーバー: 認証情報を使用してデータベースに接続し、スキーマを取得して、検証用の SQL を実行します。
- DB コンテキスト拡充拡張機能: 認証に認証情報を使用して Gemini API を呼び出します。
ターミナルで次のコマンドを実行して認証します。
gcloud auth application-default loginデータベース接続ファイルを構成する
この拡張機能では、コンテキスト生成にデータベース接続が必要です。これは、MCP ツールボックスがサポートしており、構成ファイル内で定義されています。
構成ファイルには、データベース ソースと、スキーマの取得または SQL の実行に必要なツールが指定されています。DB コンテキスト拡充拡張機能には、構成の生成に役立つエージェント スキルがプリインストールされています。
Gemini CLI を起動します。
geminiGemini CLI に次のコマンドを入力して、スキルが有効になっていることを確認します。
/skillsプロンプトを入力します（例:
help me set up the database connection）。このスキルでは、現在の作業ディレクトリにautoctx/tools.yamlとして構成ファイルを作成する手順を説明します。Gemini CLI で次のコマンドを実行して、
tools.yaml構成を Toolbox MCP サーバーに適用します。/mcp reload
データベース構成ファイルを手動で構成する方法については、MCP ツールボックスの構成をご覧ください。
自動化されたワークフローでコンテキストを生成する
コンテキスト エンジニアリングによる精度向上は、通常、手動による試行錯誤のプロセスです。デベロッパーは、クエリが失敗した理由を推測し、修正を記述して手動でテストすることがよくあります。Gemini CLI の DB コンテキスト拡充拡張機能は、この改善プロセスを自動化します。評価データセット（正しい SQL の回答を含む一連の質問）を使用して、パフォーマンスを測定し、特定のクエリが失敗する理由を特定します。Gemini は、精度を高めるために特定のコンテキストの更新を自動的に提案します。次の手順を完了して、データ エージェントの精度を体系的に向上させます。
ワークスペースを初期化する
初期化コマンドは、データベース接続構成やテスト ディレクトリなど、ローカル ワークスペースを設定します。この専用ワークスペースにより、すべての構成、テスト、生成されたファイルが 1 か所に整理されるため、コンテキストの最適化の取り組みを簡単に管理、追跡できます。
- 反復最適化フローのワークスペースとして機能する新しいディレクトリを作成し、そのディレクトリに移動します。
新しいディレクトリで Gemini CLI を起動します。
gemini初期化コマンドを実行します。
/autoctx:initデータベース接続が設定されていない場合、エージェントは
tools.yamlファイルの作成をガイドします。また、ローカルのstate.mdファイルとexperimentsディレクトリを初期化します。初期化後、ワークスペースは次のようになります。
my-workspace/ └── autoctx/ ├── tools.yaml # Database connection and tools configuration ├── state.md # Local file to track the experiment progress └── experiments/ # Dedicated directory for future experiment-specific files
データセットを準備して拡張する
Gemini がコンテキスト セットで最適化を体系的に実行できるようにするには、コンテキスト セットを評価するための代表的な自然言語の質問とその想定される SQL 回答（「ゴールデン」）の評価データセットを準備します。高品質の評価データセットは、パフォーマンスの測定、クエリの失敗の特定、経時的な改善の追跡に不可欠です。データセットは、データ アプリケーションの対象となるユースケースをカバーする自然言語クエリ（NLQ）とゴールデン SQL を含む JSON ファイルである必要があります。
正しい形式の例を次に示します。
[
{
"id": "example_001",
"nlq": "What is the total revenue for the top 5 products?",
"golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
}
]
Gemini CLI 拡張機能には、評価用に質問の小さなベースラインを作成してスケーリングするコマンドが含まれています。
- ワークスペース フォルダに移動します。
新しいディレクトリで Gemini CLI を起動します。
geminiGemini CLI で
/autoctx:generate-datasetコマンドを実行します。/autoctx:generate-datasetエージェントからプロンプトが表示されたら、シードを指定します。シードは、より大きなデータセットの生成をガイドする最初の例または小さな例のセットです。シードは次のいずれかになります。
- 小さなゴールデン データセット ファイル
- 自然言語から SQL への変換（NL2SQL）の特定のゴールデン ペア
たとえば、次の NL2SQL ゴールデン ペアをシードとして指定できます。
Question: "What are the names of all airports in California?" SQL: "SELECT name FROM airports WHERE state = 'CA';"エージェントは、
execute_sqlツールを使用して構文と実行の有効性を確認する権限を求めます。この手順は省略可能です。エージェントは、シードデータからバリエーションを使用してデータセットを拡張するかどうかを尋ねます（さまざまなフィルタや同義語などを適用します）。この手順は省略可能です。
エージェントは
execute_sqlツールを使用して、新しく生成された SQL クエリをデータベースに対して実行し、構文と実行の有効性を検証してから、ユーザーに提示します。提案を個別に承認、編集、または拒否します。承認されたペアは自動的にローカルに保存され、評価の準備が整います。
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json # Generated dataset └── experiments/
初期コンテキスト セットを作成する
初期コンテキスト セットを生成すると、評価と反復的な改善のベースラインが提供されます。このステップでは、データベース スキーマとアプリケーション アーティファクトを使用して、ビジネス ロジックを反映した基本的なコンテキストを作成します。
Gemini CLI 拡張機能には、データベース スキーマとデータ エージェント アプリケーションに関する情報（アプリケーション コードやビジネス要件に関する情報を含むファイルなど）に基づいて、テンプレートとファセットの初期セットを生成する事前構築済みのコマンドが含まれています。ベースライン コンテキスト セットをゼロから生成するには:
- ワークスペース フォルダに移動します。
新しいディレクトリで Gemini CLI を起動します。
geminiGemini CLI で
/autoctx:bootstrapコマンドを実行します。/autoctx:bootstrap通常、エージェントは次のことを行います。
エージェントからテスト名の指定を求められます。テストは、データベース コンテキスト構成の完全なライフサイクルをカプセル化し、ベースライン状態、評価テストの結果、後続の反復的なヒルクライミングの改善を追跡する専用のワークスペース フォルダです。この名前は、ワークスペースの試験運用フォルダに生成されたすべてのファイルを整理するために使用されます。わかりやすく覚えやすい名前を選択してください。
エージェントは、ターゲット データベースからスキーマを取得して一覧表示し、必要に応じて追加のリソースまたはファイルを提供するよう求めます。スキーマが複雑な場合は、初期コンテキスト セットの特定のスキーマまたはテーブルを選択するように求めるメッセージも表示されます。指定しない場合、現在のデータベース スキーマで使用可能なすべてのテーブルが対象となります。
生成されたコンテキスト セットを確認し、必要に応じて調整します。エージェントは、調整が完了すると、ワークスペース フォルダのローカル ディスクに JSON コンテキスト ファイルを直接生成します。
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md └── experiments/ └── my-experiment/ └── bootstrap_context.json # The generated initial context set file手順に沿って、AlloyDB Studio からコンテキストをアップロードします。
コンテキストの有効性を評価する
Gemini CLI 拡張機能には、ゴールデン データセットを使用してデータ エージェントを評価するための組み込みコマンドが含まれています。この拡張機能は Evalbench と統合され、ゴールデン セットで指定された質問を使用してエージェントの QueryData API をクエリし、生成された SQL とその実行結果をゴールデン SQL と比較することで評価を実行します。評価は、現在のコンテキスト セットの有効性を理解するうえで重要です。生成された SQL をゴールデン データセットと比較することで、失敗している特定のクエリを特定し、コンテキストの改善が必要な領域を特定できます。
現在のコンテキストの有効性をゴールデン データセットと比較するには:
- AlloyDB Studio からターゲット コンテキスト セットにコンテキストをアップロードして評価します。評価するコンテキストがアップロードされていない場合、この手順は省略可能です。
- ワークスペース フォルダに移動します。
フォルダで Gemini CLI を起動します。
geminiGemini CLI で
/autoctx:evaluateコマンドを実行します。/autoctx:evaluateゴールデン データセットのパス、評価構成の生成と評価実行のコンテキスト セット ID、指定された出力ディレクトリを指定します。
完了すると、エージェントはテストフォルダに評価結果をファイルとして生成し、評価結果を要約します。
必要に応じて、詳細な評価レポートから評価を手動で検査できます。このレポートは、実験フォルダに CSV ファイルとして保存されます。
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json └── experiments/ └── my-experiment/ └── bootstrap_context.json └── eval_configs/ └── <configs_for_eval_run>/ └── eval_reports/ └── <eval_id>/ └── eval_report/ ├── configs.csv ├── evals.csv ├── scores.csv └── summary.csv
ギャップ分析とコンテキストの最適化を行う
コンテキスト セットを最適化するうえで重要なステップとして、Gemini CLI 拡張機能には、既存のコンテキスト セットに対してギャップ分析を実行し、品質を向上させるための変更を提案する組み込みコマンドが含まれています。ギャップ分析は、特定のクエリが失敗する理由と、コンテキストを改善できる場所を理解するために不可欠です。この分析に基づいて、Gemini は自動推論を使用して、これらのエラーに対処し、クエリの精度を繰り返し改善するための、新しいテンプレートやファセットなどのターゲット コンテキストの更新を提案します。
- ワークスペース フォルダに移動します。
フォルダで Gemini CLI を起動します。
geminiGemini CLI で
/autoctx:hillclimbコマンドを実行します。/autoctx:hillclimbエージェントは、ヒルクライミングに最適な評価結果とベース コンテキストを自動的に特定し、複数のオプションがある場合は確認を求めます。
評価結果がない場合、エージェントはデータセットとコンテキストが設定された評価実行を求めるプロンプトを表示します。
準備ができたら、エージェントは評価結果と既存のコンテキスト セットを読み取り、ギャップ分析レポートを生成します。
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json └── experiments/ └── my-experiment/ └── bootstrap_context.json └── eval_configs/ └── eval_reports/ └── hillclimb/ └── gap_analysis_v1.mdエージェントは、新しい規範的テンプレートとファセットを提案し、必要に応じて
execute_sqlを介して DB に対して SQL をテストすることで、修正を策定します。準備が整うと、新しい改善されたコンテキスト JSON ファイルがローカルで生成され、ベースライン コンテキスト JSON ファイルはそのまま残ります。
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json └── experiments/ └── my-experiment/ └── bootstrap_context.json └── eval_configs/ └── eval_reports/ └── hillclimb/ ├── gap_analysis_v1.md └── improved_context_v1.md手順に沿って、AlloyDB Studio からターゲット コンテキスト セットにコンテキストをアップロードし、評価から始まる次のイテレーションの準備をします。
制限事項
自動ワークフローは、テンプレートとファセットの生成と最適化のみをサポートしています。データ エージェントの値検索を構成する場合は、値検索クエリを生成するをご覧ください。
ターゲットを絞ったコンテキストを生成する
コンテキストの作成をよりカスタマイズしたい場合は、DB Context Enrichment 拡張機能を使用して、特定のコンテキスト要素を手動で生成できます。次のコマンドは、JSON ファイルとしてコンテキストを作成する手順を示しています。これにより、テンプレート、ファセット、値の検索クエリの生成をきめ細かく制御できます。
ターゲットを絞ったテンプレートを生成する
特定のクエリと SQL のペアをクエリ テンプレートとしてコンテキスト セットに追加するには、/generate_targeted_templates コマンドを使用します。
コンテキスト セット ファイルとクエリ テンプレートの詳細については、コンテキスト セットの概要をご覧ください。
クエリ テンプレートをコンテキスト セットに追加する手順は次のとおりです。
Gemini CLI で
/generate_targeted_templatesコマンドを実行します。/generate_targeted_templatesクエリ テンプレートに追加する自然言語クエリを入力します。
対応する SQL クエリをクエリ テンプレートに入力します。
生成されたクエリ テンプレートを確認します。クエリ テンプレートは、コンテキスト セット ファイルとして保存することも、既存のコンテキスト セット ファイルに追加することもできます。
コンテキスト セット ファイル（my-cluster-psc-primary_postgres_context_set_20251104111122.json など）が、コマンドを実行したディレクトリに保存されます。
ターゲットを絞ったファセットを生成する
特定のクエリを SQL 条件としてコンテキスト セット ファイルにファセットとして追加するには、/generate_targeted_facets コマンドを使用します。
コンテキスト セット ファイルとファセットの詳細については、コンテキスト セットの概要をご覧ください。
コンテキスト セット ファイルにファセットを追加する手順は次のとおりです。
Gemini CLI で
/generate_targeted_facetsコマンドを実行します。/generate_targeted_facetsファセットに追加する自然言語インテントを入力します。
対応する SQL スニペットをファセットに入力します。
生成されたファセットを確認します。ファセットは、コンテキスト セット ファイルとして保存することも、既存のコンテキスト セット ファイルに追加することもできます。
コンテキスト セット ファイル（my-cluster-psc-primary_postgres_context_set_20251104111122.json など）が、コマンドを実行したディレクトリに保存されます。
値検索クエリを生成する
コンセプト タイプ内の特定の値の検索と照合方法を指定する値検索を生成するには、/generate_targeted_value_searches コマンドを使用します。
値インデックスの詳細については、コンテキスト セットの概要をご覧ください。
値インデックスを生成する手順は次のとおりです。
/generate_targeted_value_searchesコマンドを実行します。/generate_targeted_value_searches「
postgresql」と入力して、データベース エンジンとして AlloyDB を選択します。使用する PostgreSQL のバージョンを入力します。
defaultを選択して、PostgreSQL 16 を選択します。次のように値検索構成を入力します。
Table name: TABLE_NAME Column name: COLUMN_NAME Concept type: CONCEPT_TYPE Match function: MATCH_FUNCTION Description: DESCRIPTION次のように置き換えます。
TABLE_NAME: コンセプト タイプに関連付けられた列が存在するテーブル。COLUMN_NAME: コンセプト タイプに関連付けられた列名。CONCEPT_TYPE: 定義するコンセプト タイプ（例:City name）。MATCH_FUNCTION: 値の検索に使用する一致関数。次のいずれかの関数を使用できます。EXACT_STRING_MATCH: 2 つの文字列値の完全一致。一意の ID、コード、主キーに最適です。TRIGRAM_STRING_MATCH: 正規化されたトライグラム距離を計算するファジー マッチング。ユーザー検索や名前の修正に最適です。TRIGRAM_STRING_MATCHを使用するには、pg_trgm拡張機能を有効にします。
SEMANTIC_SIMILARITY_MATCH: 文字列値のセマンティック検索。多言語検索と同義語検索に最適です。サポートされているモデルの一覧については、サポートされている Google モデルをご覧ください。SEMANTIC_SIMILARITY_MATCHを使用するには、vector拡張機能とgoogle_ml_integration拡張機能を有効にします。
DESCRIPTION: （省略可）値検索クエリの説明。
必要に応じて、値の検索を追加します。追加の値インデックスの追加をスキップすると、テンプレート ベースの SQL 生成は次のステップに進みます。
生成された値検索を確認します。コンテキスト セットは、コンテキスト セット ファイルとして保存することも、既存のコンテキスト セット ファイルに追加することもできます。
コンテキスト セット ファイル（my-cluster-psc-primary_postgres_context_set_20251104111122.json など）が、コマンドを実行したディレクトリに保存されます。
次のステップ
- 詳しくは、コンテキスト セットをご覧ください。
- AlloyDB Studio でコンテキスト セットを作成または削除する方法を確認する
- コンテキスト セットをテストする方法を確認する