尧图网站建设 
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-aiAuto RAG Eval 是 Google Cloud 生成式 AI 示例仓库generative-ai中一套自动化基准生成工具它利用 Vertex AI Agent PlatformDiscovery Engine文档检索能力与 Gemini 模型的结构化输出能力从你的文档语料库中自动产出高质量、覆盖面广的 RAG 问答对。读完本文你将掌握 Benchmark Generator 与 Benchmark Transformer 的完整使用流程、全部命令行参数、内部多阶段流水线原理以及如何自定义 QA 生成维度让评测基准从人工编写数周变为自动化生成数小时。一、这是什么一次认清两个核心组件Auto RAG Eval 的定位是面向 RAG 系统的自动化评测基准生成器它由两个组件构成Benchmark Generatormain.py核心组件从 Vertex AI Agent Platform 数据存储中的文档生成 QA 问答对是本文讲解的主体Benchmark Transformertransform_benchmark.py辅助工具把生成的基准转换为兼容评估框架如 Google Agent Development KitADK的格式。两者代码均位于仓库 search/auto-rag-eval/ 目录下依赖声明见 requirements.txt。二、为什么要用自动化基准生成2.1 人工构建基准的痛点耗时巨大手工为 RAG 系统构建高质量基准往往需要数周甚至数月覆盖缺口人工编写的基准常遗漏边界情况无法系统覆盖整个文档语料难以扩展随着文档库不断增长维护相关基准的难度持续上升一致性差缺少标准化基准RAG 系统性能难以被一致、可复现地评估。2.2 Auto RAG Eval 的解法自动化生成数小时产出数百个 QA 对取代数周的人工劳动全面覆盖系统性地对文档与分块chunk进行采样覆盖整个语料库多阶段质量控制多个 AI 评审critic逐对校验 QA达成共识后才放行可扩展架构适配任意规模的 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_IDyour-gcp-project-id # - LOCATIONus-central1 # - DATA_STORE_IDyour-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完成后QA 对将写入benchmark.json。需要说明的是README 中提到的exemplary_docs/、qa_profiles.json、benchmark.json、env_example等文件托管在 Google Cloud Storagegs://github-repo/search/auto-rag-eval/上并不在仓库目录中。qa_profiles.json缺失时main.py会自动尝试从 GCS 下载exemplary_docs中的示例文档则需你自行上传到数据存储中用于验证。四、环境准备Prerequisites4.1 Google Cloud 项目与 API需要启用以下 APIVertex AI Agent Platform APIDiscovery Engine APIVertex AI Agent Platform 底层检索能力Cloud Storage API。4.2 认证# 配置 Application Default Credentials gcloud auth application-default login从源码看llm_utils.py中通过 get_client() 使用genai.Client(vertexaiTrue, projectproject_id, locationlocation)创建 Gemini 客户端检索侧则由 vertex_search_utils.py 中的DocumentServiceClient、SearchServiceClient、ChunkServiceClient承载这些客户端都依赖默认凭据完成鉴权。4.3 创建并填充 Vertex AI Agent Platform 数据存储在 Google Cloud Console 中进入AI Applications为你的应用新建数据存储配置解析器选择Digital Parser或Layout ParserREADME 中的示例数据在摄取时启用了 Layout Parser 并开启 LLM 特性用于表格与图片标注启用高级分块配置Advanced Chunking Configuration✓ 勾选Include ancestor headings in chunks在分块中附带祖先标题其余设置保持默认摄取自由文本文档进入数据存储从控制台复制 DATA_STORE_ID将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.txtGoogle Cloud 套件google-cloud-aiplatform1.38.0、google-cloud-storage2.10.0、google-cloud-discoveryengine0.11.0、google-genai1.0.0、vertexai1.38.0数据处理pandas2.0.0环境管理python-dotenv1.0.0其余json、re、time、random、argparse等均为 Python 标准库无需安装。4.5 必需文件qa_profiles.jsonQA 生成配置档从 GCS 下载命令见快速开始.env由env_example复制生成。五、分步使用指南Step 1配置环境变量cp env_example .env # 编辑以下值 PROJECT_IDyour-gcp-project-id LOCATIONus-central1 DATA_STORE_IDyour-data-store-idmain.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() 逐一对应参数作用默认值--project-id覆盖.env中的 PROJECT_ID取自.env--location覆盖.env中的 LOCATIONus-central1--data-store-id覆盖.env中的 DATA_STORE_ID取自.env--docs处理的文档数量2--chunks每篇文档处理的分块数量2--clues每个分块生成的线索问题数量2--profiles每个线索生成的 QA Profile 数量2--chunks-to-merge合并为更大分块时合并的块数3--output-file输出 JSON 文件名benchmark.json--qa-profiles-file自定义 QA Profiles JSON 路径脚本目录下的qa_profiles.json--llm-model使用的 LLM 模型gemini-3.5-flash--top-k-chunks上下文检索时取回的 top-k 分块数3--neighbour-chunks检索时附带的前后相邻分块数0--max-retriesAPI 调用的最大重试次数3注意--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 一致第一个参数输入基准文件路径第二个参数输出文件路径可选--indentJSON 缩进级别默认2。Auto RAG Eval 源格式{ context: ..., QA Gen Profile: {...}, Question: ..., Answer: ... }转换后的 ADK 评估格式{ query: ..., expected_tool_use: [], reference: ... }字段映射规则清晰记录在脚本 docstring 中query ← Questionreference ← Answerexpected_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 │ └──────────┬──────────┘ │ ▼ ┌─────────────────────────┐ ┌─────────────────────┐ │ QA Profile Generation │────▶│ QA Generation │ │ - Analyze context │ │ - Create QA 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 → QAs输出含已验证 QA 对的 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_typeapplication/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. QA Profile GenerationProfile 生成从qa_profiles.json中读取可定制维度默认维度Type、Persona、Scope、Difficulty为每个上下文随机组合一组维度取值生成 Profile。实现位于 _build_random_profile()遍历每个维度从取值集合中随机选一个值并把取值描述与name一并注入 profile。7. QA Generation问答生成generate_qa_pair() 把蒸馏后的上下文与随机 Profile 交给 Gemini要求问题匹配 profile 的类型、角色与难度答案仅基于给定上下文输出由QAPairschema 约束为{question, answer}。8. Multi-Agent Review 与增量保存review_qa_pair() 以指定 critic 角色如Analyst对 QA 对做准确性、清晰度与相关性评审返回APPROVED/REJECTED及理由。当前仓库实现中简化为一轮单 critic 评审源码注释标明Simplified review: just use one critic for nowREADM 描述的多 critic 共识机制是其设计蓝图。通过评审的条目立即由 save_qa_incrementally() 追加写入输出文件——每次读取既有 JSON 列表、追加新条目并整体写回保证任意时刻进程中断都不丢失已生成的成果。6.4 关键设计决策增量处理每条 QA 通过即落盘防止数据丢失多阶段相关性评估单块与聚合两级评估保证上下文完整聚焦共识式评审多个 AI critic 保障输出质量灵活 Profile通过外部 JSON 配置自定义 QA 维度重试机制API 调用带指数退避的自动重试提升容错性进度追踪控制台以[LOGGING]前缀输出详细日志。6.5 API 集成点Vertex AI Agent Platform文档列举、分块检索、语义搜索经 Discovery EngineSearchServiceClientGemini 模型Clue 生成、Profile 建议、QA 生成、评审经genai.Client的generate_content Pydantic 结构化输出Google Cloud Storageqa_profiles.json下载download_from_gcs()与文档存储Discovery Engine API核心搜索与检索能力。七、示例数据与输出仓库文档说明其附带的示例文档为三份关于 Google AI 智能体的 PDF托管于 GCS不在仓库内input_2_ai-responsibility-update-published-february-2025.pdfGoogle AI 责任更新input_2_exec_guide_gen_ai.pdf生成式 AI 高管指南input_2_google-about-generative-ai.pdfGoogle 生成式 AI 概述。这些文档以如下设置摄取进数据存储启用 LLM 特性表格与图片标注、摄取时开启Layout Parser数据存储 ID 配置在示例 env 文件中。基于这些文档生成的基准包括原始输出benchmark.json含 15 个 QA 对与转换后的converted_benchmark.json。八、输出格式Auto RAG Eval 基准格式benchmark.json[ { context: The distilled context used for QA generation, QA 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、QA Gen Profile、Question、Answer平铺结构并通过convert_to_serializable()递归清洗 Pydantic 对象与MappingProxyType确保 JSON 可序列化。九、自定义 QA Profilesqa_profiles.json是 QA 生成的配置中枢支持灵活维度处理可定制项维度名称可重命名如Type→QuestionType、Persona→AudienceLevel维度数量可增删维度至少保留 1 个维度维度取值可增删改每个维度下的取值取值描述可自定义每个取值的说明。结构要求唯一要求是维持以下 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} } } } }定制步骤按你的维度与取值编辑qa_profiles.json运行基准生成器——脚本会自动适配新结构main.py 的 _build_random_profile() 遍历parameters下所有维度逐维随机取值脚本会校验结构并直接使用你提供的维度。使用注意qa_profiles.json缺失时脚本会尝试从 GCS 下载下载失败则打印提示当前实现会直接返回。README 还强调尽管具备多阶段质量控制与多 agent 评审生成的基准仍应被视为起点而非终稿。建议由熟悉业务领域的领域专家人工复核尤其对安全敏感或高度专业的领域要格外审慎并抽样人工检查生成对的质量。工具的价值是加速基准创建而非替代人的专业判断。十、监控与故障排查日志控制台输出中查找[LOGGING]前缀跟踪执行进度每个函数的进入/退出均有日志如Processing document: {doc[id]}、Successfully saved QA #N to ...API 重试尝试会连同错误详情一并记录。常见问题认证错误gcloud auth application-default loginAPI 限流调整代码中的延时、降低并发处理量输出为空检查DATA_STORE_ID是否正确、文档是否已正常摄取、API 权限是否具备内存问题一次处理更少的文档、减小分块合并规模缺少 qa_profiles.json确认文件与脚本同目录缺失时脚本会尝试自动下载。结语Auto RAG Eval 把文档 → 分块 → 线索 → 检索 → 蒸馏 → Profile → QA → 评审这条多阶段流水线固化成了两个可直接运行的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Auto RAG Eval 实战：基于 Vertex AI Agent Platform 与 Gemini 自动化生成 RAG 评测基准
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-aiAuto RAG Eval 是 Google Cloud 生成式 AI 示例仓库generative-ai中一套自动化基准生成工具它利用 Vertex AI Agent PlatformDiscovery Engine文档检索能力与 Gemini 模型的结构化输出能力从你的文档语料库中自动产出高质量、覆盖面广的 RAG 问答对。读完本文你将掌握 Benchmark Generator 与 Benchmark Transformer 的完整使用流程、全部命令行参数、内部多阶段流水线原理以及如何自定义 QA 生成维度让评测基准从人工编写数周变为自动化生成数小时。一、这是什么一次认清两个核心组件Auto RAG Eval 的定位是面向 RAG 系统的自动化评测基准生成器它由两个组件构成Benchmark Generatormain.py核心组件从 Vertex AI Agent Platform 数据存储中的文档生成 QA 问答对是本文讲解的主体Benchmark Transformertransform_benchmark.py辅助工具把生成的基准转换为兼容评估框架如 Google Agent Development KitADK的格式。两者代码均位于仓库 search/auto-rag-eval/ 目录下依赖声明见 requirements.txt。二、为什么要用自动化基准生成2.1 人工构建基准的痛点耗时巨大手工为 RAG 系统构建高质量基准往往需要数周甚至数月覆盖缺口人工编写的基准常遗漏边界情况无法系统覆盖整个文档语料难以扩展随着文档库不断增长维护相关基准的难度持续上升一致性差缺少标准化基准RAG 系统性能难以被一致、可复现地评估。2.2 Auto RAG Eval 的解法自动化生成数小时产出数百个 QA 对取代数周的人工劳动全面覆盖系统性地对文档与分块chunk进行采样覆盖整个语料库多阶段质量控制多个 AI 评审critic逐对校验 QA达成共识后才放行可扩展架构适配任意规模的 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_IDyour-gcp-project-id # - LOCATIONus-central1 # - DATA_STORE_IDyour-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完成后QA 对将写入benchmark.json。需要说明的是README 中提到的exemplary_docs/、qa_profiles.json、benchmark.json、env_example等文件托管在 Google Cloud Storagegs://github-repo/search/auto-rag-eval/上并不在仓库目录中。qa_profiles.json缺失时main.py会自动尝试从 GCS 下载exemplary_docs中的示例文档则需你自行上传到数据存储中用于验证。四、环境准备Prerequisites4.1 Google Cloud 项目与 API需要启用以下 APIVertex AI Agent Platform APIDiscovery Engine APIVertex AI Agent Platform 底层检索能力Cloud Storage API。4.2 认证# 配置 Application Default Credentials gcloud auth application-default login从源码看llm_utils.py中通过 get_client() 使用genai.Client(vertexaiTrue, projectproject_id, locationlocation)创建 Gemini 客户端检索侧则由 vertex_search_utils.py 中的DocumentServiceClient、SearchServiceClient、ChunkServiceClient承载这些客户端都依赖默认凭据完成鉴权。4.3 创建并填充 Vertex AI Agent Platform 数据存储在 Google Cloud Console 中进入AI Applications为你的应用新建数据存储配置解析器选择Digital Parser或Layout ParserREADME 中的示例数据在摄取时启用了 Layout Parser 并开启 LLM 特性用于表格与图片标注启用高级分块配置Advanced Chunking Configuration✓ 勾选Include ancestor headings in chunks在分块中附带祖先标题其余设置保持默认摄取自由文本文档进入数据存储从控制台复制 DATA_STORE_ID将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.txtGoogle Cloud 套件google-cloud-aiplatform1.38.0、google-cloud-storage2.10.0、google-cloud-discoveryengine0.11.0、google-genai1.0.0、vertexai1.38.0数据处理pandas2.0.0环境管理python-dotenv1.0.0其余json、re、time、random、argparse等均为 Python 标准库无需安装。4.5 必需文件qa_profiles.jsonQA 生成配置档从 GCS 下载命令见快速开始.env由env_example复制生成。五、分步使用指南Step 1配置环境变量cp env_example .env # 编辑以下值 PROJECT_IDyour-gcp-project-id LOCATIONus-central1 DATA_STORE_IDyour-data-store-idmain.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() 逐一对应参数作用默认值--project-id覆盖.env中的 PROJECT_ID取自.env--location覆盖.env中的 LOCATIONus-central1--data-store-id覆盖.env中的 DATA_STORE_ID取自.env--docs处理的文档数量2--chunks每篇文档处理的分块数量2--clues每个分块生成的线索问题数量2--profiles每个线索生成的 QA Profile 数量2--chunks-to-merge合并为更大分块时合并的块数3--output-file输出 JSON 文件名benchmark.json--qa-profiles-file自定义 QA Profiles JSON 路径脚本目录下的qa_profiles.json--llm-model使用的 LLM 模型gemini-3.5-flash--top-k-chunks上下文检索时取回的 top-k 分块数3--neighbour-chunks检索时附带的前后相邻分块数0--max-retriesAPI 调用的最大重试次数3注意--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 一致第一个参数输入基准文件路径第二个参数输出文件路径可选--indentJSON 缩进级别默认2。Auto RAG Eval 源格式{ context: ..., QA Gen Profile: {...}, Question: ..., Answer: ... }转换后的 ADK 评估格式{ query: ..., expected_tool_use: [], reference: ... }字段映射规则清晰记录在脚本 docstring 中query ← Questionreference ← Answerexpected_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 │ └──────────┬──────────┘ │ ▼ ┌─────────────────────────┐ ┌─────────────────────┐ │ QA Profile Generation │────▶│ QA Generation │ │ - Analyze context │ │ - Create QA 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 → QAs输出含已验证 QA 对的 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_typeapplication/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. QA Profile GenerationProfile 生成从qa_profiles.json中读取可定制维度默认维度Type、Persona、Scope、Difficulty为每个上下文随机组合一组维度取值生成 Profile。实现位于 _build_random_profile()遍历每个维度从取值集合中随机选一个值并把取值描述与name一并注入 profile。7. QA Generation问答生成generate_qa_pair() 把蒸馏后的上下文与随机 Profile 交给 Gemini要求问题匹配 profile 的类型、角色与难度答案仅基于给定上下文输出由QAPairschema 约束为{question, answer}。8. Multi-Agent Review 与增量保存review_qa_pair() 以指定 critic 角色如Analyst对 QA 对做准确性、清晰度与相关性评审返回APPROVED/REJECTED及理由。当前仓库实现中简化为一轮单 critic 评审源码注释标明Simplified review: just use one critic for nowREADM 描述的多 critic 共识机制是其设计蓝图。通过评审的条目立即由 save_qa_incrementally() 追加写入输出文件——每次读取既有 JSON 列表、追加新条目并整体写回保证任意时刻进程中断都不丢失已生成的成果。6.4 关键设计决策增量处理每条 QA 通过即落盘防止数据丢失多阶段相关性评估单块与聚合两级评估保证上下文完整聚焦共识式评审多个 AI critic 保障输出质量灵活 Profile通过外部 JSON 配置自定义 QA 维度重试机制API 调用带指数退避的自动重试提升容错性进度追踪控制台以[LOGGING]前缀输出详细日志。6.5 API 集成点Vertex AI Agent Platform文档列举、分块检索、语义搜索经 Discovery EngineSearchServiceClientGemini 模型Clue 生成、Profile 建议、QA 生成、评审经genai.Client的generate_content Pydantic 结构化输出Google Cloud Storageqa_profiles.json下载download_from_gcs()与文档存储Discovery Engine API核心搜索与检索能力。七、示例数据与输出仓库文档说明其附带的示例文档为三份关于 Google AI 智能体的 PDF托管于 GCS不在仓库内input_2_ai-responsibility-update-published-february-2025.pdfGoogle AI 责任更新input_2_exec_guide_gen_ai.pdf生成式 AI 高管指南input_2_google-about-generative-ai.pdfGoogle 生成式 AI 概述。这些文档以如下设置摄取进数据存储启用 LLM 特性表格与图片标注、摄取时开启Layout Parser数据存储 ID 配置在示例 env 文件中。基于这些文档生成的基准包括原始输出benchmark.json含 15 个 QA 对与转换后的converted_benchmark.json。八、输出格式Auto RAG Eval 基准格式benchmark.json[ { context: The distilled context used for QA generation, QA 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、QA Gen Profile、Question、Answer平铺结构并通过convert_to_serializable()递归清洗 Pydantic 对象与MappingProxyType确保 JSON 可序列化。九、自定义 QA Profilesqa_profiles.json是 QA 生成的配置中枢支持灵活维度处理可定制项维度名称可重命名如Type→QuestionType、Persona→AudienceLevel维度数量可增删维度至少保留 1 个维度维度取值可增删改每个维度下的取值取值描述可自定义每个取值的说明。结构要求唯一要求是维持以下 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} } } } }定制步骤按你的维度与取值编辑qa_profiles.json运行基准生成器——脚本会自动适配新结构main.py 的 _build_random_profile() 遍历parameters下所有维度逐维随机取值脚本会校验结构并直接使用你提供的维度。使用注意qa_profiles.json缺失时脚本会尝试从 GCS 下载下载失败则打印提示当前实现会直接返回。README 还强调尽管具备多阶段质量控制与多 agent 评审生成的基准仍应被视为起点而非终稿。建议由熟悉业务领域的领域专家人工复核尤其对安全敏感或高度专业的领域要格外审慎并抽样人工检查生成对的质量。工具的价值是加速基准创建而非替代人的专业判断。十、监控与故障排查日志控制台输出中查找[LOGGING]前缀跟踪执行进度每个函数的进入/退出均有日志如Processing document: {doc[id]}、Successfully saved QA #N to ...API 重试尝试会连同错误详情一并记录。常见问题认证错误gcloud auth application-default loginAPI 限流调整代码中的延时、降低并发处理量输出为空检查DATA_STORE_ID是否正确、文档是否已正常摄取、API 权限是否具备内存问题一次处理更少的文档、减小分块合并规模缺少 qa_profiles.json确认文件与脚本同目录缺失时脚本会尝试自动下载。结语Auto RAG Eval 把文档 → 分块 → 线索 → 检索 → 蒸馏 → Profile → QA → 评审这条多阶段流水线固化成了两个可直接运行的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考