前言¶

企業裏做問答、知識庫助手，往往要把文檔灌進 RAG 語料庫，再查有哪些 corpus、裏面有哪些文件、檢索片段是否命中，最後用模型做 grounded 生成。這些步驟分散在 Vertex AI SDK、資源名規則和 GenAI 調用之間，Agent 很容易拼錯 projects/.../ragCorpora/... 或混用不合適的 API。

下面介紹 Google 官方倉庫裏的 agent-platform-rag-engine-management Skill（當前 metadata 版本 1.0.1）。它把「發現語料庫 → 查看詳情 → 檢索上下文 → 可選的 grounded 生成」寫成固定工作流，並規定必須用 vertexai Python SDK，而不是裸 REST 或 MCP。

這是什麼¶

• 定位：管理與查詢 Agent Platform RAG Engine 的 Corpora，並用 Google GenAI SDK 檢索 grounding 內容、在指定 corpus 上生成 grounded 回答。
• 維護方：Google，收錄於 google/skills 的 AI/ML 類 Skill。
• 適用對象：已在 Google Cloud 上使用 Agent Platform RAG Engine、希望由編碼 Agent 按官方步驟執行運維與檢索的開發者。
• 明確不覆蓋：標準數據庫查詢（應使用 SQL/Spanner 相關 Skill）、Google Workspace RAG、以及 gRAG 等其他 RAG 產品。

Skill 正文說明：操作應由外部客戶端執行，因此 必須 通過 Agent Platform Python SDK（vertexai）完成 RAG Engine 相關調用。

核心功能¶

Skill 按任務類型組織能力，與官方描述一致：

工作流決策上：若用戶未提供 Project ID、Region、Corpus ID，應先做「列舉 corpora / files」做發現；已知 ID 則按任務直接進入對應章節。腳本中的 {project_id}、{region}、{corpus_id} 佔位符必須在執行前替換爲真實值。

安全與確認分級（Agent 必遵守）¶

官方將操作分爲兩級，寫 Skill 的 Agent 在執行前要對齊：

1. Tier R（只讀）：list_corpora、list_files、get_corpus、retrieval_query — 無需確認，可直接執行。
2. Tier RC（只讀但消耗計算）：client.models.generate_content 的 grounded 生成 — 必須先交互確認（Yes/No），且須列出 Target Corpus ID、Target Model、Query Text 等確切參數；不得在同一輪對話裏先彈確認又立刻執行，須等用戶明確同意後再跑代碼。

安裝與啓用¶

Skill 隨 Google 官方 Skills 倉庫分發，安裝方式以倉庫 README 爲準：

npx skills add google/skills

按提示選擇要安裝的 Skill（可只選 Agent Platform RAG Engine Management）、目標 Agent 以及作用域（項目或全局）。環境若無 npx，需先安裝 Node.js。更新已安裝 Skill：

npx skills update

Skill 源碼目錄：

https://github.com/google/skills/tree/main/skills/cloud/agent-platform-rag-engine-management

本文未覈實 Cursor、Codex CLI、Claude Code 各自的 Skill 掛載差異，僅以 npx skills add 爲準。

環境準備（Phase 0）¶

在運行 Skill 中的 Python 片段前，先做認證與依賴準備。

1. Google Cloud 認證（配置 Application Default Credentials）：

gcloud auth login
gcloud auth application-default login

2. Python 依賴：需要 google-cloud-aiplatform 與 google-genai。Skill 建議直接運行腳本；若報 ModuleNotFoundError，再在同一條命令裏安裝並重試：

pip install -q google-cloud-aiplatform google-genai && python3 - <<'PY'
# 你的腳本
PY

3. 執行方式：推薦 python3 - <<'PY' ... PY 的 heredoc，避免 python3 -c 引號嵌套問題。多步操作（例如先 list corpora 再 list files）應合併爲一次腳本、一次命令。stderr 上出現 vertexai.preview.rag 的 deprecation 警告可忽略，仍按 Skill 中的 preview API 使用。

