Rechercher avec des embeddings vectoriels

Cette page vous explique comment utiliser Cloud Firestore pour effectuer des recherches vectorielles des k plus proches voisins (KNN) à l'aide des techniques suivantes :

  • Stocker les valeurs vectorielles
  • Créer et gérer des index vectoriels KNN
  • Envoyer une requête de type k plus proches voisins (KNN) à l'aide de l'une des mesures de distance vectorielle acceptées

Avant de commencer

Avant de stocker des embeddings dans Cloud Firestore, vous devez générer des embeddings vectoriels. Cloud Firestore ne génère pas les embeddings. Vous pouvez utiliser un service tel que Agent Platform pour créer des valeurs vectorielles, par exemple des embeddings textuels à partir de vos données Cloud Firestore. Vous pouvez ensuite stocker ces embeddings dans des documents Cloud Firestore.

Pour en savoir plus sur les embeddings, consultez Qu'est-ce qu'un embedding ?.

Pour savoir comment obtenir des embeddings textuels avec Agent Platform, consultez Obtenir des embeddings textuels.

Stocker les embeddings vectoriels

Les exemples suivants montrent comment stocker des embeddings vectoriels dans Cloud Firestore.

Opération d'écriture avec un embedding vectoriel

L'exemple suivant montre comment stocker un embedding vectoriel dans un document Cloud Firestore :

Python
from google.cloud import firestore
from google.cloud.firestore_v1.vector import Vector

firestore_client = firestore.Client()
collection = firestore_client.collection("coffee-beans")
doc = {
    "name": "Kahawa coffee beans",
    "description": "Information about the Kahawa coffee beans.",
    "embedding_field": Vector([0.18332680, 0.24160706, 0.3416704]),
}

collection.add(doc)
Node.js
import {
  Firestore,
  FieldValue,
} from "@google-cloud/firestore";

const db = new Firestore();
const coll = db.collection('coffee-beans');
await coll.add({
  name: "Kahawa coffee beans",
  description: "Information about the Kahawa coffee beans.",
  embedding_field: FieldValue.vector([1.0 , 2.0, 3.0])
});
Go
import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/firestore"
)

type CoffeeBean struct {
	Name           string             `firestore:"name,omitempty"`
	Description    string             `firestore:"description,omitempty"`
	EmbeddingField firestore.Vector32 `firestore:"embedding_field,omitempty"`
	Color          string             `firestore:"color,omitempty"`
}

func storeVectors(w io.Writer, projectID string) error {
	ctx := context.Background()

	// Create client
	client, err := firestore.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("firestore.NewClient: %w", err)
	}
	defer client.Close()

	// Vector can be represented by Vector32 or Vector64
	doc := CoffeeBean{
		Name:           "Kahawa coffee beans",
		Description:    "Information about the Kahawa coffee beans.",
		EmbeddingField: []float32{1.0, 2.0, 3.0},
		Color:          "red",
	}
	ref := client.Collection("coffee-beans").NewDoc()
	if _, err = ref.Set(ctx, doc); err != nil {
		fmt.Fprintf(w, "failed to upsert: %v", err)
		return err
	}

	return nil
}
Java
import com.google.cloud.firestore.CollectionReference;
import com.google.cloud.firestore.DocumentReference;
import com.google.cloud.firestore.FieldValue;
import com.google.cloud.firestore.VectorQuery;

CollectionReference coll = firestore.collection("coffee-beans");

Map<String, Object> docData = new HashMap<>();
docData.put("name", "Kahawa coffee beans");
docData.put("description", "Information about the Kahawa coffee beans.");
docData.put("embedding_field", FieldValue.vector(new double[] {1.0, 2.0, 3.0}));

ApiFuture<DocumentReference> future = coll.add(docData);
DocumentReference documentReference = future.get();

Calculer des embeddings vectoriels avec une fonction Cloud

Pour calculer et stocker des embeddings vectoriels chaque fois qu'un document est mis à jour ou créé, vous pouvez configurer une fonction Cloud :

