智能体的 Vertex AI Search Grounding¶

Supported in ADKPython v0.1.0Java v0.1.0

Vertex AI Search 是 Agent Development Kit (ADK) 的一项强大工具，允许 AI 智能体访问你的私有企业文档和数据存储库。通过将你的智能体连接到索引的企业内容，你可以为用户提供基于组织知识库的答案。

此功能对于需要内部文档、政策、研究论文或任何已在 Vertex AI Search 数据存储中索引的专有内容的企业级查询尤为有价值。当你的智能体判断需要知识库中的信息时，它会自动搜索已索引文档，并将结果与正确的出处整合到回复中。

准备 Vertex AI Search¶

在创建一个 Grounded 智能体之前，你必须拥有一个现有的 Vertex AI Search 数据存储 (Data Store)。如果你还没有，请按照自定义搜索入门中的说明创建一个。你将需要你的 Data store ID（例如：projects/YOUR_PROJECT_ID/locations/global/collections/default_collection/dataStores/YOUR_DATASTORE_ID）来配置智能体。

身份验证设置¶

注意：Vertex AI Search 需要 Google Cloud Platform (Vertex AI) 身份验证。不支持 Google AI Studio。

设置 gcloud CLI。
通过在终端运行 gcloud auth login 向 Google Cloud 进行身份验证。
对于 Python，打开 .env 文件并指定你的项目 ID 和位置。
对于 Java，确保你的应用环境配置了 Google Cloud 默认凭据 (GOOGLE_APPLICATION_CREDENTIALS)。

.env

GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=LOCATION

创建一个 Grounded 智能体¶

要启用 Vertex AI Search Grounding，你需要在智能体定义中包含搜索工具，并提供 data_store_id。

PythonJava

from google.adk.agents import Agent
from google.adk.tools import VertexAiSearchTool

# 配置
DATASTORE_ID = "projects/YOUR_PROJECT_ID/locations/global/collections/default_collection/dataStores/YOUR_DATASTORE_ID"

root_agent = Agent(
    name="vertex_search_agent",
    model="gemini-2.5-flash",
    instruction="使用 Vertex AI Search 从内部文档中查找信息来回答问题。尽可能引用来源。",
    description="具有 Vertex AI Search 能力的企业文档搜索助手",
    tools=[VertexAiSearchTool(data_store_id=DATASTORE_ID)]
)

import com.google.adk.agents.LlmAgent;
import com.google.adk.tools.VertexAiSearchTool;

// 配置
String DATASTORE_ID = "projects/YOUR_PROJECT_ID/locations/global/collections/default_collection/dataStores/YOUR_DATASTORE_ID";

LlmAgent rootAgent = LlmAgent.builder()
    .name("vertex_search_agent")
    .model("gemini-2.5-flash")
    .instruction("使用 Vertex AI Search 从内部文档中查找信息来回答问题。尽可能引用来源。")
    .description("具有 Vertex AI Search 能力的企业文档搜索助手")
    .tools(VertexAiSearchTool.builder().dataStoreId(DATASTORE_ID).build())
    .build();

Vertex AI Search Grounding 的工作原理¶

Vertex AI Search Grounding 让你的智能体连接到组织已索引的文档和数据，使其能基于企业私有内容生成准确回复。当用户的问题需要内部知识库信息时，智能体底层的 LLM 会智能决定调用 VertexAiSearchTool，从已索引文档中查找相关事实。

数据流图¶

下图展示了从用户提问到 Grounded 响应的逐步流程。

Vertex AI Search Grounding Data Flow

详细描述¶

Grounded 智能体使用上述数据流，从企业信息中检索、处理并整合到最终用户回复中。

用户查询 (User Query)：终端用户通过询问有关内部文档或企业数据的问题与你的智能体进行交互。
ADK 编排 (ADK Orchestration)：Agent Development Kit 编排智能体的行为，并将用户的消息传递给智能体的核心。
LLM 分析与工具调用 (LLM Analysis and Tool-Calling)：智能体的 LLM（例如 Gemini 模型）分析提示词。如果它确定需要来自索引文档的信息，它将通过调用 VertexAiSearchTool 触发 Grounding 机制。这非常适合回答有关公司政策、技术文档或专有研究的查询。
Vertex AI Search 服务交互 (Vertex AI Search Service Interaction)：VertexAiSearchTool 与你配置的 Vertex AI Search 数据存储（包含索引的企业文档）进行交互。该服务针对你的私有内容制定并执行搜索查询。
文档检索与排名 (Document Retrieval & Ranking)：Vertex AI Search 根据语义相似性和相关性评分，从你的数据存储中检索并排名最相关的文档区块。
上下文注入 (Context Injection)：搜索服务在生成最终响应之前，将检索到的文档片段整合到模型的上下文中。这一关键步骤允许模型根据你的组织事实数据进行“推理”。
生成 Grounded 响应 (Grounded Response Generation)：LLM 在获得相关企业内容的信息后，生成一个包含从文档中检索到的信息的响应。
带来源的响应呈现 (Response Presentation with Sources)：ADK 接收最终的 Grounded 响应（包含必要的源文档引用和 groundingMetadata），并将其连同归因呈现给用户。这允许终端用户根据你的企业源验证信息。

