Mit Vertex AI nach Vektorähnlichkeiten suchen

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

In lokale PostgreSQL-Instanz einbinden

1. Richten Sie eine lokale PostgreSQL-Instanz ein.
2. Gewähren Sie sich die IAM-Rolle „Vertex AI User“.
3. Richten Sie Standardanmeldedaten für Anwendungen von Google Cloud 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. Gewähren Sie sich die IAM-Rolle „Vertex AI User“.
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 in 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 description Feld 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 mit dem _embed Serverwert integrierte Unterstützung für Vektoreinbettungen. Dadurch wird Data Connect angewiesen, Vektoreinbettungen zu generieren, indem intern die Vertex AI Embeddings APIs 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 Ihrer Datenbank Datensätze hinzufügen. Hier fügt eine createMovie Mutation der Tabelle Movie einen Filmdatensatz hinzu und übergibt auch eine Film beschreibung mit einem angegebenen Einbettungsmodel.

mutation createMovie($title: String!, $description: String!) {
  movie_insert(data: {
    title: $title,
    description: $description,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $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 zweite Mutation von einem Client aus auf:

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

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

// Use the response

Abfragen

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

Sie können zurückgegebene Vektoreinbettungen verwenden, um eine Ähnlichkeitssuche durchzuführen, wie im nächsten Abschnitt beschrieben.

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

Ähnlichkeitssuche durchführen

Jetzt können wir eine Ä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. Sie unterstützt einige Parameter 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 _embed Serverwert Data Connect an, die Vektoreinbettungen mit den Vertex AI Embeddings APIs 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 gibt die Ähnlichkeitssuche bis zu fünf Filme zurück, deren Beschreibung der Eingabeabfrage semantisch am nächsten kommt. Die Ergebnisse sind in aufsteigender Reihenfolge des Abstands sortiert – vom nächsten zum weitesten.

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

Die 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 optimieren.

Um einen geeigneten Wert für within zu finden, können wir _metadata.distance zu den ausgewählten Feldern hinzufügen, um zu sehen, wie weit jedes Ergebnis vom Abfragevektor entfernt ist. Anhand der zurückgegebenen distance Werte können wir den within Parameter festlegen. Nur Ergebnisse mit einem Abstand, der kleiner als der Wert von within ist, werden 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 den Abstand zurückgeben. Wenn Sie within festgelegt haben, müssen Sie diesen Wert nach dem Ändern von method noch einmal optimieren.

Ähnlichkeitsabfrage aufrufen

So rufen Sie eine Ähnlichkeitssuche aus dem Clientcode auf:

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

const response = await searchMovieDescriptionUsingL2similarity({ query });

// Use the response

Benutzerdefinierte Einbettungen verwenden

Data Connect ermöglicht Ihnen auch, direkt mit Einbettungen als Vectors zu arbeiten, anstatt den Serverwert _embed zu verwenden, um sie zu generieren.

Benutzerdefinierte Einbettung speichern

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

Wandeln Sie dann das zurückgegebene Array von Gleitkommazahlen in einen Vector um, um es an den Aktualisierungsvorgang zur Speicherung zu übergeben.

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 sie in Vectors umzuwandeln.

Rufen Sie dann die Abfrage _similarity auf, um die einzelnen Suchvorgänge durchzufü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 die Produktion bereitstellen

Schema und Connector bereitstellen

Der letzte Schritt in einer typischen Data Connect Iteration besteht darin, Ihre Assets für die Produktion bereitzustellen.

Wenn Sie Ihr Schema mit Vector-Typen mit dem firebase deploy Befehl bereitstellen, führt die Firebase CLI die erforderlichen Schritte aus, um die auf Vertex AI basierende Einbettungsgenerierung in Ihrer Cloud SQL-Instanz zu aktivieren.

firebase deploy --only dataconnect

Wenn Sie die Einbettungsunterstützung 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 er durch die pgvector Erweiterung definiert ist. 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. Eingaben werden in ein Array von float32-Werten umgewandelt. Wenn die Umwandlung fehlschlägt, wird ein Fehler ausgelöst.

Verwenden Sie den Parameter `size` der @col-Anweisung, um die Dimensionen 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

Serverwert _embed für Abfragen und Mutationen

_embed

Dieser Serverwert weist den Data Connect Dienst an, Einbettungen mit den Vertex AI Embeddings APIs 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 nahen Nachbarn verwendet wird. Die derzeit unterstützten Algorithmen sind eine Teilmenge der pgvector-Suchalgorithmen.

within: float

Eine Beschränkung des Abstands, innerhalb dessen die Suche nach dem nächsten Nachbarn durchgeführt wird.

where: FDC filter condition

Weitere Informationen finden Sie in der Anleitung zu Schemas, Abfragen und Mutationen.

limit: int

Die Anzahl der zurückzugebenden Ergebnisse.