Python
@functions_framework.cloud_event
def store_embedding(cloud_event) -> None:
  """Triggers by a change to a Firestore document.
  """
  firestore_payload = firestore.DocumentEventData()
  payload = firestore_payload._pb.ParseFromString(cloud_event.data)

  collection_id, doc_id = from_payload(payload)
  # Call a function to calculate the embedding
  embedding = calculate_embedding(payload)
  # Update the document
  doc = firestore_client.collection(collection_id).document(doc_id)
  doc.set({"embedding_field": embedding}, merge=True)
Node.js
/**
 * A vector embedding will be computed from the
 * value of the `content` field. The vector value
 * will be stored in the `embedding` field. The
 * field names `content` and `embedding` are arbitrary
 * field names chosen for this example.
 */
async function storeEmbedding(event: FirestoreEvent<any>): Promise<void> {
  // Get the previous value of the document's `content` field.
  const previousDocumentSnapshot = event.data.before as QueryDocumentSnapshot;
  const previousContent = previousDocumentSnapshot.get("content");

  // Get the current value of the document's `content` field.
  const currentDocumentSnapshot = event.data.after as QueryDocumentSnapshot;
  const currentContent = currentDocumentSnapshot.get("content");

  // Don't update the embedding if the content field did not change
  if (previousContent === currentContent) {
    return;
  }

  // Call a function to calculate the embedding for the value
  // of the `content` field.
  const embeddingVector = calculateEmbedding(currentContent);

  // Update the `embedding` field on the document.
  await currentDocumentSnapshot.ref.update({
    embedding: embeddingVector,
  });
}
Go
  // Not yet supported in the Go client library
Java
  // Not yet supported in the Java client library

Créer et gérer des index vectoriels

Avant de pouvoir effectuer une recherche des plus proches voisins avec vos embeddings vectoriels, vous devez créer un index correspondant. Les exemples suivants montrent comment créer et gérer des index vectoriels avec Google Cloud CLI et la console. Vous pouvez également gérer les index vectoriels avec la CLI Firebase et Terraform.

Créer un index vectoriel

Console Google Cloud

Pour créer manuellement un index à partir de la console Google Cloud :

  1. Dans la console Google Cloud, accédez à la page Base de données.

    Accéder à la page "Bases de données"

  2. Sélectionnez la base de données requise dans la liste des bases de données.
  3. Dans le menu de navigation, cliquez sur Index, puis sur l'onglet Manuel.
  4. Cliquez sur Créer un index.

    Pour indexer un champ vectoriel pour les recherches vectorielles, sélectionnez Créer un index vectoriel.

  5. Saisissez un ID de collection. Saisissez un chemin d'accès au champ de vecteur et le nombre de dimensions de l'embedding vectoriel. Ajoutez les noms des champs supplémentaires que vous souhaitez indexer et un mode d'indexation pour chaque champ.

    Cliquez sur Enregistrer l'index.

Votre nouvel index s'affiche dans la liste des index manuels, et Cloud Firestore commence à le créer. Une fois l'index créé, une coche verte s'affiche à côté de celui-ci.

gcloud

Avant de créer un index vectoriel, passez à la dernière version de Google Cloud CLI :

gcloud components update

Pour créer un index vectoriel, utilisez gcloud firestore indexes composite create :

gcloud firestore indexes composite create \
--collection-group=collection-group \
--query-scope=COLLECTION \
--field-config field-path=vector-field,vector-config='vector-configuration' \
--database=database-id

où :

  • collection-group est l'ID du groupe de collections.
  • vector-field est le nom du champ contenant l'embedding vectoriel.
  • database-id est l'ID de la base de données.
  • vector-configuration inclut le vecteur dimension et le type d'index. dimension est un entier inférieur ou égal à 2 048. Le type d'index doit être flat. Formatez la configuration de l'index comme suit : {"dimension":"DIMENSION", "flat": "{}"}.

L'exemple suivant crée un index composite, y compris un index vectoriel pour le champ vector-field et un index croissant pour le champ color. Vous pouvez utiliser ce type d'index pour préfiltrer les données avant une recherche du plus proche voisin.

gcloud firestore indexes composite create \
--collection-group=collection-group \
--query-scope=COLLECTION \
--field-config=order=ASCENDING,field-path="color" \
--field-config field-path=vector-field,vector-config='{"dimension":"1024", "flat": "{}"}' \
--database=database-id

