Vektoreinbettungen generieren und verwalten

Auf dieser Seite wird beschrieben, wie Sie Vektoreinbettungen basierend auf einem Modell generieren und speichern.

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

Mit Cloud SQL können Sie ein von Vertex AI gehostetes Einbettungsmodell verwenden, um einen Textstring in eine Einbettung zu übersetzen. Das ist die Darstellung der semantischen Bedeutung des angegebenen Texts als numerischer Vektor durch das Modell.

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

Hinweise

Einige Anforderungen unterscheiden sich je nachdem, ob Sie Cloud SQL zum Generieren von Einbettungen verwenden möchten oder ob Sie 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 KI-Basismodelle unterstützt werden. 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 auf Ihrer Cloud SQL-Instanz. Installieren Sie für Vertex AI-Modelle die Version 1.2 oder höher. Installieren Sie für Drittanbieter- oder benutzerdefinierte Modelle Version 1.4.2 oder höher.

Wenn Sie diese Einbettungen speichern und Vektorfunktionen und ‑operatoren mit den Einbettungen verwenden möchten, benötigen Sie auch die Erweiterung pgvector.

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

Modellzugriff einrichten

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

Wenn Sie mit dem cloudbasierten Modell text-embedding oder textembedding-gecko 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 erteilen

    • 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 übersetzen können. Sie können diese Einbettung dann als Vektordaten in Ihrer Datenbank speichern und optional pgvector-Funktionen verwenden, um Abfragen dafür auszuführen.

Einbettung generieren

Wenn Sie eine Einbettung mit Cloud SQL generieren möchten, verwenden Sie die Funktion embedding, die von der Erweiterung google_ml_integration 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 Cloud SQL für Texteinbettungen verwenden kann. 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 muss dem Tag @ vorangestellt werden.

    Wenn Sie eines der textembedding-gecko-Modelle mit Vertex AI verwenden, geben Sie eines der in Modellversionen aufgeführten Versionstags an.

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

Im folgenden Beispiel wird das text-embedding-004-Modell verwendet, um ein Embedding 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: der Tabellenname

  • EMBEDDING_COLUMN: der Name der neuen Einbettungsspalte

  • DIMENSIONS: Die Anzahl der Dimensionen, die vom Modell unterstützt werden.

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

Wenn Sie die Erweiterung pgvector installiert haben, können Sie Embeddings 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 Einbettungsspalte.

  • 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 Cloud SQL für Texteinbettungen verwenden kann. Weitere Informationen finden Sie unter Texteinbettungen.

  • VERSION_TAG (Optional): Das Versionstag des abzufragenden Modells. Für 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 in Modellversionen aufgeführten Versionstags an.

  • 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-Spalten. Wenn Ihre Einbettungsspalte vom Typ vector ist, wandelt Cloud SQL den Rückgabewert von embedding() implizit von einem real-Array in einen vector-Wert um.

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

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 Texteinbettungen in Ihrer Datenbank speichern, indexieren und abfragen. Cloud SQL bietet eigene Optimierungen für die Arbeit mit pgvector. So können Sie Indizes erstellen, mit denen sich Abfragen mit Einbettungen beschleunigen lassen.

Index für die nächsten Nachbarn erstellen

pgvector unterstützt die Suche nach ungefähren nächsten Nachbarn (Approximate Nearest Neighbor, ANN) durch Indexierung.

Verwenden Sie die Funktion hnsw, um einen HNSW-Index zu erstellen, wie im folgenden Beispiel gezeigt:

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: eine Spalte, in der vector-Daten gespeichert werden.

  • DISTANCE_FUNCTION: Die Distanzfunktion, die für diesen Index verwendet werden soll. Wählen Sie eine der folgenden Optionen aus:

    • L2-Distanz: vector_l2_ops

    • Skalarprodukt: 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. Der Standardwert ist 16.

  • EF_CONSTRUCTION (optional): Die Größe der Liste, in der die ähnlichsten Kandidaten während der Graphdurchlaufung beim Erstellen des Index gespeichert werden. Bei höheren Werten berücksichtigt der Algorithmus mehr Kandidaten, sodass ein besserer Index erstellt werden kann. Der Standardwert ist 64.

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

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 einen solchen Index.

Abfrage nach dem nächsten Nachbarn mit einem bestimmten Text erstellen

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

Um die semantisch ähnlichsten Nachbarn eines Textabschnitts zu finden, verwenden Sie die Funktion embedding(), um den Text in einen Vektor zu übersetzen. Wenden Sie in derselben Abfrage diesen Vektor auf den pgvector-Operator für den nächsten Nachbarn, <->, 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 Cloud SQL für Texteinbettungen verwenden kann. Weitere Informationen finden Sie unter Texteinbettungen.

  • VERSION_TAG (Optional): Das Versionstag des abzufragenden Modells. Stellen Sie dem Tag @ voran.

    Wenn Sie eines der textembedding-gecko-Modelle mit Vertex AI verwenden, geben Sie eines der in Modellversionen aufgeführten Versionstags an.

  • TEXT: Der Text, für den Sie die semantisch ähnlichsten gespeicherten Nachbarn finden möchten.

  • 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 den Datentyp real[] anstelle von vector 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

Cloud SQL empfiehlt dringend, immer eine stabile Version des ausgewählten Einbettungsmodells zu verwenden. Bei den meisten Modellen bedeutet das, dass Sie ein Versionstag explizit festlegen müssen.

Das Aufrufen der Funktion embedding() ohne Angabe des Versionstags des Modells ist syntaktisch gültig, kann aber fehleranfällig sein.

Wenn Sie das Versionstag weglassen, wenn Sie ein Modell im Vertex AI Model Garden verwenden, verwendet Vertex AI die neueste Version des Modells. Dies ist möglicherweise nicht die aktuelle 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 die Modellversion in Ihren Einbettungsaufrufen nicht angeben, kann es sein, dass sich der zurückgegebene Vektor für eine bestimmte Eingabe durch eine neu veröffentlichte Modellversion abrupt ändert. Dies kann zu Fehlern oder anderem unerwarteten Verhalten in Ihren Anwendungen führen.

Nächste Schritte