Pinecone mit RAG Engine verwenden

Auf dieser Seite wird beschrieben, wie Sie Ihren RAG-Korpus mit Ihrer Pinecone-Datenbank verbinden.

Sie können auch die Schritte in diesem Notebook ausführen: RAG Engine mit Pinecone.

Sie können Ihre Pinecone-Datenbankinstanz mit der RAG Engine verwenden, um eine vektorbasierte Ähnlichkeitssuche zu indexieren und durchzuführen. Eine Ähnlichkeitssuche ist eine Möglichkeit, Textteile zu finden, die dem gesuchten Text ähneln. Dazu ist ein Einbettungsmodell erforderlich. Das Einbettungsmodell erzeugt Vektordaten für jeden Text, der verglichen wird. Die Ähnlichkeitssuche wird verwendet, um semantische Kontexte für die Fundierung abzurufen, damit Ihr LLM die genauesten Inhalte zurückgibt.

Mit der RAG Engine können Sie Ihre vollständig verwaltete Vektordatenbankinstanz weiterhin verwenden, für deren Bereitstellung Sie verantwortlich sind. Die RAG Engine verwendet Ihre Vektordatenbank für die Speicherung, die Indexverwaltung und die Suche.

Pinecone mit RAG Engine verwenden

Überlegen Sie, ob die Pinecone-Datenbank die beste Wahl für Ihre RAG-Anwendung ist. Berücksichtigen Sie dabei Folgendes:

  • Sie müssen die Skalierung Ihrer Pinecone-Datenbankinstanz erstellen, konfigurieren und verwalten.

  • Die RAG Engine verwendet den Standard-Namespace für Ihren Index. Achten Sie darauf, dass dieser Namespace nicht anderweitig geändert werden kann.

  • Sie müssen einen Pinecone-API-Schlüssel angeben, damit die RAG Engine mit der Pinecone-Datenbank interagieren kann. RAG Engine speichert und verwaltet Ihren Pinecone-API-Schlüssel nicht. Gehen Sie stattdessen so vor:

    • Speichern Sie Ihren Schlüssel im Google Cloud Secret Manager.
    • Gewähren Sie dem Dienstkonto Ihres Projekts die Berechtigung, auf Ihr Secret zuzugreifen.
    • Gewähren Sie der RAG Engine Zugriff auf den Ressourcennamen Ihres Secrets.

    • Wenn Sie mit Ihrem RAG-Korpus interagieren, greift die RAG Engine über Ihr Dienstkonto auf Ihre Secret-Ressource zu.

    • Der RAG-Korpus und der Pinecone-Index haben eine 1:1-Zuordnung. Diese Verknüpfung wird im Rahmen der ragCorpora.create-Methode oder der ragCorpora.patch-Methode hergestellt.

Pinecone-Index erstellen

So erstellen Sie Ihren Pinecone-Index:

  1. In der Pinecone-Kurzanleitung finden Sie die Indexkonfigurationen, die für Ihren Index angegeben werden müssen, damit er mit dem RAG-Korpus kompatibel ist.

  2. Aus den folgenden Gründen sollte der Standort des Pinecone-Index mit dem Standort übereinstimmen, an dem Sie die RAG Engine verwenden, oder sich in der Nähe befinden:

    • Sie möchten die Latenzen reduzieren.
    • Sie möchten die Anforderungen an den Datenstandort erfüllen, die durch geltende Gesetze festgelegt sind.

  3. Geben Sie beim Erstellen des Pinecone-Index die Einbettungsdimension an, die mit der RAG Engine verwendet werden soll. Diese Tabelle enthält die Dimensionsgrößen oder den Speicherort der Dimensionsgrößen:

    Modell Größe der Dimension
    Gecko von Google 768
    Feinabgestimmtes eigenes Gecko-Modell 768
    E5 Weitere Informationen finden Sie unter Open Source-Einbettungsmodelle verwenden.

  4. Wählen Sie einen der folgenden unterstützten Entfernungsmesswerte aus:

    • cosine
    • dotproduct
    • euclidean

  5. Optional: Wenn Sie einen Pod-basierten Index erstellen, müssen Sie im Feld pod.metadata_config.indexed den Wert file_id angeben. Weitere Informationen finden Sie unter Selektive Metadatenindexierung.

Pinecone-API-Schlüssel erstellen

Die RAG Engine kann nur über Ihren API-Schlüssel für die Authentifizierung und Autorisierung eine Verbindung zu Ihrem Pinecone-Index herstellen. Sie müssen der offiziellen Pinecone-Anleitung zur Authentifizierung folgen, um die API-Schlüssel-basierte Authentifizierung in Ihrem Pinecone-Projekt zu konfigurieren.

API-Schlüssel in Secret Manager speichern