Répertorier tous les index vectoriels

Console Google Cloud

  1. Dans la console Google Cloud, accédez à la page Base de données.

    Accéder à la page "Bases de données"

  2. Sélectionnez la base de données requise dans la liste des bases de données.

  3. Dans le menu de navigation, cliquez sur Index, puis sur l'onglet Manuel.

    La table des index liste tous les index de la base de données. Les index vectoriels incluent un champ vectoriel avec une icône .

gcloud

Pour lister tous les index et récupérer leurs ID :

gcloud firestore indexes composite list --database=database-id

Remplacez database-id par l'ID de la base de données.

Vous pouvez utiliser l'ID d'index pour afficher plus de détails sur un index :

gcloud firestore indexes composite describe index-id --database=database-id

où :

  • index-id est l'ID de l'index à décrire.
  • database-id est l'ID de la base de données.

Supprimer un index vectoriel

Console Google Cloud

  1. Dans la console Google Cloud, accédez à la page Base de données.

    Accéder à la page "Bases de données"

  2. Sélectionnez la base de données requise dans la liste des bases de données.

  3. Dans le menu de navigation, cliquez sur Index, puis sur l'onglet Manuel.

  4. Dans la liste de vos index manuels, cliquez sur le bouton Plus  correspondant à l'index que vous souhaitez supprimer. Cliquez sur Supprimer.
  5. Confirmez que vous souhaitez supprimer cet index en cliquant sur Supprimer l'index dans l'alerte.
gcloud
gcloud firestore indexes composite delete index-id --database=database-id

où :

  • index-id est l'ID de l'index à supprimer. Utilisez indexes composite list pour récupérer l'ID de l'index.
  • database-id est l'ID de la base de données.

Envoyer une requête de type plus proches voisins

Vous pouvez effectuer une recherche de similarité pour trouver les voisins les plus proches d'un embedding vectoriel. Les recherches de similarité nécessitent des index vectoriels. Si un index n'existe pas, Cloud Firestore suggère un index à créer à l'aide de gcloud CLI.

L'exemple suivant recherche les 10 voisins les plus proches du vecteur de requête.

Python
from google.cloud.firestore_v1.base_vector_query import DistanceMeasure
from google.cloud.firestore_v1.vector import Vector

collection = db.collection("coffee-beans")

# Requires a single-field vector index
vector_query = collection.find_nearest(
    vector_field="embedding_field",
    query_vector=Vector([0.3416704, 0.18332680, 0.24160706]),
    distance_measure=DistanceMeasure.EUCLIDEAN,
    limit=5,
)
Node.js
import {
  Firestore,
  FieldValue,
  VectorQuery,
  VectorQuerySnapshot,
} from "@google-cloud/firestore";

// Requires a single-field vector index
const vectorQuery: VectorQuery = coll.findNearest({
  vectorField: 'embedding_field',
  queryVector: [3.0, 1.0, 2.0],
  limit: 10,
  distanceMeasure: 'EUCLIDEAN'
});

const vectorQuerySnapshot: VectorQuerySnapshot = await vectorQuery.get();
Go
import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/firestore"
)

func vectorSearchBasic(w io.Writer, projectID string) error {
	ctx := context.Background()

	// Create client
	client, err := firestore.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("firestore.NewClient: %w", err)
	}
	defer client.Close()

	collection := client.Collection("coffee-beans")

	// Requires a vector index
	// https://firebase.google.com/docs/firestore/vector-search#create_and_manage_vector_indexes
	vectorQuery := collection.FindNearest("embedding_field",
		[]float32{3.0, 1.0, 2.0},
		5,
		// More info: https://firebase.google.com/docs/firestore/vector-search#vector_distances
		firestore.DistanceMeasureEuclidean,
		nil)

	docs, err := vectorQuery.Documents(ctx).GetAll()
	if err != nil {
		fmt.Fprintf(w, "failed to get vector query results: %v", err)
		return err
	}

	for _, doc := range docs {
		fmt.Fprintln(w, doc.Data()["name"])
	}
	return nil
}
Java
import com.google.cloud.firestore.VectorQuery;
import com.google.cloud.firestore.VectorQuerySnapshot;

