Vektorsuche 2.0 mit RAG verwenden

Auf dieser Seite wird beschrieben, wie die RAG Engine auf der Gemini Enterprise Agent Platform die Gemini Enterprise Agent Platform Vektorsuche 2.0 verwendet. Dies ist ein Cloud de Confiance by S3NS Produkt, das als umfassendes Speicher- und Abrufsystem zum Speichern und Verwalten von Vektordarstellungen Ihrer Dokumente dient. Anschließend wird die Vektorsuche 2.0 der Gemini Enterprise Agent Platform verwendet, um relevante Dokumente basierend auf der semantischen Ähnlichkeit des Dokuments mit einer bestimmten Abfrage abzurufen.

RAG verwaltet die Vektorsuche 2.0-Sammlungen für Sie und Sie haben vollen Zugriff auf die Vektorsuche 2.0-Sammlungen in Ihrem Projekt.

RAG-Backend auswählen

Wenn Sie die RAG Engine auf der Gemini Enterprise Agent Platform verwenden, können Sie zwischen verschiedenen Backend-Speicheroptionen für Ihre RAG-Korpora wählen. In der folgenden Tabelle sind die wichtigsten Unterschiede zusammengefasst:

Wählen Sie RagManagedVertexVectorSearch aus, um die neuesten Funktionen, die automatisierte Verwaltung und Transparenz für Ihre Vektorsuche 2.0-Daten zu erhalten. Wenn die CMEK-Unterstützung eine strikte Anforderung ist, sollten Sie RagManagedDb in Betracht ziehen. Beachten Sie dabei, dass die Backend-Datenbank nicht direkt sichtbar ist.

Vector Search API aktivieren

Wenn Sie die RAG-verwaltete Vektorsuche der Gemini Enterprise Agent Platform verwenden möchten, müssen Sie zuerst die Vector Search API aktivieren.

RAG-Korpus mit RagManagedVertexVectorSearch erstellen

In diesem Codebeispiel wird gezeigt, wie Sie mit RagManagedVertexVectorSearch einen RAG-Korpus erstellen.

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

Daten in RagManagedVertexVectorSearch importieren

Sie können entweder die ImportRagFiles API oder die UploadRagFile API verwenden, um Ihre Daten in die RagManagedVertexVectorSearch zu importieren.

Informationen zum Hochladen einer lokalen Datei in Ihren RAG-Korpus finden Sie unter RAG-Datei hochladen. Wenn Sie Daten in Ihren RAG-Korpus importieren möchten, sehen Sie sich das folgende Codebeispiel an, in dem der Import aus Cloud Storage veranschaulicht wird. Informationen zu den unterstützten Datenquellen finden Sie unter Für RAG unterstützte Datenquellen.

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}"\"',
      },
  }
}'

Index für Ihren Korpus erstellen

Die RAG Engine erstellt für jeden Korpus eine Vektorsuche 2.0-Sammlung, aber keinen Index für diese Sammlung. Bis Sie einen Index erstellen, ist jeder Abruf ein Brute-Force-KNN-Scan.

Ein Brute-Force-Scan ist langsamer als eine indexierte Suche und KNN wird nur für Sammlungen mit bis zu 100.000 Datenobjekten ausgeführt. Die RAG Engine speichert einen Block pro Datenobjekt. Wenn ein Korpus dieses Limit überschreitet, schlägt der Abruf fehl, bis ein Index vorhanden ist.

Indexieren Sie nicht jeden Korpus. Ein Index wird auf einer eigenen Bereitstellungsinfrastruktur ausgeführt und wird so lange abgerechnet, wie er existiert, unabhängig davon, ob er abgefragt wird oder nicht. Informationen dazu, für welche Korpora ein Index erforderlich ist, finden Sie unter Zu indexierende Korpora festlegen.

Sobald ein Index vorhanden ist, wird er automatisch für den Abruf verwendet. Der Korpus ändert sich nicht und Ihre Daten müssen nicht noch einmal importiert werden.

Wenn Sie mehrere Korpora indexieren, erstellen Sie ein Skript für die Schleife. Es gibt keinen Pfad für die Bulk-Erstellung. Gleichzeitige Indexvorgänge sind kontingentbeschränkt. Erstellen Sie die Indexe daher nacheinander oder in kleinen Batches. Weitere Informationen finden Sie unter Kontingente.

