Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用情境工程代理程式建構情境集

本文說明如何建立及最佳化脈絡資料集，協助資料代理應用程式提高 QueryData 查詢準確度。脈絡工程代理可自動建立及最佳化脈絡集，協助您建構、評估及改善脈絡集。

如要瞭解脈絡資料集和 QueryData，請參閱「脈絡資料集總覽」和「QueryData 總覽」。

如要建構企業級資料應用程式，文字轉查詢模型的準確度通常需要接近 100% 的品質。如果 SQL 生成錯誤，會影響整體應用程式可用性和使用者體驗。如要取得可解釋、與業務相關且準確度高的答案，就必須進行情境工程，也就是建立及反覆最佳化情境，以達到最佳準確度。

只要為 QueryData 提供與業務應用程式相關的背景資訊，就能提供系統所需的精確業務規則，解決細微的使用者意圖。

脈絡工程代理

脈絡工程代理會自動執行這項最佳化工作流程。您可以與代理對話，處理臨時工作，最佳化情境。下表列出一些自然語言提示範例，說明如何指示服務專員，以及服務專員的回應方式。請參考下列範例，建構及最佳化脈絡：

失敗分析提示範例：「更新情境，以便正確識別『迪士尼世界航班』等查詢的機場。」代理會分析失敗原因，並建議新增適當的背景資訊項目，例如值搜尋查詢。
提供情境建議的提示詞範例：「Read my app code and suggest some context to add.」(閱讀我的應用程式程式碼，並建議要加入的脈絡。)代理會剖析程式碼、推論應用程式的領域，並建議相關的背景資訊項目。
批次處理的提示範例：「以下是 10 個問題和 SQL 查詢範例。將其轉換為範本。」代理會大量處理輸入內容，並更新脈絡集。

黃金資料集的重要性

如要最佳化脈絡，首先必須建立一個符合應用程式自然語言輸入情境的資料集，代理可協助您建立這個黃金資料集，其中包含使用者問題和預期的資料庫查詢。黃金資料集可讓您：

建立查詢效能基準。
根據基準真相資料庫查詢驗證更新。
評估各疊代的準確度提升幅度。

系統性的爬山程序

在系統化爬山演算法中，代理會透過評估黃金資料集、差距分析和更新，反覆改善情境集，將準確率提升至接近 100%。

自動生成基準情境：根據資料庫結構定義和應用程式構件，建立起始情境集。
爬坡最佳化工作流程：讓代理評估 QueryData 準確度、分析失敗原因，並自動提出改善建議，提高準確度。

下圖顯示系統化爬坡法的工作流程：

反覆建構情境的工作流程。

事前準備

使用脈絡工程代理前，請先完成下列必要條件。

啟用必要服務

為專案啟用下列服務：

準備 Cloud SQL 執行個體

請確認您有權存取現有的 Cloud SQL 執行個體，或建立新的執行個體。詳情請參閱「建立 Cloud SQL 執行個體」。
請務必在執行個體中建立資料庫，以便在其中建立資料表。詳情請參閱「在 Cloud SQL 執行個體上建立資料庫」。

必要角色和權限

在執行個體層級新增 IAM 使用者或服務帳戶。詳情請參閱「為使用者、服務帳戶或群組新增 IAM 政策繫結」。
在專案層級，將 cloudsql.studioUser、cloudsql.instanceUser 和 geminidataanalytics.queryDataUser 角色授予 IAM 使用者或服務帳戶。詳情請參閱「為專案新增 IAM 政策繫結」。
如要建立、上傳及管理情境集，請在專案層級，將 Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin) 角色，授予 IAM 使用者或服務帳戶。詳情請參閱「情境組合權限」。
您必須請具備特殊權限的使用者，將資料庫權限授予 IAM 使用者或服務帳戶。

GRANT SELECT PRIVILEGES ON * TO "IAM_USERNAME";。

詳情請參閱「將資料庫權限授予個別 IAM 使用者或服務帳戶」。

將 `executesql` 權限授予 Cloud SQL 執行個體

執行下列指令，將 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。

