RagManagedDb mit der Vertex AI RAG Engine verwenden

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

Die von der Vertex AI RAG Engine verwaltete Spanner-Instanz wird als Vektordatenbank verwendet und ist allgemein verfügbar, wobei die Abrechnung aktiviert ist. Weitere Informationen finden Sie unter Abrechnung der Vertex AI RAG Engine.

Auf dieser Seite wird erläutert, wie die Vertex AI RAG Engine RagManagedDb verwendet. Dabei handelt es sich um eine unternehmenstaugliche 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 erläutert, wie Sie CMEK implementieren.

Wichtig: RagManagedDb wird standardmäßig verwendet und nutzt Spanner. Kunden werden für die Verwendung 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 genauen nächsten Nachbarn, indem alle Datenpunkte in Ihrem RAG-Korpus verglichen werden. Wenn Sie beim Erstellen Ihres RAG-Korpus keine Strategie angeben, ist KNN die standardmäßig verwendete Abrufstrategie.	Überprüft beim Abruf die perfekte Recall-Rate (1,0). Ideal für Anwendungen, bei denen die Recall-Rate wichtig 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 Approximationstechniken, um ähnliche Nachbarn schneller zu finden als die KNN-Technik.	Reduziert die Abfragelatenzen bei großen RAG-Korpora erheblich. Die Recall-Rate ist aufgrund der verwendeten Approximationstechniken etwas niedriger. Sehr effektiv bei großen RAG-Korpora mit mehr als 10.000 RAG-Dateien. Wie viel Recall-Verlust für Sie akzeptabel ist, hängt vom Anwendungs fall ab. In den meisten Fällen ist es jedoch ein akzeptabler Kompromiss, etwas Recall-Rate zu verlieren, um die Abfrageleistung zu verbessern.

RAG-Korpus mit KNN RagManagedDb erstellen

In diesem Codebeispiel 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 Vertex AI 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 "Pre-GA-Angebotsbedingungen" der dienstspezifischen 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 Produkteinführungsphasen. Wenn Sie die Gemini API in Vertex AI verwenden, stimmen Sie den Nutzungsbedingungen (Vorschaubedingungen ) der Vorschau der generativen KI zu.

RAG-Korpus mit ANN RagManagedDb erstellen

Um die ANN-Funktion anzubieten, verwendet RagManagedDb eine baumartige Struktur, um Daten zu partitionieren und schnellere Suchvorgänge zu ermöglichen. Um die beste Recall-Rate und Latenz zu erzielen, sollte die Struktur dieses Baums durch Experimente an Ihre Datengröße und -verteilung angepasst werden. Mit RagManagedDb können Sie die tree_depth und die leaf_count des Baums konfigurieren.

Die 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 den Wert auf 3.
• Wenn die tree_depth nicht angegeben ist, weist die Vertex AI RAG Engine für diesen Parameter den Standardwert 2 zu.

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

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

• Wenn nicht angegeben, weist die Vertex AI RAG Engine für diesen 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 Vertex AI 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 Tiefe des Baums.
• LEAF_COUNT: Die Anzahl der Blattknoten.

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 "Pre-GA-Angebotsbedingungen" der dienstspezifischen 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 Produkteinführungsphasen. Wenn Sie die Gemini API in Vertex AI verwenden, stimmen Sie den Nutzungsbedingungen (Vorschaubedingungen ) der Vorschau der generativen KI zu.

Daten in ANN RagManagedDb importieren

Sie können entweder die ImportRagFiles API oder die UploadRagFile API verwenden, um Ihre Daten in die ANN RagManagedDb zu importieren. Im Gegensatz zur KNN-Abrufstrategie muss der zugrunde liegende baumartige Index jedoch mindestens einmal neu erstellt werden. Optional kann dies auch nach dem Importieren großer Datenmengen erfolgen, um eine optimale Recall-Rate zu erzielen. Wenn die Vertex AI RAG Engine Ihren ANN-Index neu erstellen soll, setzen Sie rebuild_ann_index in Ihrer ImportRagFiles API-Anfrage auf „true“.

Wichtig:

1. Bevor Sie den RAG-Korpus abfragen, müssen Sie den ANN-Index mindestens einmal neu erstellen.
2. Pro Projekt wird an jedem Standort nur ein gleichzeitiger Indexneuaufbau unterstützt.

