使用脈絡工程代理建立及最佳化脈絡資料集

如要讓資料代理應用程式達到高 QueryData 查詢準確度和低線上延遲，可以使用脈絡工程代理建構、評估及最佳化脈絡資料集。代理會自動建立、上傳及最佳化情境，協助應用程式快速、確定且可解釋地回答自然語言問題。

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

只要為 QueryData 提供符合業務應用程式的情境，就能提供精確的業務規則，讓系統解析細微的使用者意圖，並提供近乎 100% 的查詢品質。在 CLI 或 IDE 中工作時，情境工程代理會自動將情境集上傳至 Google Cloud ，同時將本機檔案儲存在工作區中，以便控管版本。

脈絡工程代理

脈絡工程代理可直接在 CLI 或 IDE 中，扮演設計階段助理。手動編寫情境時，必須手動編寫詳細的查詢模式、預測各種措辭變化，並在反覆測試中手動診斷查詢失敗的原因。脈絡工程代理可引導基準脈絡、整理基準真相評估資料集、反覆修正準確度落差，並證明脈絡可泛化至新問題，進而消除這項負擔。

您可以使用自然語言與代理對話，推動最佳化工作流程。首先，請輸入提示，例如「根據我的應用程式需求，最佳化脈絡資料集」。

事前準備

使用脈絡工程代理前，請先完成下列各節所述的必要條件。您可以在 us-central1、us-east1、europe-west4 和 asia-southeast1 區域建立及儲存情境集，即使資料庫執行個體位於其他區域也沒問題。

啟用必要服務

為專案啟用下列服務：

準備資料庫

準備 PostgreSQL 適用的 Cloud SQL 執行個體，並設定代理程式的存取權：

必要角色和權限

如要取得使用情境工程代理和管理情境集的權限，請設定下列 Identity and Access Management (IAM) 角色和資料庫權限：

  • 將 IAM 使用者或服務帳戶新增至執行個體。詳情請參閱「使用 Cloud SQL 的 IAM 資料庫驗證功能管理使用者」。
  • 在專案層級，將 roles/cloudsql.instanceUser (如果您也會在 Cloud SQL Studio 測試查詢，則為 roles/cloudsql.studioUser)、roles/serviceusage.serviceUsageConsumer、roles/geminidataanalytics.queryDataUser 和 roles/mcp.toolUser 角色授予 IAM 使用者或服務帳戶。詳情請參閱「新增專案的 IAM 政策繫結」。
  • 如要建立、上傳及管理情境集，請在專案層級，將 Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 或 Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin) 角色授予 IAM 使用者或服務帳戶。詳情請參閱「情境組合權限」。
  • 如果您使用語意值搜尋 (google_ml.embedding)，請啟用 Vertex AI API，並將 roles/aiplatform.user 角色授予 PostgreSQL 適用的 Cloud SQL 執行個體服務帳戶。

  • 以具備超級使用者權限的使用者 (例如 postgres 使用者) 身分登入，將唯讀資料庫權限授予 IAM 使用者或服務帳戶：

    GRANT SELECT ON ALL TABLES IN SCHEMA public TO "USER_NAME";

    將 USER_NAME 替換為使用者的電子郵件地址 (如果是服務帳戶，請省略 . 尾碼)。使用者名稱含有特殊字元 (@ 和 .)，因此必須用引號括住。如果資料表位於 public 以外的自訂結構定義，請一併執行 GRANT USAGE ON SCHEMA SCHEMA_NAME TO "USER_NAME"; 和 GRANT SELECT ON ALL TABLES IN SCHEMA SCHEMA_NAME TO "USER_NAME";。詳情請參閱「將資料庫權限授予個別 IAM 使用者或服務帳戶」。

準備環境

您可以在本機開發環境或 IDE 中建構及最佳化情境集。

安裝 uv

脈絡工程代理需要 uv 來管理基礎 Python 套件：

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

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

    uv --version

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

在偏好的開發環境中，安裝情境工程代理外掛程式：

Antigravity CLI

  1. 安裝 Antigravity CLI。請參閱「開始使用 Antigravity CLI」。
  2. 安裝脈絡工程代理外掛程式： 
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. 啟動 Antigravity CLI： 
    agy

如要日後更新外掛程式，請先執行 agy plugin uninstall db-context-engineering，再執行 agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin。

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

如要日後更新外掛程式，請執行 /plugin update db-context-engineering@db-context-enrichment-marketplace。

Gemini CLI (已淘汰)

  1. 安裝 Gemini CLI。請參閱「開始使用 Gemini CLI」。
  2. 安裝擴充功能： 
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

如要日後更新擴充功能，請執行 gemini extensions update google-cloud-db-context-engineering。

