Usa Pinecone con RAG Engine

Vista previa

RAG Engine es una oferta de versión preliminar, sujeta a las “Condiciones de las ofertas de la fase previa a la DG” de las Condiciones específicas del servicio de Google Cloud. Los productos y las características anteriores a la disponibilidad general pueden tener asistencia limitada, y es posible que los cambios en estos productos y características no sean compatibles con otras versiones de la fase previa a la DG. Para obtener más información, consulta las descripciones de la etapa de lanzamiento. Además, si usas la API de Gemini en Vertex AI, aceptas los Términos y Condiciones de la versión preliminar de Generative AI (Términos de versión preliminar).

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 incorporación. El modelo de incorporación produce datos vectoriales 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 vectorial 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

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 escalamiento de tu instancia de la base de datos de Pinecone.

• El motor de RAG 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 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 el Administrador de secretos de Google Cloud.
  • Otorga permisos a la cuenta de servicio de tu proyecto para acceder a tu secret.
  • Proporciona acceso al motor de RAG al nombre del recurso de tu secreto.
  • Cuando interactúas con tu corpus de RAG, el motor de RAG accede a tu recurso secreto con tu cuenta de servicio.

• El corpus de RAG y el índice Pinecone tienen una asignación uno a uno. Esta asociación se realiza como parte de la llamada a la API de CreateRagCorpus o de 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 Pinecone sea la misma que la de RAG Engine o que esté cerca de ella 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 el motor de RAG. 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 optimizado	768
   E5	Consulta Cómo usar modelos de incorporación 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 de metadatos selectivos.

Crea tu clave de API de Pinecone

RAG Engine 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 la clave 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 se vulneran o se usan de forma inadecuada los datos de la SPII, una persona podría sufrir un riesgo o daño importante. Para minimizar los riesgos para una persona mientras usa RAG Engine, 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 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 RAG Engine y almacénalo.

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 de tus proyectos.

Aprovisiona tu cuenta de servicio de RAG Engine

Cuando creas el primer corpus de RAG en tu proyecto, RAG Engine crea una cuenta de servicio dedicada. Puedes encontrar tu cuenta de servicio en la página de administració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:

[e-mail]

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. Después de 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 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 establecer durante la llamada a la API de CreateRagCorpus. Si no está configurada, la opción predeterminada de la base de datos de vectores RagManagedDb se asigna a tu corpus de RAG.

• rag_vector_db_config.pinecone.index_name: Es el nombre que se usa para crear el índice 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 de recurso completo 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 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 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 a mano. Sin embargo, los campos son opcionales y se pueden asociar con el corpus de RAG mediante 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 Cómo crear 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.preview 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.EmbeddingModelConfig(
    publisher_model="publishers/google/models/text-embedding-004"
)

# 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,
    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 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. Luego, puedes asociar el corpus de RAG con una configuración vacía de Pinecone y agregar los detalles más adelante.

Se debe tener en cuenta lo siguiente:

• Si no proporcionas el nombre del índice ni el nombre secreto de la clave de API, los archivos no se pueden importar al corpus de RAG.
• Si eliges Pinecone como 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 la 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 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. 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 hagas una elecció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 soltarla.	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?

• Para obtener más información sobre cómo elegir modelos de incorporación, consulta Cómo usar modelos de incorporación con RAG Engine.
• Para obtener más información sobre la importación de archivos, consulta Importa archivos RAG.