典型用法¶

初始化與語料庫資源名¶

所有示例先 vertexai.init(project="{project_id}", location="{region}")。單個 corpus 的資源名格式爲：

projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}

1. 發現 corpora 與文件¶

不知道 corpus 或 file 的 Resource Name 時，必須先列舉。自動分頁示例：

import vertexai
from vertexai.preview import rag

vertexai.init(project="{project_id}", location="{region}")

all_corpora = list(rag.list_corpora())
print(f"Found {len(all_corpora)} corpora in total.")
for c in all_corpora:
    print(f"Corpus Name: {c.name} | Display Name: {c.display_name}")

針對某一 corpus 列舉文件：

corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)
files = list(rag.list_files(corpus_name=corpus_name))
for f in files:
    print(f"File: {f.display_name} | Resource: {f.name}")

2. 查看語料庫詳情¶

corpus = rag.get_corpus(name=corpus_name)
print(f"Corpus Name: {corpus.name}")
print(f"Display Name: {corpus.display_name}")

3. 檢索上下文（不調用生成模型）¶

根據自然語言 query 從 corpus 拉取相關片段；若無命中，向用戶說明使用的 corpus 與 query。可在同一腳本內嘗試調大 similarity_top_k：

response = rag.retrieval_query(
    rag_corpora=[corpus_name],
    text=query,
    similarity_top_k=3,
)

for context in response.contexts.contexts:
    print(f"Context text: {context.text}")
    print(f"Source: {context.source_uri}")

4. 基於語料庫的 grounded 生成¶

使用 google.genai 客戶端，將 RAG Engine corpus 配置爲 VertexRagStore 工具，再 generate_content。此步屬於 Tier RC，Agent 須先按 Skill 要求完成參數確認，再在下一輪執行：

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="{project_id}", location="{region}")
corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)

rag_tool = types.Tool(
    retrieval=types.Retrieval(
        vertex_rag_store=types.VertexRagStore(
            rag_resources=[types.VertexRagStoreRagResource(rag_corpus=corpus_name)],
            rag_retrieval_config=types.RagRetrievalConfig(
                top_k=3,
                filter=types.RagRetrievalConfigFilter(
                    vector_similarity_threshold=0.5,
                ),
            ),
        )
    )
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="What is the speed of light?",
    config=types.GenerateContentConfig(tools=[rag_tool]),
)
print(response.text)

官方示例中的模型名爲 gemini-2.5-flash；確認生成時 Skill 示例使用 gemini-2.5-pro 作爲說明模板，實際以你確認的模型爲準。

適用場景與注意¶

適合誰

• 已在 Agent Platform 上創建 RAG Engine corpus，需要 Agent 幫忙做資源發現、文件清單、檢索抽檢和 grounded 問答原型。
• 希望統一走 vertexai.preview.rag + GenAI SDK，避免 Agent 自行拼湊 REST 或誤用其他 RAG 產品 Skill。

限制與坑

• 依賴有效的 GCP 項目、區域與 IAM；未配置 ADC 時腳本會認證失敗。
• Grounded 生成會產生推理費用，Skill 強制二次確認，人工也應覈對 corpus 與 query，避免誤用生產語料。
• 不要用本 Skill 替代 Spanner/SQL、Workspace RAG 或 gRAG 場景。
• Sandbox 若自帶上述 Python 包，Skill 明確不建議新建空虛擬環境，以免看不到預裝依賴。

結尾¶

agent-platform-rag-engine-management 把 Agent Platform RAG Engine 的列舉、檢查、檢索與 grounded 生成收斂成可復現的 SDK 步驟，並區分只讀與耗算力操作。若你正在用 Google Cloud 企業 Agent 與 RAG Engine，可通過官方 Skills 安裝後交給 Agent 按正文執行。

官方地址：https://github.com/google/skills/tree/main/skills/cloud/agent-platform-rag-engine-management