データベースのデータソースのデータエージェントコンテキストを定義する

このページでは、QueryData メソッドを使用して、データベースデータソースを使用するデータエージェントの作成済みコンテキストを指定する方法について説明します。

作成されたコンテキストは、データエージェントのオーナーがデータエージェントの動作を形成し、API の回答を絞り込むために提供できるガイダンスです。効果的な作成済みコンテキストにより、Conversational Analytics API データエージェントは、データソースに関する質問に回答するための有用なコンテキストを取得できます。

AlloyDB、GoogleSQL for Spanner、Cloud SQL、Cloud SQL for PostgreSQL などのデータベースデータソースの場合、作成されたコンテキストを提供するには、まずデータベースでコンテキストを定義して保存し、QueryData 呼び出しで参照します。

精度の高いコンテキストを提供することで、API はより正確で関連性の高い SQL クエリと回答を生成できます。

始める前に

クエリを実行するデータベースにエージェントコンテキストがアップロードされたデータエージェントが必要です。詳細については、AlloyDB 用データエージェント、GoogleSQL for Spanner 用データエージェント、Cloud SQL 用データエージェント、Cloud SQL for PostgreSQL 用データエージェントをご覧ください。
次のように、インスタンスの Cloud SQL Data API を有効にします。
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
INSTANCE_ID は、Cloud SQL または Cloud SQL for PostgreSQL インスタンスの ID に置き換えます。

また、IAM ユーザーまたはサービスアカウントにデータベース権限を付与する必要もあります。詳細については、Cloud SQL で個々の IAM ユーザーまたはサービスアカウントにデータベース権限を付与すると Cloud SQL for PostgreSQL で個々の IAM ユーザーまたはサービスアカウントにデータベース権限を付与するをご覧ください。

`QueryData` でのコンテキストの提供

QueryData メソッドを呼び出すときに、QueryDataRequest.context.datasourceReferences フィールドでデータソースとコンテキスト情報を提供します。データベースソースの場合は、次のいずれかを使用する必要があります。

AlloyDB for PostgreSQL の場合は alloydb
GoogleSQL for Spanner の場合は spanner_reference
Cloud SQL と Cloud SQL for PostgreSQL の場合は cloud_sql_reference

これらの参照内で databaseReference フィールドを使用して、データベースとテーブルを指定します。作成されたコンテキストを含めるには、context_set_id を参照する agentContextReference も指定する必要があります。

作成されたコンテキストを含む `QueryData` リクエストの例

次の例は、alloydb を使用した QueryData リクエストを示しています。データベースに保存されている事前作成済みのコンテキストにリンクするために、agent_context_reference.context_set_id フィールドを使用しています。

AlloyDB

{
 "parent": "projects/data-agents-project/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": [
     {
       "alloydb": {
         "database_reference": {
           "project_id": "data-agents-project",
           "region": "us-central1",
           "cluster_id": "sqlgen-magic",
           "instance_id": "data-agents-primary",
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/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
 }
}

GoogleSQL for Spanner

{
 "parent": "projects/data-agents-project/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": "data-agents-project"
           "instance_id": "evalbench"
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/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
 }
}

Cloud SQL と Cloud SQL for PostgreSQL

{
 "parent": "projects/data-agents-project/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": [
     {
       "cloud_sql_reference": {
         "database_reference": {
           "engine": "MYSQL"
           "project_id": "data-agents-project",
           "region": "us-central1",
           "instance_id": "data-agents-primary",
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/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: データソースのタイプを指定します。
  - alloydb: データベースのクエリを実行する際に必須となります。このフィールドは、クエリの実行対象とするデータベースによって異なります。
    - database_reference: データベースインスタンスに関する情報を指定します。
      - engine: データベースエンジンまたは SQL 言語。AlloyDB では省略可能です。Spanner データベースの場合は GOOGLE_SQL に設定します。Cloud SQL インスタンスの場合は MYSQL に設定します。Cloud SQL for PostgreSQL インスタンスの場合は、POSTGRESQL に設定します。
      - project_id: データベースインスタンスのプロジェクト ID。
      - region: データベースインスタンスのリージョン。
      - cluster_id: データベースインスタンスのクラスタ ID。
      - instance_id: データベースのインスタンス ID。
      - database_id: データベースの ID。
    - agent_context_reference: データベースに保存されている作成済みコンテキストへのリンク。
      - context_set_id: データベースに保存されているエージェントコンテキスト ID。コンテキストセット ID を見つける方法については、AlloyDB でエージェントコンテキスト ID を見つける、GoogleSQL for Spanner でエージェントコンテキスト ID を見つける、Cloud SQL でエージェントコンテキスト ID を見つける、Cloud SQL for PostgreSQL でエージェントコンテキスト ID を見つけるをご覧ください。
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."
}

データベースのデータソースのデータ エージェント コンテキストを定義する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。