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

預覽

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》，以及《生成式 AI 預先發布版產品附加條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

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

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

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

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

脈絡工程代理

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

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

黃金資料集的重要性

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

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

系統化爬坡程序

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

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

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

事前準備

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

啟用必要服務

為專案啟用下列服務：

• Data Analytics API with Gemini
• Gemini for Google Cloud API
• Knowledge Catalog API

準備 Bigtable 執行個體

確認有可用的 Bigtable 執行個體。詳情請參閱「建立執行個體」。

必要角色和權限

• 在執行個體或專案層級，將 bigtable.admin 角色授予 IAM 使用者。詳情請參閱「使用 IAM 控管 Bigtable 存取權」。
• 在專案層級，將 geminidataanalytics.queryDataUser 角色授予 IAM 使用者。詳情請參閱「新增專案的 IAM 政策繫結」。
• 如要建立、上傳及管理情境集，請在專案層級將 Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin) 角色授予 IAM 使用者。詳情請參閱「情境組合權限」。

準備環境

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

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

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

情境工程代理會執行 Model Context Protocol (MCP) 伺服器，該伺服器需要 uv 才能管理基礎 Python 套件。

1. 按照「安裝 uv」中的操作說明安裝 uv。

2. 確認已安裝 uv，且可透過指令列存取：

   uv --version

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

注意：Gemini CLI 支援功能現已淘汰。如果您使用 Gemini CLI，建議改用 Antigravity CLI。詳情請參閱「從 Gemini CLI 遷移」。

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

Antigravity CLI

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

1. 安裝 Antigravity CLI。請參閱「開始使用 Antigravity CLI」。
2. 安裝情境工程代理外掛程式，其中包含情境生成工作流程。將 VERSION 替換為必要的發布版本：

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

3. 啟動 Antigravity CLI：

   agy

如要將外掛程式更新至最新版本，請執行下列指令。 將 VERSION 替換為必要的發布版本：

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

Claude Code

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

1. 新增外掛程式市集：

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

2. 安裝外掛程式：

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

3. 重新載入外掛程式，讓變更生效：

   /reload-plugins

4. 更新外掛程式：

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

Gemini CLI (已淘汰)

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

1. 安裝 Gemini CLI。請參閱「開始使用 Gemini CLI」。
2. 安裝擴充功能：

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

3. 更新擴充功能：

   gemini extensions update google-cloud-db-context-engineering

設定資料庫連線

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

設定應用程式預設憑證

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

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

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

gcloud auth application-default login

設定資料庫連線檔案

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

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

注意：在建立並重新載入 autoctx/tools.yaml 之前，Toolbox MCP 伺服器無法連線至 /mcp，並會傳回 unable to read config file at "autoctx/tools.yaml: ... no such file or directory。

1. 啟動代理環境。

2. 請代理協助設定資料庫連線，例如提示「幫我設定資料庫連線」。按照代理的指示，在目前使用的目錄中建立設定檔，並命名為 autoctx/tools.yaml。

3. 如要套用新的 tools.yaml 設定，請重新載入連線：

   • 在 Antigravity CLI 中執行 /mcp，然後選取 toolbox 重新啟動。
   • 在 Gemini CLI 中執行 /mcp reload。
   • 在 Claude Code 中執行 /mcp，然後依序選取 toolbox 和 Reconnect。

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

生成及最佳化背景資訊

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

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

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

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

建立及擴充評估資料集

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

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

• 根據資料庫結構定義，生成候選問題和 SQL 組合。
• 使用篩選器變化版本、同義詞和改寫方式，擴充小型種子資料集。

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

資料集是 JSON 檔案，內含問題與 SQL 配對：

[
  {
    "id": "eval_001",
    "database": "<database_name>",
    "nlq": "How many hotels are in London?",
    "golden_sql": "SELECT COUNT(*) FROM `hotels` WHERE CAST(cf['location'] AS STRING) = 'London'",
    "tags": ["complexity: low", "topic: location_lookup", "source: generated:schema"]
  }
]

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

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

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

生成基準脈絡資料集

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

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

• 「根據我的結構定義生成脈絡資料集。」
• 「使用這些結構定義和 requirements.md 中的業務規則，生成初始情境。」

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

評估情境成效

建立情境集和黃金資料集後，您可以讓代理使用每個黃金問題查詢資料代理的 QueryData API，藉此評估情境效能。代理會使用 Evalbench 比較生成的 SQL 和執行結果與預期答案。

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

• 通過和失敗結果、匯總分數等量化指標，用於追蹤各個情境疊代的進度。
• 內嵌對話摘要和詳細 CSV 報表，會寫入實驗資料夾中的 eval_reports/ 目錄。

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

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

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

如要重新執行先前產生的評估設定，而不重新設定，請直接要求代理或叫用 CLI：

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

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

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

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

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

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

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

• 「分析上次評估結果的落差，並提出修正建議。」
• 「根據golden.json最佳化這個脈絡資料集。」

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

視需要建立特定情境項目

如果您已知道必要的結構定義，例如特定問題的範本、重複篩選器的 facet，或特定資料欄的值搜尋，手動編寫結構定義 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。」
• 「建立 airports.iata 的值搜尋。」

選取情境類型的理由

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

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

• 「我一直在多個查詢中編寫篩選器 departure_time BETWEEN '00:00:00' AND '06:00:00'。如何才能拍出最佳效果？」
• 「使用者會以自由格式文字描述航班狀態，我想將這些文字與 flights.status 比對。我該設定哪種價值搜尋？
• 「範本和面向有何差異？兩者的使用時機為何？」

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

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

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

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

後續步驟

• 進一步瞭解情境組合。
• 瞭解如何在 Bigtable Studio 建立或刪除情境集。
• 瞭解如何測試情境組合。