VectorQuery vectorQuery = coll.findNearest(
        "embedding_field",
        new double[] {3.0, 1.0, 2.0},
        /* limit */ 10,
        VectorQuery.DistanceMeasure.EUCLIDEAN);

ApiFuture<VectorQuerySnapshot> future = vectorQuery.get();
VectorQuerySnapshot vectorQuerySnapshot = future.get();

Distances vectorielles

Les requêtes de recherche des plus proches voisins sont compatibles avec les options suivantes pour la distance vectorielle :

  • EUCLIDEAN : mesure la distance EUCLIDEAN entre les vecteurs. Pour en savoir plus, consultez Euclidienne.
  • COSINE : compare les vecteurs en fonction de l'angle entre eux, ce qui vous permet de mesurer la similarité qui n'est pas basée sur la magnitude des vecteurs. Nous vous recommandons d'utiliser DOT_PRODUCT avec des vecteurs normalisés unitaires plutôt que la distance COSINE, qui est mathématiquement équivalente et offre de meilleures performances. Pour en savoir plus, consultez Similarité cosinus.
  • DOT_PRODUCT : semblable à COSINE, mais affecté par la magnitude des vecteurs. Pour en savoir plus, consultez Produit scalaire.

Choisir la mesure de distance

Selon que tous vos embeddings vectoriels sont normalisés ou non, vous pouvez déterminer la mesure de distance à utiliser pour trouver la mesure de distance. Un embedding vectoriel normalisé a une magnitude (longueur) d'exactement 1,0.

De plus, si vous connaissez la mesure de distance avec laquelle votre modèle a été entraîné, utilisez-la pour calculer la distance entre vos embeddings vectoriels.

Données normalisées

Si vous disposez d'un ensemble de données dans lequel tous les embeddings vectoriels sont normalisés, les trois mesures de distance fournissent les mêmes résultats de recherche sémantique. En substance, bien que chaque mesure de distance renvoie une valeur différente, ces valeurs sont triées de la même manière. Lorsque les embeddings sont normalisés, DOT_PRODUCT est généralement la méthode la plus efficace en termes de calcul, mais la différence est négligeable dans la plupart des cas. Toutefois, si votre application est très sensible aux performances, DOT_PRODUCT peut vous aider à les régler.

Données non normalisées

Si vous disposez d'un ensemble de données dans lequel les embeddings vectoriels ne sont pas normalisés, il n'est pas mathématiquement correct d'utiliser DOT_PRODUCT comme mesure de distance, car le produit scalaire ne mesure pas la distance. Selon la façon dont les embeddings ont été générés et le type de recherche préféré, la mesure de distance COSINE ou EUCLIDEAN produit des résultats de recherche subjectivement meilleurs que les autres mesures de distance. Il peut être nécessaire de tester COSINE ou EUCLIDEAN pour déterminer l'option la mieux adaptée à votre cas d'utilisation.

Vous ne savez pas si les données sont normalisées ou non normalisées

Si vous ne savez pas si vos données sont normalisées et que vous souhaitez utiliser DOT_PRODUCT, nous vous recommandons d'utiliser plutôt COSINE. COSINE est semblable à DOT_PRODUCT avec normalisation intégrée. La distance mesurée à l'aide de COSINE est comprise entre 0 et 2. Un résultat proche de 0 indique que les vecteurs sont très similaires.

Préfiltrer les documents

Pour préfiltrer les documents avant de trouver les voisins les plus proches, vous pouvez combiner une recherche de similarité avec d'autres opérateurs de requête. Les filtres composites and et or sont acceptés. Pour en savoir plus sur les filtres de champ compatibles, consultez Opérateurs de requête.

Python
from google.cloud.firestore_v1.base_vector_query import DistanceMeasure
from google.cloud.firestore_v1.vector import Vector

collection = db.collection("coffee-beans")

