Usa Pinecone con Vertex AI RAG Engine

En esta página, se muestra cómo conectar tu corpus de RAG a tu base de datos de Pinecone.

También puedes seguir los pasos con este notebook Vertex AI RAG Engine with Pinecone.

Puedes usar tu instancia de la base de datos de Pinecone con el motor de RAG de Vertex AI para indexar y realizar una búsqueda de similitud basada en vectores. Una búsqueda de similitud es una forma de encontrar fragmentos de texto que sean similares al texto que buscas, lo que requiere el uso de un modelo de embedding. El modelo de embedding produce datos de vectores para cada fragmento de texto que se compara. La búsqueda de similitud se usa para recuperar contextos semánticos para la fundamentación y mostrar el contenido más preciso de tu LLM.

Con el motor de RAG de Vertex AI, puedes seguir usando tu instancia de base de datos de vectores completamente administrada, de la que eres responsable de aprovisionar. El motor de RAG de Vertex AI usa tu base de datos de vectores para el almacenamiento, la administración de índices y la búsqueda.

Considera si usar Pinecone con el motor de RAG de Vertex AI

Para determinar si usar la base de datos de Pinecone es la mejor opción para tu aplicación de RAG, revisa lo siguiente:

  • Debes crear, configurar y administrar el ajuste de escala de tu instancia de base de datos de Pinecone.

  • El motor de RAG de Vertex AI usa el espacio de nombres predeterminado en tu índice. Asegúrate de que nada más pueda modificar este espacio de nombres.

  • Debes proporcionar una clave de API de Pinecone, que permite que el motor de RAG de Vertex AI interactúe con la base de datos de Pinecone. El motor de RAG de Vertex AI no almacena ni administra tu clave de API de Pinecone. En cambio, debes hacer lo siguiente:

    • Almacena tu clave en Google Cloud Secret Manager.
    • Otorga permisos a la cuenta de servicio de tu proyecto para acceder a tu secreto.
    • Proporciona acceso al motor de RAG de Vertex AI al nombre del recurso de tu secreto.
    • Cuando interactúas con tu corpus de RAG, Vertex AI RAG Engine accede a tu recurso de secreto con tu cuenta de servicio.

  • El corpus de RAG y el índice de Pinecone tienen una asignación de uno a uno. Esta asociación se realiza como parte de la llamada a la API de CreateRagCorpus o la llamada a la API de UpdateRagCorpus.

Crea tu índice de Pinecone

Para crear tu índice de Pinecone, debes seguir estos pasos:

  1. Consulta la guía de inicio rápido de Pinecone para obtener las configuraciones de índice que se deben especificar en tu índice para que sea compatible con el corpus de RAG.

  2. Debes asegurarte de que la ubicación del índice de Pinecone sea la misma o esté cerca de donde usas Vertex AI RAG Engine por los siguientes motivos:

    • Deseas mantener latencias reducidas.
    • Deseas cumplir con los requisitos de residencia de datos establecidos por las leyes aplicables.

  3. Durante la creación del índice de Pinecone, especifica la dimensión de incorporación que se usará con el motor de RAG de Vertex AI. En esta tabla, se proporcionan los tamaños de las dimensiones o la ubicación de los tamaños de las dimensiones:

    Modelo Tamaño de la dimensión
    Gecko de origen 768
    Gecko propio optimizado 768
    E5 Consulta Cómo usar modelos de embedding de OSS.

  4. Elige una de las siguientes métricas de distancia admitidas:

    • cosine
    • dotproduct
    • euclidean

  5. Opcional: Cuando creas un índice basado en pods, debes especificar file_id en el campo pod.metadata_config.indexed. Para obtener más información, consulta Indexación selectiva de metadatos.

Crea tu clave de API de Pinecone

El motor de RAG de Vertex AI solo puede conectarse a tu índice de Pinecone con tu clave de API para la autenticación y autorización. Debes seguir la guía oficial de Pinecone para configurar la autenticación basada en claves de API en tu proyecto de Pinecone.

Almacena tu clave de API en Secret Manager

Una clave de API contiene información de identificación personal sensible (IIPS), que está sujeta a requisitos legales. Si los datos de la SPII se ven comprometidos o se usan de forma inadecuada, una persona podría sufrir un riesgo o daño importante. Para minimizar los riesgos para una persona mientras usa Vertex AI RAG Engine, no almacene ni administre su clave de API, y evite compartir la clave de API sin encriptar.

Para proteger los SPII, debes hacer lo siguiente:

  1. Almacena tu clave de API en Secret Manager.

  2. Otorga a tu cuenta de servicio de Vertex AI RAG Engine los permisos a tus secretos y administra el control de acceso a nivel del recurso secreto.

    1. Navega a los permisos de tu proyecto.

    2. Habilita la opción Incluir asignaciones de roles proporcionadas por Google.

    3. Busca la cuenta de servicio, que tiene el siguiente formato:

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

    4. Edita los principales de la cuenta de servicio.

    5. Agrega el rol Secret Manager Secret Accessor a la cuenta de servicio.

  3. Durante la creación o actualización del corpus de RAG, pasa el nombre del recurso secreto a Vertex AI RAG Engine y almacénalo.

