RagManagedDb mit RAG Engine auf der Gemini Enterprise Agent Platform verwenden

Die VPC-SC-Sicherheitskontrollen und CMEK werden von der Agent Platform RAG Engine unterstützt. Datenstandort- und AXT-Sicherheitskontrollen werden nicht unterstützt.

Die von der RAG Engine verwaltete Cloud Spanner-Instanz wird als Vektordatenbank verwendet und ist allgemein verfügbar, wobei die Abrechnung aktiviert ist. Weitere Informationen finden Sie unter Abrechnung für die RAG Engine auf der Gemini Enterprise Agent Platform.

Auf dieser Seite wird beschrieben, wie die RAG Engine auf der Gemini Enterprise Agent Platform RagManagedDb verwendet. Dabei handelt es sich um eine unternehmensreife Vektordatenbank, in der Vektordarstellungen Ihrer Dokumente gespeichert und verwaltet werden. Die Vektordatenbank wird dann verwendet, um relevante Dokumente basierend auf der semantischen Ähnlichkeit des Dokuments mit einer bestimmten Abfrage abzurufen.

Außerdem wird auf dieser Seite beschrieben, wie Sie CMEK implementieren.

Wichtig: RagManagedDb wird standardmäßig verwendet und nutzt Spanner. Kunden wird die Nutzung einer von Google verwalteten Spanner-Instanz in Rechnung gestellt, die in einem Google-Mandantenprojekt mit Standard-Spanner-SKUs bereitgestellt wird.

Abrufstrategie verwalten

RagManagedDb bietet die folgenden Abrufstrategien zur Unterstützung Ihrer RAG-Anwendungsfälle:

Abrufstrategie	Beschreibung
k-Nearest Neighbors (KNN) (Standard)	Findet die exakten nächsten Nachbarn, indem alle Datenpunkte in Ihrem RAG-Korpus verglichen werden. Wenn Sie beim Erstellen des RAG-Korpus keine Strategie angeben, wird KNN als Standardabrufstrategie verwendet.	Prüft die perfekte Trefferquote (1,0) beim Abruf. Ideal für Anwendungen, bei denen die Trefferquote entscheidend ist. Ideal für kleine bis mittelgroße RAG-Korpora mit weniger als 10.000 RAG-Dateien. Erfordert die Suche in jedem einzelnen Datenpunkt. Daher steigt die Latenz mit der Anzahl der RAG-Dateien im Korpus.
Approximate Nearest Neighbors (ANN)	Verwendet Näherungstechniken, um ähnliche Nachbarn schneller als mit der KNN-Technik zu finden.	Reduziert die Abfragelatenz bei großen RAG-Korpora erheblich. Recall aufgrund der verwendeten Näherungstechniken leicht verringert. Sehr effektiv, wenn Sie große RAG-Korpora haben,also mehr als 10.000 RAG-Dateien. Wie viel Trefferquotenverlust für Sie akzeptabel ist, hängt vom Anwendungsfall ab. In den meisten großen Fällen ist es jedoch ein akzeptabler Kompromiss, ein wenig Trefferquote im Gegenzug für eine verbesserte Abfrageleistung zu verlieren.

RAG-Korpus mit KNN-RagManagedDb erstellen

In diesen Codebeispielen wird gezeigt, wie Sie einen RAG-Korpus mit KNN-RagManagedDb erstellen.

Python

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.RagManagedDb(retrieval_strategy=rag.KNN())
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

Ersetzen Sie die folgenden Variablen:

• PROJECT_ID: Ihre Projekt-ID.
• LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
• CORPUS_DISPLAY_NAME: Der Anzeigename des RAG-Korpus.

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

Vorschau