使用 Google Cloud進行驗證

  1. 設定應用程式預設憑證 (ADC)，驗證開發環境：

    gcloud auth application-default login

  2. 為憑證設定配額專案，讓 Model Context Protocol (MCP) 工具可以使用您的 Google Cloud 專案：

    gcloud auth application-default set-quota-project PROJECT_ID

    將 PROJECT_ID 替換為 Google Cloud 專案 ID。

連線至資料庫

  1. 啟動代理環境，並要求代理建立資料庫連線 (例如「幫我設定資料庫連線」)。代理會引導您建立 .context-engineering/tools.yaml 設定檔，以便讀取結構定義及驗證 SQL。(在建立 .context-engineering/tools.yaml 之前，啟動時會出現初始 toolbox MCP 伺服器連線警告，這是正常現象)。

  2. 重新載入 MCP 伺服器連線，套用 .context-engineering/tools.yaml 設定：

    • Antigravity CLI：執行 /mcp 並選取 toolbox (或 db-context-engineering_toolbox) 即可重新啟動。
    • Claude Code：執行 /mcp，依序選取 toolbox 和 Reconnect。
    • Gemini CLI：執行 /mcp refresh (或 /mcp reload)。

建立及最佳化情境

脈絡工程代理會引導脈絡集完成端對端生命週期，從初始啟動到驗證一般化。

啟動基準脈絡資料集

為避免從空白頁面建立背景資訊，代理會檢查資料庫結構定義，以及任何可用的應用程式構件，例如業務需求、說明文件或 SQL 查詢範例。代理會依據資料庫模型，衍生出初始基準情境集，其中包含基礎查詢範本和查詢面向。

生成並驗證基準情境後，代理會直接將其上傳至 Google Cloud ，並傳回情境集資源名稱。

使用應用程式構件建立評估和保留資料集

如要系統性地提高準確度，您需要基準真相問題，並搭配經過驗證的 SQL 查詢。如果尚未建立評估基準，代理可以從應用程式程式碼、歷來查詢和資料庫結構定義中擷取業務情境，藉此生成基準。

生成資料集時，代理會建立兩個不同的集合：

  • 訓練基準：在疊代最佳化過程中，使用的一組代表性問題 SQL 配對。
  • 保留資料集：一組獨立的問題，領域與訓練基準類似，保留用於測試一般化能力。

使用爬山演算法提高準確度

在登山法最佳化中，代理會反覆調整情境集，將 QueryData 準確率提升至近乎 100%：

  • 評估：代理會使用 QueryData API 測試目前的脈絡資料集，並根據訓練基準評估準確度。
  • 診斷落差：代理會分析查詢失敗的原因，找出根本原因 (例如缺少資料表彙整、未連結的私人實體，或複雜的篩選條件)，並制定針對性的修正措施。
  • 修正及上傳：代理會新增或改善查詢範本、查詢面向和值搜尋，解決落差，並自動從 CLI 將更新後的背景資訊集上傳至 Google Cloud 。
  • 反覆執行：代理會反覆執行這個循環，直到準確度收斂至最佳分數。

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

反覆建構背景資訊的工作流程。

使用保留資料集證明一般化

在訓練基準上達到高準確度是必要條件，但實際工作環境流量包含開發期間未曾出現的各種措辭和複雜複合問題。

爬坡最佳化收斂後，代理會根據保留資料集測試產生的情境集。這個步驟可驗證情境設定是否能妥善歸納新的使用者輸入內容，而不會過度擬合初始基準。代理會產生一般化報表，顯示未見過的問題變化版本和複合篩選器的準確度 (例如「幫我找德爾馬靠近好學校、適合新手家庭且有海景的住宅」)。

隨選撰寫和推論

除了執行完整最佳化作業，您也可以與代理對話，根據業務需求變化進行特定更新：

  • 指定編寫：以自然語言描述特定業務需求，代理就會設定情境項目格式，並直接從 CLI 上傳，不需手動編輯：

    • 「建立範本：『尋找德爾馬靠近好學校的住宅』，SQL：SELECT p.property_id, p.address FROM properties AS p JOIN schools AS s ON p.school_id = s.school_id WHERE p.city = 'Del Mar' AND s.rating >= 7。」
    • 「為篩選器 properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500 建立一個標示為『適合小家庭』的 facet。」
    • 「建立 properties.city 的值搜尋。」

  • 大量更新情境集：如果資料庫資料欄重新命名或資料表結構變更，代理可以同時更新所有受影響的情境項目，而不修改不相關的項目：

    • 「在我的情境組合中，將所有參照獨棟住宅的項目中的『properties.property_type = 'SFR'』替換為『properties.property_type = 'Single Family Residential'』。不要理會不相關的項目。

後續步驟