企业官网建设流程全解析

Auto RAG Eval 实战：基于 Vertex AI Agent Platform 与 Gemini 自动化生成 RAG 评测基准

【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai

Auto RAG Eval 是 Google Cloud 生成式 AI 示例仓库（generative-ai）中一套自动化基准生成工具，它利用 Vertex AI Agent Platform（Discovery Engine）文档检索能力与 Gemini 模型的结构化输出能力，从你的文档语料库中自动产出高质量、覆盖面广的 RAG 问答对。读完本文，你将掌握 Benchmark Generator 与 Benchmark Transformer 的完整使用流程、全部命令行参数、内部多阶段流水线原理，以及如何自定义 Q&A 生成维度，让评测基准从"人工编写数周"变为"自动化生成数小时"。

一、这是什么：一次认清两个核心组件

Auto RAG Eval 的定位是"面向 RAG 系统的自动化评测基准生成器"，它由两个组件构成：

• Benchmark Generator（main.py）：核心组件，从 Vertex AI Agent Platform 数据存储中的文档生成 Q&A 问答对，是本文讲解的主体；
• Benchmark Transformer（transform_benchmark.py）：辅助工具，把生成的基准转换为兼容评估框架（如 Google Agent Development Kit，ADK）的格式。

两者代码均位于仓库 search/auto-rag-eval/ 目录下，依赖声明见 requirements.txt。

二、为什么要用自动化基准生成

2.1 人工构建基准的痛点

• 耗时巨大：手工为 RAG 系统构建高质量基准，往往需要数周甚至数月；
• 覆盖缺口：人工编写的基准常遗漏边界情况，无法系统覆盖整个文档语料；
• 难以扩展：随着文档库不断增长，维护相关基准的难度持续上升；
• 一致性差：缺少标准化基准，RAG 系统性能难以被一致、可复现地评估。

2.2 Auto RAG Eval 的解法

• 自动化生成：数小时产出数百个 Q&A 对，取代数周的人工劳动；
• 全面覆盖：系统性地对文档与分块（chunk）进行采样，覆盖整个语料库；
• 多阶段质量控制：多个 AI 评审（critic）逐对校验 Q&A，达成共识后才放行；
• 可扩展架构：适配任意规模的 Vertex AI Agent Platform 数据存储；
• 格式灵活：可将基准转换为不同评估框架所需的各种格式。

三、快速上手（TL;DR）

在准备好 GCP 环境的前提下，六步即可产出第一批基准：

# 1. 安装依赖 pip install -r requirements.txt # 2. 从 Google Cloud Storage 下载必需的 qa_profiles.json gcloud storage cp gs://github-repo/search/auto-rag-eval/qa_profiles.json . # 3. 配置环境变量（编辑 .env） # - PROJECT_ID=your-gcp-project-id # - LOCATION=us-central1 # - DATA_STORE_ID=your-datastore-id # 4. 完成 Google Cloud 认证 gcloud auth application-default login # 5. 生成基准（示例为小规模试跑参数） python main.py --docs 2 --chunks 2 --clues 2 --profiles 2 # 6.（可选）转换为评估框架格式 python transform_benchmark.py benchmark.json converted_benchmark.json

完成后，Q&A 对将写入benchmark.json。

需要说明的是：README 中提到的exemplary_docs/、qa_profiles.json、benchmark.json、env_example等文件托管在 Google Cloud Storage（gs://github-repo/search/auto-rag-eval/）上，并不在仓库目录中。qa_profiles.json缺失时，main.py会自动尝试从 GCS 下载；exemplary_docs中的示例文档则需你自行上传到数据存储中用于验证。

四、环境准备（Prerequisites）

4.1 Google Cloud 项目与 API

需要启用以下 API：

• Vertex AI Agent Platform API；
• Discovery Engine API（Vertex AI Agent Platform 底层检索能力）；
• Cloud Storage API。

4.2 认证

# 配置 Application Default Credentials gcloud auth application-default login

从源码看，llm_utils.py中通过 get_client() 使用genai.Client(vertexai=True, project=project_id, location=location)创建 Gemini 客户端，检索侧则由 vertex_search_utils.py 中的DocumentServiceClient、SearchServiceClient、ChunkServiceClient承载，这些客户端都依赖默认凭据完成鉴权。

4.3 创建并填充 Vertex AI Agent Platform 数据存储

1. 在 Google Cloud Console 中进入AI Applications；
2. 为你的应用新建数据存储；
3. 配置解析器：选择Digital Parser或Layout Parser（README 中的示例数据在摄取时启用了 Layout Parser 并开启 LLM 特性用于表格与图片标注）；
4. 启用高级分块配置（Advanced Chunking Configuration）：
   • ✓ 勾选"Include ancestor headings in chunks"（在分块中附带祖先标题）；
   • 其余设置保持默认；
