Utilizzare Vector Search 2.0 con RAG

Questa pagina mostra come il motore RAG su Gemini Enterprise Agent Platform utilizza Vector Search 2.0 di Gemini Enterprise Agent Platform, un prodotto Cloud de Confiance by S3NS che funge da sistema completo di archiviazione e recupero per archiviare e gestire le rappresentazioni vettoriali dei tuoi documenti. La ricerca vettoriale 2.0 di Gemini Enterprise Agent Platform viene quindi utilizzata per recuperare i documenti pertinenti in base alla somiglianza semantica del documento con una determinata query.

RAG gestirà le raccolte di Vector Search 2.0 per te e avrai accesso completo alle raccolte di Vector Search 2.0 nel tuo progetto.

Scelta di un backend RAG

Quando utilizzi RAG Engine su Gemini Enterprise Agent Platform, puoi scegliere tra diverse opzioni di archiviazione di backend per i tuoi corpora RAG. La seguente tabella riassume le differenze principali:

Scegli RagManagedVertexVectorSearch per usufruire delle funzionalità più recenti, della gestione automatizzata e della trasparenza dei dati di Vector Search 2.0. Se il supporto di CMEK è un requisito rigoroso, prendi in considerazione RagManagedDb, tenendo presente la mancanza di visibilità diretta sul database di backend.

Abilita l'API Vector Search

Per utilizzare Vector Search di Gemini Enterprise Agent Platform gestito da RAG, devi prima abilitare l'API Vector Search.

Crea un corpus RAG con RagManagedVertexVectorSearch

Questo esempio di codice mostra come creare un corpus RAG utilizzando 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": {}
      }
    }'

Importazione dei dati in RagManagedVertexVectorSearch

Puoi utilizzare l'API ImportRagFiles o l'API UploadRagFile per importare i tuoi dati in RagManagedVertexVectorSearch.

Per caricare il file locale nel corpus RAG, consulta Carica un file RAG. Per importare i dati nel corpus RAG, consulta il seguente esempio di codice che mostra come importare da Cloud Storage. Per scoprire di più sulle origini dati supportate, consulta Origini dati supportate per 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 indice per il tuo corpus

RAG Engine crea una raccolta Vector Search 2.0 per ogni corpus, ma non crea un indice per la raccolta. Finché non ne crei uno, ogni recupero è una scansione KNN di forza bruta.

Una scansione brute-force è più lenta di una ricerca indicizzata e KNN viene eseguito solo su raccolte di un massimo di 100.000 oggetti dati. RAG Engine archivia un chunk per oggetto dati, quindi, una volta che un corpus supera questo limite, il recupero non va a buon fine finché non esiste un indice.

Non indicizzare ogni corpus. Un indice viene eseguito sulla propria infrastruttura di gestione e viene fatturato per tutta la sua durata, indipendentemente dal fatto che venga eseguita o meno una query. Per decidere quali corpora ne hanno bisogno, consulta Decidi quali corpora indicizzare.

Una volta creato un indice, il recupero lo utilizza automaticamente. Il corpus non cambia e non è necessario importare nuovamente i dati.

Se stai indicizzando più corpora, crea uno script per il loop: non esiste un percorso di creazione collettiva. Le operazioni di indicizzazione simultanee sono limitate dalla quota, quindi crea gli indici in serie o in piccoli batch. Per scoprire di più, consulta Quote.

Prima di iniziare

La creazione di un indice richiede l'autorizzazione vectorsearch.indexes.create sulla raccolta, mentre il conteggio dei relativi oggetti dati richiede vectorsearch.dataObjects.query. Entrambe le autorizzazioni sono incluse nel ruolo Vector Search Admin (roles/vectorsearch.admin); Vector Search Index Writer (roles/vectorsearch.indexWriter) concede la prima. Nel progetto deve essere abilitata anche l'API Vector Search.

Trova gli ID corpus

Nel tuo progetto, ogni corpus ha esattamente una raccolta, denominata vertex-rag-RAG_CORPUS_ID. Elenca i tuoi corpora per ottenere i relativi ID.

Sostituisci PROJECT_ID con l'ID progetto:

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 numerica alla fine di ogni corpus name è il RAG_CORPUS_ID. Ogni corpus indica anche il nome completo della risorsa Collection in vectorDbConfig.ragManagedVertexVectorSearch.collectionName.

La risposta elenca al massimo 100 corpora e al massimo 25 se ometti pageSize. Se la risposta include un nextPageToken, passa questo valore come pageToken per recuperare la pagina successiva.

Se conosci già il RAG_CORPUS_ID che vuoi indicizzare, recupera solo quel corpus. La risposta contiene lo stesso 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"

Decidi quali corpora indicizzare

Per ogni corpus, conta gli oggetti dati nella relativa raccolta. Passa un filter vuoto per conteggiare l'intera raccolta:

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": {}}'

Il conteggio viene restituito in aggregateResults:

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

Crea un indice per il corpus quando si verifica una delle seguenti condizioni:

