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

撰寫的背景資訊是資料代理擁有者提供的指引，可塑造資料代理的行為，並改善 API 的回應。有效撰寫的內容可為 Conversational Analytics API 資料代理程式提供實用背景資訊，協助回答資料來源相關問題。

本頁面說明如何使用 QueryData 方法，為資料庫資料來源提供撰寫的內容。如果是 AlloyDB、GoogleSQL for Spanner、Cloud SQL 和 PostgreSQL 適用的 Cloud SQL 等資料庫資料來源，請先在資料庫中定義及儲存內容，然後在 QueryData 呼叫中參照該內容，即可提供撰寫的內容。

提供準確度高的脈絡，有助於 API 生成更準確且相關的 SQL 查詢和答案。

事前準備

您需要資料代理程式，並為要查詢的資料庫上傳代理程式環境。詳情請參閱 AlloyDB 的資料代理程式、GoogleSQL for Spanner 的資料代理程式、Cloud SQL 的資料代理程式，以及 PostgreSQL 適用的 Cloud SQL 資料代理程式。
按照下列步驟為執行個體啟用 Cloud SQL Data API：
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
將 INSTANCE_ID 改成 Cloud SQL 或 PostgreSQL 適用的 Cloud SQL 執行個體 ID。

您也必須授予 IAM 使用者或服務帳戶資料庫權限。詳情請參閱「在 Cloud SQL 中授予個別 IAM 使用者或服務帳戶資料庫權限」和「在 PostgreSQL 適用的 Cloud SQL 中授予個別 IAM 使用者或服務帳戶資料庫權限」。

使用 `QueryData` 提供背景資訊

呼叫 QueryData 方法時，請在 QueryDataRequest.context.datasourceReferences 欄位中提供資料來源和內容資訊。如果是資料庫來源，您必須使用下列其中一種方式：

alloydb for AlloyDB for PostgreSQL
spanner_reference，適用於 Spanner 適用的 GoogleSQL
cloud_sql_reference for Cloud SQL 和 PostgreSQL 適用的 Cloud SQL

在這些參照中，您可以使用 databaseReference 欄位指定資料庫和資料表。如要加入撰寫的內容，您也必須提供指向 context_set_id 的 agentContextReference。

附有撰寫背景資訊的 `QueryData` 要求範例

以下範例顯示使用 alloydb 的 QueryData 要求。agent_context_reference.context_set_id 欄位用於連結至資料庫中預先撰寫的內容。

AlloyDB

{
 "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": [
     {
       "alloydb": {
         "database_reference": {
           "project_id": "cloud-db-nl2sql",
           "region": "us-central1",
           "cluster_id": "sqlgen-magic",
           "instance_id": "sqlgen-magic-primary",
           "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
 }
}

Spanner 適用的 GoogleSQL

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

Cloud SQL 和 PostgreSQL 適用的 Cloud SQL

{
 "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": [
     {
       "cloud_sql_reference": {
         "database_reference": {
           "engine": "MYSQL"
           "project_id": "cloud-db-nl2sql",
           "region": "us-central1",
           "instance_id": "sqlgen-magic-primary",
           "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：指定資料來源類型。
  - alloydb：查詢資料庫時必須提供。這個欄位會根據您查詢的資料庫而有所不同。
    - database_reference：指定與資料庫執行個體相關的資訊。
      - engine：資料庫引擎或 SQL 方言。AlloyDB 為選填。如果是 Spanner 資料庫，請設為 GOOGLE_SQL。如果是 Cloud SQL 執行個體，請設為 MYSQL。如果是 PostgreSQL 適用的 Cloud SQL 執行個體，請設為 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」和「在 PostgreSQL 適用的 Cloud SQL 中找出代理程式內容 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."
}

為資料庫資料來源定義資料代理程式環境 透過集合功能整理內容 你可以依據偏好儲存及分類內容。