Usar una base de datos de Weaviate con el motor de RAG de Vertex AI

Vista previa

Algunas de las funciones de RAG son ofertas de vista previa sujetas a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de los Términos Específicos de los Servicios de Google Cloud. Los productos y las funciones previos a la disponibilidad general pueden tener una asistencia limitada y los cambios que se produzcan en ellos podrían no ser compatibles con otras versiones previas a la disponibilidad general. Para obtener más información, consulta las descripciones de las fases de lanzamiento. Además, al usar la API de Gemini en Vertex AI, aceptas los términos y condiciones de la vista previa de IA generativa(Términos de la Vista Previa).

Vertex AI RAG Engine admite los controles de seguridad de VPC-SC y las CMEK. No se admiten los controles de residencia de datos ni de seguridad de AXT.

Para ver un ejemplo de cómo usar RAG Engine con Weaviate, ejecuta el cuaderno "RAG Engine with Weaviate" en uno de los siguientes entornos:

Abrir en Colab | Abrir en Colab Enterprise | Abrir en Vertex AI Workbench | Ver en GitHub

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

También puedes seguir los pasos de este cuaderno RAG Engine with Weaviate.

Puedes usar tu instancia de base de datos de Weaviate, que es una base de datos de código abierto, 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 inserción. El modelo de inserción genera datos vectoriales para cada fragmento de texto que se compara. La búsqueda de similitud se usa para obtener contextos semánticos para el grounding y devolver el contenido más preciso de tu LLM.

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

Cuestiones importantes

Antes de usar la base de datos de Weaviate, sigue estos pasos:

1. Debes crear, configurar e implementar tu instancia de base de datos y tu colección de Weaviate. Sigue las instrucciones de Crear una colección de Weaviate para configurar una colección basada en tu esquema.
2. Debes proporcionar una clave de API de Weaviate, que permite que RAG Engine interactúe con la base de datos de Weaviate. RAG Engine admite las APIs AuthN y AuthZ basadas en claves de API, que se conectan a tu base de datos de Weaviate y admiten una conexión HTTPS.
3. El motor RAG no almacena ni gestiona tu clave de API de Weaviate. En su lugar, debe hacer lo siguiente:
   1. Almacena la clave en Google Cloud Secret Manager.
   2. Concede permisos a la cuenta de servicio de tu proyecto para acceder al secreto.
   3. Proporciona acceso al motor RAG al nombre de recurso de tu secreto.
   4. Cuando interactúas con tu base de datos de Weaviate, RAG Engine accede a tu recurso secreto mediante tu cuenta de servicio.
4. El corpus de RAG Engine y la colección de Weaviate tienen una asignación individual. Los archivos RAG se almacenan en una colección de bases de datos de Weaviate. Cuando se hace una llamada a la API CreateRagCorpus o a la API UpdateRagCorpus, el corpus de RAG se asocia a la colección de la base de datos.
5. Además de las búsquedas semánticas basadas en inserciones densas, la búsqueda híbrida también se admite con RAG Engine a través de una base de datos de Weaviate. También puedes ajustar el peso entre la similitud de vectores densos y dispersos en una búsqueda híbrida.

Aprovisionar la base de datos de Weaviate

Antes de usar la base de datos de Weaviate con RAG Engine, debes hacer lo siguiente:

1. Configura y despliega tu instancia de base de datos de Weaviate.
2. Prepara el punto de conexión HTTPS.
3. Crea tu colección de Weaviate.
4. Usa tu clave de API para aprovisionar Weaviate con AuthN y AuthZ.
5. Aprovisiona tu cuenta de servicio de RAG Engine.

Configurar y desplegar tu instancia de base de datos de Weaviate

Debes seguir la guía de inicio rápido oficial de Weaviate. Sin embargo, puedes usar la Google Cloud guía de Marketplace, que es opcional.

Puedes configurar tu instancia de Weaviate en cualquier lugar, siempre que se pueda acceder al endpoint de Weaviate para configurarlo e implementarlo en tu proyecto. Después, podrás gestionar por completo tu instancia de base de datos de Weaviate.

Como RAG Engine no participa en ninguna fase del ciclo de vida de tu instancia de base de datos de Weaviate, es tu responsabilidad conceder permisos a RAG Engine para que pueda almacenar y buscar datos en tu base de datos de Weaviate. También es su responsabilidad asegurarse de que el motor RAG pueda usar los datos de su base de datos. Por ejemplo, si cambias tus datos, RAG Engine no será responsable de ningún comportamiento inesperado debido a esos cambios.

Preparar el endpoint HTTPS

Durante el aprovisionamiento de Weaviate, asegúrate de crear un endpoint HTTPS. Aunque se admiten las conexiones HTTP, preferimos que el tráfico de RAG Engine y de la base de datos de Weaviate use una conexión HTTPS.

Crear una colección de Weaviate

Como el corpus de RAG Engine y la colección de Weaviate tienen una correspondencia uno a uno, debes crear una colección en tu base de datos de Weaviate antes de asociarla al corpus de RAG Engine. Esta asociación única se realiza cuando llamas a la API CreateRagCorpus o a la API UpdateRagCorpus.

