Mit Vektoreinbettungen arbeiten

Auf dieser Seite erfahren Sie, wie Sie mit Cloud SQL for PostgreSQL die folgenden Aktionen ausführen:

  • Vektoreinbettungen basierend auf einem Modell generieren und speichern

  • Indexieren und abfragen Sie Einbettungen mit der Erweiterung pgvector.

Weitere Informationen finden Sie unter Generative AI-Anwendungen mit Cloud SQL erstellen.

In Cloud SQL können Sie ein von Vertex AI gehostetes Einbettungsmodell verwenden, um einen Textstring in eine Einbettung umzuwandeln. Dabei handelt es sich um die Darstellung der semantischen Bedeutung des jeweiligen Textes als numerischer Vektor.

In Cloud SQL werden Einbettungen als Arrays von real-Werten implementiert. So können Sie generierte Einbettungen als Eingaben für pgvector-Erweiterungsfunktionen verwenden.

Hinweise

Einige Anforderungen unterscheiden sich je nachdem, ob Sie mit Cloud SQL Einbettungen generieren möchten oder nur mit Einbettungen arbeiten müssen, die aus einer anderen Quelle in Ihrer Datenbank gespeichert sind.

Regionale Einschränkungen

Wenn Sie Vertex AI-Einbettungen mit Cloud SQL generieren möchten, muss sich Ihre Instanz in einer Region befinden, in der generative AI foundational models are supported. Die Vertex AI-Modelle, die Cloud SQL für Einbettungen verwenden kann, text-embedding und textembedding-gecko, befinden sich in dieser Region.

Erforderliche Datenbankerweiterungen

Wenn Sie mit Einbettungen arbeiten möchten, installieren Sie die Erweiterung google_ml_integration in Ihrer Cloud SQL-Instanz. Für Vertex AI-Modelle muss Version 1.2 oder höher installiert sein. Für Drittanbieter- oder benutzerdefinierte Modelle ist Version 1.4.2 oder höher erforderlich.

Wenn Sie diese Einbettungen speichern und Vektorfunktionen und ‑operatoren mit ihnen verwenden möchten, benötigen Sie außerdem die Erweiterung pgvector.

Cloud SQL bietet beide Erweiterungen. Sie können sie in jeder Datenbank Ihrer Instanz installieren. Weitere Informationen finden Sie unter PostgreSQL-Erweiterungen konfigurieren.

Zugriff auf Modell einrichten

Bevor Sie Embeddings aus einer Cloud SQL-Instanz generieren können, müssen Sie Cloud SQL für die Verwendung eines Text-Embedding-Modells konfigurieren.

Wenn Sie mit dem cloudbasierten text-embedding- oder textembedding-gecko-Modell arbeiten möchten, müssen Sie Cloud SQL in Vertex AI einbinden.

Datenbanknutzern Zugriff zum Generieren von Einbettungen gewähren

Datenbankbenutzern die Berechtigung dazu erteilen, die embedding-Funktion zur Ausführung von Vorhersagen zu verwenden:

  1. Stellen Sie eine Verbindung von einem psql-Client zur primären Instanz her, wie unter Verbindung über einen psql-Client herstellen beschrieben.

  2. An der psql-Eingabeaufforderung eine Verbindung zur Datenbank herstellen und Berechtigungen gewähren:

    \c DB_NAME

GRANT EXECUTE ON FUNCTION embedding TO USER_NAME;

    Ersetzen Sie Folgendes:

    • DB_NAME: der Name der Datenbank, für die Sie Berechtigungen gewähren

    • USER_NAME: der Name des Nutzers, dem Sie die Berechtigungen erteilen

Einbettungen generieren

Cloud SQL bietet eine Funktion, mit der Sie Text in eine Vektoreinbettung umwandeln können. Sie können diese Einbettung dann in Ihrer Datenbank als Vektordaten speichern und optional pgvector-Funktionen verwenden, um Abfragen darauf auszuführen.

Einbettung generieren

Wenn Sie eine Einbettung mit Cloud SQL generieren möchten, verwenden Sie die embedding()-Funktion, die von der google_ml_integration-Erweiterung bereitgestellt wird:

SELECT embedding( 'MODEL_IDVERSION_TAG', 'TEXT');

