Usa Pinecone con 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 este notebook RAG Engine con Pinecone.

Puedes usar tu instancia de la base de datos de Pinecone con RAG Engine 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 RAG Engine, puedes seguir usando tu instancia de base de datos de vectores completamente administrada, de la que eres responsable de aprovisionar. RAG Engine usa tu base de datos de vectores para el almacenamiento, la administración de índices y la búsqueda.

Considera si usar Pinecone con RAG Engine

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

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

  • El motor de RAG usa el espacio de nombres predeterminado en tu índice. Asegúrate de que ningún otro elemento pueda modificar este espacio de nombres.

  • Debes proporcionar una clave de API de Pinecone, que permite que el motor de RAG interactúe con la base de datos de Pinecone. RAG Engine no almacena ni administra tu clave de API de Pinecone. En su lugar, 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 al motor de RAG acceso al nombre del recurso de tu secreto.

    • Cuando interactúas con tu corpus de RAG, 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 del método ragCorpora.create o del método ragCorpora.patch.

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 el motor de RAG por los siguientes motivos:

    • Quieres mantener latencias reducidas.
    • Quieres cumplir con 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 incorporación que se usará con RAG Engine. 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 propio 768
    Gecko propio ajustado 768
    E5 Consulta Usa 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 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

El motor de RAG 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 la autenticación con el objetivo de 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 el motor de RAG, no almacenes ni administres tu clave de API, y evita 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 RAG Engine los permisos para 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 al motor de RAG y almacena el nombre del recurso secreto.

Cuando realizas solicitudes a la API a tus índices de Pinecone, RAG Engine 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 de RAG Engine

Cuando creas el primer corpus de RAG en tu proyecto, el motor de RAG 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 RAG Engine, debes asociarlo con un corpus de RAG durante su etapa de creación. Una vez que se realiza la asociación, esta vinculación es permanente durante el ciclo de vida del corpus de RAG. La asociación se puede realizar con la API de CreateRagCorpus o la de UpdateRagCorpus.

Para que la asociación se considere completa, debes establecer 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 te gustaría asociar con tu corpus de RAG, y se debe establecer durante la llamada a la API de CreateRagCorpus. Si no se establece, se asigna la opción de base de datos de vectores predeterminada 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 puedes especificarlo cuando llames a la API de UpdateRagCorpus.

  • rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: Este es el nombre completo del recurso del secreto que se almacena en Secret Manager, que contiene tu clave de API de Pinecone. Puedes establecer el nombre durante la llamada a CreateRagCorpus o puedes especificarlo cuando llames a la API de UpdateRagCorpus. Hasta que 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 del secreto con tu conjunto de permisos, puedes crear tu corpus de RAG y asociarlo con tu índice de Pinecone, como se muestra en este código de muestra.

Cuando sea la primera vez que crees un corpus de RAG, no tendrás lista la información de la cuenta de servicio. Sin embargo, los campos son opcionales y se pueden asociar con el corpus de RAG con 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 Agent Platform sobre cómo usar bibliotecas cliente.

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


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.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

# 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,
    ),
    api_auth=types.ApiAuth(
        api_key_config=types.ApiAuthApiKeyConfig(
            api_key_secret_version=pinecone_api_key_secret_manager_version
        )
    ),
    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}

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

  • Cuando no proporcionas el nombre del índice ni el nombre del Secret de la clave de API, los archivos no se pueden importar al corpus de RAG.

  • Si eliges Pinecone como tu base de datos de vectores para tu corpus de RAG, no podrás cambiarla más adelante a otra base de datos.

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 de 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}

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 del secreto de la clave de API no se configuraron antes, puedes usar la API de Pinecone para actualizar los campos. No se puede actualizar la elección de una base de datos de vectores. Proporcionar el secreto de la clave de API es opcional. 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 Inmutable después de que tomas una decisión. Obligatorio
rag_vector_db_config.pinecone.index_name Inmutable 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. Después de establecer la clave de API, no puedes quitarla. 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?