Usa Vector Search 2.0 con RAG

En esta página, se muestra cómo el motor de RAG en Gemini Enterprise Agent Platform usa Vector Search 2.0 de Gemini Enterprise Agent Platform, que es un producto de Cloud de Confiance by S3NS que funciona como un sistema integral de almacenamiento y recuperación para almacenar y administrar representaciones vectoriales de tus documentos. Luego, se usa Vector Search 2.0 de Gemini Enterprise Agent Platform para recuperar documentos relevantes en función de su similitud semántica con una consulta determinada.

RAG administrará las colecciones de Vector Search 2.0 por ti y tendrás acceso completo a las colecciones de Vector Search 2.0 en tu proyecto.

Elige un backend de RAG

Cuando usas RAG Engine en Gemini Enterprise Agent Platform, puedes elegir entre diferentes opciones de almacenamiento de backend para tus corpus de RAG. En la siguiente tabla, se resumen las diferencias clave:

Elige RagManagedVertexVectorSearch para obtener las funciones más recientes, la administración automatizada y la transparencia en tus datos de Vector Search 2.0. Si la compatibilidad con CMEK es un requisito estricto, considera RagManagedDb, teniendo en cuenta la falta de visibilidad directa de la base de datos de backend.

Habilita la API de Vector Search

Para usar la búsqueda de vectores de Gemini Enterprise Agent Platform administrada por RAG, primero debes habilitar la API de Vector Search.

Crea un corpus de RAG con RagManagedVertexVectorSearch

En estas muestras de código, se muestra cómo crear un corpus de RAG con RagManagedVertexVectorSearch.

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

vector_db = rag.RagManagedVertexVectorSearch()
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "vector_db_config": {
        "rag_managed_vertex_vector_search": {}
      }
    }'

Importa tus datos a RagManagedVertexVectorSearch

Puedes usar la API de ImportRagFiles o la API de UploadRagFile para importar tus datos a RagManagedVertexVectorSearch.

Para subir tu archivo local a tu corpus de RAG, consulta Sube un archivo RAG. Para importar datos a tu corpus de RAG, consulta la siguiente muestra de código que indica cómo importar desde Cloud Storage. Para obtener información sobre las fuentes de datos compatibles, consulta Fuentes de datos compatibles con RAG.

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
CORPUS_ID = YOUR_CORPUS_ID
PATHS = ["gs://my_bucket/my_files_dir"]

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

corpus_name = f"projects/{PROJECT_ID}/locations/{LOCATION}/ragCorpora/{CORPUS_ID}"
# This is a non blocking call.
response = await rag.import_files_async(
    corpus_name=corpus_name,
    paths=PATHS,
)

# Wait for the import to complete.
await response.result()

GCS_URI=GCS_URI

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URI}"\"',
      },
  }
}'

Crea un índice para tu corpus

RAG Engine crea una colección de Vector Search 2.0 para cada corpus, pero no crea un índice en esa colección. Hasta que crees uno, cada recuperación será un análisis de KNN de fuerza bruta.

Un análisis de fuerza bruta es más lento que una búsqueda indexada, y KNN solo se ejecuta en colecciones de hasta 100,000 objetos de datos. RAG Engine almacena un fragmento por objeto de datos, por lo que, una vez que un corpus supera ese límite, la recuperación falla hasta que exista un índice.

No indexar todos los corpus. Un índice se ejecuta en su propia infraestructura de entrega y se factura durante el tiempo que exista, independientemente de si se consulta o no. Para decidir qué corpus necesitan uno, consulta Decide qué corpus indexar.

Una vez que existe un índice, la recuperación lo usa automáticamente. El corpus no cambia y no es necesario volver a importar tus datos.

Si indexas varios corpus, crea una secuencia de comandos para el bucle: no hay una ruta de creación masiva. Las operaciones de índice simultáneas tienen una cuota limitada, por lo que debes crear los índices de forma serial o en lotes pequeños. Para obtener más información, consulta Cuotas.

Antes de comenzar

Para crear un índice, se requiere el permiso vectorsearch.indexes.create en la colección, y para contar sus objetos de datos, se requiere vectorsearch.dataObjects.query. Ambos permisos se incluyen en el rol de administrador de Vector Search (roles/vectorsearch.admin); el de escritor de índices de Vector Search (roles/vectorsearch.indexWriter) otorga el primero. La API de Vector Search también debe estar habilitada en el proyecto.