# Similarity search with pre-filter
# Requires a composite vector index
vector_query = collection.where("color", "==", "red").find_nearest(
    vector_field="embedding_field",
    query_vector=Vector([0.3416704, 0.18332680, 0.24160706]),
    distance_measure=DistanceMeasure.EUCLIDEAN,
    limit=5,
)
Node.js
// Similarity search with pre-filter
// Requires composite vector index
const preFilteredVectorQuery: VectorQuery = coll
    .where("color", "==", "red")
    .findNearest({
      vectorField: "embedding_field",
      queryVector: [3.0, 1.0, 2.0],
      limit: 5,
      distanceMeasure: "EUCLIDEAN",
    });

const vectorQueryResults = await preFilteredVectorQuery.get();
Go
import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/firestore"
)

func vectorSearchPrefilter(w io.Writer, projectID string) error {
	ctx := context.Background()

	// Create client
	client, err := firestore.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("firestore.NewClient: %w", err)
	}
	defer client.Close()

	collection := client.Collection("coffee-beans")

	// Similarity search with pre-filter
	// Requires a composite vector index
	vectorQuery := collection.Where("color", "==", "red").
		FindNearest("embedding_field",
			[]float32{3.0, 1.0, 2.0},
			5,
			// More info: https://firebase.google.com/docs/firestore/vector-search#vector_distances
			firestore.DistanceMeasureEuclidean,
			nil)

	docs, err := vectorQuery.Documents(ctx).GetAll()
	if err != nil {
		fmt.Fprintf(w, "failed to get vector query results: %v", err)
		return err
	}

	for _, doc := range docs {
		fmt.Fprintln(w, doc.Data()["name"])
	}
	return nil
}
Java
import com.google.cloud.firestore.VectorQuery;
import com.google.cloud.firestore.VectorQuerySnapshot;

VectorQuery preFilteredVectorQuery = coll
        .whereEqualTo("color", "red")
        .findNearest(
                "embedding_field",
                new double[] {3.0, 1.0, 2.0},
                /* limit */ 10,
                VectorQuery.DistanceMeasure.EUCLIDEAN);

ApiFuture<VectorQuerySnapshot> future = preFilteredVectorQuery.get();
VectorQuerySnapshot vectorQuerySnapshot = future.get();

Récupérer la distance vectorielle calculée

Vous pouvez récupérer la distance vectorielle calculée en attribuant un nom de propriété de sortie distance_result_field à la requête FindNearest, comme illustré dans l'exemple suivant :

Python
from google.cloud.firestore_v1.base_vector_query import DistanceMeasure
from google.cloud.firestore_v1.vector import Vector

collection = db.collection("coffee-beans")

vector_query = collection.find_nearest(
    vector_field="embedding_field",
    query_vector=Vector([0.3416704, 0.18332680, 0.24160706]),
    distance_measure=DistanceMeasure.EUCLIDEAN,
    limit=10,
    distance_result_field="vector_distance",
)

docs = vector_query.stream()

for doc in docs:
    print(f"{doc.id}, Distance: {doc.get('vector_distance')}")
Node.js
const vectorQuery: VectorQuery = coll.findNearest(
    {
      vectorField: 'embedding_field',
      queryVector: [3.0, 1.0, 2.0],
      limit: 10,
      distanceMeasure: 'EUCLIDEAN',
      distanceResultField: 'vector_distance'
    });

const snapshot: VectorQuerySnapshot = await vectorQuery.get();

snapshot.forEach((doc) => {
  console.log(doc.id, ' Distance: ', doc.get('vector_distance'));
});
Go
import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/firestore"
)

func vectorSearchDistanceResultField(w io.Writer, projectID string) error {
	ctx := context.Background()

	client, err := firestore.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("firestore.NewClient: %w", err)
	}
	defer client.Close()

	collection := client.Collection("coffee-beans")

	// Requires a vector index
	// https://firebase.google.com/docs/firestore/vector-search#create_and_manage_vector_indexes
	vectorQuery := collection.FindNearest("embedding_field",
		[]float32{3.0, 1.0, 2.0},
		10,
		firestore.DistanceMeasureEuclidean,
		&firestore.FindNearestOptions{
			DistanceResultField: "vector_distance",
		})

	docs, err := vectorQuery.Documents(ctx).GetAll()
	if err != nil {
		fmt.Fprintf(w, "failed to get vector query results: %v", err)
		return err
	}

	for _, doc := range docs {
		fmt.Fprintf(w, "%v, Distance: %v\n", doc.Data()["name"], doc.Data()["vector_distance"])
	}
	return nil
}
Java
import com.google.cloud.firestore.VectorQuery;
import com.google.cloud.firestore.VectorQueryOptions;
import com.google.cloud.firestore.VectorQuerySnapshot;

