Mit Vertex AI nach Vektorähnlichkeiten suchen

Willkommen bei der Vektorähnlichkeitssuche von Firebase Data Connect – der Firebase-Implementierung der semantischen Suche, die in Google Vertex AI integriert ist.

Das Herzstück dieser Funktion sind Vektoreinbettungen, also Arrays von Gleitkommazahlen, die die semantische Bedeutung von Text oder Medien darstellen. Wenn Sie eine Suche nach dem nächsten Nachbarn mit einer Eingabevektoreinbettung ausführen, können Sie alle semantisch ähnlichen Inhalte finden. Data Connect verwendet für diese Funktion die PostgreSQL-Erweiterung pgvector.

Diese leistungsstarke semantische Suche kann Anwendungsfälle wie Empfehlungs- und Suchmaschinen unterstützen. Sie ist auch eine wichtige Komponente in Retrieval-Augmented Generation in generativen KI-Abläufen. In der Vertex AI-Dokumentation finden Sie weitere Informationen.

Sie können sich auf die integrierte Unterstützung von Data Connect verlassen, um Vektoreinbettungen automatisch mit der Embeddings API von Vertex AI zu generieren, oder diese API verwenden, um sie manuell zu generieren.

Vorbereitung

Einrichtung

Sie können zwischen einem lokalen Entwicklungsablauf (für Web-, Kotlin-Android- oder iOS-Entwickler) und einem IDX-Ablauf (für Webentwickler) wählen. Sie können für die Entwicklung eine lokale Datenbank oder Ihr Data Connect-Produktionsprojekt und die zugehörige Cloud SQL for PostgreSQL-Instanz verwenden.

In dieser Anleitung wird davon ausgegangen, dass Sie Ihr Data Connect-Projekt gemäß der Kurzanleitung erstellt haben.

Integration in lokale PostgreSQL-Instanz

  1. Richten Sie eine lokale PostgreSQL-Instanz ein.
  2. Weisen Sie sich selbst die IAM-Rolle „Vertex AI User“ zu.
  3. Richten Sie Standardanmeldedaten für Google Cloud-Anwendungen in Ihrer Umgebung ein.
  4. Installieren Sie die pgvector-Erweiterung in Ihrer lokalen PostgreSQL-Instanz.
  5. Aktivieren Sie die Erweiterung mit CREATE EXTENSION vector gemäß der Anleitung im pgvector-Repository.

In IDX einbinden

  1. Richten Sie Ihren IDX-Arbeitsbereich mit der Data Connect-Vorlage ein.
  2. Weisen Sie sich selbst die IAM-Rolle „Vertex AI User“ zu.
  3. Aktivieren Sie die Erweiterung mit CREATE EXTENSION vector gemäß der Anleitung im pgvector-Repository.

Schema entwerfen

Wenn Sie eine Vektorsuche durchführen möchten, fügen Sie Ihrem Schema ein neues Feld vom Typ Vector hinzu. Wenn Sie beispielsweise eine semantische Suche mit Filmbeschreibungen durchführen möchten, fügen Sie ein Feld hinzu, in dem die Vektoreinbettungen für die Filmbeschreibung gespeichert werden. In diesem Schema wird descriptionEmbedding hinzugefügt, um Vektoreinbettungen für das Feld description zu speichern.

type Movie @table {
 id: ID! @col(name: "movie_id") @default(id: ID! @col(name: "movie_id") @default(expr: "uuidV4()")
 title: String!
 description: String
 descriptionEmbedding: Vector! @col(size:768)
 // ...
}

Einbettungen generieren und abrufen

Data Connect bietet integrierte Unterstützung für Vektoreinbettungen mit dem Serverwert _embed. Dadurch wird Data Connect angewiesen, Vektoreinbettungen zu generieren, indem intern die Embedding APIs von Vertex AI aufgerufen werden. Der Serverwert _embed kann sowohl in Mutationen als auch in Abfragen verwendet werden.

Mutationen

Einbettung über Data Connect generieren und speichern

In Ihrer Vektorsuch-App möchten Sie wahrscheinlich, dass Einbettungen generiert werden, sobald Sie Datensätze in Ihre Datenbank einfügen. Hier sehen Sie, wie mit einer createMovie-Mutation ein Filmdatensatz in die Tabelle Movie eingefügt und gleichzeitig eine Filmbeschreibung mit einer bestimmten Einbettung model übergeben wird.

mutation createMovie($movieData: Movie_Data! @pick(fields: ["title", "genre", "description"])) {
  movie_insert(data: {
    ...movieData,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $movieData.description}
  })
}