Einige der RAG-Funktionen sind Vorschauangebote, die den „Nutzungsbedingungen des Pre-GA-Angebots“ der Nutzungsbedingungen von Google Cloud unterliegen. Pre-GA-Produkte und -Funktionen sind „wie besehen“ verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Änderungen an Pre-GA-Produkten und -Funktionen sind möglicherweise nicht mit anderen Pre-GA-Versionen kompatibel. Weitere Informationen finden Sie in den Beschreibungen der Phasen der Produkteinführung. Wenn Sie die Gemini API auf der Gemini Enterprise Agent Platform verwenden, stimmen Sie den Nutzungsbedingungen für die Vorabversion von generativer KI zu.

RAG-Korpus mit ANN-RagManagedDb erstellen

Für die ANN-Funktion verwendet RagManagedDb eine baumbasierte Struktur, um Daten zu partitionieren und schnellere Suchvorgänge zu ermöglichen. Um den besten Recall und die beste Latenz zu erreichen, sollte die Struktur dieses Baums durch Experimente so konfiguriert werden, dass sie der Größe und Verteilung Ihrer Daten entspricht. Mit RagManagedDb können Sie die tree_depth und die leaf_count des Baums konfigurieren.

Der tree_depth bestimmt die Anzahl der Ebenen im Baum. Befolgen Sie diese Richtlinien:

• Wenn Sie etwa 10.000 RAG-Dateien im RAG-Korpus haben, setzen Sie den Wert auf 2.
• Wenn Sie mehr RAG-Dateien haben, setzen Sie diesen Wert auf 3.
• Wenn tree_depth nicht angegeben ist, weist die RAG Engine diesem Parameter den Standardwert 2 zu.

Der leaf_count bestimmt die Anzahl der Blattknoten in der baumbasierten Struktur. Jeder Blattknoten enthält Gruppen von eng verwandten Vektoren zusammen mit ihrem entsprechenden Zentroid. Befolgen Sie diese Richtlinien:

• Der empfohlene Wert ist 10 * sqrt(num of RAG files in your RAG corpus).

• Wenn keine Angabe erfolgt, weist die RAG Engine diesem Parameter den Standardwert 500 zu.

Python

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
TREE_DEPTH = YOUR_TREE_DEPTH # Optional: Acceptable values are 2 or 3. Default is 2.
LEAF_COUNT = YOUR_LEAF_COUNT # Optional: Default is 500.

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

ann_config = rag.ANN(tree_depth=TREE_DEPTH, leaf_count=LEAF_COUNT)
vector_db = rag.RagManagedDb(retrieval_strategy=ann_config)
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

REST

Ersetzen Sie die folgenden Variablen:

• PROJECT_ID: Ihre Projekt-ID.
• LOCATION: Die Region, in der die Anfrage verarbeitet werden soll.
• CORPUS_DISPLAY_NAME: Der Anzeigename des RAG-Korpus.
• TREE_DEPTH: Die Baumtiefe.
• LEAF_COUNT: Die Anzahl deiner Blätter.

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME
TREE_DEPTH=TREE_DEPTH
LEAF_COUNT=LEAF_COUNT

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": {
        "ragManagedDb": {
          "ann": {
            "tree_depth": '"${TREE_DEPTH}"',
            "leaf_count": '"${LEAF_COUNT}"'
          }
        }
      }
    }'

Vorschau

Einige der RAG-Funktionen sind Vorschauangebote, die den „Nutzungsbedingungen des Pre-GA-Angebots“ der Nutzungsbedingungen von Google Cloud unterliegen. Pre-GA-Produkte und -Funktionen sind „wie besehen“ verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Änderungen an Pre-GA-Produkten und -Funktionen sind möglicherweise nicht mit anderen Pre-GA-Versionen kompatibel. Weitere Informationen finden Sie in den Beschreibungen der Phasen der Produkteinführung. Wenn Sie die Gemini API auf der Gemini Enterprise Agent Platform verwenden, stimmen Sie den Nutzungsbedingungen für die Vorabversion von generativer KI zu.

Daten in ANN RagManagedDb importieren