Informationen zum Hochladen Ihrer lokalen Datei in Ihren RAG-Korpus finden Sie unter RAG -Datei hochladen. Informationen zum Importieren von Daten in Ihren RAG-Korpus und zum Auslösen eines ANN-Indexneuaufbaus finden Sie im folgenden Codebeispiel, in dem gezeigt wird, wie Sie aus Cloud Storage importieren. 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 Vertex AI 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 Vertex AI RAG Engine bietet robuste Optionen zum Verwalten der Verschlüsselung Ihrer inaktiven Daten. Standardmäßig werden alle Nutzerdaten in RagManagedDb mit verschlüsselt Google-owned and Google-managed encryption key. Dies ist die Standardeinstellung . Mit dieser Standardeinstellung können Sie überprüfen, ob Ihre Daten sicher sind, ohne dass eine spezielle Konfiguration erforderlich ist.

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

Informationen zu CMEK-Einschränkungen für RAG-Korpora finden Sie unter CMEK-Einschränkungen für die Vertex AI RAG Engine.

KMS-Schlüssel einrichten und Berechtigungen erteilen

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 Dienstkonto der Vertex AI RAG Engine die erforderlichen Berechtigungen zur Verwendung dieses Schlüssels erteilen.

Vorbereitung

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

API aktivieren

So aktivieren Sie die Cloud KMS API:

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

KMS-Schlüsselbund und -Schlüssel erstellen

So erstellen Sie einen Schlüsselbund:

1. Klicken Sie im Bereich 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 Key Management Service-Schlüsselbund muss sich in derselben Region wie der Vertex AI RAG Engine-Endpunkt befinden, den Sie verwenden, wenn Sie einen RAG-Korpus mit CMEK verschlüsseln.
   • 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 navigieren.

   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 Symmetrische Ver-/Entschlüsselung aus. Dies ist für CMEK erforderlich.
   • Quelle des Schlüsselmaterials: Wählen Sie Generierter Schlüssel aus.
   • Rotationszeitraum: Optional. Empfohlen. 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 Ressourcennamen des Schlüssels:

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 die EncryptionSpec in Ihrem RAG-Korpus müssen Sie den Ressourcennamen des Schlüssels ohne die Versionsnummer verwenden.

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

Berechtigungen für den Dienst-Agent der Vertex AI RAG Engine erteilen

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

So ermitteln Sie den Dienst-Agent der Vertex AI RAG Engine:

1. Gehen Sie in der Google Cloud Console für Ihr Projekt zur Seite IAM & Verwaltung > IAM.

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

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

   Ersetzen Sie YOUR_PROJECT_NUMBER durch Ihre Google Cloud Projekt nummer.

Wenn der Dienst-Agent der Vertex AI RAG Engine 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 der 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 Dienst-Agent der Vertex AI RAG Engine erstellt wurde.

So erteilen Sie Berechtigungen für den KMS-Schlüssel:

1. Kehren Sie in der Google Cloud Console zum Dienst „Schlüsselverwaltung“ 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 Dienst-Agents der Vertex AI RAG Engine 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. Diese Rolle gewährt dem 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 kundenverwalteter Verschlüsselung erstellen

In diesem Codebeispiel wird gezeigt, wie Sie einen RAG-Korpus erstellen, der mit einem kundenverwalteten Verschlüsselungsschlüssel (Customer-Managed Encryption Key, 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 Vertex AI-Diensten wie der Vertex AI RAG Engine 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 der Messwert aiplatform.googleapis.com/in_use_customer_managed_encryption_keys erfasst.

Jedes Mal, wenn Sie einen neuen, eindeutigen KMS-Schlüssel verwenden, um eine Ressource wie einen RAG-Korpus in einem Projekt und einer Region zu erstellen, verbraucht der 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 als das aktuelle Limit benötigen, müssen Sie eine Kontingenterhöhung für aiplatform.googleapis.com/in_use_customer_managed_encryption_keys für die ausgewählte Region beantragen.

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

Nächste Schritte

• Weitere Informationen zu RagManagedDb finden Sie unter Understanding RagManagedDb.
• Informationen zum Importieren von Dateien und Ordnern aus Google Drive oder Cloud Storage finden Sie im Beispiel für den Import von RAG-Dateien example.
• Informationen zum Auflisten von RAG-Dateien finden Sie im Beispiel für das Auflisten von RAG-Dateien.