In einigen Fällen möchten Sie möglicherweise die Filmbeschreibung und die Einbettung aktualisieren.

mutation updateDescription($id: String!, $description: String!) {
  movie_update(id: $id, data: {
    description: $description,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
  })
}

So rufen Sie die letzte Mutation von einem Client aus auf:

import { updateMovieDescriptionWithEmbed } from 'lib/dataconnect-sdk/';

await updateMovieDescriptionWithEmbed({ id: movieId, description: description});

// Use the response

Abfragen

Rufen Sie Vektoreinbettungen mit einer Abfrage wie der folgenden ab. Der von der Abfrage zurückgegebene descriptionEmbedding ist ein Array von Gleitkommazahlen, das in der Regel nicht für Menschen lesbar ist. Daher wird die direkte Rückgabe in den von Data Connect generierten SDKs nicht unterstützt.

Sie können die zurückgegebenen Vektoreinbettungen für die Ähnlichkeitssuche verwenden, wie im nächsten Abschnitt beschrieben.

query getMovieDescription($id: String!) @auth(is: PUBLIC) {
 movie(id: $id)
   id
   description
   descriptionEmbedding
}

Ähnlichkeitssuche durchführen

Jetzt können wir die Ähnlichkeitssuche durchführen.

Für jedes Vector-Feld generiert Data Connect eine GraphQL-Funktion, die die Ähnlichkeitssuche implementiert. Der Name dieser generierten Funktion ist ${pluralType}_${vectorFieldName}_similarity. Es werden einige Parameter unterstützt, wie in den folgenden Beispielen und in der Referenzliste gezeigt.

Sie können eine GraphQL-Funktion definieren, die die Ähnlichkeitssuche aufruft. Wie oben erwähnt, weist der Serverwert _embed Data Connect an, die Vektoreinbettungen mit den Embedding APIs von Vertex AI zu generieren. In diesem Fall werden Einbettungen für den Suchstring erstellt, der für den Vergleich mit Einbettungen von Filmbeschreibungen verwendet wird.

In diesem Beispiel werden bei der Ähnlichkeitssuche bis zu fünf Filme zurückgegeben, deren Beschreibung der Eingabeanfrage semantisch am nächsten kommt. Das Ergebnis wird in aufsteigender Reihenfolge nach Entfernung sortiert – von der nächstgelegenen zur am weitesten entfernten.

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
      }
  }

Ähnlichkeitsabfrage optimieren

Standardwerte für Suchparameter wie method und within eignen sich für die meisten Anwendungsfälle. Wenn Sie jedoch feststellen, dass Ihre Abfrage zu unterschiedliche Ergebnisse zurückgibt oder Ergebnisse fehlen, die Sie einbeziehen möchten, können Sie diese Parameter anpassen.

Um einen geeigneten Wert für within zu finden, können wir den ausgewählten Feldern _metadata.distance hinzufügen, um zu sehen, wie weit jedes Ergebnis vom Abfragevektor entfernt ist. Anhand der zurückgegebenen distance-Werte können wir den Parameter within festlegen. Es werden nur Ergebnisse mit einer Distanz von weniger als dem Wert von within berücksichtigt:

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      within: 2,
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
        _metadata {
          distance
        }
      }
  }

Sie können auch mit verschiedenen Distanzfunktionen experimentieren, indem Sie den Parameter method festlegen.

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      within: .5,
      method: COSINE,
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
        _metadata {
          distance
        }
      }
  }

Beachten Sie, dass verschiedene Methoden sehr unterschiedliche Werte für die Entfernung zurückgeben. Wenn Sie within festgelegt haben, müssen Sie diesen Wert nach dem Ändern von method noch einmal anpassen.

Ähnlichkeitsabfrage aufrufen

So rufen Sie eine Ähnlichkeitssuche über Clientcode auf:

import { searchMovieDescriptionUsingL2similarity} from 'lib/dataconnect-sdk';

const response = await searchMovieDescriptionUsingL2similarity({ query });

// Use the response

Benutzerdefinierte Einbettungen verwenden

