将 Pinecone 与 RAG 引擎搭配使用

Agent Platform RAG Engine 支持 VPC-SC 安全控制和 CMEK。不支持数据驻留和 AXT 安全控制。

如需查看将 RAG 引擎与 Pinecone 搭配使用的示例，请在以下任一环境中运行“RAG 引擎搭配 Pinecone”笔记本：

在 Colab 中打开 | 在 Colab Enterprise 中打开 | 在 Agent Platform Workbench 中打开 | 在 GitHub 上查看

本页面介绍了如何将 RAG 语料库连接到 Pinecone 数据库。

您也可以使用此笔记本 RAG Engine 搭配 Pinecone 进行操作。

您可以将 Pinecone 数据库实例与 RAG 引擎搭配使用以编制索引并执行基于向量的相似性搜索。相似性搜索是一种查找与您要寻找的文本相似的文本片段的方法，需要使用嵌入模型。嵌入模型会为要比较的每个文本片段生成向量数据。相似度搜索用于检索语义上下文以进行接地，以便可从 LLM 返回最准确的内容。

借助 RAG Engine，您可以继续使用您负责预配的全托管式向量数据库实例。RAG 引擎使用您的向量数据库进行存储、索引管理和搜索。

考虑是否将 Pinecone 与 RAG 引擎搭配使用

请查看以下内容，考虑使用 Pinecone 数据库是否是 RAG 应用的最佳选择：

• 您必须创建、配置和管理 Pinecone 数据库实例的扩缩。

• RAG 引擎对索引使用默认命名空间。请确保此命名空间无法被其他任何内容修改。

• 您必须提供 Pinecone API 密钥，以便 RAG 引擎可以与 Pinecone 数据库进行交互。RAG 引擎不会存储和管理您的 Pinecone API 密钥。相反，您必须执行以下操作：

  • 将密钥存储在 Google Cloud Secret Manager 中。
  • 向项目的服务账号授予访问 Secret 的权限。
  • 向 RAG 引擎提供对 Secret 资源名称的访问权限。

  • 当您与 RAG 语料库进行交互时，RAG 引擎会使用您的服务账号访问您的 Secret 资源。

  • RAG 语料库与 Pinecone 索引之间存在一对一的映射关系。这种关联是在 ragCorpora.create 方法或 ragCorpora.patch 方法中建立的。

创建 Pinecone 索引

如需创建 Pinecone 索引，您必须执行以下步骤：

1. 请参阅 Pinecone 快速入门指南，了解为使索引与 RAG 语料库兼容而必须对索引指定的索引配置。

2. 您需要确保 Pinecone 索引的位置与您使用 RAG 引擎的位置相同或相近，原因如下：

   • 您希望保持较短的延迟时间。
   • 您希望满足适用法律规定的数据驻留要求。

3. 在 Pinecone 索引创建期间，指定要与 RAG 引擎搭配使用的嵌入维度。下表提供了维度大小或维度大小的位置：

   模型	维度大小
   第一方 Gecko	768
   经过微调的第一方 Gecko	768
   E5	请参阅使用 OSS 嵌入模型。

4. 选择以下支持的距离指标之一：

   • cosine
   • dotproduct
   • euclidean

5. 可选：创建基于 Pod 的索引时，您必须在 pod.metadata_config.indexed 字段中指定 file_id。如需了解详情，请参阅选择性元数据索引编制。

创建 Pinecone API 密钥

只有使用您的 API 密钥进行身份验证和授权，RAG 引擎才能连接到您的 Pinecone 索引。您必须按照 Pinecone 官方身份验证指南在 Pinecone 项目中配置基于 API 密钥的身份验证。

将 API 密钥存储在 Secret Manager 中

API 密钥包含受法律要求约束的敏感的个人身份信息 (SPII)。如果 SPII 数据遭到破解或滥用，个人可能会面临重大风险或伤害。为最大限度降低个人在使用 RAG 引擎时的风险，请勿存储和管理您的 API 密钥，并避免共享未加密的 API 密钥。

如需保护 SPII，您必须执行以下操作：

1. 将 API 密钥存储在 Secret Manager 中。

2. 向您的 RAG 引擎服务账号授予对您的 Secret 的相应权限，并在 Secret 资源级管理访问权限控制。

   1. 前往项目的权限。

   2. 启用包括 Google 提供的角色授予选项。

   3. 查找具有以下格式的服务账号：

      service-{project number}@gcp-sa-vertex-rag.

   4. 修改服务账号的主账号。

   5. 将 Secret Manager Secret Accessor 角色添加到 服务账号。

3. 在创建或更新 RAG 语料库期间，将 Secret 资源名称传递给 RAG 引擎，并存储 Secret 资源名称。

向 Pinecone 索引发出 API 请求时，RAG 引擎会使用每个服务账号从您的项目中读取与 Secret Manager 中的 Secret 资源对应的 API 密钥。

预配 RAG 引擎服务账号

当您在项目中创建第一个 RAG 语料库时，RAG 引擎会创建一个专用服务账号。您可以在项目的“Identity and Access Management”页面中找到服务账号。

服务账号采用以下固定格式：

service-{project number}@gcp-sa-vertex-rag.

例如，

service-123456789@gcp-sa-vertex-rag.

准备 RAG 语料库

如需将 Pinecone 索引与 RAG 引擎搭配使用，您必须在索引创建阶段将索引与 RAG 语料库相关联。关联建立后，此绑定在 RAG 语料库的整个生命周期内会持续存在。可以使用 CreateRagCorpus 或 UpdateRagCorpus API 建立关联。

如需使系统将关联视为已完成，您必须在 RAG 语料库中设置三个关键字段：