Sie können entweder die ImportRagFiles API oder die UploadRagFile API verwenden, um Ihre Daten in den ANN-RagManagedDb zu importieren. Im Gegensatz zur KNN-Abrufstrategie muss der zugrunde liegende baumbasierte Index beim ANN-Ansatz jedoch mindestens einmal und optional nach dem Importieren großer Datenmengen neu erstellt werden, um eine optimale Trefferquote zu erzielen. Wenn die RAG Engine Ihren ANN-Index neu erstellen soll, setzen Sie in Ihrer ImportRagFiles-API-Anfrage rebuild_ann_index auf „true“.

Folgendes ist wichtig:

1. Bevor Sie den RAG-Korpus abfragen können, müssen Sie den ANN-Index mindestens einmal neu erstellen.
2. Pro Projekt und Standort wird nur eine gleichzeitige Indexneuerstellung unterstützt.

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

Python

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"]
REBUILD_ANN_INDEX = REBUILD_ANN_INDEX # Choose true or false.

# 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,
    rebuild_ann_index=REBUILD_ANN_INDEX
)

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

REST

GCS_URI=GCS_URI
REBUILD_ANN_INDEX=<true/false>

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}"\"',
      },
    "rebuild_ann_index": '${REBUILD_ANN_INDEX}'
  }
}'

Verschlüsselung verwalten

Die RAG Engine bietet robuste Optionen für die Verwaltung der Verschlüsselung Ihrer ruhenden Daten. Standardmäßig werden alle Nutzerdaten in RagManagedDb mit einem Google-owned and Google-managed encryption keyverschlüsselt. Dies ist die Standardeinstellung. Mit dieser Standardeinstellung können Sie prüfen, ob Ihre Daten sicher sind, ohne dass eine bestimmte Konfiguration erforderlich ist.

Wenn Sie mehr Kontrolle über die für die Verschlüsselung verwendeten Schlüssel benötigen, unterstützt die RAG Engine kundenverwaltete Verschlüsselungsschlüssel (Customer-Managed Encryption Keys, CMEK). Mit CMEK können Sie Ihre kryptografischen Schlüssel, die in Cloud Key Management Service (Cloud KMS) verwaltet werden, zum Schutz Ihrer RAG-Korpusdaten verwenden.

Informationen zu CMEK-Einschränkungen für RAG-Korpora finden Sie unter CMEK-Einschränkungen für die RAG Engine auf der Gemini Enterprise Agent Platform.

Cloud KMS-Schlüssel einrichten und Berechtigungen gewähren

Bevor Sie einen mit CMEK verschlüsselten RAG-Korpus erstellen können, müssen Sie einen kryptografischen Schlüssel in Google Cloud KMS einrichten und dem RAG Engine-Dienstkonto die erforderlichen Berechtigungen zur Verwendung dieses Schlüssels gewähren.

Vorbereitung

Prüfen Sie, ob Ihr Nutzerkonto die entsprechenden IAM-Berechtigungen (Identity and Access Management) im Projekt von Google Cloud hat, in dem Sie den Cloud KMS-Schlüssel und den RAG-Korpus erstellen möchten, um die folgenden Einrichtungsschritte auszuführen. In der Regel ist eine Rolle wie die Cloud KMS-Administratorrolle (roles/cloudkms.admin) erforderlich.

API aktivieren

So aktivieren Sie die Cloud Key Management Service API:

1. Rufen Sie die Google Cloud Console auf.
2. Wählen Sie das Projekt aus, in dem Sie Ihre Schlüssel verwalten möchten, und erstellen Sie Ihren RAG-Korpus.
3. Geben Sie in die Suchleiste „Key Management“ ein und wählen Sie den Dienst „Key Management“ aus.
4. Wenn die API nicht aktiviert ist, klicken Sie auf Aktivieren. Es kann einige Minuten dauern, bis die API vollständig bereitgestellt ist.

Cloud KMS-Schlüsselbund und -Schlüssel erstellen

So erstellen Sie einen Schlüsselbund:

1. Klicken Sie im Abschnitt Schlüsselverwaltung auf Schlüsselbund erstellen.

   Geben Sie Folgendes ein:

   • Schlüsselbundname: Geben Sie einen eindeutigen Namen für den Schlüsselbund ein, z. B. rag-engine-cmek-keys.
   • Standorttyp: Wählen Sie „Region“ aus. Der Cloud KMS-Schlüsselbund muss sich in derselben Region wie der RAG Engine-Endpunkt befinden, den Sie beim Verschlüsseln eines RAG-Korpus mit CMEK verwenden.
   • Standort: Wählen Sie die ausgewählte Region aus, z. B. us-central1. Diese Region sollte idealerweise mit der Region übereinstimmen, in der sich Ihre RAG Engine-Ressourcen befinden.

2. Klicken Sie auf Erstellen.

So erstellen Sie einen Schlüssel im Schlüsselbund:

1. Nachdem der Schlüsselbund erstellt wurde, werden Sie aufgefordert, einen Schlüssel zu erstellen. Alternativ können Sie zu Schlüssel erstellen wechseln.

   Geben Sie Folgendes ein:

   • Schlüsselname: Geben Sie einen eindeutigen Namen für den Schlüssel ein, z. B. my-rag-corpus-key.
   • Schutzniveau: Wählen Sie ein Schutzniveau aus (Software oder HSM). Wenn Sie hardwaregestützte Schlüssel benötigen, wählen Sie HSM aus.
   • Zweck: Wählen Sie Symmetrisches Ver-/Entschlüsseln aus. Dies ist für CMEK erforderlich.
   • Schlüsselmaterialquelle: Wählen Sie Generierter Schlüssel aus.
   • Rotationszeitraum: Optional. Recommended. Konfigurieren Sie einen Zeitplan für die Schlüsselrotation gemäß den Sicherheitsrichtlinien Ihrer Organisation, z. B. alle 90 Tage.

2. Klicken Sie auf Erstellen.

So kopieren Sie den Namen der Schlüsselressource:

1. Nachdem der Schlüssel erstellt wurde, rufen Sie die Detailseite auf.

2. Suchen Sie den Ressourcennamen. Das Format ist projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME/cryptoKeyVersions/1.

   Wichtig: Für den EncryptionSpec in Ihrem RAG-Korpus müssen Sie den Schlüsselressourcennamen ohne Versionsnummer verwenden.

3. Kopieren Sie den Ressourcennamen und entfernen Sie den Teil /cryptoKeyVersions/VERSION_NUMBER. Der korrekt formatierte Ressourcenname lautet projects/YOUR_PROJECT_ID/locations/YOUR_REGION/keyRings/YOUR_KEY_RING_NAME/cryptoKeys/YOUR_KEY_NAME.

Berechtigungen für den RAG Engine-Dienst-Agent erteilen

Damit die RAG Engine Daten mit Ihrem Cloud KMS-Schlüssel verschlüsseln und entschlüsseln kann, benötigt ihr Dienst-Agent die entsprechenden Berechtigungen für diesen Schlüssel.

So ermitteln Sie den Dienst-Agent der RAG Engine:

1. Rufen Sie in der Google Cloud Console für Ihr Projekt die Seite IAM & Verwaltung > IAM auf.

2. Aktivieren Sie auf der Seite „Identity and Access Management“ das Kästchen Von Google bereitgestellte Rollenzuweisungen einschließen.

3. Suchen Sie in der Filter- oder Suchleiste für die Liste der Hauptkonten nach dem RAG Engine-Dienst-Agenten. Sie folgt dem Muster [e-mail].

   Ersetzen Sie YOUR_PROJECT_NUMBER durch die Projektnummer Ihres Projekts in Google Cloud .

Wenn Ihr RAG Engine-Dienst-Agent noch nicht vorhanden ist, gehen Sie so vor, um die Erstellung des Dienst-Agents auszulösen:

1. Aktivieren Sie die Resource Manager API.