如要執行本教學課程中的步驟，請登入 Google Cloud，然後使用 IAM 驗證機制向資料庫進行驗證。

準備資料庫以進行值搜尋

如要使用語意和三元值搜尋，您必須設定 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 執行個體執行三字母組合值搜尋，請按照下列步驟操作：
1. 啟用 ngram_token_size 旗標。
```
gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3
```
2. 為機場名稱的三字母組合比對建立 FULLTEXT 索引：
```
CREATE FULLTEXT INDEX `idx_ngram_airports_name`
ON `airports`(`name`) 
WITH PARSER ngram;
```

準備環境

您可以在任何本機開發環境或 IDE 中建構脈絡集檔案。如要準備環境，請完成下列步驟：

安裝內容比對引擎代理程式
設定資料庫連線

安裝內容比對引擎代理程式

情境工程代理會執行 Model Context Protocol (MCP) 伺服器，需要 uv 管理基礎 Python 封裝。

按照「安裝 uv」中的操作說明安裝 uv。
確認已安裝 uv，且可從指令列存取：
```
uv --version
```

如要準備環境，請在所選代理程式架構中安裝脈絡工程代理程式，例如 Antigravity CLI、Claude Code 或 Gemini CLI。

根據所選的代理駕馭系統，按照對應的安裝步驟操作：

Antigravity CLI

如要在 Antigravity CLI 中安裝情境工程代理，請按照下列步驟操作：

安裝 Antigravity CLI。請參閱「開始使用 Antigravity CLI」。

安裝情境工程代理外掛程式，其中包含情境生成工作流程：

agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin

啟動 Antigravity CLI：
```
agy
```

如要將外掛程式更新至最新版本，請按照下列步驟操作：

agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin

Claude Code

如要在 Claude Code 中安裝脈絡工程代理程式，請按照下列步驟操作：

新增外掛程式市集：

/plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git

安裝外掛程式：

/plugin install db-context-engineering@db-context-enrichment-marketplace

重新載入外掛程式，啟用變更：
```
/reload-plugins
```

更新外掛程式：

/plugin update db-context-engineering@db-context-enrichment-marketplace

Gemini CLI (已淘汰)

如要在 Gemini CLI 中安裝情境工程代理，請按照下列步驟操作：

安裝 Gemini CLI。請參閱「開始使用 Gemini CLI」。

安裝擴充功能：

gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

更新擴充功能：

gemini extensions update mcp-db-context-enrichment

設定資料庫連線

代理需要資料庫連線來擷取結構定義，並驗證生成的 SQL 內容語法。如要讓代理與資料庫互動，請設定驗證憑證，並定義資料庫連線設定。

設定應用程式預設憑證

設定應用程式預設憑證 (ADC)，提供使用者憑證，以便從情境工程代理存取 Google Cloud 資源：

Toolbox MCP 伺服器：使用憑證連線至資料庫、擷取結構定義，並執行 SQL 進行驗證。
Evalbench：使用憑證叫用 QueryData 進行評估。

在終端機中執行下列指令來進行驗證：

gcloud auth application-default login

設定資料庫連線檔案

代理需要資料庫連線才能生成背景資訊，MCP Toolbox 支援這項功能，並在設定檔中定義。

設定檔會指定資料庫來源，以及擷取結構定義或執行 SQL 時所需的工具。脈絡工程代理預先安裝了代理技能，可協助您生成設定。

啟動代理環境。
要求代理協助設定資料庫連線，例如輸入「help me set up the database connection」提示。按照代理程式的指示，在目前使用的目錄中建立設定檔 autoctx/tools.yaml。
如要套用新的 tools.yaml 設定，請重新載入連線：
- 在 Antigravity CLI 中執行 /mcp，然後選取 toolbox 重新啟動。
- 在 Gemini CLI 中執行 /mcp reload。
- 在 Cloud Code 中執行 /mcp，選取 toolbox，然後選取 Reconnect。

如要進一步瞭解如何手動設定資料庫設定檔，請參閱「MCP Toolbox 設定」。

生成及最佳化背景資訊

