本文說明如何建立及最佳化情境，進而提高 QueryData 的準確率，以便建構資料代理程式應用程式。透過 Gemini CLI 中的 DB 脈絡資料擴充功能，即可存取一系列開發人員工具，自動建立及最佳化脈絡資料集。
如要瞭解內容集，請參閱「內容集總覽」。這項擴充功能會自動建立及最佳化背景資訊集，順序如下：
- 瞭解應用程式：擷取資料庫結構定義、應用程式程式碼和業務需求等構件，為資料代理程式建立基礎商業邏輯。
- 建立資料集：建立評估資料集，其中包含代表性的自然語言問題和預期的 SQL 答案。建立這個基準資料集，對於評估效能和追蹤一段時間內的改善情況至關重要。
- 產生初始內容：自動產生直接衍生自資料庫結構定義和選用應用程式構件的基準內容集，以便快速上手。
- 反覆最佳化內容：評估資料集，找出特定查詢失敗的原因。Gemini 會使用自動推論功能建議目標脈絡更新，逐步提高準確率。
雖然擴充功能提供強大的自動化工作流程，但仍可根據您的需求調整。您可以略過自動化程序，在更精細的層級撰寫及插入內容。您可以使用專門的生成指令，控管高品質範本、構面和值搜尋查詢的建立作業。
事前準備
建立代理程式前，請先完成下列先決條件。
啟用必要服務
為專案啟用下列服務：準備 Cloud SQL 執行個體
- 請確認您有權存取現有的 Cloud SQL 執行個體，或建立新的執行個體。 詳情請參閱「為 Cloud SQL 建立執行個體」。
- 請務必在執行個體中建立資料庫，並在其中建立資料表。詳情請參閱在 Cloud SQL 執行個體上建立資料庫。
必要角色和權限
- 在執行個體層級新增 IAM 使用者或服務帳戶。詳情請參閱「為使用者、服務帳戶或群組新增 IAM 政策繫結」。
- 在專案層級將
cloudsql.studioUser、cloudsql.instanceUser和geminidataanalytics.queryDataUser角色授予 IAM 使用者或服務帳戶。詳情請參閱「為專案新增 IAM 政策繫結」。 - 您必須請具備權限的使用者將資料庫權限授予 IAM 使用者或服務帳戶。
GRANT SELECT PRIVILEGES ON * TO "IAM_USERNAME";
詳情請參閱「將資料庫權限授予個別 IAM 使用者或服務帳戶」。
授予 Cloud SQL 執行個體 executesql 權限
如要將 executesql 權限授予 Cloud SQL 執行個體，並啟用 Cloud SQL Data API，請執行下列指令：gcloud config set project PROJECT_ID gcloud components update gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
PROJECT_ID： Google Cloud 專案的 ID。INSTANCE_ID：Cloud SQL 執行個體的 ID。
準備資料庫以進行值搜尋
如要使用語意和三元值搜尋，您必須設定 MySQL 適用的 Cloud SQL 執行個體，支援向量嵌入和 n 元索引。
如要讓 MySQL 適用的 Cloud SQL 執行個體執行語意值搜尋，請啟用下列標記。
啟用
cloudsql_vector旗標。gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on啟用
enable-google-ml-integration旗標，允許 MySQL 適用的 Cloud SQL 執行個體與 Vertex AI 整合。gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration建立向量資料欄來儲存城市嵌入
ALTER TABLE `airports` ADD COLUMN `city_embedding` VECTOR(768);生成及儲存城市名稱的向量嵌入
UPDATE `airports` SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) WHERE `city` IS NOT NULL;
如要讓 MySQL 適用的 Cloud SQL 執行個體執行三連字值搜尋，請完成下列步驟。
啟用
ngram_token_size旗標。gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3為機場名稱建立三元組比對的 FULLTEXT 索引
CREATE FULLTEXT INDEX `idx_ngram_airports_name` ON `airports`(`name`) WITH PARSER ngram;
準備環境
您可以從任何本機開發環境或 IDE 建構脈絡集檔案。如要準備環境，請完成下列步驟：
- 安裝 Gemini CLI
- 安裝 DB Context Enrichment 擴充功能
- 設定資料庫連線
安裝 Gemini CLI
如要安裝 Gemini CLI，請參閱「開始使用 Gemini CLI」。
安裝 DB Context Enrichment 擴充功能
DB 內容擴充功能提供互動式導覽工作流程，可產生結構化內容集並進行疊代。
如要進一步瞭解如何安裝 DB Context Enrichment 擴充功能，請參閱「DB Context Enrichment 擴充功能」。
如要安裝 DB Context Enrichment 擴充功能，請完成下列步驟：
安裝 DB Context Enrichment Gemini CLI 擴充功能：
gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment(選用) 更新 DB Context Enrichment 擴充功能。
如要確認已安裝的擴充功能版本，請執行下列指令：
gemini extensions list確認版本為
0.5.0以上。如要更新 DB Context Enrichment 擴充功能，請執行下列指令：gemini extensions update mcp-db-context-enrichment如要更新 DB Context Enrichment 擴充功能或取代
GEMINI_API_KEY，請執行下列指令：gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY然後將 GEMINI_API_KEY 替換成您的 Gemini API 金鑰。
設定資料庫連線
擴充功能需要資料庫連線才能擷取結構定義，並驗證產生的 SQL 內容語法。如要讓擴充功能與資料庫互動，請設定驗證憑證，並定義資料庫連線設定。
設定應用程式預設憑證
設定應用程式預設憑證 (ADC)，為兩個主要元件提供使用者憑證：
- Toolbox MCP 伺服器：使用憑證連線至資料庫、擷取結構定義，並執行 SQL 進行驗證。
- 資料庫內容擴充功能：使用憑證驗證並呼叫 Gemini API。
在終端機中執行下列指令來進行驗證：
gcloud auth application-default login設定資料庫連線檔案
擴充功能需要資料庫連線才能生成內容，而 MCP Toolbox 支援這項功能，並在設定檔中定義。
設定檔會指定資料庫來源，以及擷取結構定義或執行 SQL 時所需的工具。DB 內容擴充功能已預先安裝 Agent Skills，可協助您產生設定。
啟動 Gemini CLI：
gemini在 Gemini CLI 中輸入下列內容，確認技能是否已啟用：
/skills輸入提示，例如
help me set up the database connection。這項技能會引導您在目前的工作目錄中，建立名為autoctx/tools.yaml的設定檔。在 Gemini CLI 中執行下列指令，將
tools.yaml設定套用至 Toolbox MCP 伺服器。/mcp reload
如要進一步瞭解如何手動設定資料庫設定檔，請參閱「MCP Toolbox 設定」。
透過自動化工作流程產生內容
透過情境工程提高準確度通常需要手動試誤。開發人員通常會猜測查詢失敗的原因、編寫修正內容，然後手動測試。Gemini CLI 中的 DB Context Enrichment 擴充功能可自動執行這項改善程序。這項功能會使用評估資料集 (包含問題和正確的 SQL 答案) 評估效能，並找出特定查詢失敗的原因。接著，Gemini 會自動建議具體的背景資訊更新，以提高準確度。完成這些步驟，有系統地提升資料代理程式的準確度。
初始化工作區
初始化指令會設定本機工作區，包括資料庫連線設定和實驗目錄。這個專屬工作區可確保所有設定、實驗和產生的檔案都集中管理，方便您追蹤及管理內容最佳化作業。
- 建立新目錄做為疊代最佳化流程的工作區，然後前往該目錄。
在新目錄中啟動 Gemini CLI：
gemini執行初始化指令：
/autoctx:init如果尚未設定資料庫連線，代理程式會引導您建立
tools.yaml檔案，並初始化本機state.md檔案和experiments目錄。初始化後，工作區應如下所示：
my-workspace/ └── autoctx/ ├── tools.yaml # Database connection and tools configuration ├── state.md # Local file to track the experiment progress └── experiments/ # Dedicated directory for future experiment-specific files
準備及擴充資料集
如要讓 Gemini 系統性地對內容集進行最佳化，請準備代表性的自然語言問題和預期 SQL 答案 (「黃金」) 的評估資料集，以評估內容集。高品質的評估資料集對於評估效能、找出查詢失敗情形，以及追蹤一段時間內的改善情況至關重要。資料集應為 JSON 檔案，內含自然語言問題 (NLQ) 和涵蓋資料應用程式目標用途的黃金 SQL。
正確格式應符合以下範例：
[
{
"id": "example_001",
"nlq": "What is the total revenue for the top 5 products?",
"golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
}
]
Gemini CLI 擴充功能內含提供的指令，可建立並擴展一小組問題做為評估基準。
- 前往工作區資料夾。
在新目錄中啟動 Gemini CLI：
gemini在 Gemini CLI 中執行
/autoctx:generate-dataset指令：/autoctx:generate-dataset當代理程式提示時，請提供種子，也就是引導生成較大資料集的初始範例或一小組範例。種子可以是下列任一值：
- 小型黃金資料集檔案
- 特定的自然語言轉 SQL (NL2SQL) 黃金配對
舉例來說，您可以提供下列 NL2SQL 黃金配對做為種子：
Question: "What are the names of all airports in California?" SQL: "SELECT name FROM airports WHERE state = 'CA';"代理程式會提示使用者授權，以便使用
execute_sql工具驗證語法和執行有效性。本步驟為選擇性步驟。代理程式會詢問是否要使用種子資料的變化形式 (套用不同篩選器、同義字等) 擴充資料集。本步驟為選擇性步驟。
代理程式會使用
execute_sql工具，對資料庫執行新生成的 SQL 查詢，驗證語法和執行有效性，然後再向您顯示。選擇性接受、編輯或拒絕建議。系統會自動將核准的配對儲存在本機，以供評估。
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json # Generated dataset └── experiments/
建立初始脈絡資料集
產生初始內容集可做為評估和疊代改善的基準。這個步驟會使用資料庫結構定義和應用程式構件，建立反映商業邏輯的基礎環境。
Gemini CLI 擴充功能內建指令，可根據資料庫結構定義和資料代理應用程式的相關資訊 (例如應用程式程式碼，或包含業務需求資訊的檔案)，產生初始範本和構面集。如要從頭產生基準內容集，請按照下列步驟操作：
- 前往工作區資料夾。
在新目錄中啟動 Gemini CLI：
gemini在 Gemini CLI 中執行
/autoctx:bootstrap指令：/autoctx:bootstrap一般來說，代理程式會提供以下服務。
代理程式會提示您指定實驗名稱。實驗是專屬的工作區資料夾，可封裝資料庫環境設定的完整生命週期、追蹤基準狀態、評估測試結果，以及後續的疊代式爬山改良。這個名稱會用於整理工作區中實驗資料夾下的所有產生檔案，請選擇容易辨識和記憶的名稱。
代理程式會從目標資料庫擷取並列出結構定義，並提示您視需要提供其他資源或檔案。如果結構定義很複雜，代理程式也會提示您選取特定結構定義或資料表，做為初始脈絡集。如未指定，系統會假設為目前資料庫結構定義中的所有資料表。
查看並視需要調整生成的脈絡資料集。完成修正後，代理程式會直接在工作區資料夾下，於本機磁碟上產生 JSON 結構定義檔案：
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md └── experiments/ └── my-experiment/ └── bootstrap_context.json # The generated initial context set file按照操作說明從 Cloud SQL Studio 上傳內容。
評估情境效益
Gemini CLI 擴充功能內建指令，可使用黃金資料集評估資料代理程式。這項擴充功能會與 Evalbench 整合，透過使用黃金集中指定的問答查詢代理程式的 QueryData API，然後比較產生的 SQL 和其執行結果與黃金 SQL，執行評估作業。評估是瞭解目前情境集成效的關鍵。比較產生的 SQL 與黃金資料集，即可找出失敗的特定查詢，並找出需要改善情境的區域。
如要根據黃金資料集評估目前情境的有效性，請按照下列步驟操作：
- 將 Cloud SQL Studio 的內容上傳至目標內容集，以進行評估。如果未上傳要評估的內容，則可略過這個步驟。
- 前往工作區資料夾。
在資料夾中啟動 Gemini CLI：
gemini在 Gemini CLI 中執行
/autoctx:evaluate指令：/autoctx:evaluate提供黃金資料集的路徑、評估設定生成和評估執行的內容集 ID，以及指定的輸出目錄。
完成後，代理程式會在實驗資料夾中以檔案形式產生評估結果，並摘要說明評估結果。
您也可以選擇手動檢查詳細評估報告中的評估結果，該報告會以 CSV 檔案格式儲存在實驗資料夾中。
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json └── experiments/ └── my-experiment/ └── bootstrap_context.json └── eval_configs/ └── <configs_for_eval_run>/ └── eval_reports/ └── <eval_id>/ └── eval_report/ ├── configs.csv ├── evals.csv ├── scores.csv └── summary.csv
執行缺口分析並最佳化情境
Gemini CLI 擴充功能內建指令，可對現有脈絡集執行差距分析，並建議變更，以提升脈絡集品質，這是最佳化脈絡集的重要步驟。差距分析有助於瞭解特定查詢失敗的原因，以及可改善的背景資訊。根據這項分析，Gemini 會使用自動推論功能，建議進行目標脈絡更新 (例如新範本或 facet)，以解決這些失敗問題，並逐步提高查詢準確率。
- 前往工作區資料夾。
在資料夾中啟動 Gemini CLI：
gemini在 Gemini CLI 中執行
/autoctx:hillclimb指令：/autoctx:hillclimb代理程式會自動找出最合適的評估結果和爬山演算法的基礎脈絡，並在有多個選項時要求確認。
如果沒有可用的評估結果，服務專員會提示您使用資料集和環境設定執行評估。
準備就緒後，AI 助理會讀取評估結果和現有內容集，然後生成差距分析報告。
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json └── experiments/ └── my-experiment/ └── bootstrap_context.json └── eval_configs/ └── eval_reports/ └── hillclimb/ └── gap_analysis_v1.md代理程式會提出新的規範範本和層面，並視需要透過
execute_sql針對資料庫測試 SQL，藉此制定修正措施。準備就緒後，系統會在本地產生新的改良式內容 JSON 檔案，而基準內容 JSON 檔案則會保持不變。
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json └── experiments/ └── my-experiment/ └── bootstrap_context.json └── eval_configs/ └── eval_reports/ └── hillclimb/ ├── gap_analysis_v1.md └── improved_context_v1.md按照操作說明從 Cloud SQL Studio 將內容上傳至目標內容集，準備好開始下一輪的評估疊代。
限制
自動化工作流程僅支援產生及最佳化範本和構面。如要為資料代理程式設定值搜尋功能，請參閱「產生值搜尋查詢」。
生成目標脈絡
如果您偏好更自訂的內容建立方式，可以使用 DB Context Enrichment 擴充功能手動生成特定內容元素。下列指令會引導您以 JSON 檔案形式撰寫內容，精細控管範本、構面和值搜尋查詢的產生作業。
生成指定範本
如要將特定查詢/SQL 配對新增為內容集的查詢範本，請使用 /generate_targeted_templates 指令。
如要進一步瞭解內容集檔案和查詢範本，請參閱「內容集總覽」。
如要將查詢範本新增至內容集，請完成下列步驟：
在 Gemini CLI 中執行
/generate_targeted_templates指令：/generate_targeted_templates輸入要加入查詢範本的自然語言查詢。
在查詢範本中輸入對應的 SQL 查詢。
查看生成的查詢範本。您可以將查詢範本儲存為內容集檔案，或附加至現有的內容集檔案。
內容集檔案 (例如 my-cluster-psc-primary_postgres_context_set_20251104111122.json) 會儲存在您執行指令的目錄中。
生成目標層面
如要將特定查詢新增至 SQL 條件，做為內容集檔案的層面，請使用 /generate_targeted_facets 指令。
如要進一步瞭解內容集檔案和構面，請參閱「內容集總覽」
如要將構面新增至內容集檔案，請完成下列步驟：
在 Gemini CLI 中執行
/generate_targeted_facets指令：/generate_targeted_facets輸入要新增至側面的自然語言意圖。
在構面中輸入對應的 SQL 程式碼片段。
查看生成的構面。您可以將構面儲存至內容集檔案，或附加至現有的內容集檔案。
內容集檔案 (例如 my-cluster-psc-primary_postgres_context_set_20251104111122.json) 會儲存在您執行指令的目錄中。
生成值搜尋查詢
如要產生值搜尋，指定系統在概念類型中搜尋及比對特定值的方式，請使用 /generate_targeted_value_searches 指令。
如要進一步瞭解值索引，請參閱「內容集總覽」
完成「準備資料庫以進行值搜尋」一文中的步驟。
如要產生價值指數，請完成下列步驟：
執行
/generate_targeted_value_searches指令：/generate_targeted_value_searches輸入
mysql，選取 MySQL 做為資料庫引擎。選取「預設」即可選取 MySQL 8.0。輸入值搜尋設定，如下所示：
Table name: TABLE_NAME Column name: COLUMN_NAME Concept type: CONCEPT_TYPE Match function: MATCH_FUNCTION Description: DESCRIPTION更改下列內容：
TABLE_NAME：與概念類型相關聯的資料欄所在資料表。COLUMN_NAME：與概念類型相關聯的資料欄名稱。CONCEPT_TYPE：要定義的概念類型，例如City name。MATCH_FUNCTION：用於搜尋值的比對函式。你可以使用下列其中一個函式：EXACT_STRING_MATCH：用於完全比對兩個字串值。最適合不重複 ID、代碼和主鍵。TRIGRAM_STRING_MATCH：用於模糊比對，可計算正規化三連字距離。最適合使用者搜尋和更正名稱。如要使用TRIGRAM_STRING_MATCH，請準備資料庫，支援 n-gram 索引。
SEMANTIC_SIMILARITY_MATCH：用於字串值的語意搜尋。最適合跨語言和同義字搜尋。如需支援的機型清單，請參閱「支援的 Google 機型」。如要使用SEMANTIC_SIMILARITY_MATCH，請準備資料庫，支援向量嵌入。
DESCRIPTION：(選用) 值搜尋查詢的說明。
視需要新增其他值搜尋。如果略過新增額外值索引，系統會直接進入下一個步驟，根據範本產生 SQL。
查看生成的價值搜尋。您可以將內容集儲存為內容集檔案，或附加至現有的內容集檔案。
內容集檔案 (例如 my-cluster-psc-primary_postgres_context_set_20251104111122.json) 會儲存在您執行指令的目錄中。
後續步驟
- 進一步瞭解情境集。
- 瞭解如何在 Cloud SQL Studio 中建立或刪除內容集
- 瞭解如何測試內容集