このドキュメントでは、エージェントを検査してエージェントのコンテキスト ファイルを更新する方法について説明します。エージェントを検査して、自然言語の質問から SQL クエリを生成する能力をテストできます。生成されたクエリが正確でない場合は、エージェントのコンテキストを更新できます。
データ エージェントについては、データ エージェントの概要をご覧ください。始める前に
データ エージェントがすでに作成され、エージェント コンテキストがデータ エージェントにアップロードされていることを確認します。詳細については、Spanner Studio でデータ エージェントを管理するをご覧ください。
データ エージェントを検査する
データ エージェントを検査する手順は次のとおりです。
Google Cloud コンソールで、Spanner ページに移動します。
リストからインスタンスを選択し、データベースを選択します。
ナビゲーション メニューで [Spanner Studio] をクリックします。
[エクスプローラ] ペインで、[データ エージェント] の横にある [アクションを表示] をクリックします。
[エージェントを検査] をクリックします。
クエリエディタで、[SQL を生成] をクリックして [コーディングをサポート] パネルを開きます。
自然言語の質問を入力して SQL クエリを生成し、[生成] をクリックします。
SQL クエリの精度を確認します。
データ エージェントのコンテキストをダウンロードして更新する
自然言語の質問に対して生成された SQL クエリに満足できない場合は、既存のエージェント コンテキスト ファイルをダウンロードします。その後、クエリ テンプレートを確認して更新し、更新したコンテキスト ファイルをエージェントに再アップロードできます。
データ エージェントのコンテキストをダウンロードして更新する手順は次のとおりです。
- [エクスプローラ] ペインで、[データ エージェント] の横にある [アクションを表示] をクリックします。
- [エージェント コンテキスト ファイルをダウンロード] をクリックします。
- Gemini CLI を使用してコンテキストを構築するの手順に沿って、追加のクエリペアでコンテキストを更新します。
- [エクスプローラ] ペインで、データ エージェントの横にある [アクションを表示] をクリックします。
- [エージェントを編集] をクリックします。
- [エージェント コンテキスト ファイルをアップロード] セクションで [参照] をクリックし、更新したエージェント コンテキスト ファイルを選択します。
- [保存] をクリックして、エージェント コンテキストを更新します。
回答の精度に満足したら、QueryData エンドポイントを使用してアプリケーションをデータ エージェントに接続できます。
エージェントのコンテキスト ID を確認する
データ アプリケーションをデータ エージェントに接続するには、エージェントのコンテキスト ID が必要です。
Google Cloud コンソールで、Spanner ページに移動します。
リストからインスタンスを選択し、データベースを選択します。
ナビゲーション メニューで [Spanner Studio] をクリックします。
[エクスプローラ] ペインで、[データ エージェント] の横にある [アクションを表示] をクリックします。
[エージェントを編集] をクリックします。
[エージェントのコンテキスト ID] でコンテキスト ID をメモします。エージェント コンテキスト ID の形式は
projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templatesのようになります。
データ エージェントをアプリケーションに接続する
QueryData メソッド呼び出しでエージェント コンテキスト ID を設定して、AlloyDB、Spanner、Cloud SQL、Cloud SQL for PostgreSQL などのデータベース データソースの作成済みコンテキストを提供します。詳細については、データベース データソースのデータ エージェント コンテキストを定義するをご覧ください。
データ エージェントを検査したら、QueryData 呼び出しでデータベース データソースを参照できます。
作成済みコンテキストを含む QueryData リクエストの例
次の例は、spanner_reference データベース データソースを使用した QueryData リクエストを示しています。agent_context_reference.context_set_id フィールドは、データベースに保存されている事前作成済みのコンテキストにリンクするために使用されます。
{ "parent": "projects/cloud-db-nl2sql/locations/us-central1", "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.", "context": { "datasource_references": [ { "spanner_reference" { "database_reference" { "engine": "GOOGLE_SQL" "project_id": "cloud-db-nl2sql" "region": "us-central1" "instance_id": "evalbench" "database_id": "financial" }, "agent_context_reference": { "context_set_id": "projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates" } } } ] }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_disambiguation_question": true, "generate_explanation": true } }
リクエスト本文には次のフィールドが含まれます。
prompt: エンドユーザーからの自然言語の質問。context: データソースに関する情報が含まれます。datasource_references: データソースのタイプを指定します。spanner_reference: データベースのクエリ時に必要です。このフィールドは、クエリを実行するデータベースによって異なります。database_reference: データベース インスタンスに関連する情報を指定します。engine: データベースの SQL 言語。Spanner データベースの場合はGOOGLE_SQLに設定します。project_id: データベース インスタンスのプロジェクト ID。region: Spanner インスタンスのリージョン。instance_id: Spanner インスタンスのインスタンス ID。database_id: データベースの ID。
agent_context_reference: データベース内の作成されたコンテキストへのリンク。context_set_id: データベースに保存されているコンテキストの完全なエージェント コンテキスト ID。例:projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates
generationOptions: 生成する出力のタイプを構成します。generate_query_result: クエリ結果を生成して返す場合は true に設定します。generate_natural_language_answer: 省略可。true に設定すると、自然言語の回答が生成されます。generate_explanation: 省略可。true に設定すると、SQL クエリの説明が生成されます。generate_disambiguation_question: 省略可。true に設定すると、クエリがあいまいな場合に曖昧さ回避の質問が生成されます。
QueryData レスポンスの例
以下は、QueryData 呼び出しからの成功したレスポンスの例です。
{
"generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
"intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
"query_result": {
"columns": [
{
"name": "count"
}
],
"rows": [
{
"values": [
{
"value": "2"
}
]
}
],
"total_row_count": 1
},
"natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}
次のステップ
- データ エージェントの詳細を確認する。
- Gemini CLI を使用してコンテキストを構築する方法を学習する
- Spanner Studio でデータ エージェントを管理する方法を確認する。