Ersetzen Sie die folgenden Werte:

  • MODEL_ID: Die ID des Modells, das abgefragt werden soll.

    Wenn Sie Vertex AI Model Garden verwenden, geben Sie text-embedding-004 oder
    text-multilingual-embedding-002 an. Dies sind die cloudbasierten Modelle, die in Cloud SQL für Texteinbettungen verwendet werden können. Weitere Informationen finden Sie unter Texteinbettungen.

  • VERSION_TAG (optional): das Versions-Tag des Modells, das abgefragt werden soll. Bei Versionen von textembedding-gecko vor text-embedding-004 oder text-multilingual-embedding-002:Prepend the tag with@`.

    Wenn Sie eines der textembedding-gecko-Modelle mit Vertex AI verwenden, geben Sie eines der Versions-Tags an, die unter Modellversionen aufgeführt sind.

  • TEXT: Der Text, der in eine Vektoreinbettung umgewandelt werden soll.

Im folgenden Beispiel wird das text-embedding-004-Modell verwendet, um eine Einbettung basierend auf einem bereitgestellten Literalstring zu generieren:

SELECT embedding( 'text-embedding-004', 'Cloud SQL is a managed, cloud-hosted SQL database service.');

Generierte Einbettung speichern

Der Rückgabewert der Funktion embedding() ist ein Array von real-Werten. Wenn Sie diesen Wert in einer Tabelle speichern möchten, fügen Sie eine real[]-Spalte hinzu:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN real[DIMENSIONS];

Ersetzen Sie die folgenden Werte:

  • TABLE: den Tabellennamen

  • EMBEDDING_COLUMN: der Name der neuen Einbettungsspalte

  • DIMENSIONS: die Anzahl der Dimensionen, die das Modell unterstützt.

    Wenn Sie eines der Modelle text-embedding oder textembedding-gecko mit Vertex AI verwenden, geben Sie 768 an.

Wenn Sie die pgvector-Erweiterung installiert haben, können Sie Einbettungen optional als vector-Werte speichern:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);

Nachdem Sie eine Spalte zum Speichern von Einbettungen erstellt haben, können Sie sie anhand der Werte füllen, die bereits in einer anderen Spalte in derselben Tabelle gespeichert sind:

UPDATE TABLE SET EMBEDDING_COLUMN = embedding('MODEL_IDVERSION_TAG', SOURCE_TEXT_COLUMN);

Ersetzen Sie die folgenden Werte:

  • TABLE: der Tabellenname.

  • EMBEDDING_COLUMN: Der Name der Spalte, in die eingebettet werden soll.

  • MODEL_ID: Die ID des Modells, das abgefragt werden soll.

    Wenn Sie Vertex AI Model Garden verwenden, geben Sie text-embedding-004 oder
    text-multilingual-embedding-002 an. Dies sind die cloudbasierten Modelle, die in Cloud SQL für Texteinbettungen verwendet werden können. Weitere Informationen finden Sie unter Texteinbettungen.

  • VERSION_TAG (optional): das Versions-Tag des Modells, das abgefragt werden soll. Bei Versionen von textembedding-gecko vor text-embedding-004 oder text-multilingual-embedding-002:Prepend the tag with@`.

    Wenn Sie eines der textembedding-gecko-Modelle mit Vertex AI verwenden, geben Sie eines der Versions-Tags an, die unter Modellversionen aufgeführt sind.

  • SOURCE_TEXT_COLUMN: Der Name der Spalte, in der der Text gespeichert ist. Sie übersetzen diesen Text in Einbettungen.

Der vorherige Befehl funktioniert sowohl für real[]- als auch für vector-Embedding-Spalten. Wenn die Einbettungsspalte den Typ vector hat, wird der Rückgabewert von embedding() in Cloud SQL implizit von einem real-Array in einen vector-Wert umgewandelt.

Im folgenden Beispiel wird das text-embedding-004-Modell verwendet, um die Spalte messages.message_vector mit Einbettungen zu füllen, die auf dem Inhalt der Spalte messages.message basieren:

UPDATE messages SET message_vector = embedding( 'text-embedding-004', message);

Einbettungen mit pgvector abfragen und indexieren

Mit der PostgreSQL-Erweiterung pgvector können Sie vektorspezifische Operatoren und Funktionen verwenden, wenn Sie Text-Embeddings in Ihrer Datenbank speichern, indexieren und abfragen. Cloud SQL bietet eigene Optimierungen für die Arbeit mit pgvector. So können Sie Indexe erstellen, mit denen Abfragen mit Einbettungen beschleunigt werden.

Index für nächsten Nachbarn erstellen

pgvector unterstützt die ungefähre Suche nach dem nächsten Nachbarn durch Indexierung.

Im folgenden Beispiel wird gezeigt, wie Sie einen pgvector-basierten Index mit hnsw als Indexmethode erstellen:

CREATE INDEX ON TABLE
  USING hnsw (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (m = M, ef_construction = EF_CONSTRUCTION);

Ersetzen Sie die folgenden Werte:

  • TABLE: die Tabelle, der Sie den Index hinzufügen.

  • EMBEDDING_COLUMN: Spalte, in der vector-Daten gespeichert werden.

  • DISTANCE_FUNCTION: die Entfernungsfunktion, die mit diesem Index verwendet werden soll. Wählen Sie eine der folgenden Optionen aus:

    • L2-Distanz: vector_l2_ops

    • Inneres Produkt: vector_ip_ops

    • Kosinus-Distanz: vector_cosine_ops

  • M (optional): Die maximale Anzahl von Verbindungen mit benachbarten Datenpunkten in einem Diagramm. Wir empfehlen einen Bereich von 5 bis 48, da 16 der Standardwert für pgvector ist.

  • EF_CONSTRUCTION (optional): Die Größe der Liste, die die nächsten Kandidaten während der Graphendurchquerung beim Erstellen des Index enthält. Bei höheren Werten werden vom Algorithmus mehr Kandidaten berücksichtigt, sodass ein besserer Index erstellt werden kann. Die Standardgröße ist 64.

Wenn Sie diesen Index für eine Einbettungsspalte erstellen möchten, die den Datentyp real[] anstelle von vector verwendet, müssen Sie die Spalte in den Datentyp vector umwandeln:

CREATE INDEX ON TABLE
  USING hnsw ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS))) DISTANCE_FUNCTION)
  WITH (m = M, ef_construction = EF_CONSTRUCTION);