• Il conteggio è vicino o superiore a 100.000. Il limite conteggia gli oggetti di dati, non i file, quindi un corpus contenente un numero ridotto di file di grandi dimensioni può comunque superarlo di molto.
• Il recupero è troppo lento rispetto alla frequenza delle query. Una ricerca indicizzata è più veloce di una scansione brute-force e il divario aumenta man mano che la raccolta cresce.

In caso contrario, lascia il corpus non indicizzato ed evita il costo di pubblicazione. Puoi aggiungere un indice in un secondo momento se il database cresce.

Esamina lo schema Collection

Il motore RAG crea ogni raccolta con il seguente schema. Utilizza questi nomi quando specifichi il campo dell'indice e i campi di filtro.

Scegli le impostazioni dell'indice

UpdateIndex modifica solo il nome visualizzato, la descrizione, le etichette e i conteggi delle repliche, quindi per modificare una qualsiasi delle impostazioni in questa sezione devi eliminare l'indice e crearne uno nuovo.

Campo indice: impostalo su text_embedding, l'unico campo vettoriale nello schema della raccolta.

Metrica di distanza: impostala su coseno. Il motore RAG invia sempre COSINE_DISTANCE nelle richieste di recupero e Vector Search 2.0 rifiuta una richiesta di recupero la cui metrica non corrisponde all'indice. La metrica viene impostata su DOT_PRODUCT per impostazione predefinita se la ometti, quindi un indice creato senza questa metrica interrompe il recupero per quel corpus. Il motore RAG segnala l'errore come FAILED_PRECONDITION con il messaggio Failed to process Rag Managed Vertex Vector Search response., che non identifica la metrica come causa. La grafia varia in base alla piattaforma: il corpo REST accetta COSINE_DISTANCE, mentre il flag gcloud CLI accetta cosine-distance.

Infrastruttura: lascia l'indice sull'infrastruttura predefinita ottimizzata per le prestazioni, perché la distanza coseno non è supportata sull'infrastruttura ottimizzata per l'archiviazione. Un indice viene eseguito su un'infrastruttura di gestione dedicata e viene fatturato per tutta la sua durata. In v1, min_replica_count e max_replica_count sono entrambi impostati su 2, quindi per impostazione predefinita l'indice viene gestito da due repliche e non viene scalato automaticamente. Per saperne di più, consulta Indici di raccolta.

Campi filtro: imposta filter_fields solo su file_id. È l'unico campo su cui RAG Engine applica i filtri al momento del recupero e lo fa solo quando una richiesta di recupero limita la ricerca a file specifici. In particolare, corpus_id contiene lo stesso valore per ogni oggetto dati in una determinata raccolta, pertanto il filtro non offre alcun vantaggio.

Inoltre, il filtro dei metadati non richiede campi di filtro aggiuntivi. Quando una richiesta di recupero imposta ragRetrievalConfig.filter.metadataFilter, il motore RAG risolve prima il filtro in base ai metadati del file, converte il risultato nell'insieme di ID file RAG corrispondenti e invia questo insieme a Vector Search come lo stesso filtro file_id. L'aggiunta di rag_metadata a filter_fields aumenta le dimensioni dell'indice senza modificare il recupero.

Campi di datastore: lascia store_fields non impostato. Il motore RAG richiede tutti i campi di dati a ogni recupero, il che non è mai idoneo per l'erogazione in linea, pertanto i dati dei blocchi vengono letti dal database di supporto indipendentemente. I campi elencati in store_fields vengono inseriti nell'indice e conteggiati ai fini delle sue dimensioni, pertanto l'impostazione di questi campi comporta un aumento dei costi senza modificare il recupero.

Crea l'indice

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

Esegui il polling per il completamento

La creazione di un indice restituisce un'operazione a lunga esecuzione:

{
  "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
}

Esegui il polling dell'operazione utilizzando il nome della risposta:

OPERATION_NAME=OPERATION_NAME

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

Quando done è true, un campo response indica che l'indice è stato creato correttamente, mentre un campo error indica il motivo per cui non è stato creato. La creazione di un indice richiede diversi minuti e più tempo per un corpus di grandi dimensioni.

Per elencare le operazioni nel progetto e nella località, esegui questo comando:

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

Per ispezionare un indice esistente, esegui questo 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

Per eliminare un indice, operazione necessaria per modificare una qualsiasi delle sue impostazioni permanenti, esegui il comando seguente. Il recupero torna a una scansione KNN di forza bruta fino alla creazione dell'indice sostitutivo e non va a buon fine se il corpus supera i 100.000 chunk.

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

Passaggi successivi

• Per importare file e cartelle da Google Drive o Cloud Storage, consulta l'esempio di importazione di file RAG.

• Per elencare i file RAG, consulta l'esempio di elenco dei file RAG.

• Per utilizzare un reranker per il recupero, consulta Reranking per il motore RAG di Gemini Enterprise Agent Platform

• Per ottimizzare l'infrastruttura degli indici, le metriche di distanza e i parametri ScaNN, consulta Indici di raccolta.