Cuando crees una colección en Weaviate, debes usar el siguiente esquema:

Nombre de la propiedad	Tipo de datos
fileId	text
corpusId	text
chunkId	text
chunkDataType	text
chunkData	text
fileOriginalUri	text

Usa tu clave de API para aprovisionar Weaviate con AuthN y AuthZ.

Para aprovisionar la clave de API de Weaviate, sigue estos pasos:

1. Crea la clave de API de Weaviate.
2. Configura Weaviate con tu clave de API de Weaviate.
3. Almacena tu clave de API de Weaviate en Secret Manager.

Crear la clave de API

RAG Engine solo puede conectarse a tus instancias de base de datos de Weaviate mediante tu clave de API para la autenticación y la autorización. Debes seguir la guía oficial de autenticación de Weaviate para configurar la autenticación basada en claves de API en tu instancia de la base de datos de Weaviate.

Si para crear la clave de API de Weaviate se necesita información de identidad para asociarla, que procede de RAG Engine, debes crear tu primer corpus y usar tu cuenta de servicio de RAG Engine como identidad.

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 un usuario al usar el motor RAG, no almacenes ni gestiones tu clave de API, y evita compartirla sin cifrar.

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

1. Almacena tu clave de API en Secret Manager.
2. Concede a tu cuenta de servicio de RAG Engine los permisos de 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 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 Permiso para acceder a los recursos de Secret Manager 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 haces solicitudes de API a tus instancias de base de datos de Weaviate, 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 la cuenta de servicio de RAG Engine

Cuando creas el primer recurso en tu proyecto, RAG Engine crea una cuenta de servicio específica. Puedes encontrar tu cuenta de servicio en la página de gestión de identidades y accesos de tu proyecto. La cuenta de servicio sigue este formato:

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

Por ejemplo, [e-mail].

Cuando se integra con la base de datos de Weaviate, tu cuenta de servicio se usa en los siguientes casos:

• Puedes usar tu cuenta de servicio para generar tu clave de API de Weaviate para la autenticación. En algunos casos, para generar la clave de API no se necesita información del usuario, lo que significa que no es necesario tener una cuenta de servicio para generar la clave de API.
• Puedes vincular tu cuenta de servicio con la clave de API de tu base de datos de Weaviate para configurar la autenticación (AuthN) y la autorización (AuthZ). Sin embargo, no es obligatorio usar una cuenta de servicio.
• Puedes almacenar la clave de API en Secret Manager en tu proyecto y conceder permisos a tu cuenta de servicio para acceder a estos recursos secretos.
• RAG Engine usa cuentas de servicio para acceder a la clave de API del Gestor de secretos de tus proyectos.

Configurar el entorno de la consola Google Cloud

Haz clic para saber cómo configurar tu entorno

Para saber cómo configurar su entorno, seleccione una de las siguientes pestañas:

Python

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

   Nota: Si ya conoces la API de Gemini en Google AI Studio, ten en cuenta que la API de Gemini para Vertex AI usa Identity and Access Management en lugar de claves de API para gestionar el acceso.

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

3. Instala o actualiza el SDK de Vertex AI para Python ejecutando el siguiente comando:

   pip3 install --upgrade "google-cloud-aiplatform>=1.38"
       

Node.js

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

   Nota: Si ya conoces la API de Gemini en Google AI Studio, ten en cuenta que la API de Gemini para Vertex AI usa Identity and Access Management en lugar de claves de API para gestionar el acceso.

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

3. Instala o actualiza el SDK de Vertex AI para Node.js ejecutando el siguiente comando:

   npm install @google-cloud/vertexai
       

Java

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

   Nota: Si ya conoces la API de Gemini en Google AI Studio, ten en cuenta que la API de Gemini para Vertex AI usa Identity and Access Management en lugar de claves de API para gestionar el acceso.

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

3. Para añadir google-cloud-vertexai como dependencia, añade el código adecuado para tu entorno:

   Maven con BOM

   Añade el siguiente código HTML a tu pom.xml:

   <dependencyManagement>
     <dependencies>
       <dependency>
         <groupId>com.google.cloud</groupId>
         <artifactId>libraries-bom</artifactId>
         <version>26.32.0</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>
     </dependencies>
   </dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>com.google.cloud</groupId>
       <artifactId>google-cloud-vertexai</artifactId>
     </dependency>
   </dependencies>
               

   Maven sin BOM

   Añade el siguiente código HTML a tu pom.xml:

   <dependency>
     <groupId>com.google.cloud</groupId>
     <artifactId>google-cloud-vertexai</artifactId>
     <version>0.4.0</version>
   </dependency>
             

   Gradle without BOM

   Add the following to your build.gradle

   implementation 'com.google.cloud:google-cloud-vertexai:0.4.0'

Go

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

   Nota: Si ya conoces la API de Gemini en Google AI Studio, ten en cuenta que la API de Gemini para Vertex AI usa Identity and Access Management en lugar de claves de API para gestionar el acceso.

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