情境工程代理提供一組代理技能和 MCP 工具，可強化程式設計代理的情境工程能力。您可以搭配使用這些工具，產生基準、評估成效，並反覆套用改善措施。不過，您可以在工作流程的任何階段開始：

如果已設定情境，可以直接進行評估。
如果您想修正失敗的查詢，可以直接進行差距分析。

每項功能都會說明代理的動作、用途和叫用指令。

範例提示說明如何以自然語言查詢代理程式。如果代理需要更多詳細資料才能完成要求，就會提示您提供說明。

建立及擴充評估資料集

如要提升成效，首先必須評估成效。如果沒有黃金資料集 (由使用者問題和預期 SQL 組成)，情境工程就缺乏系統化驗證。有了黃金資料集，每項變更都是可衡量的改善，您可以根據基準真相進行驗證。

手動建立具代表性的黃金資料集相當耗時，而且小型資料集可能無法涵蓋使用者用詞的變化。代理會採取下列行動來解決這個問題：

根據資料庫結構定義，生成候選問題和 SQL 配對。
使用篩選器變化、同義詞和改寫內容，擴充小型種子資料集。

您也可以選擇讓代理對資料庫執行生成的 SQL。這項驗證可確保查詢順利執行，再將查詢新增至資料集。

資料集是 JSON 檔案，內含問題和 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;"
  }
]

核准的配對會填入工作區的 autoctx/golden.json 檔案，供您評估。您可以提供現有檔案，或在內嵌中編寫一些評估範例，供代理擴充。

您可以使用下列範例提示詞，指示代理：

「根據我的結構定義生成評估資料集。」
「以下是種子問題和 SQL。將其擴展為更廣泛的資料集，並驗證查詢是否執行。

生成基準脈絡資料集

為避免從頭建立脈絡，您可以讓 AI 代理從資料庫結構定義和應用程式構件 (例如業務規則、範例查詢或 README 檔案) 衍生初始脈絡集。雖然這個基準環境並非最終版本，但可做為經過驗證的起點，並以資料庫模型為基礎。

您可以使用下列範例提示指示代理程式：

「Generate a context set from my schema.」(根據我的結構定義產生內容集。)
「使用這些結構定義和 requirements.md 中的業務規則，生成初始情境。」

代理會提示您為實驗命名，以便整理生成的構件。如果資料庫結構定義較大，代理可能會要求您縮小範圍。如要使用 Cloud SQL Studio 上傳脈絡資料，請在代理生成 JSON 檔案後，按照操作說明進行。

評估情境成效

建立內容集和黃金資料集後，您可以透過每個黃金問題查詢資料代理程式的 QueryData API，讓代理程式評估內容成效。代理程式會使用 Evalbench 比較生成的 SQL 查詢及其執行結果與預期答案，以處理比較作業。

執行評估作業後，您會取得下列資訊：

量化指標，例如通過和失敗結果以及總分，可追蹤各情境疊代的進度。
內嵌對話摘要和詳細 CSV 報表，會寫入實驗資料夾中的 eval_reports/ 目錄。

如要開始評估，請提供黃金資料集路徑和背景資訊集 ID。如要瞭解如何找出情境集 ID，請參閱「找出代理情境 ID」。

您可以使用下列範例提示詞，指示代理：

「根據 golden.json 評估我的脈絡。」
「使用上次實驗的設定重新執行評估。」

如要重新執行先前產生的評估設定，不必再次設定，請詢問代理程式或直接叫用 CLI：

uvx google-evalbench --run_config=autoctx/experiments/my-experiment/eval_configs/run_config.json

如要進一步瞭解評估設定結構定義，以及如何自訂評估執行作業，請參閱 Evalbench 說明文件。

進行差距分析並提出改善建議

如要解決查詢失敗的問題，您必須找出根本原因，例如資料欄不正確、缺少資料表彙整，或模糊字詞未解析。如要手動找出這些問題，必須深入分析評估報告。

代理會自動執行這項分析和修正循環：

落差分析：代理會讀取評估結果和您設定的情境，將類似的失敗案例分組，並建議新增特定情境，例如範本、面向或值搜尋。
建議修正：代理會提出具體編輯建議，並可選擇對資料庫測試 SQL，驗證解決方案。
保留基準：代理會將改善項目寫入新的 JSON 檔案，並與基準結構定義一併儲存，保留原始檔案。