VectorQuery vectorQuery = coll.findNearest(
        "embedding_field",
        new double[] {3.0, 1.0, 2.0},
        /* limit */ 10,
        VectorQuery.DistanceMeasure.EUCLIDEAN,
        VectorQueryOptions.newBuilder().setDistanceResultField("vector_distance").build());

ApiFuture<VectorQuerySnapshot> future = vectorQuery.get();
VectorQuerySnapshot vectorQuerySnapshot = future.get();

for (DocumentSnapshot document : vectorQuerySnapshot.getDocuments()) {
    System.out.println(document.getId() + " Distance: " + document.get("vector_distance"));
}

Si vous souhaitez utiliser un masque de champ pour renvoyer un sous-ensemble de champs de document avec un distanceResultField, vous devez également inclure la valeur de distanceResultField dans le masque de champ, comme illustré dans l'exemple suivant :

Python
vector_query = collection.select(["color", "vector_distance"]).find_nearest(
    vector_field="embedding_field",
    query_vector=Vector([0.3416704, 0.18332680, 0.24160706]),
    distance_measure=DistanceMeasure.EUCLIDEAN,
    limit=10,
    distance_result_field="vector_distance",
)
Node.js
const vectorQuery: VectorQuery = coll
    .select('name', 'description', 'vector_distance')
    .findNearest({
      vectorField: 'embedding_field',
      queryVector: [3.0, 1.0, 2.0],
      limit: 10,
      distanceMeasure: 'EUCLIDEAN',
      distanceResultField: 'vector_distance'
    });
Go
import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/firestore"
)

func vectorSearchDistanceResultFieldMasked(w io.Writer, projectID string) error {
	ctx := context.Background()

	client, err := firestore.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("firestore.NewClient: %w", err)
	}
	defer client.Close()

	collection := client.Collection("coffee-beans")

	// Requires a vector index
	// https://firebase.google.com/docs/firestore/vector-search#create_and_manage_vector_indexes
	vectorQuery := collection.Select("color", "vector_distance").
		FindNearest("embedding_field",
			[]float32{3.0, 1.0, 2.0},
			10,
			firestore.DistanceMeasureEuclidean,
			&firestore.FindNearestOptions{
				DistanceResultField: "vector_distance",
			})

	docs, err := vectorQuery.Documents(ctx).GetAll()
	if err != nil {
		fmt.Fprintf(w, "failed to get vector query results: %v", err)
		return err
	}

	for _, doc := range docs {
		fmt.Fprintf(w, "%v, Distance: %v\n", doc.Data()["color"], doc.Data()["vector_distance"])
	}
	return nil
}
Java
import com.google.cloud.firestore.VectorQuery;
import com.google.cloud.firestore.VectorQueryOptions;
import com.google.cloud.firestore.VectorQuerySnapshot;

VectorQuery vectorQuery = coll
        .select("name", "description", "vector_distance")
        .findNearest(
          "embedding_field",
          new double[] {3.0, 1.0, 2.0},
          /* limit */ 10,
          VectorQuery.DistanceMeasure.EUCLIDEAN,
          VectorQueryOptions.newBuilder()
            .setDistanceResultField("vector_distance")
            .build());

ApiFuture<VectorQuerySnapshot> future = vectorQuery.get();
VectorQuerySnapshot vectorQuerySnapshot = future.get();

for (DocumentSnapshot document : vectorQuerySnapshot.getDocuments()) {
    System.out.println(document.getId() + " Distance: " + document.get("vector_distance"));
}

Spécifier un seuil de distance