Encuentra los IDs de tus corpus

En tu proyecto, cada corpus tiene exactamente una colección, llamada vertex-rag-RAG_CORPUS_ID. Enumera tus corpus para obtener sus IDs.

Reemplaza PROJECT_ID por el ID de tu proyecto:

PROJECT_ID=PROJECT_ID
LOCATION=us-central1

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora?pageSize=100"

La parte numérica al final de cada corpus name es el RAG_CORPUS_ID. Cada corpus también informa el nombre completo del recurso Collection en vectorDbConfig.ragManagedVertexVectorSearch.collectionName.

La respuesta enumera como máximo 100 corpus y, como máximo, 25 si omites pageSize. Si la respuesta incluye un nextPageToken, pasa ese valor como pageToken para recuperar la página siguiente.

Si ya conoces el RAG_CORPUS_ID que quieres indexar, recupera ese corpus. La respuesta lleva el mismo collectionName:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/RAG_CORPUS_ID"

Decide qué corpus indexar

Para cada corpus, cuenta los objetos de datos de su colección. Pasa un filter vacío para contar toda la colección:

COLLECTION_ID=vertex-rag-RAG_CORPUS_ID

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://vectorsearch.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/collections/${COLLECTION_ID}/dataObjects:aggregate" \
-d '{"aggregate": "COUNT", "filter": {}}'

El recuento se devuelve en aggregateResults:

{
  "aggregateResults": [
    {
      "count": 95217
    }
  ]
}

Crea un índice para ese corpus cuando se cumpla alguna de las siguientes condiciones:

• El recuento se acerca a 100,000 o lo supera. El límite cuenta los objetos de datos, no los archivos, por lo que un corpus que contenga una pequeña cantidad de archivos grandes puede superarlo con creces.
• La recuperación es demasiado lenta para tu frecuencia de consultas. Una búsqueda indexada es más rápida que un análisis de fuerza bruta, y la brecha se amplía a medida que crece la colección.

De lo contrario, deja el corpus sin indexar y evita el costo de publicación. Puedes agregar un índice más adelante si crece.

Revisa el esquema de Collection

El motor de RAG crea cada colección con el siguiente esquema. Usa estos nombres cuando especifiques el campo de índice y los campos de filtro.

Elige la configuración del índice

UpdateIndex solo cambia el nombre visible, la descripción, las etiquetas y los recuentos de réplicas, por lo que, para cambiar cualquiera de los parámetros de configuración de esta sección, debes borrar el índice y crear uno nuevo.

Campo de índice: Configúralo como text_embedding, el único campo de vector en el esquema de la colección.

Métrica de distancia: Configúrala como coseno. El motor de RAG siempre envía COSINE_DISTANCE en sus solicitudes de recuperación, y Vector Search 2.0 rechaza una solicitud de recuperación cuya métrica no coincide con el índice. La métrica predeterminada es DOT_PRODUCT cuando la omites, por lo que un índice creado sin ella interrumpe la recuperación de ese corpus. El motor de RAG informa la falla como FAILED_PRECONDITION con el mensaje Failed to process Rag Managed Vertex Vector Search response., que no identifica la métrica como la causa. La ortografía varía según la plataforma: el cuerpo de REST toma COSINE_DISTANCE y la marca de gcloud CLI toma cosine-distance.

Infraestructura: Deja el índice en la infraestructura predeterminada optimizada para el rendimiento, ya que la distancia de coseno no es compatible con la infraestructura optimizada para el almacenamiento. Un índice se ejecuta en una infraestructura de entrega dedicada y se factura durante el tiempo que exista. En v1, min_replica_count y max_replica_count se establecen de forma predeterminada en 2, por lo que, de forma predeterminada, el índice se entrega con dos réplicas y no se ajusta automáticamente. Para obtener más información, consulta Índices de colecciones.

Campos de filtro: Configura filter_fields solo en file_id. Es el único campo en el que RAG Engine filtra en el momento de la recuperación, y lo hace solo cuando una solicitud de recuperación restringe la búsqueda a archivos específicos. En particular, corpus_id tiene el mismo valor para cada objeto de datos de una colección determinada, por lo que filtrarlo no proporciona ningún beneficio.

