agent-platform-rag-engine-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Platform RAG Engine Management

Agent Platform RAG Engine 管理

This skill provides instructions on how to interact with Agent Platform RAG Engine using the Agent Platform Python SDK. You MUST use the

vertexai

Python SDK to perform RAG Engine operations, rather than raw REST calls or MCP tools, because this code is intended to be run by external clients.

本技能提供了如何使用Agent Platform Python SDK与Agent Platform RAG Engine交互的说明。您必须使用

vertexai

Python SDK执行RAG Engine操作，而不是原始REST调用或MCP工具，因为此代码旨在供外部客户端运行。

Phase 0: Environment Setup

阶段0：环境设置

CRITICAL: Before running any of the Python snippets below, you MUST ensure the environment is correctly initialized by following these steps:

Google Cloud Authentication: Authenticate with your Google Cloud credentials and configure active Application Default Credentials (ADC) for Agent Platform access:
bash
```
gcloud auth login
gcloud auth application-default login
```
Virtual Environment: Create and activate a dedicated virtual environment:
bash
```
python3 -m venv ~/rag_agent_venv
source ~/rag_agent_venv/bin/activate
```
Install Dependencies: Install the required Agent Platform SDKs:
bash
```
pip install google-cloud-aiplatform google-genai
```
Execution: Advise the user that every time they execute a Python snippet, they must ensure this virtual environment is activated first.

关键提示：在运行以下任何Python代码片段之前，您必须按照以下步骤确保环境已正确初始化：

Google Cloud身份验证：使用您的Google Cloud凭据进行身份验证，并为Agent Platform访问配置有效的应用默认凭据（ADC）：
bash
```
gcloud auth login
gcloud auth application-default login
```

虚拟环境：创建并激活专用虚拟环境：

bash

python3 -m venv ~/rag_agent_venv
source ~/rag_agent_venv/bin/activate

安装依赖：安装所需的Agent Platform SDK：
bash
```
pip install google-cloud-aiplatform google-genai
```
执行说明：告知用户每次执行Python代码片段时，必须确保先激活此虚拟环境。

Workflow Decision Tree

工作流决策树

Information Gathering: Has the user provided the Project ID, Region, and Corpus ID?
- No -> Proceed to [1. Listing Corpora and Files] to discover the necessary Resource Names and IDs. Only ask the user if discovery fails.
- Yes -> Proceed.
Task Type: What does the user want to do?
- List Corpora and Files -> Proceed to [1. Listing Corpora and Files].
- Inspect a Corpus -> Proceed to [2. Getting / Inspecting a RAG Engine Corpus].
- Search for Contexts -> Proceed to [3. Retrieving Contexts].
- Answer questions using RAG Engine -> Proceed to [4. Answering the User with Retrieved Context].

[!TIP] Placeholder Parameter Replacement: The Python scripts below use bracketed string placeholders (like
"{project_id}"
,
"{region}"
, and
"{corpus_id}"
). You MUST dynamically replace these placeholders with the actual Project ID, Region, and Corpus ID values provided in the user's prompt (or active context) before generating, providing, or executing the scripts.

信息收集：用户是否提供了项目ID、区域和语料库ID？
- 否 -> 进入[1. 列出语料库和文件]以查找必要的资源名称和ID。仅当查找失败时才询问用户。
- 是 -> 继续下一步。
任务类型：用户想要执行什么操作？
- 列出语料库和文件 -> 进入[1. 列出语料库和文件]。
- 检查语料库 -> 进入[2. 获取/检查RAG Engine语料库]。
- 搜索上下文 -> 进入[3. 检索上下文]。
- 使用RAG Engine回答问题 -> 进入[4. 基于检索到的上下文回答用户问题]。

[!TIP] 占位符参数替换：以下Python脚本使用带括号的字符串占位符（如
"{project_id}"
、
"{region}"
和
"{corpus_id}"
）。在生成、提供或执行脚本之前，您必须将这些占位符动态替换为用户提示（或当前上下文）中提供的实际项目ID、区域和语料库ID值。

1. Listing Corpora and Files (Discovery)

1. 列出语料库和文件（查找）

If you do not know the Resource Name of the corpus or file, you MUST list them first to discover them. The SDK handles pagination automatically when converted to a list, but you can also use manual pagination for large sets.

如果您不知道语料库或文件的资源名称，必须先列出它们进行查找。转换为列表时，SDK会自动处理分页，但对于大型数据集，您也可以使用手动分页。

1.1 Listing and Discovering Corpora

1.1 列出并查找语料库

python

import vertexai
from vertexai.preview import rag

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

python

import vertexai
from vertexai.preview import rag

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

