Bu sayfada, aşağıdaki teknikleri kullanarak K en yakın komşu (KNN) vektör aramaları yapmak için Cloud Firestore'un nasıl kullanılacağı gösterilmektedir:
- Vektör değerlerini depola
- KNN vektör dizinlerini oluşturma ve yönetme
- Desteklenen vektör mesafe işlevlerinden birini kullanarak K-en yakın-komşu (KNN) sorgusu oluşturma
Vektör yerleştirmeleri depolama
Cloud Firestore verilerinizden metin yerleştirmeler gibi vektör değerleri oluşturabilir ve bunları Cloud Firestore belgelerinde saklayabilirsiniz.
Vektör yerleştirmeyi içeren yazma işlemi
Aşağıdaki örnek, Cloud Firestore belgesine yerleştirilen bir vektörün nasıl depolanacağını gösterir:
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([1.0 , 2.0, 3.0]) } 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]) });
Cloud Functions işleviyle vektör yerleştirmeleri hesaplayın
Bir belge güncellendiğinde veya oluşturulduğunda vektör yerleştirmeleri hesaplamak ve depolamak için bir Cloud Functions işlevi kurabilirsiniz:
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, }); }
Vektör dizinleri oluşturma ve yönetme
Vektör yerleştirmelerinizle en yakın komşu araması yapabilmeniz için önce buna karşılık gelen bir dizin oluşturmanız gerekir. Aşağıdaki örnekler, vektör dizinlerinin nasıl oluşturulacağını ve yönetileceğini göstermektedir.
Vektör dizini oluşturma
Bir vektör dizini oluşturmak için gcloud alpha firestore indexes composite create
işlevini kullanın:
gcloud
gcloud alpha firestore indexes composite create \ --collection-group=collection-group \ --query-scope=COLLECTION \ --field-config field-path=vector-field,vector-config='vector-configuration' \ --database=database-id
Bu örnekte:
- collection-group, koleksiyon grubunun kimliğidir.
- vector-field, vektör yerleştirmeyi içeren alanın adıdır.
- database-id, veritabanının kimliğidir.
- vector-configuration,
dimension
vektörünü ve dizin türünü içeriyor.dimension
, 2048'e kadar olan bir tam sayıdır. Dizin türüflat
olmalıdır. Dizin yapılandırmasını şu şekilde biçimlendirin:{"dimension":"DIMENSION", "flat": "{}"}
.
Aşağıdaki örnek, vector-field
alanı için vektör dizini ve color
alanı için artan dizin içeren bir bileşik dizin oluşturmaktadır. Bu dizin türünü, en yakın komşu aramadan önce verileri önceden filtrelemek için kullanabilirsiniz.
gcloud
gcloud alpha 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
Tüm vektör dizinlerini listeleme
gcloud
gcloud alpha firestore indexes composite list --database=database-id
database-id değerini veritabanının kimliğiyle değiştirin.
Vektör dizinini silme
gcloud
gcloud alpha firestore indexes composite delete index-id --database=database-id
Bu örnekte:
- index-id, silinecek dizinin kimliğidir.
Dizin kimliğini almak için
indexes composite list
işlevini kullanın. - database-id, veritabanının kimliğidir.
Vektör endeksini açıklama
gcloud
gcloud alpha firestore indexes composite describe index-id --database=database-id
Bu örnekte:
- index-id, açıklanacak dizin kimliğidir. Dizin kimliğini almak için veya
indexes composite list
öğesini kullanın. - database-id, veritabanının kimliğidir.
En yakın komşu sorgusu oluşturma
Vektör yerleştirmenin en yakın komşularını bulmak için benzerlik araması yapabilirsiniz. Benzerlik aramaları için vektör dizinleri gerekir. Dizin mevcut değilse Cloud Firestore, gcloud CLI kullanılarak oluşturulacak bir dizin önerir.
Python
from google.cloud.firestore_v1.base_vector_query import DistanceMeasure collection = collection("coffee-beans") # Requires vector index collection.find_nearest( vector_field="embedding_field", query_vector=Vector([3.0, 1.0, 2.0]), distance_measure=DistanceMeasure.EUCLIDEAN, limit=5)
Node.js
import { Firestore, FieldValue, VectorQuery, VectorQuerySnapshot, } from "@google-cloud/firestore"; // Requires single-field vector index const vectorQuery: VectorQuery = coll.findNearest('embedding_field', FieldValue.vector([3.0, 1.0, 2.0]), { limit: 5, distanceMeasure: 'EUCLIDEAN' }); const vectorQuerySnapshot: VectorQuerySnapshot = await vectorQuery.get();
Vektör mesafeleri
En yakın komşu sorgular, vektör mesafesi için aşağıdaki seçenekleri destekler:
EUCLIDEAN
: Vektörler arasındaki EUCLIDEAN mesafesini ölçer. Daha fazla bilgi edinmek için Öklid bölümünü inceleyin.COSINE
: Vektörleri aralarındaki açıya göre karşılaştırır. Bu sayede, vektörlerin büyüklüğüne bağlı olmayan benzerliği ölçebilirsiniz. Daha iyi performans gösteren ve matematiksel açıdan eşdeğer olan COSINE mesafesi yerine birim normalleştirilmiş vektörlerleDOT_PRODUCT
kullanmanızı öneririz. Daha fazla bilgi için Kosinüs benzerliği bölümüne bakın.DOT_PRODUCT
:COSINE
özelliğine benzer, ancak vektörlerin büyüklüğünden etkilenir. Daha fazla bilgi için Nokta çarpımı bölümüne bakın.
Verileri ön filtrele
En yakın komşuları bulmadan önce verileri önceden filtrelemek için benzerlik aramasını eşitsizlik filtreleri hariç diğer filtrelerle birleştirebilirsiniz. and
ve or
bileşik filtreler desteklenir. Alan filtreleri için aşağıdaki filtreler desteklenir:
==
eşittirin
array_contains
array_contains_any
Python
# Similarity search with pre-filter # Requires composite vector index collection.where("color", "==", "red").find_nearest( vector_field="embedding_field", query_vector=Vector([3.0, 1.0, 2.0]), 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("embedding_field", FieldValue.vector([3.0, 1.0, 2.0]), { limit: 5, distanceMeasure: "EUCLIDEAN", }); vectorQueryResults = await preFilteredVectorQuery.get();
Sınırlamalar
Vektör yerleştirmeleriyle çalışırken aşağıdaki sınırlamaları göz önünde bulundurun:
- Desteklenen maksimum yerleştirme boyutu 2048'dir. Daha büyük dizinleri depolamak için boyutluluk azaltma özelliğini kullanın.
- En yakın komşu sorgudan döndürülecek maksimum doküman sayısı 1.000'dir.
- Vektör arama, gerçek zamanlı anlık görüntü işleyicileri desteklemez.
- Verileri önceden filtrelemek için eşitsizlik filtrelerini kullanamazsınız.
- Vektör aramasını yalnızca Python ve Node.js istemci kitaplıkları destekler.
Sırada ne var?
- Cloud Firestore ile ilgili en iyi uygulamalar hakkında bilgi edinin.
- Geniş ölçekte okuma ve yazma işlemlerini anlama