Vous pouvez spécifier un seuil de similarité qui ne renvoie que les documents compris dans ce seuil. Le comportement du champ de seuil dépend de la mesure de distance que vous choisissez :

  • Les distances EUCLIDEAN et COSINE limitent le seuil aux documents dont la distance est inférieure ou égale au seuil spécifié. Ces mesures de distance diminuent à mesure que les vecteurs deviennent plus similaires.
  • La distance DOT_PRODUCT limite le seuil aux documents dont la distance est supérieure ou égale au seuil spécifié. Les distances de produit scalaire augmentent à mesure que les vecteurs deviennent plus similaires.

L'exemple suivant montre comment spécifier un seuil de distance pour renvoyer jusqu'à 10 documents les plus proches situés à une distance maximale de 4,5 unités à l'aide de la métrique de distance EUCLIDEAN :

Python
from google.cloud.firestore_v1.base_vector_query import DistanceMeasure
from google.cloud.firestore_v1.vector import Vector

collection = db.collection("coffee-beans")

vector_query = collection.find_nearest(
    vector_field="embedding_field",
    query_vector=Vector([0.3416704, 0.18332680, 0.24160706]),
    distance_measure=DistanceMeasure.EUCLIDEAN,
    limit=10,
    distance_threshold=4.5,
)

docs = vector_query.stream()

for doc in docs:
    print(f"{doc.id}")
Node.js
const vectorQuery: VectorQuery = coll.findNearest({
  vectorField: 'embedding_field',
  queryVector: [3.0, 1.0, 2.0],
  limit: 10,
  distanceMeasure: 'EUCLIDEAN',
  distanceThreshold: 4.5
});

const snapshot: VectorQuerySnapshot = await vectorQuery.get();

snapshot.forEach((doc) => {
  console.log(doc.id);
});
Go
import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/firestore"
)

func vectorSearchDistanceThreshold(w io.Writer, projectID string) error {
	ctx := context.Background()

	client, err := firestore.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("firestore.NewClient: %w", err)
	}
	defer client.Close()

	collection := client.Collection("coffee-beans")

	// Requires a vector index
	// https://firebase.google.com/docs/firestore/vector-search#create_and_manage_vector_indexes
	vectorQuery := collection.FindNearest("embedding_field",
		[]float32{3.0, 1.0, 2.0},
		10,
		firestore.DistanceMeasureEuclidean,
		&firestore.FindNearestOptions{
			DistanceThreshold: firestore.Ptr[float64](4.5),
		})

	docs, err := vectorQuery.Documents(ctx).GetAll()
	if err != nil {
		fmt.Fprintf(w, "failed to get vector query results: %v", err)
		return err
	}

	for _, doc := range docs {
		fmt.Fprintln(w, doc.Data()["name"])
	}
	return nil
}
Java
import com.google.cloud.firestore.VectorQuery;
import com.google.cloud.firestore.VectorQueryOptions;
import com.google.cloud.firestore.VectorQuerySnapshot;

VectorQuery vectorQuery = coll.findNearest(
        "embedding_field",
        new double[] {3.0, 1.0, 2.0},
        /* limit */ 10,
        VectorQuery.DistanceMeasure.EUCLIDEAN,
        VectorQueryOptions.newBuilder()
          .setDistanceThreshold(4.5)
          .build());

ApiFuture<VectorQuerySnapshot> future = vectorQuery.get();
VectorQuerySnapshot vectorQuerySnapshot = future.get();

for (DocumentSnapshot document : vectorQuerySnapshot.getDocuments()) {
    System.out.println(document.getId());
}

Limites

Lorsque vous utilisez des embeddings vectoriels, tenez compte des limites suivantes :

  • La dimension d'embedding maximale acceptée est de 2 048. Pour stocker des index plus volumineux, utilisez la réduction de la dimensionnalité.
  • Le nombre maximal de documents à renvoyer à partir d'une requête de plus proche voisin est de 1 000 (limitation de l'édition Standard uniquement).
  • La recherche vectorielle n'est pas compatible avec les écouteurs d'instantanés en temps réel.
  • Seules les bibliothèques clientes Python, Node.js, Go et Java sont compatibles avec la recherche vectorielle.

Étape suivante