2. Führen Sie diesen Befehl in Cloud Shell oder in der Befehlszeile aus:

   gcloud beta services identity create --service=aiplatform.googleapis.com \
       --projects=PROJECT_ID
   

   Alternativ können Sie den REST API-Aufruf senden:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json; charset=utf-8" -d "" "https://serviceusage.googleapis.com/v1beta1/projects/PROJECT_ID/services/aiplatform.googleapis.com:generateServiceIdentity"
   

3. Prüfen Sie, ob der RAG Engine-Dienst-Agent erstellt wurde.

So gewähren Sie Berechtigungen für den Cloud KMS-Schlüssel:

1. Kehren Sie in der Google Cloud Console zum Cloud KMS-Dienst zurück.

2. Wählen Sie den Schlüsselbund aus, der den von Ihnen erstellten Schlüssel enthält.

3. Wählen Sie den von Ihnen erstellten Schlüssel aus.

4. Rufen Sie auf der Detailseite des Schlüssels den Tab Berechtigungen auf.

5. Klicken Sie auf Hauptkonto hinzufügen.

6. Geben Sie im Feld Neue Hauptkonten die E-Mail-Adresse des RAG Engine-Dienst-Agents ein.

7. Wählen Sie im Drop-down-Menü Rolle auswählen die Rolle „Cloud KMS CryptoKey-Verschlüsseler/Entschlüsseler“ (roles/cloudkms.cryptoKeyEncrypterDecrypter) aus. Mit dieser Rolle erhält der Dienst-Agent die erforderlichen Berechtigungen, um den Schlüssel für Verschlüsselungs- und Entschlüsselungsvorgänge zu verwenden.

8. Klicken Sie auf Speichern.

RAG-Korpus mit vom Kunden verwalteter Verschlüsselung erstellen

In diesem Codebeispiel wird gezeigt, wie Sie einen RAG-Korpus erstellen, der mit kundenverwalteten Verschlüsselungsschlüsseln (CMEK) verschlüsselt ist.

Ersetzen Sie die Variablen in den folgenden Codebeispielen:

Python

import vertexai
from google.cloud import aiplatform
from vertexai import rag
from google.cloud.aiplatform_v1.types.encryption_spec import EncryptionSpec

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

vertexai.init(project=PROJECT_ID)

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, encryption_spec=EncryptionSpec(kms_key_name=KMS_KEY_NAME))

REST

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME
KMS_KEY_NAME = YOUR_KMS_KEY_NAME

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

Kontingente

Wenn Sie CMEK mit Gemini Enterprise Agent Platform-Diensten wie der RAG Engine auf der Gemini Enterprise Agent Platform verwenden, gibt es ein Kontingent für die Anzahl der eindeutigen Cloud KMS-Schlüssel, die pro Projekt und Region verwendet werden können. Dieses Kontingent wird mit dem Messwert aiplatform.googleapis.com/in_use_customer_managed_encryption_keys erfasst.

Jedes Mal, wenn Sie einen neuen, eindeutigen Cloud KMS-Schlüssel verwenden, um eine Ressource wie einen RAG-Korpus in einem Projekt und einer Region zu erstellen, verbraucht der Cloud KMS-Schlüssel eine Einheit dieses Kontingents. Diese Kontingenteinheit wird auch dann nicht freigegeben, wenn die Ressourcen, die diesen bestimmten Schlüssel verwenden, gelöscht werden.

Wenn Sie mehr eindeutige Schlüssel benötigen, als das aktuelle Limit zulässt, müssen Sie eine Kontingenterhöhung für aiplatform.googleapis.com/in_use_customer_managed_encryption_keys für die ausgewählte Region anfordern.

Weitere Informationen zum Anfordern einer Kontingenterhöhung finden Sie unter Kontingente in der Google Cloud Console ansehen und bearbeiten.

Nächste Schritte

• Weitere Informationen zu RagManagedDb finden Sie unter Bereitstellungsmodi.
• 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.