Ein API-Schlüssel enthält vertrauliche personenidentifizierbare Informationen, die rechtlichen Anforderungen unterliegen. Wenn vertrauliche personenidentifizierbare Informationen kompromittiert oder missbraucht werden, kann dies für eine Person ein erhebliches Risiko oder einen Schaden bedeuten. Um die Risiken für Einzelpersonen bei der Verwendung der RAG Engine zu minimieren, sollten Sie Ihren API-Schlüssel nicht speichern und verwalten und den unverschlüsselten API-Schlüssel nicht weitergeben.

So schützen Sie SPII:

  1. Speichern Sie Ihren API-Schlüssel in Secret Manager.

  2. Gewähren Sie Ihrem RAG Engine-Dienstkonto die Berechtigungen für Ihre Secrets und verwalten Sie die Zugriffssteuerung auf der Ebene der Secret-Ressource.

    1. Rufen Sie die Berechtigungen Ihres Projekts auf.

    2. Aktivieren Sie die Option Von Google bereitgestellte Rollenzuweisungen einschließen.

    3. Suchen Sie das Dienstkonto, das das folgende Format hat:

      service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

    4. Bearbeiten Sie die Hauptkonten des Dienstkontos.

    5. Fügen Sie dem Dienstkonto die Rolle Secret Manager Secret Accessor hinzu.

  3. Übergeben Sie beim Erstellen oder Aktualisieren des RAG-Korpus den Namen der Secret-Ressource an die RAG Engine und speichern Sie den Namen der Secret-Ressource.

Wenn API-Anfragen an Ihre Pinecone-Indexe gestellt werden, verwendet die RAG Engine jedes Dienstkonto, um den API-Schlüssel zu lesen, der den Secret-Ressourcen in Secret Manager aus Ihren Projekten entspricht.

RAG Engine-Dienstkonto bereitstellen

Wenn Sie den ersten RAG-Korpus in Ihrem Projekt erstellen, erstellt die RAG Engine ein dediziertes Dienstkonto. Sie finden Ihr Dienstkonto auf der Seite „Identity and Access Management“ Ihres Projekts.

Das Dienstkonto hat das folgende feste Format:

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

Beispiel:

service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com

RAG-Korpus vorbereiten

Wenn Sie Ihren Pinecone-Index mit der RAG Engine verwenden möchten, müssen Sie den Index während der Erstellung mit einem RAG-Korpus verknüpfen. Nachdem die Verknüpfung hergestellt wurde, ist diese Bindung für die gesamte Lebensdauer des RAG-Korpus dauerhaft. Die Verknüpfung kann entweder über die CreateRagCorpus- oder die UpdateRagCorpus-API erfolgen.

Damit die Verknüpfung als abgeschlossen gilt, müssen Sie drei Schlüsselfelder im RAG-Korpus festlegen:

  • rag_vector_db_config.pinecone: Mit diesem Feld können Sie die Vektordatenbank festlegen, die Sie mit Ihrem RAG-Korpus verknüpfen möchten. Es muss während des API-Aufrufs CreateRagCorpus festgelegt werden. Wenn sie nicht festgelegt ist, wird Ihrem RAG-Korpus die Standard-Vektordatenbank RagManagedDb zugewiesen.

  • rag_vector_db_config.pinecone.index_name: Dies ist der Name, der zum Erstellen des Pinecone-Index verwendet wird, der mit dem RAG-Korpus verwendet wird. Sie können den Namen während des CreateRagCorpus-Aufrufs festlegen oder beim Aufrufen der UpdateRagCorpus API angeben.

  • rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: Der vollständige Ressourcenname des Secrets, das in Secret Manager gespeichert ist und Ihren Pinecone-API-Schlüssel enthält. Sie können den Namen während des CreateRagCorpus-Aufrufs festlegen oder den Namen beim Aufrufen der UpdateRagCorpus API angeben. Bis Sie dieses Feld angeben, können Sie keine Daten in den RAG-Korpus importieren.

    Dieses Feld sollte das folgende Format haben:

    projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

RAG-Korpus erstellen

Wenn Sie mit Ihrem Berechtigungssatz Zugriff auf Ihren Pinecone-Indexnamen und den Namen der Secret-Ressource haben, können Sie Ihren RAG-Korpus erstellen und mit Ihrem Pinecone-Index verknüpfen. Dies wird in diesem Beispielcode gezeigt.

Wenn Sie zum ersten Mal einen RAG-Korpus erstellen, haben Sie die Dienstkontoinformationen noch nicht parat. Die Felder sind jedoch optional und können mit der UpdateRagCorpus API mit dem RAG-Korpus verknüpft werden.

Ein Beispiel für das Erstellen des RAG-Korpus ohne Angabe der Dienstkontoinformationen finden Sie unter RAG-Korpus ohne Indexnamen oder API-Schlüssel erstellen.

Python

Bevor Sie dieses Beispiel ausprobieren, folgen Sie der Einrichtungsanleitung für Python in der Kurzanleitung zur Verwendung von Clientbibliotheken für die Agent Platform.