3. Consulta los paquetes Go de la API Vertex AI disponibles para determinar qué paquete se adapta mejor a las necesidades de tu proyecto:

   • Paquete cloud.google.com/go/vertexai (recomendado)

     vertexai es un paquete creado por humanos que proporciona acceso a funciones y características comunes.

     Recomendamos este paquete como punto de partida para la mayoría de los desarrolladores que crean aplicaciones con la API de Vertex AI. Para acceder a las funciones y características que aún no se incluyen en este paquete, usa el aiplatform generado automáticamente.

   • Package cloud.google.com/go/aiplatform

     aiplatform es un paquete generado automáticamente.

     Este paquete está pensado para proyectos que requieren acceso a las funciones y características de la API Vertex AI que aún no ofrece el paquete vertexai creado por humanos.

4. Instala el paquete de Go que necesites para tu proyecto ejecutando uno de los siguientes comandos:

   # Human authored package. Recommended for most developers.
   go get cloud.google.com/go/vertexai
       
   
   # Auto-generated package.
   go get cloud.google.com/go/aiplatform
       

C#

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

   Nota: Si ya conoces la API de Gemini en Google AI Studio, ten en cuenta que la API de Gemini para Vertex AI usa Identity and Access Management en lugar de claves de API para gestionar el acceso.

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

REST

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

   Nota: Si ya conoces la API de Gemini en Google AI Studio, ten en cuenta que la API de Gemini para Vertex AI usa Identity and Access Management en lugar de claves de API para gestionar el acceso.
2. Configura las variables de entorno introduciendo lo siguiente. Sustituye PROJECT_ID por el ID de tu proyecto Google Cloud .

   MODEL_ID="gemini-2.0-flash-001"
   PROJECT_ID="PROJECT_ID"
       

3. Aprovisiona el endpoint:

   gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJECT_ID}
       

4. Opcional: Si usas Cloud Shell y se te pide que lo autorices, haz clic en Autorizar.

Prepara tu corpus de RAG

Para acceder a los datos de tu base de datos de Weaviate, RAG Engine debe tener acceso a un corpus RAG. En esta sección se describen los pasos para crear un solo corpus de RAG y otros.

Usar las APIs CreateRagCorpus y UpdateRagCorpus

Debes especificar los siguientes campos al llamar a las APIs CreateRagCorpus y UpdateRagCorpus:

• rag_vector_db_config.weaviate: después de llamar a la API CreateRagCorpus, se elige la configuración de la base de datos de vectores. La configuración de la base de datos vectorial contiene todos los campos de configuración. Si no se define el campo rag_vector_db_config.weaviate, se asigna el valor predeterminado a rag_vector_db_config.rag_managed_db.
• weaviate.http_endpoint: el endpoint de Weaviate HTTPS o HTTP se crea durante el aprovisionamiento de la instancia de la base de datos de Weaviate.
• weaviate.collection_name: el nombre de la colección que se crea durante el aprovisionamiento de la instancia de Weaviate. El nombre debe empezar por una letra mayúscula.
• api_auth.api_key_config: la configuración especifica que se debe usar una clave de API para autorizar el acceso a la base de datos de vectores.
• api_key_config.api_key_secret_version: el nombre de recurso del secreto almacenado en Secret Manager, que contiene tu clave de API de Weaviate.

Puedes crear y asociar tu corpus de RAG a la colección de Weaviate de tu instancia de base de datos. Sin embargo, es posible que necesites la cuenta de servicio para generar tu clave de API y configurar tu instancia de base de datos de Weaviate. La cuenta de servicio se genera cuando creas tu primer corpus de RAG. Después de crear tu primer corpus de RAG, es posible que la asociación entre la base de datos de Weaviate y la clave de API no esté lista para usarse en la creación de otro corpus de RAG.

Por si acaso tu base de datos y tu clave no están listas para asociarse a tu corpus de RAG, haz lo siguiente con tu corpus de RAG:

1. Define el campo weaviate en rag_vector_db_config.

   • No puedes cambiar la base de datos de vectores asociada.
   • Deja en blanco los campos http_endpoint y collection_name. Ambos campos se pueden actualizar más adelante.

2. Si no tiene la clave de API almacenada en Secret Manager, puede dejar el campo api_auth vacío. Cuando llamas a la API UpdateRagCorpus, puedes actualizar el campo api_auth. Weaviate requiere que se haga lo siguiente:

   1. Define el api_key_config en el campo api_auth.

   2. Define el api_key_secret_version de tu clave de API de Weaviate en Secret Manager. El campo api_key_secret_version usa el siguiente formato:

      projects/{project}/secrets/{secret}/versions/{version}

3. Si especificas campos que solo se pueden definir una vez, como http_endpoint o collection_name, no podrás cambiarlos a menos que elimines tu corpus de RAG y lo vuelvas a crear. También se pueden actualizar otros campos, como el campo de clave de API, api_key_secret_version.