理解 Vertex AI Search Grounding 响应¶

当智能体使用 Vertex AI Search 来 Ground 响应时，它会返回详细信息，包括最终的文本答案以及用于生成该答案的文档元数据。此元数据对于验证响应和为你的企业源提供归因至关重要。

Grounded 响应示例¶

以下是模型在针对企业文档进行 Grounded 查询后返回的内容对象示例。

最终答案文本：

"为医学速记员开发模型面临着几个重大挑战，这主要是由于医疗文档的复杂性、涉及的敏感数据以及临床工作流的严苛要求。主要挑战包括：**准确性和可靠性：** 医疗文档要求极高的准确性，因为错误可能导致误诊、错误的治疗以及法律后果。确保 AI 模型能可靠地捕捉细微的医学语言，区分主观和客观信息，并准确转录医患互动，是一个主要的障碍。**自然语言理解 (NLU) 和语音识别：** 医疗对话通常进行很快，涉及高度专业化的术语、首字母缩略词和缩写，并且说话者可能有不同的口音或说话模式……[响应继续，详细分析隐私、集成和技术挑战]"

Grounding 元数据片段：

{
  "groundingMetadata": {
    "groundingChunks": [
      {
        "document": {
          "title": "AI in Medical Scribing: Technical Challenges",
          "uri": "projects/your-project/locations/global/dataStores/your-datastore-id/documents/doc-medical-scribe-ai-tech-challenges",
          "id": "doc-medical-scribe-ai-tech-challenges"
        }
      },
      {
        "document": {
          "title": "Regulatory and Ethical Hurdles for AI in Healthcare",
          "uri": "projects/your-project/locations/global/dataStores/your-datastore-id/documents/doc-ai-healthcare-ethics",
          "id": "doc-ai-healthcare-ethics"
        }
      }
    ],
    "groundingSupports": [
      {
        "groundingChunkIndices": [0, 1],
        "segment": {
          "endIndex": 637,
          "startIndex": 433,
          "text": "确保 AI 模型能可靠捕捉细致的医学语言……"
        }
      }
    ],
    "retrievalQueries": [
      "challenges in natural language processing medical domain",
      "AI medical scribe challenges",
      "difficulties in developing AI for medical scribes"
    ]
  }
}

如何解读响应¶

元数据将模型生成的文本与企业文档建立了关联。分解如下：

groundingChunks: 这是模型参考的企业文档列表。每个区块都包含文档标题 title、统一资源标识符 uri（文档路径）和 id。
groundingSupports: 此列表将最终答案中的特定句子连接回 groundingChunks。
segment: 此对象标识最终文本答案的一个特定部分，由其 startIndex、endIndex 和文本本身定义。
groundingChunkIndices: 此数组包含与 groundingChunks 中列出的来源相对应的索引号。例如，关于“符合 HIPAA 标准”的文本由索引为 1 的 groundingChunks（“监管与伦理障碍”文档）中的信息支持。
retrievalQueries: 此数组显示了针对你的数据存储执行的特定搜索查询，以查找相关信息。

简单文本展示（最小实现）：

PythonJava

for event in events:
    if event.is_final_response():
        print(event.content.parts[0].text)

        # 可选：显示来源数量
        if event.grounding_metadata:
            print(f"\n基于 {len(event.grounding_metadata.grounding_chunks)} 个文档")

for (Event event : events) {
    if (event.finalResponse()) {
        System.out.println(event.content().parts().get(0).text());

        // 可选：显示来源数量
        if (event.groundingMetadata().isPresent()) {
            System.out.println("\n基于 " + event.groundingMetadata().get().groundingChunks().size() + " 个文档");
        }
    }
}

增强型引用展示（可选）： 你可以实现交互式引用，展示每句话由哪些文档支持。Grounding 元数据提供了将文本片段映射到来源文档的全部信息。

实现注意事项¶

在实现 Vertex AI Search Grounding 展示时：

文档访问：验证用户对所引用文档的访问权限。
简单集成：基础文本输出不需要额外的显示逻辑。
可选增强：仅在你的用例受益于来源归因时添加引用。
文档链接：必要时将文档 URI 转换为可访问的内部链接。
搜索查询：retrievalQueries 数组显示了针对你的数据存储执行了哪些搜索。