Hinweis

Zum Erstellen eines Index ist die Berechtigung vectorsearch.indexes.create für die Sammlung erforderlich. Zum Zählen der Datenobjekte ist die Berechtigung vectorsearch.dataObjects.query erforderlich. Beide Berechtigungen sind in der Rolle „Vektorsuche Admin“ (roles/vectorsearch.admin) enthalten. Die erste Berechtigung wird durch „Vektorsuche Index Writer“ (roles/vectorsearch.indexWriter) gewährt. Die Vektorsuche API muss ebenfalls im Projekt aktiviert sein.

Korpus-IDs ermitteln

In Ihrem Projekt hat jeder Korpus genau eine Sammlung mit dem Namen vertex-rag-RAG_CORPUS_ID. Listen Sie Ihre Korpora auf, um ihre IDs abzurufen.

Ersetzen Sie PROJECT_ID durch Ihre Projekt-ID:

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"

Der numerische Teil am Ende jedes Korpus name ist die RAG_CORPUS_ID. Für jeden Korpus wird auch der vollständige Ressourcenname der Sammlung in vectorDbConfig.ragManagedVertexVectorSearch.collectionName angegeben.

Die Antwort enthält maximal 100 Korpora und maximal 25, wenn Sie pageSize weglassen. Wenn die Antwort ein nextPageToken enthält, übergeben Sie diesen Wert als pageToken, um die nächste Seite abzurufen.

Wenn Sie den RAG_CORPUS_ID, den Sie indexieren möchten, bereits kennen, rufen Sie stattdessen diesen einen Korpus ab. Die Antwort enthält dieselbe 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"

Entscheiden, welche Korpora indexiert werden sollen

Zählen Sie für jeden Korpus die Datenobjekte in der zugehörigen Sammlung. Übergeben Sie einen leeren filter, um die gesamte Sammlung zu zählen:

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

Die Anzahl wird in aggregateResults zurückgegeben:

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

Erstellen Sie einen Index für diesen Korpus, wenn eine der folgenden Bedingungen erfüllt ist:

• Die Anzahl liegt bei oder über 100.000. Das Limit bezieht sich auf Datenobjekte, nicht auf Dateien. Ein Korpus mit einer kleinen Anzahl großer Dateien kann also weit über dem Limit liegen.
• Der Abruf ist bei Ihrer Abfragerate zu langsam. Eine indexierte Suche ist schneller als ein Brute-Force-Scan. Je größer die Sammlung, desto größer ist der Unterschied.

Andernfalls lassen Sie den Korpus nicht indexiert und vermeiden die Kosten für die Bereitstellung. Sie können später einen Index hinzufügen, wenn die Datenbank wächst.

Schema der Sammlung prüfen

Die RAG-Engine erstellt jede Sammlung mit dem folgenden Schema. Verwenden Sie diese Namen, wenn Sie das Indexfeld und die Filterfelder angeben.

Wählen Sie die Indexeinstellungen aus.

UpdateIndex ändert nur den Anzeigenamen, die Beschreibung, die Labels und die Anzahl der Replikate. Wenn Sie also eine der Einstellungen in diesem Abschnitt ändern möchten, müssen Sie den Index löschen und einen neuen erstellen.

Indexfeld: Legen Sie es auf text_embedding fest, das einzige Vektorfeld im Sammlungsschema.

Distanzmesswert: Legen Sie „Kosinus“ fest. Die RAG Engine sendet bei ihren Abrufanfragen immer COSINE_DISTANCE und Vektorsuche 2.0 lehnt eine Abrufanfrage ab, deren Messwert nicht mit dem Index übereinstimmt. Der Messwert wird standardmäßig auf DOT_PRODUCT gesetzt, wenn Sie ihn weglassen. Ein ohne ihn erstellter Index führt also dazu, dass der Abruf für diesen Korpus nicht funktioniert. Die RAG Engine meldet den Fehler als FAILED_PRECONDITION mit der Nachricht Failed to process Rag Managed Vertex Vector Search response., die den Messwert nicht als Ursache identifiziert. Die Schreibweise unterscheidet sich je nach Oberfläche: Der REST-Text verwendet COSINE_DISTANCE und das gcloud CLI-Flag cosine-distance.