4. Cuando llamas a UpdateRagCorpus, puedes definir el campo vector_db. El valor de vector_db debe ser weaviate en la llamada a la API CreateRagCorpus. De lo contrario, el sistema elegirá la opción Base de datos gestionada por RAG, que es la predeterminada. Esta opción no se puede cambiar al llamar a la API UpdateRagCorpus. Cuando llamas a UpdateRagCorpus y el campo vector_db está configurado parcialmente, puedes actualizar los campos marcados como Modificable (también denominados mutables).

En esta tabla se enumeran los campos mutables e inmutables de WeaviateConfig que se usan en tu código.

Nombre del campo	Mutable o inmutable
http_endpoint	Inmutable una vez configurada
collection_name	Inmutable una vez configurada
api_key_authentication	Modificable

Crear el primer corpus de RAG

Si la cuenta de servicio de RAG Engine no existe, haz lo siguiente:

1. Crea un corpus de RAG en RAG Engine con una configuración de Weaviate vacía, que inicia el aprovisionamiento de RAG Engine para crear una cuenta de servicio.
2. Elige un nombre para tu cuenta de servicio de RAG Engine que siga este formato:
   

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

   Por ejemplo, [e-mail].

3. Con tu cuenta de servicio, accede al secreto almacenado en el Gestor de secretos de tu proyecto, que contiene tu clave de API de Weaviate.
4. Obtén la siguiente información una vez que se haya completado el aprovisionamiento de Weaviate:
   • Tu endpoint HTTPS o HTTP de Weaviate.
   • El nombre de tu colección de Weaviate.
5. Llama a la API CreateRagCorpus para crear un corpus de RAG con una configuración de Weaviate vacía y llama a la API UpdateRagCorpus para actualizar el corpus de RAG con la siguiente información:
   • Tu endpoint HTTPS o HTTP de Weaviate.
   • El nombre de tu colección de Weaviate.
   • Nombre del recurso de clave de API.

Crear otro corpus RAG

Si la cuenta de servicio de RAG Engine ya existe, haga lo siguiente:

1. Obtén la cuenta de servicio de tu RAG Engine en los permisos de tu proyecto.
2. Habilita la opción "Incluir concesiones de roles proporcionadas por Google".
3. Elige un nombre para tu cuenta de servicio de RAG Engine que siga este formato:
   

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

4. Con tu cuenta de servicio, accede al secreto almacenado en el Gestor de secretos de tu proyecto, que contiene tu clave de API de Weaviate.
5. Durante el aprovisionamiento de Weaviate, obtenga la siguiente información:
   • El endpoint HTTPS o HTTP de Weaviate.
   • El nombre de tu colección de Weaviate.
6. Crea un corpus de RAG en RAG Engine y conéctalo con tu colección de Weaviate de una de las siguientes formas:
   1. Haz una llamada a la API CreateRagCorpus para crear un corpus de RAG con una configuración de Weaviate rellenada, que es la opción preferida.
   2. Haz una llamada a la API CreateRagCorpus para crear un corpus de RAG con una configuración de Weaviate vacía y haz una llamada a la API UpdateRagCorpus para actualizar el corpus de RAG con la siguiente información:
      • Endpoint HTTP de la base de datos de Weaviate
      • Nombre de la colección de Weaviate
      • Clave de API

Ejemplos

En esta sección se muestra un ejemplo de código que explica cómo configurar tu base de datos de Weaviate, Secret Manager, el corpus de RAG y el archivo de RAG. También se proporciona código de ejemplo para mostrar cómo importar archivos, obtener contexto, generar contenido y eliminar el corpus y los archivos de RAG.

Para usar el cuaderno de la API RAG de Model Garden, consulta Usar Weaviate con Llama 3.

Configurar tu base de datos de Weaviate

En este ejemplo de código se muestra cómo configurar los datos de Weaviate y Secret Manager.

REST

# TODO(developer): Update the variables.
# The HTTPS/HTTP Weaviate endpoint you created during provisioning.
HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"

# Select your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
# For example, "MyCollectionName"
# Note that the first letter needs to be capitalized.
# Otherwise, Weavaite will capitalize it for you.
WEAVIATE_COLLECTION_NAME="MyCollectionName"

# Create a collection in Weaviate which includes the required schema fields shown below.
echo '{
  "class": "'${WEAVIATE_COLLECTION_NAME}'",
  "properties": [
    { "name": "fileId", "dataType": [ "string" ] },
    { "name": "corpusId", "dataType": [ "string" ] },
    { "name": "chunkId", "dataType": [ "string" ] },
    { "name": "chunkDataType", "dataType": [ "string" ] },
    { "name": "chunkData", "dataType": [ "string" ] },
    { "name": "fileOriginalUri", "dataType": [ "string" ] }
  ]
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer "${WEAVIATE_API_KEY} \
    -d @- \
    ${HTTP_ENDPOINT_NAME}/v1/schema

Configurar Secret Manager

Para configurar Secret Manager, debes habilitarlo y definir los permisos.

Crear secreto

Para habilitar Secret Manager, sigue estos pasos:

Consola

