将 Pinecone 与 Vertex AI RAG 引擎搭配使用

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

您也可以使用此笔记本 Vertex AI RAG 引擎搭配 Pinecone 进行操作。

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

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

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

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

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

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

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

    • 将密钥存储在 Google Cloud Secret Manager 中。
    • 向项目的服务账号授予访问 Secret 的权限。
    • 向 Vertex AI RAG 引擎提供对 Secret 资源名称的访问权限。
    • 当您与 RAG 语料库进行交互时,Vertex AI RAG 引擎会使用您的服务账号访问您的 Secret 资源。
  • RAG 语料库与 Pinecone 索引之间存在一对一的映射关系。这种关联是在 CreateRagCorpus API 调用UpdateRagCorpus API 调用中建立的。

创建 Pinecone 索引

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

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

  2. 您需要确保 Pinecone 索引的位置与您使用 Vertex AI RAG Engine 的位置相同或相近,原因如下:

    • 您希望保持较短的延迟时间。
    • 您希望满足适用法律规定的数据驻留要求。
  3. 在 Pinecone 索引创建期间,指定要与 Vertex AI RAG 引擎搭配使用的嵌入维度。下表提供了维度大小或维度大小的位置:

    型号 维度大小
    第一方 Gecko 768
    经过微调的第一方 Gecko 768
    E5 请参阅使用 OSS 嵌入模型
  4. 选择以下支持的距离指标之一:

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

创建 Pinecone API 密钥

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

将 API 密钥存储在 Secret Manager 中

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

如需保护 SPII,您必须执行以下操作:

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

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

    1. 前往项目的权限

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

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

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

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

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

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

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

预配 Vertex AI RAG 引擎服务账号

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

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

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

例如,

service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com

准备 RAG 语料库

如需将 Pinecone 索引与 Vertex AI RAG 引擎搭配使用,您必须在索引创建阶段将索引与 RAG 语料库相关联。关联建立后,此绑定在 RAG 语料库的整个生命周期内会持续存在。可以使用 CreateRagCorpusUpdateRagCorpus 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

在尝试此示例之前,请按照《Vertex AI 快速入门:使用客户端库》中的 Python 设置说明执行操作。 如需了解详情,请参阅 Vertex AI Python API 参考文档

如需向 Vertex AI 进行身份验证,请设置应用默认凭证。 如需了解详情,请参阅为本地开发环境设置身份验证


from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# pinecone_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = rag.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
        publisher_model="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = rag.Pinecone(
    index_name=pinecone_index_name,
    api_key=pinecone_api_key_secret_manager_version,
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    backend_config=rag.RagVectorDbConfig(
        rag_embedding_model_config=embedding_model_config,
        vector_db=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}

后续步骤