5. 摄取自由文本文档进入数据存储；
6. 从控制台复制 DATA_STORE_ID；
7. 将DATA_STORE_ID写入.env文件。

之后把exemplary_docs中的文档上传到数据存储（文件位于gs://github-repo/search/auto-rag-eval/）。勾选"Include ancestor headings"至关重要：它会让每个分块携带所在章节的标题层级，为后续 Clue 生成和检索上下文提供更完整的语义信息。

4.4 Python 环境

pip install -r requirements.txt

依赖覆盖四个维度（见 requirements.txt）：

• Google Cloud 套件：google-cloud-aiplatform>=1.38.0、google-cloud-storage>=2.10.0、google-cloud-discoveryengine>=0.11.0、google-genai>=1.0.0、vertexai>=1.38.0；
• 数据处理：pandas>=2.0.0；
• 环境管理：python-dotenv>=1.0.0；
• 其余json、re、time、random、argparse等均为 Python 标准库，无需安装。

4.5 必需文件

• qa_profiles.json：Q&A 生成配置档，从 GCS 下载（命令见快速开始）；
• .env：由env_example复制生成。

五、分步使用指南

Step 1：配置环境变量

cp env_example .env # 编辑以下值 PROJECT_ID=your-gcp-project-id LOCATION=us-central1 DATA_STORE_ID=your-data-store-id

main.py的 main() 会先load_dotenv()，再以"命令行参数优先、环境变量兜底"的方式解析三项配置：--project-id覆盖PROJECT_ID，--location覆盖LOCATION（默认us-central1），--data-store-id覆盖DATA_STORE_ID。若PROJECT_ID与DATA_STORE_ID均缺失，程序会直接报错退出。

Step 2：生成基准

默认运行：

python main.py

自定义参数运行：

python main.py \ --docs 5 \ --chunks 3 \ --clues 2 \ --profiles 2 \ --chunks-to-merge 3 \ --output-file my_benchmark.json \ --qa-profiles-file custom_profiles.json

完整参数表（与 main.py 的 _parse_args() 逐一对应）：

注意--top-k-chunks与--neighbour-chunks的差异：前者控制"检索返回多少条结果"，后者控制"每条结果周围额外拼接多少个相邻分块"。例如--neighbour-chunks 1时，检索命中块会连同其前后各 1 个分块一起合并成更完整的上下文（见下文 Chunk 增强细节）。

Step 3：转换基准（可选）

生成完成后，可将基准转换为 ADK 等评估框架可消费的格式：

python transform_benchmark.py benchmark.json converted_bench.json

命令行参数（与 transform_benchmark.py 一致）：

• 第一个参数：输入基准文件路径；
• 第二个参数：输出文件路径；
• 可选--indent：JSON 缩进级别（默认2）。

Auto RAG Eval 源格式：

{ "context": "...", "Q&A Gen Profile": {...}, "Question": "...", "Answer": "..." }

转换后的 ADK 评估格式：

{ "query": "...", "expected_tool_use": [], "reference": "..." }

字段映射规则清晰记录在脚本 docstring 中：query ← Question，reference ← Answer，expected_tool_use置空列表。实现上 transform_benchmark_data() 会逐条检查Question与Answer字段是否存在，缺失的记录会告警跳过并统计数量；输入文件不存在、JSON 解析失败、数据非数组等场景都有明确的错误退出分支。

六、架构与流水线原理

6.1 系统架构

Auto RAG Eval 是一个多阶段流水线，编排了多个 AI 模型与云服务：

┌─────────────────────────┐ │ Vertex AI Agent Platform│ │ (Document Store) │ └───────────┬─────────────┘ │ ▼ ┌─────────────────────────┐ ┌─────────────────────┐ │ Document Selection │────▶│ Chunk Processing │ │ - List all documents │ │ - Retrieve chunks │ │ - Random sampling │ │ - Merge chunks │ └─────────────────────────┘ └──────────┬──────────┘ │ ▼ ┌─────────────────────┐ │ Clue Generation │ │ - Identify topics │ │ - Generate question│ └──────────┬──────────┘ │ ▼ ┌─────────────────────────┐ ┌─────────────────────┐ │ Context Retrieval │────▶│ Context Distillation│ │ - Search with clues │ │ - Relevance filter │ │ - Find related chunks │ │ - Extract focused │ └─────────────────────────┘ │ content │ └──────────┬──────────┘ │ ▼ ┌─────────────────────────┐ ┌─────────────────────┐ │ Q&A Profile Generation │────▶│ Q&A Generation │ │ - Analyze context │ │ - Create Q&A pairs │ │ - Suggest profiles │ │ - Self-contained │ └─────────────────────────┘ └──────────┬──────────┘ │ ▼ ┌─────────────────────────┐ ┌─────────────────────┐ │ Multi-Agent Review │────▶│ Incremental Saving │ │ - 3 AI critics │ │ - Immediate save │ │ - Consensus decision │ │ - JSON output │ └─────────────────────────┘ └─────────────────────┘