Mit Data Connect können Sie auch direkt mit Einbettungen als Vectors arbeiten, anstatt den Serverwert _embed zum Generieren zu verwenden.

Benutzerdefiniertes Embedding speichern

Geben Sie mit der Vertex Embeddings API ein Matching-Modell an und fordern Sie Einbettungsergebnisse mit der richtigen Dimension an.

Wandeln Sie das zurückgegebene Array von Gleitkommazahlen dann in ein Vector um, das Sie an den Update-Vorgang zur Speicherung übergeben können.

mutation updateDescription($id: String!, $description: String!, $descriptionEmbedding: Vector!) {
  movie_update(id: $id, data: {
    // title, genre...
    description: $description,
    descriptionEmbedding: $descriptionEmbedding
  })
}

Ähnlichkeitssuche mit benutzerdefinierten Einbettungen durchführen

Führen Sie denselben Vorgang aus, um Einbettungen für Suchbegriffe abzurufen und in Vectors umzuwandeln.

Rufen Sie dann die _similarity-Abfrage auf, um die einzelnen Suchvorgänge auszuführen.

query searchMovieDescriptionUsingL2Similarity($compare: Vector!, $within: Float, $excludesContent: String, $limit: Int) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare: $compare,
      method: L2,
      within: $within,
      where: {content: {ne: $excludesContent}}, limit: $limit)
      {
        id
        title
        description
      }
  }

Für Produktion bereitstellen

Schema und Connector bereitstellen

Der letzte Schritt in einer typischen Data Connect-Iteration ist die Bereitstellung Ihrer Assets in der Produktion.

Wenn Sie Ihr Schema mit Vector-Typen mit dem Befehl firebase deploy in CloudSQL bereitstellen, führt die Firebase-Befehlszeile die erforderlichen Schritte aus, um die auf Vertex AI basierende Einbettungserstellung für Ihre CloudSQL-Instanz zu aktivieren.

firebase deploy --only dataconnect

Wenn Sie die Unterstützung für das Einbetten in Ihrer Cloud SQL-Instanz manuell aktivieren möchten oder ein CLI-Fehler auftritt, folgen Sie dieser Anleitung.

Syntax der Vektorsuche

Schemaerweiterungen

Der Datentyp Vector von Data Connect wird dem Typ vector von PostgreSQL zugeordnet, wie durch die pgvector-Erweiterung definiert. Der Typ vector von pgvector wird in PostgreSQL als Array von Gleitkommazahlen mit einfacher Genauigkeit gespeichert.

In Data Connect wird der Typ Vector als Array von JSON-Zahlen dargestellt. Die Eingaben werden in ein Array von float32-Werten umgewandelt. Wenn die Typumwandlung fehlschlägt, wird ein Fehler ausgegeben.

Verwenden Sie den Größenparameter der @col-Anweisung, um die Abmessungen des Vektors festzulegen.

type Question @table {
    text: String!
    category: String!
    textEmbedding: Vector! @col(size: 768)
}

size wird nur für Vector-Typen unterstützt. Für Vector-Vorgänge wie die Ähnlichkeitssuche müssen alle Vectors dieselbe Anzahl von Dimensionen haben.

directive @col(
  # … existing args
  """
  Defines a fixed column size for certain scalar types.

  - For Vector, size is required.
  - For all other types, size is currently unsupported and hence supplying it will result in a schema error.
  """
  size: Int
) on FIELD_DEFINITION

_embed-Serverwert für Abfragen und Mutationen

_embed

Dieser Serverwert weist den Data Connect-Dienst an, Einbettungen mit den Embedding APIs von Vertex AI zu generieren und zu speichern. Dieser Serverwert kann sowohl für Abfragen als auch für Mutationen verwendet werden.

Parameter für die Ähnlichkeitssuche

method: COSINE|INNER_PRODUCT|L2

Die Distanzfunktion, die zum Suchen nach benachbarten Nachbarn verwendet wird. Die derzeit unterstützten Algorithmen sind eine Teilmenge der pgvector-Suchalgorithmen.

within: float

Eine Einschränkung für die Distanz, innerhalb derer die Suche nach dem nächsten Nachbarn durchgeführt wird.

where: FDC filter condition

Weitere Informationen finden Sie im Leitfaden zu Schemas, Abfragen und Mutationen.

limit: int

Die Anzahl der zurückzugebenden Ergebnisse.