1. Ve a la página Secret Manager.

   Ir a Secret Manager

2. Haz clic en + Crear secreto.

3. Introduce el nombre del secreto. Los nombres de secreto solo pueden contener letras del alfabeto latino (A-Z), números (0-9), guiones (-) y guiones bajos (_).

4. Especificar los siguientes campos es opcional:

   1. Para subir el archivo con tu secreto, haz clic en Examinar.
   2. Consulta la política de réplica.
   3. Si quieres gestionar manualmente las ubicaciones de tu secreto, marca la opción Gestionar las ubicaciones de este secreto manualmente. Debes seleccionar al menos una región.
   4. Selecciona la opción de cifrado.
   5. Si quieres definir manualmente el periodo de rotación, marca Definir periodo de rotación.
   6. Si quiere especificar temas de publicación o suscripción para recibir notificaciones de eventos, haga clic en Añadir temas.
   7. De forma predeterminada, los secretos no caducan nunca. Si quieres definir una fecha de vencimiento, marca Definir fecha de vencimiento.
   8. De forma predeterminada, las versiones de secretos se destruyen cuando se solicita. Para retrasar la destrucción de las versiones secretas, marca Definir la duración de la destrucción retrasada.
   9. Si quieres usar etiquetas para organizar y categorizar tus secretos, haz clic en + Añadir etiqueta.
   10. Si quiere usar anotaciones para adjuntar metadatos no identificativos a sus secretos, haga clic en + Añadir anotación.

5. Haz clic en Crear secreto.

REST

# Create a secret in SecretManager.
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets?secretId=${SECRET_NAME}" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"replication\": {\"automatic\": {}}}"

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.

# Import the Secret Manager client library.
from google.cloud import secretmanager


def create_secret(
    project_id: str, secret_id: str, ttl: Optional[str] = None
) -> secretmanager.Secret:
    """
    Create a new secret with the given name. A secret is a logical wrapper
    around a collection of secret versions. Secret versions hold the actual
    secret material.

     Args:
        project_id (str): The project ID where the secret is to be created.
        secret_id (str): The ID to assign to the new secret. This ID must be unique within the project.
        ttl (Optional[str]): An optional string that specifies the secret's time-to-live in seconds with
                             format (e.g., "900s" for 15 minutes). If specified, the secret
                             versions will be automatically deleted upon reaching the end of the TTL period.

    Returns:
        secretmanager.Secret: An object representing the newly created secret, containing details like the
                              secret's name, replication settings, and optionally its TTL.

    Example:
        # Create a secret with automatic replication and no TTL
        new_secret = create_secret("my-project", "my-new-secret")

        # Create a secret with a TTL of 30 days
        new_secret_with_ttl = create_secret("my-project", "my-timed-secret", "7776000s")
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent project.
    parent = f"projects/{project_id}"

    # Create the secret.
    response = client.create_secret(
        request={
            "parent": parent,
            "secret_id": secret_id,
            "secret": {"replication": {"automatic": {}}, "ttl": ttl},
        }
    )

    # Print the new secret name.
    print(f"Created secret: {response.name}")

Definir permisos

Debes conceder permisos de Secret Manager a tu cuenta de servicio.

Consola

1. En la sección IAM y administración de la consola Google Cloud , busca tu cuenta de servicio y haz clic en el icono del lápiz para editarla.

2. En el campo Rol, selecciona Permiso para acceder a los recursos de Secret Manager.

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.

def iam_grant_access(
    project_id: str, secret_id: str, member: str
) -> iam_policy_pb2.SetIamPolicyRequest:
    """
    Grant the given member access to a secret.
    """

    # Import the Secret Manager client library.
    from google.cloud import secretmanager

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret.
    name = client.secret_path(project_id, secret_id)

    # Get the current IAM policy.
    policy = client.get_iam_policy(request={"resource": name})

    # Add the given member with access permissions.
    policy.bindings.add(role="roles/secretmanager.secretAccessor", members=[member])

    # Update the IAM Policy.
    new_policy = client.set_iam_policy(request={"resource": name, "policy": policy})

    # Print data about the secret.
    print(f"Updated IAM policy on {secret_id}")

Añadir versión de secreto

REST

# TODO(developer): Update the variables.
# Select a resource name for your Secret, which contains your API Key.
SECRET_NAME="MyWeaviateApiKeySecret"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"
# Encode your WEAVIATE_API_KEY using base 64.
SECRET_DATA=$(echo ${WEAVIATE_API_KEY} | base64)

# Create a new version of your secret which uses SECRET_DATA as payload
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets/${SECRET_NAME}:addVersion" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"payload\": {\"data\": \"${SECRET_DATA}\"}}"

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 google.cloud import secretmanager
import google_crc32c  # type: ignore


def add_secret_version(
    project_id: str, secret_id: str, payload: str
) -> secretmanager.SecretVersion:
    """
    Add a new secret version to the given secret with the provided payload.
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent secret.
    parent = client.secret_path(project_id, secret_id)

    # Convert the string payload into a bytes. This step can be omitted if you
    # pass in bytes instead of a str for the payload argument.
    payload_bytes = payload.encode("UTF-8")

    # Calculate payload checksum. Passing a checksum in add-version request
    # is optional.
    crc32c = google_crc32c.Checksum()
    crc32c.update(payload_bytes)

    # Add the secret version.
    response = client.add_secret_version(
        request={
            "parent": parent,
            "payload": {
                "data": payload_bytes,
                "data_crc32c": int(crc32c.hexdigest(), 16),
            },
        }
    )

    # Print the new secret version name.
    print(f"Added secret version: {response.name}")