6.2 数据流

• 输入：Vertex AI Agent Platform 数据存储中的文档；
• 处理链：Documents → Chunks → Clues → Retrieved Contexts → Distilled Context → Profiles → Q&As；
• 输出：含已验证 Q&A 对的 JSON 文件。

6.3 各阶段详解（含源码级实现）

1. Document Selection（文档选择）通过DocumentServiceClient.list_documents列出数据存储中的全部文档（list_documents_in_datastore()），再用rng.sample随机抽取指定数量，保证对语料库的多样性覆盖。main.py中随机源选用的是加密安全的random.SystemRandom()。

2. Chunk Processing（分块处理）对每篇文档，先用ChunkServiceClient.list_chunks拉取全部分块（list_chunks_for_document()），再由 merge_chunks_into_bigger_chunks() 按--chunks-to-merge（默认 3）把连续分块拼接成更大块，以提供更完整的上下文；合并块会记录chunk_ids、chunk_count与跨分页的page_span。随后随机采样指定数量的合并块进入下一阶段。

3. Clue Generation（线索生成）clue_generator() 基于分块文本让 Gemini 生成"线索"（潜在问题），提示词严格要求：问题只能依据给定文本回答、不得借助外部知识，且需直接相关、覆盖主要主题、独立自足。输出通过Gemini 结构化输出（response_mime_type="application/json"+ Pydantic schemaClueResponse）约束为questions: list[QuestionClue]，其中每个QuestionClue还包含chain_of_thought（该问题为何相关且可回答的推理）。之后rng.sample随机选取--clues个线索。

4. Context Retrieval（上下文检索）先由 targeted_information_seeking() 对线索做三步增强：描述相关文本类型、改写为清晰问题、生成 50-100 词的假设性示例（HyDE 风格）。随后 search_with_chunk_augmentation() 以改写后的问题发起 Discovery Engine 语义搜索，设置SearchResultMode.CHUNKS分块结果模式，并按--neighbour-chunks拼接命中块的前后相邻分块，最终把"previous + relevant + next"各块内容合并为augmented_content作为生成上下文。main.py当前取第一个结果（search_results[0]["augmented_content"]）作为上下文；若检索无结果则跳过该线索。

5. Context Distillation（上下文蒸馏）按 README 的设计意图，该阶段从检索到的上下文中提取最相关的部分，同时进行单块级与整篇文档级的相关性评估，过滤无关信息后聚合形成聚焦上下文。这是保证"问题可答、答案有据"的关键过滤环节。

6. Q&A Profile Generation（Profile 生成）从qa_profiles.json中读取可定制维度（默认维度：Type、Persona、Scope、Difficulty），为每个上下文随机组合一组维度取值生成 Profile。实现位于 _build_random_profile()：遍历每个维度，从取值集合中随机选一个值，并把取值描述与name一并注入 profile。

7. Q&A Generation（问答生成）generate_qa_pair() 把蒸馏后的上下文与随机 Profile 交给 Gemini，要求"问题匹配 profile 的类型、角色与难度，答案仅基于给定上下文"，输出由QAPairschema 约束为{question, answer}。

8. Multi-Agent Review 与增量保存review_qa_pair() 以指定 critic 角色（如Analyst）对 Q&A 对做准确性、清晰度与相关性评审，返回APPROVED/REJECTED及理由。当前仓库实现中简化为一轮单 critic 评审（源码注释标明"Simplified review: just use one critic for now"），READM 描述的多 critic 共识机制是其设计蓝图。通过评审的条目立即由 save_qa_incrementally() 追加写入输出文件——每次读取既有 JSON 列表、追加新条目并整体写回，保证任意时刻进程中断都不丢失已生成的成果。

6.4 关键设计决策

1. 增量处理：每条 Q&A 通过即落盘，防止数据丢失；
2. 多阶段相关性评估：单块与聚合两级评估，保证上下文完整聚焦；
3. 共识式评审：多个 AI critic 保障输出质量；
4. 灵活 Profile：通过外部 JSON 配置自定义 Q&A 维度；
5. 重试机制：API 调用带指数退避的自动重试，提升容错性；
6. 进度追踪：控制台以[LOGGING]前缀输出详细日志。

6.5 API 集成点

• Vertex AI Agent Platform：文档列举、分块检索、语义搜索（经 Discovery EngineSearchServiceClient）；
• Gemini 模型：Clue 生成、Profile 建议、Q&A 生成、评审（经genai.Client的generate_content+ Pydantic 结构化输出）；
• Google Cloud Storage：qa_profiles.json下载（download_from_gcs()）与文档存储；
• Discovery Engine API：核心搜索与检索能力。

