Usar Pinecone con el motor de RAG de Vertex AI

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

También puedes seguir los pasos con este cuaderno Motor de RAG de Vertex AI con Pinecone.

Puedes usar tu instancia de base de datos de Pinecone con Vertex AI RAG Engine para indexar y realizar una búsqueda de similitud basada en vectores. Una búsqueda por similitud es una forma de encontrar fragmentos de texto similares al texto que buscas, lo que requiere el uso de un modelo de inserciones. El modelo de inserción genera datos vectoriales de cada fragmento de texto que se compara. La búsqueda de similitud se usa para obtener contextos semánticos para el fundamento con el fin de devolver el contenido más preciso de tu LLM.

Con Vertex AI RAG Engine, puedes seguir usando tu instancia de base de datos de vectores totalmente gestionada, que eres responsable de aprovisionar. Vertex AI RAG Engine usa tu base de datos de vectores para el almacenamiento, la gestión de índices y la búsqueda.

Considerar si se debe usar Pinecone con Vertex AI RAG Engine

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

  • Debes crear, configurar y gestionar el escalado de tu instancia de base de datos de Pinecone.

  • Vertex AI RAG Engine usa el espacio de nombres predeterminado de tu índice. Asegúrate de que este espacio de nombres no se pueda modificar por ningún otro elemento.

  • 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. Vertex AI RAG Engine no almacena ni gestiona tu clave de API de Pinecone. En su lugar, debe hacer lo siguiente:

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

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

Crear un í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 debes especificar en tu índice para que sea compatible con el corpus de RAG.

  2. Quieres 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:

    • Quieres mantener una latencia baja.
    • Quieres cumplir los requisitos de residencia de datos que establecen las leyes aplicables.

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

    Modelo Tamaño de la dimensión
    Gecko propio 17.
    Gecko propio optimizado 17.
    E5 Consulta Usar modelos de inserciones de software libre.

  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 el 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

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

Almacenar la clave de API en Secret Manager

Una clave de API contiene información personal identificable sensible (IPIS), que está sujeta a requisitos legales. Si los datos de IIPS se vulneran o se usan de forma inadecuada, una persona puede sufrir un riesgo o un daño significativos. Para minimizar los riesgos para una persona al usar Vertex AI RAG Engine, no almacenes ni gestiones tu clave de API, y evita compartirla sin cifrar.

Para proteger la información personal sensible, debes hacer lo siguiente:

  1. Almacena tu clave de API en Secret Manager.

  2. Concede a tu cuenta de servicio de Vertex AI RAG Engine los permisos para tus secretos y gestiona el control de acceso a nivel de recurso secreto.

    1. Ve a los permisos de tu proyecto.

    2. Habilita la opción Incluir concesiones 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 las entidades de la cuenta de servicio.

    5. Añade 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 al motor de RAG de Vertex AI y almacena el nombre del recurso secreto.

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

Aprovisionar 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 específica. Puedes encontrar tu cuenta de servicio en la página Gestión de Identidades y Accesos 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 Vertex AI RAG Engine, debes asociar el índice con un corpus de RAG durante la fase de creación. Una vez que se ha creado la asociación, esta vinculación es permanente durante la vida útil del corpus de RAG. La asociación se puede hacer mediante la CreateRagCorpus o la API UpdateRagCorpus.

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

  • rag_vector_db_config.pinecone: este campo te ayuda a elegir la base de datos de vectores que quieras asociar a tu corpus de RAG y debe definirse durante la llamada a la API CreateRagCorpus. Si no se define, se asignará a tu corpus de RAG la base de datos vectorial predeterminada RagManagedDb.

  • 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 definir el nombre durante la llamada CreateRagCorpus o especificarlo al llamar a la API UpdateRagCorpus.

  • rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: es el nombre completo del recurso del secreto almacenado en Secret Manager, que contiene tu clave de API de Pinecone. Puedes definir el nombre durante la llamada CreateRagCorpus o especificarlo al llamar a la API 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 de recurso secreto con tus permisos configurados, puedes crear tu corpus de RAG y asociarlo a tu índice de Pinecone, tal como se muestra en este código de ejemplo.

Si es la primera vez que creas un corpus de RAG, no tendrás la información de la cuenta de servicio. Sin embargo, los campos son opcionales y se pueden asociar al corpus de RAG mediante la API UpdateRagCorpus.

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

Python

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

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en 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}

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

Si es tu primer corpus de RAG y no tienes acceso a los detalles de tu cuenta de servicio o no has completado los pasos de aprovisionamiento de tu índice de Pinecone, puedes crear tu corpus de RAG. Después, puedes asociar el corpus de RAG a una configuración de Pinecone vacía y añadir 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 base de datos de vectores para tu corpus de RAG, no podrás cambiarla por 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 de Pinecone ni un nombre de secreto de API. Usa la API UpdateRagCorpus para especificar más adelante la información que falta.

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}

Actualizar el corpus de RAG

La API UpdateRagCorpus te permite actualizar la configuración de la base de datos vectorial. Si el nombre del índice de Pinecone y la versión secreta de la clave de API no se han definido previamente, puedes usar la API de Pinecone para actualizar los campos. La elección de una base de datos de vectores no se puede actualizar. 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 No se puede cambiar después de elegir una opción. Obligatorio
rag_vector_db_config.pinecone.index_name No se puede modificar después de configurar el campo en el corpus de RAG. Obligatorio
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version Mutable. Una vez que hayas definido la clave de API, no podrás eliminarla. 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}

Siguientes pasos