Usa Pinecone con el motor de RAG de Agent Platform de Gemini Enterprise

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

También puedes seguir este notebook de RAG Engine de Gemini Enterprise Agent Platform con Pinecone.

Puedes usar tu instancia de la base de datos de Pinecone con RAG Engine de Gemini Enterprise Agent Platform 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 de Gemini Enterprise Agent Platform, puedes seguir usando tu instancia de base de datos de vectores completamente administrada, de la que eres responsable de aprovisionar. RAG Engine de Gemini Enterprise Agent Platform 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 de Gemini Enterprise Agent Platform

Para decidir 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 la base de datos de Pinecone.

  • RAG Engine de Gemini Enterprise Agent Platform usa el espacio de nombres predeterminado en tu índice. Asegúrate de que este espacio de nombres no se pueda modificar con nada más.

  • Debes proporcionar una clave de API de Pinecone, que permite que RAG Engine de Gemini Enterprise Agent Platform interactúe con la base de datos de Pinecone. RAG Engine de Gemini Enterprise Agent Platform no almacena ni administra tu clave de API de Pinecone. En cambio, debes hacer lo siguiente:

    • Almacena tu clave en el Google Cloud Secret Manager.
    • Otorga permisos a la cuenta de servicio de tu proyecto para acceder a tu secreto.
    • Proporciona a RAG Engine de Gemini Enterprise Agent Platform acceso al nombre del recurso de tu secreto.

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

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 RAG Engine de Gemini Enterprise Agent Platform 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 embedding que se usará con RAG Engine de Gemini Enterprise Agent Platform. En esta tabla, se proporcionan los tamaños de dimensión o la ubicación de los tamaños de dimensión:

    Modelo Tamaño de la dimensión
    Gecko de origen 768
    Gecko de origen ajustado 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 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

RAG Engine de Gemini Enterprise Agent Platform 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 autenticación 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 RAG Engine de Gemini Enterprise Agent Platform, no almacene ni administre su clave de API, y evite compartir la clave de API sin encriptar.

Para proteger la SPII, debes hacer lo siguiente:

  1. Almacena tu clave de API en Secret Manager.

  2. Otorga a tu cuenta de servicio de RAG Engine de Gemini Enterprise Agent Platform 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 formato:

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

    4. Edita los principales de la cuenta de servicio.

    5. Agrega la función 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 RAG Engine de Gemini Enterprise Agent Platform y almacénalo.

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

Cuando creas el primer corpus de RAG de tu proyecto, RAG Engine de Gemini Enterprise Agent Platform crea una cuenta de servicio dedicada. Puedes encontrar tu cuenta de servicio en la página de administración de identidades y accesosde 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 de Gemini Enterprise Agent Platform, 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 la API de CreateRagCorpus o 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 configurar la elección de una base de datos de vectores que te gustaría asociar con tu corpus de RAG, y se debe configurar durante la llamada a la API de CreateRagCorpus. Si no está configurado, se asigna la opción predeterminada de 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 configurar el nombre durante la llamada a CreateRagCorpus o puedes especificarlo cuando llamas 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, que contiene tu clave de API de Pinecone. Puedes configurar el nombre durante la llamada a CreateRagCorpus o puedes especificarlo cuando llamas 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 del índice de Pinecone y al nombre del recurso secreto con tus permisos configurados, puedes crear tu corpus de RAG y asociarlo con tu índice de Pinecone, como se muestra en este código de muestra.

Cuando creas un corpus de RAG por primera vez, 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 mediante la API de UpdateRagCorpus.

Para obtener 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 de Python en la guía de inicio rápido de Agent Platform con 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. 


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 no completaste los pasos de aprovisionamientopara tu índice de Pinecone, puedes crear tu corpus de RAG. 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 y el nombre secreto de la clave de API, no se pueden importar archivos al corpus de RAG.

  • Si eliges Pinecone como tu base de datos de vectores para tu corpus de RAG, no se puede cambiar más adelante a una base de datos diferente.

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 secreto de API. Usa la API de UpdateRagCorpus para especificar más adelante la información faltante.

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 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. 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 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 configurar 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?