七、示例数据与输出

仓库文档说明其附带的示例文档为三份关于 Google AI 智能体的 PDF（托管于 GCS，不在仓库内）：

• input_2_ai-responsibility-update-published-february-2025.pdf：Google AI 责任更新；
• input_2_exec_guide_gen_ai.pdf：生成式 AI 高管指南；
• input_2_google-about-generative-ai.pdf：Google 生成式 AI 概述。

这些文档以如下设置摄取进数据存储：启用 LLM 特性（表格与图片标注）、摄取时开启Layout Parser，数据存储 ID 配置在示例 env 文件中。

基于这些文档生成的基准包括：原始输出benchmark.json（含 15 个 Q&A 对）与转换后的converted_benchmark.json。

八、输出格式

Auto RAG Eval 基准格式（benchmark.json）：

[ { "context": "The distilled context used for Q&A generation", "Q&A Gen Profile": { "type": "How-to", "persona": "The Expert", "scope": "Whole", "difficulty": "Hard" }, "Question": "The generated question", "Answer": "The generated answer" } ]

ADK 格式（转换后）：

[ { "query": "The generated question", "expected_tool_use": [], "reference": "The generated answer" } ]

注意：save_qa_incrementally()在落盘前会做字段归一化——把内部"distilled context:"、"qa gen profile:"、"qa:"嵌套结构转换为 README 文档所述的context、Q&A Gen Profile、Question、Answer平铺结构，并通过convert_to_serializable()递归清洗 Pydantic 对象与MappingProxyType，确保 JSON 可序列化。

九、自定义 Q&A Profiles

qa_profiles.json是 Q&A 生成的配置中枢，支持灵活维度处理：

可定制项

1. 维度名称：可重命名（如Type→QuestionType、Persona→AudienceLevel）；
2. 维度数量：可增删维度（至少保留 1 个维度）；
3. 维度取值：可增删改每个维度下的取值；
4. 取值描述：可自定义每个取值的说明。

结构要求

唯一要求是维持以下 JSON 结构（脚本会自动校验）：

{ "parameters": { "YourDimensionName": { "description": "Description of this dimension", "values": { "ValueName1": {"description": "Description of this value"}, "ValueName2": {"description": "Description of this value"} } } } }

自定义维度示例

{ "parameters": { "Domain": { "description": "Subject area", "values": { "Technical": {"description": "Technical documentation"}, "Business": {"description": "Business processes"} } } } }

定制步骤

1. 按你的维度与取值编辑qa_profiles.json；
2. 运行基准生成器——脚本会自动适配新结构（main.py 的 _build_random_profile() 遍历parameters下所有维度逐维随机取值）；
3. 脚本会校验结构，并直接使用你提供的维度。

使用注意

qa_profiles.json缺失时脚本会尝试从 GCS 下载，下载失败则打印提示（当前实现会直接返回）。README 还强调：尽管具备多阶段质量控制与多 agent 评审，生成的基准仍应被视为起点而非终稿。建议由熟悉业务领域的领域专家人工复核，尤其对安全敏感或高度专业的领域要格外审慎，并抽样人工检查生成对的质量。工具的价值是"加速基准创建"，而非替代人的专业判断。

十、监控与故障排查

日志

• 控制台输出中查找[LOGGING]前缀跟踪执行进度；
• 每个函数的进入/退出均有日志（如Processing document: {doc['id']}、Successfully saved Q&A #N to ...）；
• API 重试尝试会连同错误详情一并记录。

常见问题

1. 认证错误：

   gcloud auth application-default login

2. API 限流：调整代码中的延时、降低并发处理量；
3. 输出为空：检查DATA_STORE_ID是否正确、文档是否已正常摄取、API 权限是否具备；
4. 内存问题：一次处理更少的文档、减小分块合并规模；
5. 缺少 qa_profiles.json：确认文件与脚本同目录；缺失时脚本会尝试自动下载。

结语

Auto RAG Eval 把"文档 → 分块 → 线索 → 检索 → 蒸馏 → Profile → Q&A → 评审"这条多阶段流水线固化成了两个可直接运行的 Python 脚本，配合 Gemini 的结构化输出与 Discovery Engine 的分块检索，为 RAG 系统的持续评测提供了一条可重复、可扩展、覆盖面广的基准生产路径。在此基础上，你可以通过qa_profiles.json自由塑造题目难度、角色与视角，再借transform_benchmark.py把成果无缝接入 ADK 等评估框架——让评测基准真正成为 RAG 系统迭代的"质量标尺"。

【免费下载链接】generative-aiSample code and notebooks for Generative AI on Google Cloud, with Gemini Enterprise Agent Platform项目地址: https://gitcode.com/GitHub_Trending/ge/generative-ai