Ersetzen Sie DIMENSIONS durch die dimensionale Breite der Einbettungsspalte.

Im nächsten Abschnitt finden Sie ein Beispiel für diese Art von Index.

Abfrage nach dem nächsten Nachbarn mit angegebenem Text

Nachdem Sie Einbettungen in Ihrer Datenbank gespeichert und indexiert haben, steht Ihnen die gesamte Bandbreite der pgvector-Abfragefunktionen zur Verfügung.

Wenn Sie die semantisch nächsten Nachbarn eines Texts finden möchten, verwenden Sie die Funktion embedding(), um den Text in einen Vektor zu übersetzen. Wenden Sie in derselben Abfrage diesen Vektor auf den pgvector Operator „Nächster Nachbar“, <->, an, um die Datenbankzeilen mit den semantisch ähnlichsten Einbettungen zu finden.

Da embedding() ein real-Array zurückgibt, müssen Sie den embedding()-Aufruf in vector umwandeln, um diese Werte mit pgvector-Operatoren zu verwenden.

  SELECT RESULT_COLUMNS FROM TABLE
    ORDER BY EMBEDDING_COLUMN
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

Ersetzen Sie die folgenden Werte:

  • RESULT_COLUMNS: die Spalten, die aus semantisch ähnlichen Zeilen angezeigt werden sollen.

  • TABLE: die Tabelle mit der Einbettung, mit der Sie den Text vergleichen.

  • EMBEDDING_COLUMN: die Spalte mit den gespeicherten Einbettungen.

  • MODEL_ID: Die ID des Modells, das abgefragt werden soll.

    Wenn Sie Vertex AI Model Garden verwenden, geben Sie text-embedding-004 oder
    text-embedding-multilingual-002 an. Dies sind die cloudbasierten Modelle, die in Cloud SQL für Texteinbettungen verwendet werden können. Weitere Informationen finden Sie unter Texteinbettungen.

  • VERSION_TAG (optional): das Versions-Tag des Modells, das abgefragt werden soll. Stellen Sie dem Tag @ voran.

    Wenn Sie eines der textembedding-gecko-Modelle mit Vertex AI verwenden, geben Sie eines der Versions-Tags an, die unter Modellversionen aufgeführt sind.

  • TEXT: den gewünschten Text, damit Sie die nächsten gespeicherten semantischen Nachbarn finden können.

  • ROW_COUNT: die Anzahl der zurückzugebenden Zeilen. Wenn Sie nur die beste Übereinstimmung erhalten möchten, geben Sie 1 als Wert für diesen Parameter an.

Wenn Sie diese Abfrage mit einer gespeicherten Einbettungsspalte ausführen möchten, die anstelle von vector den Datentyp real[] verwendet, wandeln Sie die Spalte in den Datentyp vector um:

  SELECT RESULT_COLUMNS FROM TABLE
    ORDER BY EMBEDDING_COLUMN::vector
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

Tags für Modellversionen verwenden, um Fehler zu vermeiden

Google empfiehlt dringend, immer eine stabile Version des ausgewählten Embedding-Modells zu verwenden. Bei den meisten Modellen bedeutet das, dass Sie ein Versions-Tag explizit festlegen müssen.

Der Aufruf der embedding()-Funktion ohne Angabe des Versionstags des Modells ist syntaktisch gültig, aber auch fehleranfällig.

Wenn Sie das Versions-Tag bei der Verwendung eines Modells im Vertex AI Model Garden weglassen, verwendet Vertex AI die neueste Version des Modells. Dies ist möglicherweise nicht die neueste stabile Version. Weitere Informationen zu verfügbaren Vertex AI-Modellversionen finden Sie unter Modellversionen.

Eine bestimmte Vertex AI-Modellversion gibt für eine bestimmte Texteingabe immer dieselbe embedding()-Antwort zurück. Wenn Sie in Ihren Aufrufen von embedding() keine Modellversionen angeben, kann eine neue veröffentlichte Modellversion den zurückgegebenen Vektor für eine bestimmte Eingabe abrupt ändern. Dies kann zu Fehlern oder anderem unerwarteten Verhalten in Ihren Anwendungen führen.

Geben Sie daher immer die Modellversion an, um diese Probleme zu vermeiden.

Nächste Schritte