ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

基于 Agent Platform Search(Discovery Engine)构建 RAG 智能体:adk-samples 的 rag-agent-search 实战指南

基于 Agent Platform Search(Discovery Engine)构建 RAG 智能体:adk-samples 的 rag-agent-search 实战指南 基于 Agent Platform SearchDiscovery Engine构建 RAG 智能体adk-samples 的 rag-agent-search 实战指南【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本指南围绕 adk-samples 仓库中的 core/rag-agent-search 示例展开讲解如何用 Agent Development KitADK构建一个以Agent Platform SearchDiscovery Engine为检索底座的问答型 RAG 智能体。该示例的核心特点是零独立摄取管道文档放入 GCS 桶后由 GCS Data Connector 自动同步索引Agent 通过VertexAiSearchTool工具完成检索增强生成。读完本文你将掌握数据存储Data Store的 Terraform 交付、.env配置链路、make工作流以及带 Mock 的集成测试与 ADK 原生部署路径。一、示例概览rag-agent-search是一个面向文档问答的 RAG 起步示例starter RAG agent它回答的问题以Agent Platform Search即 Discovery Engine中索引的文档为依据。文档被放置到 GCS 桶后由 GCS Data Connector 自动摄取无需单独维护摄取管道——这是它与传统文档切分 向量化 入库RAG 方案最显著的区别。该示例的核心属性如下表源自 README.md属性详情交互类型Interaction TypeConversational对话式复杂度ComplexityIntermediate进阶智能体类型Agent TypeSingle Agent单智能体组件ComponentsTools、RAG、Terraform、Evaluation在 manifest.yaml 中可以看到该示例被声明为type: standalone、language: python、architecture.agent: single、datasources: [external]进一步印证了它单 Agent 外部数据源的定位。二、工作原理与源码结构README 给出了三个核心模块的分工结合仓库源码可以还原出完整的调用链app/agent.py —— ADK 智能体定义负责把检索工具装配进 Agentapp/retrievers.py ——create_search_tool()工厂函数返回绑定到数据存储Data Store的VertexAiSearchTool当INTEGRATION_TESTTRUE时返回 Mockinfra/terraform/ —— 交付文档 GCS 桶、GCS Data Connector 以及基于自动创建的数据存储构建的搜索引擎Search Engine。2.1 Agent 装配agent.pyapp/agent.py 启动时会做四件事通过load_dotenv()加载 .env.example 中定义的配置环境变量已存在时优先用os.environ.setdefault设置GOOGLE_CLOUD_LOCATIONglobal与GOOGLE_GENAI_USE_VERTEXAITrue强制走 Vertex AI 通道若未显式设置GOOGLE_CLOUD_PROJECT则通过google.auth.default()从 Application Default CredentialsADC解析项目 ID以vertexai.init(projectproject_id, locationus-east1)初始化 Vertex AI SDK。关键变量包括LLM_LOCATION global、LOCATION us-east1前者用于模型调用后者用于 Vertex AI 初始化LLM os.getenv(MODEL_NAME)模型名从环境变量读取.env.example 中默认gemini-flash-latestDATA_STORE_REGION默认global、DATA_STORE_COLLECTION默认default_collection、DATA_STORE_ID默认rag-agent-search-collection_documents三者拼接出数据存储的完整资源路径data_store_path ( fprojects/{project_id}/locations/{data_store_region} f/collections/{data_store_collection}/dataStores/{data_store_id} )随后root_agent使用Gemini模型配置了HttpRetryOptions(attempts3)重试 3 次将vertex_search_tool挂载到tools[vertex_search_tool]最后通过App(root_agentroot_agent, nameapp)组装成可运行的 ADK 应用。模型指令instruction明确要求优先利用提供的工具基于上下文回答若已知答案可直接作答这正是 RAG 智能体典型的检索增强 直答兜底策略。2.2 检索工具工厂retrievers.pyapp/retrievers.py 中的create_search_tool()是整个检索能力的开关def create_search_tool(data_store_path: str) - VertexAiSearchTool | Callable[[str], str]: # 集成测试模式下返回 Mock避免真实调用 Discovery Engine if os.getenv(INTEGRATION_TEST) TRUE: def mock_search(query: str) - str: return Mock search result for testing purposes. return mock_search return VertexAiSearchTool(data_store_iddata_store_path)从源码可以看到正常运行路径下返回google.adk.tools.VertexAiSearchTool直接以数据存储资源路径作为data_store_id当INTEGRATION_TESTTRUE时则返回一个固定返回字符串的 Mock 函数。这一设计让测试无需触碰真实检索服务但 Agent 的模型调用仍保持真实详见第五节。三、基础设施交付Terraform 一键搭建检索底座infra/terraform/是数据链路的地基包含 7 个.tf文件与 4 个 Python 辅助脚本。执行make setup-infra时Makefile 会运行cd infra/terraform terraform init terraform apply -var-filevars/env.tfvars整个交付过程由 agent_platform_search.tf 串联文档桶创建google_storage_bucket命名规则${project_id}-${project_name}-docs开启 uniform bucket level accessGCS Data Connector通过null_resource的local-execprovisioner 调用 setup_data_connector.py 创建连接器把gs://docs_bucket/*与数据存储绑定并传入--refresh-interval刷新间隔与--data-schema数据模式销毁时自动调用 delete_data_connector.py 清理解析自动生成的数据存储data external data_store_id调用 get_data_store_id.py 从连接器中反查实际创建的数据存储 ID——注意连接器会把数据存储放进自己专属的 collectionproject_name-collection而非默认的default_collection这是 README 特别提醒设置.env的原因搜索引擎google_discovery_engine_search_engine以该数据存储为后端创建 Search Engine Appsearch_tier SEARCH_TIER_ENTERPRISE即企业版搜索层级。apis.tf 会一次性启用 11 个 GCP API含discoveryengine.googleapis.com、aiplatform.googleapis.com、bigquery.googleapis.com、run.googleapis.com等并创建 Vertex AI 服务账号身份。3.1 Terraform 变量与输出env.tfvars 是需要你填写的唯一输入复制后填写project_id your-gcp-project-id project_name rag-agent-search region us-central1其余变量定义见 variables.tf 与 agent_platform_search_variables.tf均带默认值变量默认值说明project_id必填GCP 项目 IDproject_namerag-agent-search资源命名基名regionus-central1资源部署区域data_store_regionglobal数据存储区域data_connector_refresh_interval86400s连接器周期同步间隔默认每日data_connector_data_schemacontent摄取数据模式见 3.2terraform apply结束后datastore_outputs.tf 会输出 5 个关键值data_store_id、data_store_collection、data_store_path完整资源路径、search_engine_id、docs_bucket_name。其中前两个必须回填到.env。3.2 数据连接器的四种数据模式setup_data_connector.py 是幂等的已存在则跳过它把data_schema映射为不同的实体参数data_schema适用场景关键行为content默认非结构化文件PDF、HTML、TXT每文件一个文档ID 由 SHA256(URI) 自动生成需CONTENT_REQUIRED以存储原始文件documentNDJSON/JSONL 结构化文档每行一个 JSON 文档需携带Document.idcsv带表头的 CSV 文件自动生成 IDcustom符合数据存储 schema 的自定义 JSON自动生成 ID脚本内部通过 Discovery Enginev1alphaREST APIsetUpDataConnectorV2创建连接器并对长时运行操作LRO轮询最多 60 次、每次间隔 10 秒等待创建完成。四、快速开始从零到可问答的五个步骤4.1 配置环境变量cp .env.example .env然后编辑.env至少设置GOOGLE_CLOUD_PROJECT。完整的 .env.example 字段如下变量默认值说明GOOGLE_CLOUD_PROJECT需填写GCP 项目 IDGOOGLE_CLOUD_LOCATIONglobal模型调用区域GOOGLE_GENAI_USE_VERTEXAITrue走 Vertex AI 通道DATA_STORE_REGIONglobal数据存储区域DATA_STORE_COLLECTIONdefault_collection需替换为make setup-infra输出的data_store_collectionDATA_STORE_IDrag-agent-search-collection_documents需替换为make setup-infra输出的data_store_idMODEL_NAMEgemini-flash-latest使用的 Gemini 模型INTEGRATION_TEST需填写置为TRUE时检索工具被 Mock4.2 交付基础设施make setup-infra4.3 回填数据存储配置将 Terraform 输出中的data_store_id/data_store_collection复制进.env分别写入DATA_STORE_ID与DATA_STORE_COLLECTION。README 特别强调连接器会自动生成这两个值默认值很可能与实际不符务必以输出为准。4.4 上传文档并触发同步make upload-sample-data make ingestmake upload-sample-data通过gcloud storage cp把仓库自带的 sample_data/product_catalog.txt产品目录、support_faq.txt售后 FAQ上传到docs_bucket_name指向的桶你也可以把自己的文件拷入桶内。随后make ingest读取.env中的项目与区域调用 start_connector_run.py 并携带--wait等待摄取完成。ingest之所以是可选但推荐是因为 GCS Data Connector 默认按data_connector_refresh_interval默认86400s即每日周期刷新想立即让文档可检索就必须手动触发一次同步。从 start_connector_run.py 源码可见它读取连接器实体信息以reconciliationMode: FULL调用 ImportDocuments API将 GCS 中的文件同步进数据存储并轮询 LRO 直到返回successCount/totalCount/failureCount统计最多等待约 10 分钟。五、运行与测试5.1 启动 Playgroundmake install make playgroundmake install执行uv sync --dev --extra eval安装开发与评测依赖pyproject.toml 中要求google-adk[gcp]2.0.0,3.0.0、Python3.11,3.14make playground执行uv run adk web . --port 8501 --reload_agents在本地 8501 端口启动 ADK Web UI。在界面上选择app目录后即可提问例如What is the payload and battery life of the Atlas-7 robot?该问题对应的答案正是仓库内置sample_data/product_catalog.txt中记载的产品规格——Agent 会先通过检索工具命中文档片段再由 Gemini 生成有依据的回答。5.2 集成测试与 Mock 机制make testmake test等价于INTEGRATION_TESTTRUE uv run pytest tests/integration。在 tests/integration/test_agent.py 中可以看到完整的验证逻辑通过INTEGRATION_TESTTRUE使create_search_tool()返回 Mock检索调用不触达 Discovery Engine但 Agent 仍会发起一次真实的 Gemini 调用因此需要 Google Cloud 凭据ADC与 Vertex AI 访问权限测试用_has_gcp_credentials()检测 ADC无凭据时整个测试被pytest.mark.skipif跳过同时避免在导入app.agent时因google.auth.default()抛错用例以InMemorySessionServiceRunner驱动root_agent以StreamingMode.SSE流式运行断言至少产出一个含文本内容的事件。仓库还附带 tests/eval 评测目录eval_config.yaml与basic-dataset.json对应 README 中 Components 里的 Evaluation 项可用 ADK 的 eval 能力对问答质量做离线评测。六、CI/CD 与生产部署这些示例不内置部署流水线但文档保鲜由 GCS Data Connector 自动完成定时保鲜连接器按data_connector_refresh_interval默认每日重新同步 GCS 桶中的文档按需强制同步在 CI或本地调用make ingest即可跳过等待周期、立刻刷新索引部署智能体推荐走 ADK 原生路径例如uv run adk deploy cloud_run .或adk deploy agent_engine不要使用已弃用的 agent-starter-pack 工具链。结合 apis.tf 中预置的run.googleapis.com、cloudbuild.googleapis.com、bigquery.googleapis.com等 API可以推断该示例为 Cloud Run / Agent Engine 部署以及评测链路预留了完整的能力面。七、延伸向量检索与混合 RAG 变体如果你需要的不是关键词/语义检索而是向量检索README 给出了两条延伸路径core/rag-vector-search —— Vector Search 2.0 变体数据摄取与检索链路更贴近传统 RAGcontrib/python/multiformat-hybrid-rag —— 生产级混合检索系统语义 关键词并附带完整的数据摄取管道、基础设施即代码与 Notebook 走查。小结rag-agent-search用最少的组件演示了一条GCS 桶 → Data Connector 自动索引 → VertexAiSearchTool 检索 → Gemini 生成的完整 RAG 链路Terraform 负责一键交付检索底座make工作流屏蔽了环境准备、文档上传与强制同步的细节Mock 机制让集成测试在无检索服务依赖下即可验证 Agent 流式响应而 ADK 原生的adk deploy则为生产落地提供了平滑路径。对于想快速在 Google Cloud 上获得一个上传即问答智能体的开发者这是一个可以直接动手复现的起步模板。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表