Richten Sie zur Authentifizierung bei der Agent Platform Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 


import agentplatform
from agentplatform import types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

# Configure embedding model (Optional)
embedding_model_config = types.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=types.RagEmbeddingModelConfigVertexPredictionEndpoint(
        endpoint="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = types.RagVectorDbConfig(
    pinecone=types.RagVectorDbConfigPinecone(
        index_name=pinecone_index_name,
    ),
    api_auth=types.ApiAuth(
        api_key_config=types.ApiAuthApiKeyConfig(
            api_key_secret_version=pinecone_api_key_secret_manager_version
        )
    ),
    rag_embedding_model_config=embedding_model_config,
)

corpus = client.rag.create_corpus(
    rag_corpus=types.RagCorpus(
        display_name=display_name,
        description=description,
        rag_vector_db_config=vector_db,
    )
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

REST

   # Set your project ID under which you want to create the corpus
   PROJECT_ID = "YOUR_PROJECT_ID"

   # Choose a display name for your corpus
   CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

   # Set your Pinecone index name
   PINECONE_INDEX_NAME=YOUR_INDEX_NAME

   # Set the full resource name of your secret. Follows the format
   # projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
   SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

   # Call CreateRagCorpus API with all the Vector DB information.
   # You can also add the embedding model choice or set other RAG corpus parameters on
   # this call per your choice.
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
         "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
         "rag_vector_db_config" : {
            "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
            "api_auth": {"api_key_config":
                  {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
            }
         }
      }'

   # To poll the status of your RAG corpus creation, get the operation_id returned in
   # response of your CreateRagCorpus call.
   OPERATION_ID="YOUR_OPERATION_ID"

   # Poll Operation status until done = true in the response.
   # The response to this call will contain the ID for your created RAG corpus
   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

RAG-Korpus ohne Indexnamen oder API-Schlüssel erstellen

Wenn dies Ihr erster RAG-Korpus ist und Sie keinen Zugriff auf die Details Ihres Dienstkontos haben oder die Bereitstellungsschritte für Ihren Pinecone-Index noch nicht abgeschlossen haben, können Sie Ihren RAG-Korpus trotzdem erstellen. Sie können den RAG-Korpus dann mit einer leeren Pinecone-Konfiguration verknüpfen und die Details später hinzufügen.

Folgendes muss berücksichtigt werden:

  • Wenn Sie den Indexnamen und den Secret-Namen des API-Schlüssels nicht angeben, können Dateien nicht in den RAG-Korpus importiert werden.

  • Wenn Sie Pinecone als Vektordatenbank für Ihren RAG-Korpus auswählen, kann sie später nicht mehr in eine andere Datenbank geändert werden.

In diesem Codebeispiel wird gezeigt, wie Sie einen RAG-Korpus mit Pinecone erstellen, ohne einen Pinecone-Indexnamen oder einen API-Secret-Namen anzugeben. Verwenden Sie die UpdateRagCorpus API, um die fehlenden Informationen später anzugeben.

Python 

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone()

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST 

# Set your project ID under which you want to create the corpus
PROJECT_ID = "YOUR_PROJECT_ID"

# Choose a display name for your corpus
CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

# Call CreateRagCorpus API with all the Vector DB information.
# You can also add the embedding model choice or set other RAG corpus parameters on
# this call per your choice.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "rag_vector_db_config" : {
         "pinecone": {}
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

RAG-Korpus aktualisieren

Mit der UpdateRagCorpus API können Sie die Konfiguration der Vektordatenbank aktualisieren. Wenn der Pinecone-Indexname und die Secret-Version des API-Schlüssels nicht zuvor festgelegt wurden, können Sie die Felder mit der Pinecone API aktualisieren. Die Auswahl einer Vektordatenbank kann nicht aktualisiert werden. Die Angabe des API-Schlüssel-Secrets ist optional. Wenn Sie das API-Schlüssel-Secret jedoch nicht angeben, können Sie Daten in den RAG-Korpus importieren.

Feld Veränderlichkeit Erforderlich oder optional
rag_vector_db_config.vector_db Nach der Auswahl unveränderlich. Erforderlich
rag_vector_db_config.pinecone.index_name Unveränderlich, nachdem Sie das Feld im RAG-Korpus festgelegt haben. Erforderlich
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version Veränderlich. Nachdem Sie den API-Schlüssel festgelegt haben, können Sie ihn nicht mehr löschen. Optional

Python 

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone(index_name=)

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST 

# Set your project ID for the corpus that you want to create.
PROJECT_ID = "YOUR_PROJECT_ID"

# Set your Pinecone index name
PINECONE_INDEX_NAME=YOUR_INDEX_NAME

# Set the full resource name of your secret. Follows the format
# projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

# Call UpdateRagCorpus API with the Vector DB information.
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "rag_vector_db_config" : {
         "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
         "api_auth": {"api_key_config":
               {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
         }
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

Nächste Schritte