• rag_vector_db_config.pinecone：此字段可帮助您设置要与 RAG 语料库相关联的向量数据库的选择，并且必须在 CreateRagCorpus API 调用期间进行设置。如果未设置，则默认向量数据库选项 RagManagedDb 会分配给您的 RAG 语料库。

• rag_vector_db_config.pinecone.index_name：这是用于创建与 RAG 语料库搭配使用的 Pinecone 索引的名称。您可以在 CreateRagCorpus 调用期间设置名称，也可以在调用 UpdateRagCorpus API 时指定名称。

• rag_vector_db_config.api_auth.api_key_config.api_key_secret_version：这是存储在 Secret Manager 中的 Secret 的完整资源名称，该 Secret 包含您的 Pinecone API 密钥。您可以在 CreateRagCorpus 调用期间设置名称，也可以在调用 UpdateRagCorpus API 时指定名称。在您指定此字段之前，无法将数据导入 RAG 语料库。

  此字段应采用以下格式：

  projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

创建 RAG 语料库

如果您可以通过您的权限集访问 Pinecone 索引名称和 Secret 资源名称，那么可以创建 RAG 语料库，并将其与 Pinecone 索引相关联（在此示例代码中进行了演示）。

如果您是首次创建 RAG 语料库，则不会有现成可用的服务账号信息。不过，这些字段是可选的，可以使用 UpdateRagCorpus API 与 RAG 语料库相关联。

如需查看如何在不提供服务账号信息的情况下创建 RAG 语料库的示例，请参阅在不使用索引名称或 API 密钥的情况下创建 RAG 语料库。

Python

试用此示例之前，请按照《Agent Platform 快速入门：使用客户端库》中的 Python 设置说明进行操作。

如需向代理平台进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。

import agentplatform
from agentplatform import types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Agent Platform client once per session
client = agentplatform.Client(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = types.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=types.RagEmbeddingModelConfigVertexPredictionEndpoint(
        endpoint="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = types.RagVectorDbConfig(
    pinecone=types.RagVectorDbConfigPinecone(
     index_name=pinecone_index_name,
    ),
    rag_embedding_model_config=embedding_model_config,
)

corpus = client.rag.create_corpus(
    rag_corpus=types.RagCorpus(
        display_name=display_name,
        description=description,
        rag_vector_db_config=vector_db,
    )
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

REST

   # Set your project ID under which you want to create the corpus
   PROJECT_ID = "YOUR_PROJECT_ID"

   # Choose a display name for your corpus
   CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

   # Set your Pinecone index name
   PINECONE_INDEX_NAME=YOUR_INDEX_NAME

   # Set the full resource name of your secret. Follows the format
   # projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
   SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

   # Call CreateRagCorpus API with all the Vector DB information.
   # You can also add the embedding model choice or set other RAG corpus parameters on
   # this call per your choice.
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
         "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
         "rag_vector_db_config" : {
            "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
            "api_auth": {"api_key_config":
                  {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
            }
         }
      }'

   # To poll the status of your RAG corpus creation, get the operation_id returned in
   # response of your CreateRagCorpus call.
   OPERATION_ID="YOUR_OPERATION_ID"

   # Poll Operation status until done = true in the response.
   # The response to this call will contain the ID for your created RAG corpus
   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

在不使用索引名称或 API 密钥的情况下创建 RAG 语料库

如果这是您的第一个 RAG 语料库，并且您无法访问服务账号详细信息，或者尚未对 Pinecone 索引完成预配步骤，您仍然可以创建 RAG 语料库。您随后可以将 RAG 语料库与空的 Pinecone 配置相关联，并在以后添加详细信息。

必须考虑以下因素：

• 如果不提供索引名称和 API 密钥 Secret 名称，则无法将文件导入 RAG 语料库。

• 如果您选择 Pinecone 作为 RAG 语料库的向量数据库，则无法在之后切换到其他数据库。

此代码示例演示了如何在不提供 Pinecone 索引名称或 API Secret 名称的情况下使用 Pinecone 创建 RAG 语料库。使用 UpdateRagCorpus API 可在以后指定缺失的信息。

Python

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone()

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST

# Set your project ID under which you want to create the corpus
PROJECT_ID = "YOUR_PROJECT_ID"

# Choose a display name for your corpus
CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

# Call CreateRagCorpus API with all the Vector DB information.
# You can also add the embedding model choice or set other RAG corpus parameters on
# this call per your choice.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "rag_vector_db_config" : {
         "pinecone": {}
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

更新 RAG 语料库

借助 UpdateRagCorpus API，您可以更新向量数据库配置。如果之前未设置 Pinecone 索引名称和 API 密钥 Secret 版本，您可以使用 Pinecone API 更新这些字段。向量数据库的选择无法更新。您可以选择是否提供 API 密钥 Secret。不过，如果您未指定 API 密钥 Secret，可以将数据导入 RAG 语料库。

字段	可变性	必填或可选
rag_vector_db_config.vector_db	进行选择后便无法更改。	必需
rag_vector_db_config.pinecone.index_name	在 RAG 语料库中设置该字段后便无法更改。	必需
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version	可更改。设置 API 密钥后，您无法删除该密钥。	可选

Python

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone(index_name=)

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST

# Set your project ID for the corpus that you want to create.
PROJECT_ID = "YOUR_PROJECT_ID"

# Set your Pinecone index name
PINECONE_INDEX_NAME=YOUR_INDEX_NAME

# Set the full resource name of your secret. Follows the format
# projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

# Call UpdateRagCorpus API with the Vector DB information.
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "rag_vector_db_config" : {
         "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
         "api_auth": {"api_key_config":
               {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
         }
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

后续步骤

• 将 Gemini Enterprise Agent Platform Vector Search 与 RAG Engine 搭配使用