本文說明如何檢查代理程式，以及更新代理程式的結構定義檔案。您可以檢查代理程式，測試其根據自然語言問題生成 SQL 查詢的能力。如果生成的查詢不準確，可以更新代理程式的背景資訊。
如要瞭解資料代理程式，請參閱「資料代理程式總覽」。事前準備
請確認已建立資料代理，並將代理程式脈絡上傳至資料代理。詳情請參閱「在 Spanner Studio 中管理資料代理程式」。
檢查資料代理程式
如要檢查資料代理程式，請執行下列步驟：
前往 Google Cloud 控制台的「Spanner」頁面。
從清單中選取執行個體，然後選取資料庫。
在導覽選單中，按一下「Spanner Studio」。
在「Explorer」窗格中，點選「資料代理」旁邊的「查看動作」。
按一下「檢查代理程式」。
在查詢編輯器中，點選「Generate SQL」(產生 SQL)，開啟「幫我編寫程式碼」面板。
輸入自然語言問題來生成 SQL 查詢，然後按一下「生成」。
檢查 SQL 查詢是否正確。
下載及更新資料代理程式的環境
如果您對自然語言問題生成的 SQL 查詢不滿意，請下載現有的代理程式結構定義檔案。接著，您就可以查看及更新查詢範本，然後將更新後的內容檔案重新上傳至代理程式。
如要下載及更新資料代理程式的內容，請按照下列步驟操作：
- 在「Explorer」窗格中，點選「資料代理」旁邊的「查看動作」。
- 按一下「下載代理結構定義檔案」。
- 按照「使用 Gemini CLI 建構脈絡」一文中的步驟，使用其他查詢組合更新脈絡。
- 在「Explorer」窗格中，點選資料代理程式旁的「查看動作」。
- 按一下「編輯代理程式」。
- 在「Upload agent context file」(上傳代理程式結構定義檔案) 區段中，按一下「Browse」(瀏覽)，然後選取更新後的代理程式結構定義檔案。
- 按一下「儲存」，更新代理程式環境。
確認回覆內容準確無誤後，您可以使用 QueryData 端點將應用程式連結至資料代理程式。
找出代理脈絡資料 ID
如要將資料應用程式連結至資料代理程式，您需要代理程式的內容 ID。
前往 Google Cloud 控制台的「Spanner」頁面。
從清單中選取執行個體，然後選取資料庫。
在導覽選單中，按一下「Spanner Studio」。
在「Explorer」窗格中，點選「資料代理」旁邊的「查看動作」。
按一下「編輯代理程式」。
記下「Agent context ID」(代理脈絡資料 ID) 中的脈絡資料 ID。代理程式環境 ID 格式與
projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates類似。
將資料代理程式連結至應用程式
在 QueryData 方法呼叫中設定代理程式內容 ID，為資料庫資料來源 (例如 AlloyDB、Spanner、Cloud SQL 和 PostgreSQL 適用的 Cloud SQL) 提供撰寫的內容。詳情請參閱「為資料庫資料來源定義資料代理程式環境」。
檢查資料代理程式後，您可以在 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 中管理資料代理程式。