為資料庫資料來源定義資料代理程式環境

本頁面說明如何為使用資料庫資料來源的資料代理,提供編寫的背景資訊。

編寫的背景資訊是資料代理擁有者可提供的指引,用於塑造資料代理的行為,並調整 API 的回覆。有效的編寫情境可為對話式數據分析 API 資料代理提供實用情境,以便回答有關資料來源的問題。

如果是 AlloyDB、GoogleSQL for Spanner、MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 等資料庫資料來源,請先在資料庫中定義並儲存背景資訊,然後在資料來源參照中參照該背景資訊,即可提供編寫的背景資訊。本頁範例使用 QueryData 方法。

提供高準確度的背景資訊,可讓 API 生成更準確且相關的 SQL 查詢和答案。

事前準備

使用 QueryData 提供背景資訊

呼叫 QueryData 方法時,您會在 QueryDataRequest.context.datasourceReferences 欄位中提供資料來源和背景資訊。如果是資料庫資料來源,則必須使用下列其中一項:

  • AlloyDB for PostgreSQL alloydb
  • spanner_reference (適用於 GoogleSQL for Spanner)
  • MySQL 適用的 Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 的 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
 }
}

Spanner 適用的 GoogleSQL

{
 "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
 }
}

Spanner Graph

{
 "parent": "projects/data-agents-project/locations/global",
 "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
 "context": {
   "datasource_references": {
     "spanner_reference": {
       "database_reference": {
         "engine": "GOOGLE_SQL",
         "project_id": "data-agents-project",
         "instance_id": "data-agents-instance",
         "database_id": "fin-graph-db",
         "graph_ids": [
           "FinGraph"
         ]
       },
       "agent_context_reference": {
         "context_set_id": "projects/data-agents-project/locations/us-central1/contextSets/fingraph-assistant"
       }
     }
   }
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

MySQL 適用的 Cloud SQL

{
 "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
 }
}

PostgreSQL 適用的 Cloud SQL

{
 "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": "POSTGRES"
           "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。如果是 MySQL 適用的 Cloud SQL 執行個體,請設為 MYSQL。如果是 PostgreSQL 適用的 Cloud SQL 執行個體,請設為 POSTGRESQL。
          • project_id:資料庫執行個體的專案 ID。
          • region:資料庫執行個體的區域。
          • cluster_id:資料庫執行個體的叢集 ID。
          • instance_id:資料庫的執行個體 ID。
          • database_id:資料庫 ID。
          • graph_ids:Spanner Graph 必須提供。Spanner 資料庫中要查詢的屬性圖名稱清單 (例如 ["FinGraph"])。如果省略 graph_ids,QueryData 會針對基礎資料表生成 GoogleSQL 查詢,而非 GQL 查詢。
        • agent_context_reference:資料庫中編寫內容的連結。
  • 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."
}