El filtrado de metadatos tampoco necesita campos de filtro adicionales. Cuando una solicitud de recuperación establece ragRetrievalConfig.filter.metadataFilter, el motor de RAG resuelve el filtro con los metadatos de tu archivo primero, convierte el resultado en el conjunto de IDs de archivos de RAG que coinciden y envía ese conjunto a Vector Search como el mismo filtro file_id. Agregar rag_metadata a filter_fields aumenta el tamaño del índice sin cambiar la recuperación.

Campos de la tienda: Deja store_fields sin configurar. El motor de RAG solicita todos los campos de datos en cada recuperación, lo que nunca califica para la entrega intercalada, por lo que los datos del fragmento se leen de la base de datos de respaldo de todos modos. Los campos que se indican en store_fields se envían al índice y se tienen en cuenta para su tamaño, por lo que, si los configuras, se agregan costos sin cambiar la recuperación.

Crea el índice

from google.cloud import vectorsearch_v1

client = vectorsearch_v1.VectorSearchServiceClient()

index = vectorsearch_v1.Index(
    index_field="text_embedding",
    distance_metric=vectorsearch_v1.DistanceMetric.COSINE_DISTANCE,
    filter_fields=["file_id"],
)
request = vectorsearch_v1.CreateIndexRequest(
    parent="projects/PROJECT_ID/locations/us-central1/collections/vertex-rag-RAG_CORPUS_ID",
    index_id="vertex-rag-RAG_CORPUS_ID-index",
    index=index,
)

operation = client.create_index(request=request)

# Wait for the result (note this may take up to several minutes).
operation.result()

PROJECT_ID=PROJECT_ID
RAG_CORPUS_ID=RAG_CORPUS_ID
LOCATION=us-central1
COLLECTION_ID=vertex-rag-${RAG_CORPUS_ID}
INDEX_ID=${COLLECTION_ID}-index

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://vectorsearch.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/collections/${COLLECTION_ID}/indexes?indexId=${INDEX_ID}" \
-d '{
      "index_field": "text_embedding",
      "distance_metric": "COSINE_DISTANCE",
      "filter_fields": ["file_id"]
    }'

gcloud vector-search collections indexes create vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --index-field=text_embedding \
  --distance-metric=cosine-distance \
  --filter-fields=file_id \
  --location=us-central1 \
  --project=PROJECT_ID

Sondea para verificar la finalización

La creación de un índice devuelve una operación de larga duración:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/operation-1770302393524-64a14a54fa197-0dea326c-5a90efda",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.OperationMetadata",
    "createTime": "2026-02-05T14:39:53.558308609Z",
    "target": "projects/PROJECT_ID/locations/us-central1/collections/vertex-rag-RAG_CORPUS_ID/indexes/vertex-rag-RAG_CORPUS_ID-index",
    "verb": "create",
    "apiVersion": "v1"
  },
  "done": false
}

Sondea la operación con el nombre de esa respuesta:

OPERATION_NAME=OPERATION_NAME

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://vectorsearch.googleapis.com/v1/${OPERATION_NAME}"

Cuando done es true, un campo response significa que el índice se compiló correctamente, y un campo error indica el motivo por el que falló. La compilación de un índice tarda varios minutos y más para un corpus grande.

Para enumerar las operaciones en el proyecto y la ubicación, ejecuta el siguiente comando:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/operations"

Para inspeccionar un índice existente, ejecuta el siguiente comando:

gcloud vector-search collections indexes describe vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --location=us-central1 \
  --project=PROJECT_ID

Para borrar un índice, lo que debes hacer para cambiar cualquiera de sus parámetros de configuración permanentes, ejecuta lo siguiente. La recuperación recurre a un análisis de KNN de fuerza bruta hasta que se compila el índice de reemplazo y falla por completo si el corpus supera los 100,000 fragmentos.

gcloud vector-search collections indexes delete vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --location=us-central1 \
  --project=PROJECT_ID

¿Qué sigue?

• Para importar archivos y carpetas desde Google Drive o Cloud Storage, consulta el ejemplo de importación de archivos de RAG.

• Para enumerar archivos RAG, consulta el ejemplo Enumera archivos RAG.

• Para usar un reclasificador para la recuperación, consulta Reclasificación para el motor de RAG de Gemini Enterprise Agent Platform.

• Para ajustar la infraestructura de índices, las métricas de distancia y los parámetros de ScaNN, consulta Índices de colecciones.