Usar Weaviate con Llama 3

El cuaderno de la API RAG de Model Garden muestra cómo usar el SDK de Vertex AI para Python con un corpus de Weaviate y un modelo Llama 3. Para usar el cuaderno, debes hacer lo siguiente:

1. Configura tu base de datos de Weaviate.

2. Configura Secret Manager.

3. Usa el cuaderno de la API RAG de Model Garden.

Para ver más ejemplos, consulta la sección Ejemplos.

Crear un corpus de RAG

Este código de ejemplo muestra cómo crear un corpus de RAG y define la instancia de Weaviate como su base de datos de vectores.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  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" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  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}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

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.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# weaviate_http_endpoint = "weaviate-http-endpoint"
# weaviate_collection_name = "weaviate-collection-name"
# weaviate_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.Weaviate(
    weaviate_http_endpoint=weaviate_http_endpoint,
    collection_name=weaviate_collection_name,
    api_key=weaviate_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=...
# ...

Usar el archivo RAG

La API RAG gestiona la subida, la importación, la creación de listas y la eliminación de archivos.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• PROJECT_ID: .
• LOCATION: la región en la que se procesará la solicitud.
• RAG_CORPUS_ID: ID del recurso RagCorpus.
• INPUT_FILE: la ruta de un archivo local.
• FILE_DISPLAY_NAME: nombre visible del RagFile.
• RAG_FILE_DESCRIPTION: la descripción del RagFile.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload

Cuerpo JSON de la solicitud:

{
 "rag_file": {
  "display_name": "FILE_DISPLAY_NAME",
  "description": "RAG_FILE_DESCRIPTION"
 }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado INPUT_FILE y ejecuta el siguiente comando:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @INPUT_FILE \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado INPUT_FILE y ejecuta el siguiente comando:

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile INPUT_FILE `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload" | Select-Object -Expand Content

Si la respuesta es correcta, se devuelve el recurso RagFile. El último componente del campo RagFile.name es el rag_file_id generado por el servidor.

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"
# path = "path/to/local/file.txt"
# display_name = "file_display_name"
# description = "file description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_file = rag.upload_file(
    corpus_name=corpus_name,
    path=path,
    display_name=display_name,
    description=description,
)
print(rag_file)
# RagFile(name='projects/[PROJECT_ID]/locations/us-central1/ragCorpora/1234567890/ragFiles/09876543',
#  display_name='file_display_name', description='file description')

Importar archivos RAG

Los archivos y las carpetas se pueden importar desde Drive o Cloud Storage.

REST

Usa response.metadata para ver los fallos parciales, el tiempo de solicitud y el tiempo de respuesta en el objeto response del SDK.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• PROJECT_ID: .
• LOCATION: la región en la que se procesará la solicitud.
• RAG_CORPUS_ID: ID del recurso RagCorpus.
• GCS_URIS: lista de ubicaciones de Cloud Storage. Ejemplo: gs://my-bucket1, gs://my-bucket2
• DRIVE_RESOURCE_ID: ID del recurso de Drive. Ejemplos:
• https://drive.google.com/file/d/ABCDE
• https://drive.google.com/corp/drive/u/0/folders/ABCDEFG
• DRIVE_RESOURCE_TYPE: tipo de recurso de Drive. Opciones:
• RESOURCE_TYPE_FILE - Archivo
• RESOURCE_TYPE_FOLDER - Carpeta
• CHUNK_SIZE: opcional. Número de tokens que debe tener cada fragmento.
• CHUNK_OVERLAP: opcional: número de tokens que se solapan entre fragmentos.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import

Cuerpo JSON de la solicitud:

{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": GCS_URIS
    },
    "google_drive_source": {
      "resource_ids": {
        "resource_id": DRIVE_RESOURCE_ID,
        "resource_type": DRIVE_RESOURCE_TYPE
      },
    }
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import" | Select-Object -Expand Content

Si la respuesta es correcta, se devuelve el recurso ImportRagFilesOperationMetadata.

En el siguiente ejemplo se muestra cómo importar un archivo desde Cloud Storage. Usa el campo de control max_embedding_requests_per_min para limitar la frecuencia con la que el motor RAG llama al modelo de inserciones durante el proceso de indexación ImportRagFiles. El campo tiene un valor predeterminado de 1000 llamadas por minuto.

// Cloud Storage bucket/file location.
// Such as "gs://rag-e2e-test/"
GCS_URIS=YOUR_GCS_LOCATION

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import a single Cloud Storage file or all files in a Cloud Storage bucket.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, GCS_URIS
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URIS}"\"'
    },
    "rag_file_chunking_config": {
      "chunk_size": 512
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

En el siguiente ejemplo se muestra cómo importar un archivo de Drive. Usa el campo de control max_embedding_requests_per_min para limitar la frecuencia con la que el motor RAG llama al modelo de inserciones durante el proceso de indexación ImportRagFiles. El campo tiene un valor predeterminado de 1000 llamadas por minuto.

// Google Drive folder location.
FOLDER_RESOURCE_ID=YOUR_GOOGLE_DRIVE_FOLDER_RESOURCE_ID

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import all files in a Google Drive folder.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, FOLDER_RESOURCE_ID
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "google_drive_source": {
      "resource_ids": {
        "resource_id": '\""${FOLDER_RESOURCE_ID}"\"',
        "resource_type": "RESOURCE_TYPE_FOLDER"
      }
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"
# paths = ["https://drive.google.com/file/123", "gs://my_bucket/my_files_dir"]  # Supports Google Cloud Storage and Google Drive Links

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.import_files(
    corpus_name=corpus_name,
    paths=paths,
    transformation_config=rag.TransformationConfig(
        rag.ChunkingConfig(chunk_size=512, chunk_overlap=100)
    ),
    import_result_sink="gs://sample-existing-folder/sample_import_result_unique.ndjson",  # Optional, this has to be an existing storage bucket folder, and file name has to be unique (non-existent).
    max_embedding_requests_per_min=900,  # Optional
)
print(f"Imported {response.imported_rag_files_count} files.")
# Example response:
# Imported 2 files.

Obtener un archivo RAG

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• PROJECT_ID: .
• LOCATION: la región en la que se procesará la solicitud.
• RAG_CORPUS_ID: ID del recurso RagCorpus.
• RAG_FILE_ID: ID del recurso RagFile.

Método HTTP y URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente:

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

Ejecuta el comando siguiente:

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content

Si la respuesta es correcta, se devuelve el recurso RagFile.

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_file = rag.get_file(name=file_name)
print(rag_file)
# Example response:
# RagFile(name='projects/1234567890/locations/us-central1/ragCorpora/11111111111/ragFiles/22222222222',
# display_name='file_display_name', description='file description')

Mostrar archivos RAG

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• PROJECT_ID: .
• LOCATION: la región en la que se procesará la solicitud.
• RAG_CORPUS_ID: ID del recurso RagCorpus.
• PAGE_SIZE: tamaño de página de lista estándar. Puedes ajustar el número de RagFiles que se devuelven por página actualizando el parámetro page_size.
• PAGE_TOKEN: el token de página de lista estándar. Se obtiene normalmente mediante ListRagFilesResponse.next_page_token de la llamada VertexRagDataService.ListRagFiles anterior.

Método HTTP y URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente:

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

PowerShell

Ejecuta el comando siguiente:

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content

Deberías recibir un código de estado que indique que la operación se ha realizado correctamente (2xx) junto con una lista de RagFiles en el RAG_CORPUS_ID proporcionado.

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

files = rag.list_files(corpus_name=corpus_name)
for file in files:
    print(file.display_name)
    print(file.name)
# Example response:
# g-drive_file.txt
# projects/1234567890/locations/us-central1/ragCorpora/111111111111/ragFiles/222222222222
# g_cloud_file.txt
# projects/1234567890/locations/us-central1/ragCorpora/111111111111/ragFiles/333333333333

Eliminar un archivo RAG

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• PROJECT_ID: .
• LOCATION: la región en la que se procesará la solicitud.
• RAG_CORPUS_ID: ID del recurso RagCorpus.
• RAG_FILE_ID: ID del recurso RagFile. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file_id}.

Método HTTP y URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el comando siguiente:

curl -X DELETE \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

Ejecuta el comando siguiente:

$headers = @{  }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content

Si la respuesta es correcta, se devuelve el recurso DeleteOperationMetadata.

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag.delete_file(name=file_name)
print(f"File {file_name} deleted.")
# Example response:
# Successfully deleted the RagFile.
# File projects/1234567890/locations/us-central1/ragCorpora/1111111111/ragFiles/2222222222 deleted.

Recuperar contexto

Cuando un usuario hace una pregunta o proporciona una petición, el componente de recuperación de RAG busca en su base de conocimientos información relevante para la consulta.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• LOCATION: la región en la que se procesará la solicitud.
• PROJECT_ID: .
• RAG_CORPUS_RESOURCE: el nombre del recurso RagCorpus. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.
• VECTOR_DISTANCE_THRESHOLD: solo se devuelven los contextos con una distancia vectorial inferior al umbral.
• TEXT: el texto de la consulta para obtener contextos relevantes.
• SIMILARITY_TOP_K: número de contextos principales que se van a obtener.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts

Cuerpo JSON de la solicitud:

{
 "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "vector_distance_threshold": 0.8
  },
  "query": {
   "text": "TEXT",
   "similarity_top_k": SIMILARITY_TOP_K
  }
 }

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts" | Select-Object -Expand Content

Deberías recibir un código de estado correcto (2xx) y una lista de RagFiles relacionados.

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-central1/ragCorpora/[rag_corpus_id]"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.retrieval_query(
    rag_resources=[
        rag.RagResource(
            rag_corpus=corpus_name,
            # Optional: supply IDs from `rag.list_files()`.
            # rag_file_ids=["rag-file-1", "rag-file-2", ...],
        )
    ],
    text="Hello World!",
    rag_retrieval_config=rag.RagRetrievalConfig(
        top_k=10,
        filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
    ),
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Genera contenido

Una predicción controla el método de LLM que genera contenido.

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• PROJECT_ID: .
• LOCATION: la región en la que se procesará la solicitud.
• MODEL_ID: modelo de LLM para generar contenido. Ejemplo: gemini-2.5-flash
• GENERATION_METHOD: método de LLM para generar contenido. Opciones: generateContent, streamGenerateContent
• INPUT_PROMPT: El texto enviado al LLM para generar contenido. Prueba a usar una petición relacionada con los archivos RAG subidos.
• RAG_CORPUS_RESOURCE: el nombre del recurso RagCorpus. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.
• SIMILARITY_TOP_K: opcional. Número de contextos principales que se van a recuperar.
• VECTOR_DISTANCE_THRESHOLD: opcional. Se devuelven los contextos con una distancia vectorial inferior al umbral.

Método HTTP y URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD

Cuerpo JSON de la solicitud:

{
 "contents": {
  "role": "user",
  "parts": {
    "text": "INPUT_PROMPT"
  }
 },
 "tools": {
  "retrieval": {
   "disable_attribution": false,
   "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "similarity_top_k": SIMILARITY_TOP_K,
    "vector_distance_threshold": VECTOR_DISTANCE_THRESHOLD
   }
  }
 }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD" | Select-Object -Expand Content

Si la respuesta es correcta, se devuelve el contenido generado con las citas.

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

from vertexai import rag
from vertexai.generative_models import GenerativeModel, Tool
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_retrieval_tool = Tool.from_retrieval(
    retrieval=rag.Retrieval(
        source=rag.VertexRagStore(
            rag_resources=[
                rag.RagResource(
                    rag_corpus=corpus_name,
                    # Optional: supply IDs from `rag.list_files()`.
                    # rag_file_ids=["rag-file-1", "rag-file-2", ...],
                )
            ],
            rag_retrieval_config=rag.RagRetrievalConfig(
                top_k=10,
                filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
            ),
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-2.0-flash-001", tools=[rag_retrieval_tool]
)
response = rag_model.generate_content("Why is the sky blue?")
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

Búsqueda híbrida

La búsqueda híbrida es compatible con la base de datos de Weaviate, que combina la búsqueda semántica y por palabras clave para mejorar la relevancia de los resultados de búsqueda. Durante la recuperación de los resultados de búsqueda, se combinan las puntuaciones de similitud de la búsqueda semántica (un vector denso) y de la búsqueda por palabras clave (un vector disperso) para obtener los resultados finales ordenados.

Búsqueda híbrida con la API de recuperación de RAG Engine

Este es un ejemplo de cómo habilitar una búsqueda híbrida mediante la API de extracción de RAG Engine.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  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" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  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}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

from vertexai import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-central1/ragCorpora/[rag_corpus_id]"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.retrieval_query(
    rag_resources=[
        rag.RagResource(
            rag_corpus=corpus_name,
            # Optional: supply IDs from `rag.list_files()`.
            # rag_file_ids=["rag-file-1", "rag-file-2", ...],
        )
    ],
    text="Hello World!",
    rag_retrieval_config=rag.RagRetrievalConfig(
        top_k=10,
        filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
    ),
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Usar la búsqueda híbrida y el motor RAG para la generación fundamentada

Este es un ejemplo de cómo usar la búsqueda híbrida y el motor RAG para generar contenido fundamentado.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Vertex AI Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  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" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  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}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python

Para saber cómo instalar o actualizar el SDK de Vertex AI para Python, consulta Instalar el SDK de Vertex AI para Python. Para obtener más información, consulta la documentación de referencia de la API Python.

from vertexai import rag
from vertexai.generative_models import GenerativeModel, Tool
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_retrieval_tool = Tool.from_retrieval(
    retrieval=rag.Retrieval(
        source=rag.VertexRagStore(
            rag_resources=[
                rag.RagResource(
                    rag_corpus=corpus_name,
                    # Optional: supply IDs from `rag.list_files()`.
                    # rag_file_ids=["rag-file-1", "rag-file-2", ...],
                )
            ],
            rag_retrieval_config=rag.RagRetrievalConfig(
                top_k=10,
                filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
            ),
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-2.0-flash-001", tools=[rag_retrieval_tool]
)
response = rag_model.generate_content("Why is the sky blue?")
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

Siguientes pasos

• Usar Pinecone con el motor de RAG de Vertex AI