> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Vertex AI 搜索集成

> 使用 LangChain Python 集成 Google Vertex AI 搜索检索器。

> [Google Vertex AI 搜索](https://cloud.google.com/enterprise-search)（前身为 `Generative AI App Builder` 上的 `Enterprise Search`）是 `Google Cloud` 提供的 [Vertex AI](https://cloud.google.com/vertex-ai) 机器学习平台的一部分。
>
> `Vertex AI 搜索` 让组织能够快速为客户和员工构建由生成式 AI 驱动的搜索引擎。它基于多种 `Google 搜索` 技术，包括语义搜索，该技术通过使用自然语言处理和机器学习技术来推断内容中的关系以及用户查询输入的意图，从而提供比传统基于关键词的搜索技术更相关的结果。Vertex AI 搜索还受益于 Google 在理解用户搜索方式方面的专业知识，并考虑内容相关性来排序显示的结果。

> `Vertex AI 搜索` 可在 `Google Cloud 控制台` 中使用，也可通过 API 用于企业工作流集成。

本笔记本演示了如何配置 `Vertex AI 搜索` 并使用 Vertex AI 搜索[检索器](/oss/python/langchain/retrieval)。Vertex AI 搜索检索器封装了 [Python 客户端库](https://cloud.google.com/generative-ai-app-builder/docs/libraries#client-libraries-install-python)，并使用它来访问 [搜索服务 API](https://cloud.google.com/python/docs/reference/discoveryengine/latest/google.cloud.discoveryengine_v1beta.services.search_service)。

有关所有 `VertexAISearchRetriever` 功能和配置的详细文档，请访问 [API 参考](https://reference.langchain.com/python/langchain-google-community/vertex_ai_search/VertexAISearchRetriever)。

### 集成详情

<ItemTable category="document_retrievers" item="VertexAISearchRetriever" />

## 设置

### 安装

您需要安装 `langchain-google-community` 和 `google-cloud-discoveryengine` 包才能使用 Vertex AI 搜索检索器。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pip install -qU langchain-google-community google-cloud-discoveryengine
```

### 配置对 Google Cloud 和 Vertex AI 搜索的访问权限

自 2023 年 8 月起，Vertex AI 搜索无需允许名单即可普遍使用。

在使用检索器之前，您需要完成以下步骤：

#### 创建搜索引擎并填充非结构化数据存储

* 按照 [Vertex AI 搜索入门指南](https://cloud.google.com/generative-ai-app-builder/docs/try-enterprise-search) 中的说明设置 Google Cloud 项目和 Vertex AI 搜索。
* [使用 Google Cloud 控制台创建非结构化数据存储](https://cloud.google.com/generative-ai-app-builder/docs/create-engine-es#unstructured-data)
  * 使用 `gs://cloud-samples-data/gen-app-builder/search/alphabet-investor-pdfs` Cloud Storage 文件夹中的示例 PDF 文档填充它。
  * 确保使用 `Cloud Storage (without metadata)` 选项。

#### 设置访问 Vertex AI 搜索 API 的凭据

Vertex AI 搜索检索器使用的 [Vertex AI 搜索客户端库](https://cloud.google.com/generative-ai-app-builder/docs/libraries) 提供了高级语言支持，用于以编程方式向 Google Cloud 进行身份验证。
客户端库支持[应用默认凭据 (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials)；这些库会在一组定义的位置中查找凭据，并使用这些凭据向 API 进行身份验证。
使用 ADC，您可以在各种环境（如本地开发或生产环境）中向应用程序提供凭据，而无需修改应用程序代码。

如果在 [Google Colab](https://colab.google) 中运行，请使用 `google.colab.google.auth` 进行身份验证，否则请按照[支持的方法](https://cloud.google.com/docs/authentication/application-default-credentials)之一操作，以确保您的应用默认凭据已正确设置。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import sys

if "google.colab" in sys.modules:
    from google.colab import auth as google_auth

    google_auth.authenticate_user()
```

### 配置和使用 Vertex AI 搜索检索器

Vertex AI 搜索检索器在 `langchain_google_community.VertexAISearchRetriever` 类中实现。`get_relevant_documents` 方法返回一个 `langchain.schema.Document` 文档列表，其中每个文档的 `page_content` 字段填充了文档内容。
根据 Vertex AI 搜索中使用的数据类型（网站、结构化或非结构化），`page_content` 字段的填充方式如下：

* 具有高级索引的网站：与查询匹配的 `抽取式答案`。`metadata` 字段填充了从中提取片段或答案的文档的元数据（如果有）。
* 非结构化数据源：与查询匹配的 `抽取式片段` 或 `抽取式答案`。`metadata` 字段填充了从中提取片段或答案的文档的元数据（如果有）。
* 结构化数据源：包含从结构化数据源返回的所有字段的字符串 JSON。`metadata` 字段填充了文档的元数据（如果有）

#### 抽取式答案与抽取式片段

抽取式答案是随每个搜索结果返回的逐字文本。它直接从原始文档中提取。抽取式答案通常显示在网页顶部附近，为最终用户提供与其查询上下文相关的简短答案。抽取式答案可用于网站和非结构化搜索。

抽取式片段是随每个搜索结果返回的逐字文本。抽取式片段通常比抽取式答案更详细。抽取式片段可以显示为查询的答案，可用于执行后处理任务，并作为大型语言模型生成答案或新文本的输入。抽取式片段可用于非结构化搜索。

有关抽取式片段和抽取式答案的更多信息，请参阅[产品文档](https://cloud.google.com/generative-ai-app-builder/docs/snippets)。

注意：抽取式片段需要启用[企业版](https://cloud.google.com/generative-ai-app-builder/docs/about-advanced-features#enterprise-features)功能。

创建检索器实例时，您可以指定多个参数来控制访问哪个数据存储以及如何处理自然语言查询，包括抽取式答案和片段的配置。

#### 必需参数是

* `project_id` - 您的 Google Cloud 项目 ID。
* `location_id` - 数据存储的位置。
  * `global`（默认）
  * `us`
  * `eu`

以下之一：

* `search_engine_id` - 您要使用的搜索应用的 ID。（混合搜索必需）
* `data_store_id` - 您要使用的数据存储的 ID。

`project_id`、`search_engine_id` 和 `data_store_id` 参数可以在检索器的构造函数中显式提供，也可以通过环境变量提供 - `PROJECT_ID`、`SEARCH_ENGINE_ID` 和 `DATA_STORE_ID`。

您还可以配置多个可选参数，包括：

* `max_documents` - 用于提供抽取式片段或抽取式答案的最大文档数
* `get_extractive_answers` - 默认情况下，检索器配置为返回抽取式片段。
  * 将此字段设置为 `True` 以返回抽取式答案。仅当 `engine_data_type` 设置为 `0`（非结构化）时使用。
* `max_extractive_answer_count` - 每个搜索结果中返回的最大抽取式答案数。
  * 最多返回 5 个答案。仅当 `engine_data_type` 设置为 `0`（非结构化）时使用。
* `max_extractive_segment_count` - 每个搜索结果中返回的最大抽取式片段数。
  * 目前将返回一个片段。仅当 `engine_data_type` 设置为 `0`（非结构化）时使用。
* `filter` - 基于数据存储中与文档关联的元数据对搜索结果进行过滤的表达式。
* `query_expansion_condition` - 确定在何种条件下应进行查询扩展的规范。
  * `0` - 未指定的查询扩展条件。在这种情况下，服务器行为默认为禁用。
  * `1` - 禁用查询扩展。仅使用精确的搜索查询，即使 SearchResponse.total\_size 为零。
  * `2` - 由搜索 API 构建的自动查询扩展。
* `engine_data_type` - 定义 Vertex AI 搜索数据类型
  * `0` - 非结构化数据
  * `1` - 结构化数据
  * `2` - 网站数据
  * `3` - [混合搜索](https://cloud.google.com/generative-ai-app-builder/docs/create-data-store-es#multi-data-stores)

### `GoogleCloudEnterpriseSearchRetriever` 迁移指南

在以前的版本中，此检索器称为 `GoogleCloudEnterpriseSearchRetriever`。

要更新到新的检索器，请进行以下更改：

* 更改导入：`from langchain.retrievers import GoogleCloudEnterpriseSearchRetriever` -> `from langchain_google_community import VertexAISearchRetriever`。
* 将所有类引用从 `GoogleCloudEnterpriseSearchRetriever` 更改为 `VertexAISearchRetriever`。

注意：使用检索器时，如果您想从单个查询中获得自动跟踪，也可以通过取消注释以下内容来设置您的 [LangSmith](/langsmith/home) API 密钥：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"
```

## 实例化

### 配置和使用用于**非结构化**数据的检索器（带抽取式片段）

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_google_community import (
    VertexAIMultiTurnSearchRetriever,
    VertexAISearchRetriever,
)

PROJECT_ID = "<YOUR PROJECT ID>"  # 设置为您的项目 ID
LOCATION_ID = "<YOUR LOCATION>"  # 设置为您的数据存储位置
SEARCH_ENGINE_ID = "<YOUR SEARCH APP ID>"  # 设置为您的搜索应用 ID
DATA_STORE_ID = "<YOUR DATA STORE ID>"  # 设置为您的数据存储 ID
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
retriever = VertexAISearchRetriever(
    project_id=PROJECT_ID,
    location_id=LOCATION_ID,
    data_store_id=DATA_STORE_ID,
    max_documents=3,
)
```

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
query = "What are Alphabet's Other Bets?"

result = retriever.invoke(query)
for doc in result:
    print(doc)
```

### 配置和使用用于**非结构化**数据的检索器（带抽取式答案）

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
retriever = VertexAISearchRetriever(
    project_id=PROJECT_ID,
    location_id=LOCATION_ID,
    data_store_id=DATA_STORE_ID,
    max_documents=3,
    max_extractive_answer_count=3,
    get_extractive_answers=True,
)

result = retriever.invoke(query)
for doc in result:
    print(doc)
```

### 配置和使用用于**结构化**数据的检索器

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
retriever = VertexAISearchRetriever(
    project_id=PROJECT_ID,
    location_id=LOCATION_ID,
    data_store_id=DATA_STORE_ID,
    max_documents=3,
    engine_data_type=1,
)

result = retriever.invoke(query)
for doc in result:
    print(doc)
```

### 配置和使用用于具有高级网站索引的**网站**数据的检索器

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
retriever = VertexAISearchRetriever(
    project_id=PROJECT_ID,
    location_id=LOCATION_ID,
    data_store_id=DATA_STORE_ID,
    max_documents=3,
    max_extractive_answer_count=3,
    get_extractive_answers=True,
    engine_data_type=2,
)

result = retriever.invoke(query)
for doc in result:
    print(doc)
```

### 配置和使用用于**混合**数据的检索器

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
retriever = VertexAISearchRetriever(
    project_id=PROJECT_ID,
    location_id=LOCATION_ID,
    search_engine_id=SEARCH_ENGINE_ID,
    max_documents=3,
    engine_data_type=3,
)

result = retriever.invoke(query)
for doc in result:
    print(doc)
```

### 配置和使用用于多轮搜索的检索器

[带后续问题的搜索](https://cloud.google.com/generative-ai-app-builder/docs/multi-turn-search)基于生成式 AI 模型，与常规的非结构化数据搜索不同。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
retriever = VertexAIMultiTurnSearchRetriever(
    project_id=PROJECT_ID, location_id=LOCATION_ID, data_store_id=DATA_STORE_ID
)

result = retriever.invoke(query)
for doc in result:
    print(doc)
```

## 用法

遵循上述示例，我们使用 `invoke` 发出单个查询。

***

## API 参考

有关所有 `VertexAISearchRetriever` 功能和配置的详细文档，请访问 [API 参考](https://reference.langchain.com/python/langchain-google-community/vertex_ai_search/VertexAISearchRetriever)。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/retrievers/google_vertex_ai_search.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>