您可以使用下列範例提示詞，指示代理：

「分析我上次評估的落差，並提出修正建議。」
「根據 golden.json 最佳化這組內容。」

為準備下一次疊代，請使用 Data Agents Studio 將改良後的內容上傳至目標內容集，請按照操作說明進行。

視需要建立特定情境項目

如果您已瞭解必要內容，例如特定問題的範本、重複篩選條件的層面，或特定資料欄的值搜尋，手動編寫內容 JSON 可能會在參數名稱、型別中繼資料或片段語法中，產生序列化錯誤。代理會處理 JSON 格式，讓您專注於業務意圖。

您也可以使用這項功能進行臨時更新，例如需要支援新的查詢模式，或解決缺少的結構定義詳細資料。如要取得 JSON，請向代理說明所需情境，不必執行評估或設定實驗。

當您接到一次性工作時，這項功能也相當實用：例如，利害關係人提供新的問題與 SQL 組合，希望您支援；或是在程式碼審查期間，您發現缺少某個面向。您不必設定實驗或執行評估，只要說明需求，代理就會產生 JSON。

您可以使用下列範例提示指示代理程式：

「為『加州有哪些機場？』建立範本，並使用 SQL：SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'。」
「為標示為『紅眼』的篩選器 departure_time BETWEEN '00:00:00' AND '06:00:00' 建立 facet。」
「Create a value search for .」(為 airports.iata 建立值搜尋。)

選擇脈絡類型的原因

無論是範本、構面或值搜尋，選取正確的內容類型都有助於避免內容膨脹和資料庫查詢迴歸。舉例來說，使用範本而非 facet 可能會導致規則重複，而在範本足夠的情況下引入值搜尋，則可能會增加查詢延遲時間。如要找出正確的結構定義格式，請在建立情境項目之前，提示代理根據查詢結構或資料庫資料欄推薦類型。代理會說明推論過程，協助您瞭解情境選項。

您可以使用下列範例提示指示代理程式：

「我一直要在許多查詢中撰寫篩選條件。departure_time BETWEEN '00:00:00' AND '06:00:00' 如何才能拍出最棒的效果？」
「使用者以任意文字描述航班狀態，我想將這些文字與 flights.status 進行比對。我該設定哪種值搜尋？"
「範本和構面有何差異？我應該在什麼時候使用哪一個？」

對脈絡資料集套用大量作業

代理支援大量更新，可持續管理大型脈絡集。如果需要同時更新多個內容項目，例如重新命名資料庫資料欄、變更程式碼值的格式，或範本參照已淘汰的資料表，代理程式可以對所有受影響的項目套用變更，而不影響不相關的項目。

您可以使用下列範例提示詞，指示代理：

「請閱讀 golden.txt，並將所有配對轉換為範本。」
「在 context_set.json 中，將參照『United』的任何項目中的 airline = 'UA' 替換為 airline = 'United Airlines'。不要理會不相關的項目。

後續步驟

進一步瞭解情境集。
瞭解如何在 Cloud SQL Studio 中建立或刪除情境集。
瞭解如何測試內容集。

使用情境工程代理程式建構情境集 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

脈絡工程代理

黃金資料集的重要性

系統性的爬山程序

事前準備

啟用必要服務

準備 Cloud SQL 執行個體

必要角色和權限

將 executesql 權限授予 Cloud SQL 執行個體

準備資料庫以進行值搜尋

準備環境

安裝內容比對引擎代理程式

Antigravity CLI

Claude Code

Gemini CLI (已淘汰)

設定資料庫連線

設定應用程式預設憑證

設定資料庫連線檔案

生成及最佳化背景資訊

建立及擴充評估資料集

生成基準脈絡資料集

評估情境成效

進行差距分析並提出改善建議

視需要建立特定情境項目

選擇脈絡類型的原因

對脈絡資料集套用大量作業

後續步驟

使用情境工程代理程式建構情境集

將 `executesql` 權限授予 Cloud SQL 執行個體