本页面介绍了如何将 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 索引,您必须执行以下步骤:
请参阅 Pinecone 快速入门指南,了解为使索引与 RAG 语料库兼容而必须对索引指定的索引配置。
您需要确保 Pinecone 索引的位置与您使用 Vertex AI RAG Engine 的位置相同或相近,原因如下:
- 您希望保持较短的延迟时间。
- 您希望满足适用法律规定的数据驻留要求。
在 Pinecone 索引创建期间,指定要与 Vertex AI RAG 引擎搭配使用的嵌入维度。下表提供了维度大小或维度大小的位置:
型号 维度大小 第一方 Gecko 768 经过微调的第一方 Gecko 768 E5 请参阅使用 OSS 嵌入模型。 选择以下支持的距离指标之一:
cosine
dotproduct
euclidean
可选:创建基于 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,您必须执行以下操作:
将 API 密钥存储在 Secret Manager 中。
向您的 Vertex AI RAG 引擎服务账号授予对您的 Secret 的相应权限,并在 Secret 资源级管理访问权限控制。
前往项目的权限。
启用包括 Google 提供的角色授予选项。
查找具有以下格式的服务账号:
service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com
修改服务账号的主账号。
将
Secret Manager Secret Accessor
角色添加到 服务账号。
在创建或更新 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 语料库的整个生命周期内会持续存在。可以使用 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
在尝试此示例之前,请按照《Vertex AI 快速入门:使用客户端库》中的 Python 设置说明执行操作。 如需了解详情,请参阅 Vertex AI Python API 参考文档。
如需向 Vertex AI 进行身份验证,请设置应用默认凭证。 如需了解详情,请参阅为本地开发环境设置身份验证。
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}