Cuando realizas solicitudes a la API a tus índices de Pinecone, el motor de RAG de Vertex AI usa cada cuenta de servicio para leer la clave de API que corresponde a tus recursos secretos en Secret Manager desde tus proyectos.

Aprovisiona tu cuenta de servicio del motor de RAG de Vertex AI

Cuando creas el primer corpus de RAG en tu proyecto, Vertex AI RAG Engine crea una cuenta de servicio dedicada. Puedes encontrar tu cuenta de servicio en la página de Identity and Access Management de tu proyecto.

La cuenta de servicio sigue este formato fijo:

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

Por ejemplo:

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

Prepara tu corpus de RAG

Para usar tu índice de Pinecone con el motor de RAG de Vertex AI, debes asociar el índice con un corpus de RAG durante la etapa de creación. Después de que se realiza la asociación, esta vinculación es permanente durante la vida útil del corpus de RAG. La asociación se puede realizar con CreateRagCorpus o la API de UpdateRagCorpus.

Para que la asociación se considere completa, debes configurar tres campos clave en el corpus de RAG:

  • rag_vector_db_config.pinecone: Este campo te ayuda a establecer la elección de una base de datos de vectores que deseas asociar con tu corpus de RAG y se debe configurar durante la llamada a la API de CreateRagCorpus. Si no se configura, se asigna la opción predeterminada de la base de datos de vectores RagManagedDb a tu corpus de RAG.

  • rag_vector_db_config.pinecone.index_name: Es el nombre que se usa para crear el índice de Pinecone que se usa con el corpus de RAG. Puedes establecer el nombre durante la llamada a CreateRagCorpus o especificarlo cuando llames a la API de UpdateRagCorpus.

  • rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: Es el nombre completo del recurso del secreto que se almacena en Secret Manager y que contiene tu clave de API de Pinecone. Puedes establecer el nombre durante la llamada a CreateRagCorpus o especificarlo cuando llames a la API de UpdateRagCorpus. Hasta que no especifiques este campo, no podrás importar datos al corpus de RAG.
    Este campo debe tener el siguiente formato:
    projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

Crea tu corpus de RAG

Si tienes acceso al nombre de tu índice de Pinecone y al nombre del recurso secreto con tus permisos establecidos, puedes crear tu corpus de RAG y asociarlo con tu índice de Pinecone, como se muestra en este código de muestra.

Cuando crees un corpus de RAG por primera vez, no tendrás la información de la cuenta de servicio disponible. Sin embargo, los campos son opcionales y se pueden asociar con el corpus de RAG a través de la API de UpdateRagCorpus.

Para ver un ejemplo de cómo crear el corpus de RAG sin proporcionar la información de la cuenta de servicio, consulta Crea un corpus de RAG sin un nombre de índice ni una clave de API.

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de Vertex AI sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Vertex AI Python.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 


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}

Crea un corpus de RAG sin un nombre de índice ni una clave de API

Si este es tu primer corpus de RAG y no tienes acceso a los detalles de tu cuenta de servicio, o bien no completaste los pasos de aprovisionamiento para tu índice de Pinecone, puedes crear tu corpus de RAG de todos modos. Luego, puedes asociar el corpus de RAG con una configuración de Pinecone vacía y agregar los detalles más adelante.

Se debe tener en cuenta lo siguiente:

  • Si no proporcionas el nombre del índice y el nombre secreto de la clave de API, no se podrán importar archivos al corpus de RAG.
  • Si eliges Pinecone como tu base de datos de vectores para tu corpus de RAG, no podrás cambiarla a otra base de datos más adelante.

En este ejemplo de código, se muestra cómo crear un corpus de RAG con Pinecone sin proporcionar un nombre de índice ni un nombre secreto de la API de Pinecone. Usa la API de UpdateRagCorpus para especificar la información faltante más adelante.

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}

Actualiza tu corpus de RAG

La API de UpdateRagCorpus te permite actualizar la configuración de la base de datos de vectores. Si el nombre del índice de Pinecone y la versión secreta de la clave de API no se establecieron previamente, puedes usar la API de Pinecone para actualizar los campos. No se puede actualizar la elección de una base de datos de vectores. Es opcional proporcionar el secreto de la clave de API. Sin embargo, si no especificas el secreto de la clave de API, puedes importar datos al corpus de RAG.

Campo Mutabilidad Obligatorio u opcional
rag_vector_db_config.vector_db Es inmutable después de que tomas una decisión. Obligatorio
rag_vector_db_config.pinecone.index_name Es inmutable después de que configures el campo en el corpus de RAG. Obligatorio
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version Mutable. Después de establecer la clave de API, no podrás descartarla. Opcional

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}

¿Qué sigue?