Approach A: List ALL (Automatic Pagination)

方法A：列出所有（自动分页）

The SDK's Pager iterates through all pages for you.

SDK的Pager会为您遍历所有页面。

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}")

all_corpora = list(rag.list_corpora()) print(f"共找到 {len(all_corpora)} 个语料库。") for c in all_corpora: print(f"语料库名称: {c.name} | 显示名称: {c.display_name}")

Approach B: Manual Pagination (for very large projects)

方法B：手动分页（适用于超大型项目）

pager = rag.list_corpora(page_size=10)

Process first page

处理第一页

for c in pager: print(f"Corpus: {c.display_name}")

for c in pager: print(f"语料库: {c.display_name}")

Get next page if needed

如有需要，获取下一页

if pager.next_page_token: second_page = rag.list_corpora( page_size=10, page_token=pager.next_page_token )

undefined

if pager.next_page_token: second_page = rag.list_corpora( page_size=10, page_token=pager.next_page_token )

undefined

1.2 Listing and Discovering Files

1.2 列出并查找文件

To understand what files (and types) are in a corpus, list them and inspect the

display_name

(usually includes the extension).

python

import vertexai
from vertexai.preview import rag

vertexai.init(project="{project_id}", location="{region}")
corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)

要了解语料库中有哪些文件（及类型），请列出它们并检查

display_name

（通常包含文件扩展名）。

python

import vertexai
from vertexai.preview import rag

vertexai.init(project="{project_id}", location="{region}")
corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)

List files with automatic pagination

自动分页列出文件

files = list(rag.list_files(corpus_name=corpus_name)) print(f"Found {len(files)} files.")

for f in files: # High-level SDK RagFile objects usually have name, display_name, # description print(f"File: {f.display_name} | Resource: {f.name}") # Tip: Check extension to understand file type (PDF, TXT, etc.) if f.display_name.lower().endswith(".pdf"): print(" Type: PDF") elif f.display_name.lower().endswith(".txt"): print(" Type: Plain Text")

undefined

files = list(rag.list_files(corpus_name=corpus_name)) print(f"共找到 {len(files)} 个文件。")

for f in files: # 高级SDK RagFile对象通常包含name、display_name、description属性 print(f"文件: {f.display_name} | 资源: {f.name}") # 提示：通过扩展名判断文件类型（PDF、TXT等） if f.display_name.lower().endswith(".pdf"): print(" 类型: PDF") elif f.display_name.lower().endswith(".txt"): print(" 类型: 纯文本")

undefined

2. Getting / Inspecting an Agent Platform RAG Engine Corpus

2. 获取/检查Agent Platform RAG Engine语料库

To retrieve details about an existing Agent Platform RAG Engine corpus:

python

import vertexai
from vertexai.preview import rag

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

要检索现有Agent Platform RAG Engine语料库的详细信息：

python

import vertexai
from vertexai.preview import rag

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

To get details of a specific corpus

获取特定语料库的详细信息

corpus_name = ( "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}" ) corpus = rag.get_corpus(name=corpus_name) print(f"Corpus Name: {corpus.name}") print(f"Display Name: {corpus.display_name}")

undefined

corpus_name = ( "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}" ) corpus = rag.get_corpus(name=corpus_name) print(f"语料库名称: {corpus.name}") print(f"显示名称: {corpus.display_name}")

undefined

3. Retrieving Contexts

3. 检索上下文

To retrieve relevant contexts from a RAG Engine corpus based on a query:

python

import vertexai
from vertexai.preview import rag

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

corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)
query = "What is the speed of light?"

根据查询从RAG Engine语料库中检索相关上下文：

python

import vertexai
from vertexai.preview import rag

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

corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)
query = "光速是多少？"

Retrieve contexts

检索上下文

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}")

undefined

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

for context in response.contexts.contexts: print(f"上下文文本: {context.text}") print(f"来源: {context.source_uri}")

undefined

4. Answering the User with Retrieved Context

4. 基于检索到的上下文回答用户问题

To use the retrieved context alongside an Agent Platform model to generate a grounded response:

python

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}"
)

结合检索到的上下文和Agent Platform模型生成有依据的回答：

python

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}"
)

Define the Agent Platform RAG Engine tool pointing to the corpus

定义指向语料库的Agent Platform RAG Engine工具

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, ), ), ) ) )

Generate content using the RAG Engine tool

使用RAG Engine工具生成内容

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)

undefined

response = client.models.generate_content( model="gemini-2.5-flash", contents="光速是多少？", config=types.GenerateContentConfig( tools=[rag_tool] ) ) print(response.text)

undefined