Infrastruktur: Belassen Sie den Index auf der standardmäßigen leistungsoptimierten Infrastruktur, da die Kosinusdistanz auf speicheroptimierter Infrastruktur nicht unterstützt wird. Ein Index wird auf einer dedizierten Bereitstellungsinfrastruktur ausgeführt und wird so lange abgerechnet, wie er existiert. In v1 sind min_replica_count und max_replica_count standardmäßig auf 2 festgelegt. Der Index wird also standardmäßig von zwei Replikaten bereitgestellt und nicht automatisch skaliert. Weitere Informationen finden Sie unter Sammlungsindexe.

Filterfelder: Legen Sie für filter_fields nur file_id fest. Es ist das einzige Feld, nach dem die RAG Engine beim Abrufen filtert, und zwar nur dann, wenn eine Abrufanfrage die Suche auf bestimmte Dateien beschränkt. Insbesondere enthält corpus_id für jedes Datenobjekt in einer bestimmten Sammlung denselben Wert, sodass ein Filtern danach keinen Vorteil bietet.

Für die Metadatenfilterung sind auch keine zusätzlichen Filterfelder erforderlich. Wenn in einer Abrufanfrage ragRetrievalConfig.filter.metadataFilter festgelegt ist, löst die RAG Engine den Filter zuerst anhand Ihrer Dateimetadaten auf, konvertiert das Ergebnis in die entsprechenden RAG-Datei-IDs und sendet diese Gruppe als denselben file_id-Filter an die Vektorsuche. Wenn Sie rag_metadata zu filter_fields hinzufügen, wird die Indexgröße erhöht, ohne dass sich der Abruf ändert.

Felder speichern:Lassen Sie store_fields leer. Die RAG Engine fordert bei jedem Abruf alle Datenfelder an. Dies ist nie für die Inline-Bereitstellung geeignet. Daher werden die Blockdaten unabhängig davon aus der zugrunde liegenden Datenbank gelesen. In store_fields aufgeführte Felder werden in den Index übertragen und auf seine Größe angerechnet. Wenn Sie sie festlegen, entstehen also Kosten, ohne dass sich der Abruf ändert.

Index erstellen

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

Abfrage auf Abschluss

Beim Erstellen eines Index wird ein Vorgang mit langer Ausführungszeit zurückgegeben:

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

Fragen Sie den Vorgang mit dem Namen aus dieser Antwort ab:

OPERATION_NAME=OPERATION_NAME

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

Wenn done den Wert true hat, bedeutet ein response-Feld, dass der Index erfolgreich erstellt wurde. Ein error-Feld gibt den Grund für den Fehler an. Das Erstellen eines Index dauert einige Minuten, bei einem großen Korpus auch länger.

Führen Sie den folgenden Befehl aus, um die Vorgänge im Projekt und am Standort aufzulisten:

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

Führen Sie den folgenden Befehl aus, um einen vorhandenen Index zu prüfen:

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

Führen Sie den folgenden Befehl aus, um einen Index zu löschen. Dies ist erforderlich, um die permanenten Einstellungen zu ändern. Der Abruf erfolgt über einen Brute-Force-KNN-Scan, bis der Ersatzindex erstellt ist. Wenn der Korpus mehr als 100.000 Blöcke umfasst,schlägt der Abruf vollständig fehl.

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

Nächste Schritte

• Informationen zum Importieren von Dateien und Ordnern aus Google Drive oder Cloud Storage finden Sie im Beispiel zum Importieren von RAG-Dateien.

• Informationen zum Auflisten von RAG-Dateien finden Sie im Beispiel zum Auflisten von RAG-Dateien.

• Informationen zur Verwendung eines Rerankers für den Abruf finden Sie unter Reranking für die RAG Engine der Gemini Enterprise Agent Platform.

• Informationen zum Optimieren der Indexinfrastruktur, der Distanzmesswerte und der ScaNN-Parameter finden Sie unter Sammlungsindizes.