Kalıcı Krom Verilerini Başlatma
import { ChromaClient } from 'chromadb'
Müşteriyi Başlatma
const client = new ChromaClient();
Ortak Müşteri İşlemleri
await client.reset() // Veritabanını temizle
Koleksiyonlarla Çalışma
Chromadb, vektör verilerini yönetmek için koleksiyon kavramını kullanır, bu da MySQL'deki tablolara benzeyebilir.
Koleksiyon Oluşturma, Görüntüleme ve Silme
Chroma, koleksiyon adını URL'de kullanır, bu nedenle bazı adlandırma kısıtlamaları vardır:
- Ad uzunluğu 3 ile 63 karakter arasında olmalıdır.
- Ad küçük harfler veya rakamlarla başlamalı ve bitmelidir ve içinde noktalar, tireler ve alt çizgiler bulunabilir.
- Ad arka arkaya iki nokta içeremez.
- Ad geçerli bir IP adresi olamaz.
Bir koleksiyon oluşturmak için koleksiyon adı ve isteğe bağlı vektör hesaplama işlevi (ayrıca gömme işlevi olarak da bilinir) belirtilmelidir. Bir gömme işlevi verilirse, her koleksiyona erişildiğinde sağlanmalıdır.
Not: Gömme işlevi metin vektörlerini hesaplamak için kullanılır.
import { ChromaClient } from 'chromadb'
Aşağıdaki gibi bir koleksiyon oluşturun ve başvurun:
let collection = await client.createCollection({name: "my_collection", embeddingFunction: emb_fn})
let collection2 = await client.getCollection({name: "my_collection", embeddingFunction: emb_fn})
Gömme işlevi, metin alır ve hesaplanmış bir vektör verisi döndürür.
Not: Başlangıç düzeydeki kullanıcılar metin gömme modelleri hakkında bu öğreticidenbilgi edinebilirler.
Mevcut koleksiyonlar, adlarıyla .getCollection kullanılarak başvurulabilir ve aynı zamanda .deleteCollection kullanılarak silinebilir.
const collection = await client.getCollection({name: "tizi365"}) // tizi365 koleksiyonuna başvur
await client.deleteCollection({name: "my_collection"}) // Koleksiyonu sil
Ortak Koleksiyon İşlevleri
await collection.peek() // Koleksiyonda bulunan ilk 10 veri kaydını döndürür
await collection.count() // Koleksiyonda bulunan toplam veri kayıtlarını döndürür
Vektör Uzaklık Hesaplama Yöntemlerini Ayarlama
createCollection ayrıca, vektör uzayı için mesafe hesaplama yöntemini özelleştirmek için hnsw:space değerini ayarlayabilen isteğe bağlı bir metadata parametresi içerir.
Not: Vektör verileri, benzerliği hesaplayarak vektörler arasındaki mekansal uzaklık aracılığıyla benzerliği temsil eder; daha yakın mesafeler daha yüksek benzerliği ve tersi gösterir.
let collection = client.createCollection("collection_name", undefined, metadata={ "hnsw:space": "cosine" })
hnsw:space için geçerli seçenekler "l2", "ip" veya "cosine"dir. Varsayılan "l2"dir.
Bir Koleksiyona Veri Ekleme
Veri eklemek için .add metodunu Chroma koleksiyonuna kullanın.
Belgelerin vektörlerini belirtmeden doğrudan veri ekleyin:
await collection.add({
ids: ["id1", "id2", "id3", ...],
metadatas: [{"bölüm": "3", "ayet": "16"}, {"bölüm": "3", "ayet": "5"}, {"bölüm": "29", "ayet": "11"}, ...],
documents: ["lorem ipsum...", "doc2", "doc3", ...],
})
// Parametre Açıklaması
// ids - zorunlu
// embeddings - isteğe bağlı
// metadata - isteğe bağlı
// documents - isteğe bağlı
Chroma'ya belge listesi geldiğinde, belgelerin vektörlerini hesaplamak için koleksiyonun gömme işlevini otomatik olarak kullanacaktır (koleksiyon oluşturulurken bir gömme işlevi belirtilmemişse, varsayılan değer kullanılacaktır). Chroma ayrıca belgeleri kendisi de saklayacaktır. Seçilen gömme işleviyle kullanılamayacak kadar büyükse bir belge, bir istisna oluşturur.
Her belgenin benzersiz bir kimliği (ids) olmalıdır. Aynı ID iki kez eklenirse, yalnızca ilk değer saklanır. Her belge için filtreleme sorguları sırasında ek bilgileri depolamak için isteğe bağlı bir metadata sözlükleri listesi (metadatas) sağlanabilir.
Alternatif olarak, doğrudan belgeyle ilgili vektör verileri listesi sağlayabilir ve Chroma vektörleri otomatik olarak hesaplama yapmadan sağladığınız vektör verilerini kullanacaktır.
await collection.add({
ids: ["id1", "id2", "id3", ...],
embeddings: [[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...],
metadatas: [{"bölüm": "3", "ayet": "16"}, {"bölüm": "3", "ayet": "5"}, {"bölüm": "29", "ayet": "11"}, ...],
documents: ["lorem ipsum...", "doc2", "doc3", ...],
})
Sağlanan vektör veri boyutları (uzunluk) koleksiyonun boyutlarıyla eşleşmiyorsa bir istisna oluşur.
Ayrıca belgeleri başka bir yerde saklayabilir ve basitçe vektör verilerini ve metadata listesini Chroma'ya sağlayabilirsiniz. Ids'yi vektörleri başka yerde depolanan belgelerle ilişkilendirmek için kullanabilirsiniz.
await collection.add({
ids: ["id1", "id2", "id3", ...],
embeddings: [[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2], ...],
metadatas: [{"bölüm": "3", "ayet": "16"}, {"bölüm": "3", "ayet": "5"}, {"bölüm": "29", "ayet": "11"}, ...],
})
Not: Vektör veritabanının temel işlevi vektör verilerine dayalı anlamsal benzerlik aramasıdır. Vektör veritabanının boyutunu azaltmak ve verimliliği artırmak için vektör verilerini ve bazı filtrelenabilir öznitelik koşullarını vektör veritabanında saklama seçeneğine sahibiz. Diğer veriler, makale içeriği gibi, MySQL gibi veritabanlarına saklanabilir, yeter ki ids aracılığıyla ilişkilendirilsin.
Koleksiyon Verilerinin Sorgulanması
.query yöntemi, Chroma veri kümesini çeşitli şekillerde sorgulamak için kullanılabilir.
Sorgulamak için bir dizi sorgu gömülmesi (vektör verisi) kullanabilirsiniz.
İpucu: Sorgu gömüsünü almak için, gerçek geliştirme senaryolarında, kullanıcının sorgusu genellikle önce bir metin gömme modeli aracılığıyla bir sorgu vektörüne hesaplanır ve ardından bu vektör benzer içerikleri sorgulamak için kullanılır.
const sonuç = await koleksiyon.sorgu({
queryEmbeddings: [[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...],
nResults: 10,
where: {"metadata_alanı": "buna_eşit"},
})
// input sırası
// query_gömüleri - opsionel
// n_sonuçlar - gerekli
// where - opsionel
// query_metinleri - opsionel
Sorgu, her sorgu vektörü (sorgu gömüsü) için en iyi n_sonuçlar sonucu sırayla döndürecektir. Her belgeyle ilişkilendirilmiş metadatalara dayalı olarak sonuçları filtrelemek için isteğe bağlı olarak bir where filtre sözlüğü sağlanabilir. Ayrıca, isteğe bağlı olarak bir where_document filtre sözlüğü sağlanarak belge içeriğine dayalı olarak sonuçları filtrelemek mümkündür.
Sağlanan sorgu gömüleri koleksiyonun boyutlarıyla tutarlı değilse, bir istisna oluşacaktır. Vektör tutarlılığını sağlamak için aynı metin gömme modelinin kullanılması önerilir.
Ayrıca, bir dizi sorgu metni kullanarak da sorgulama yapabilirsiniz. Chroma, önce her sorgu metni için koleksiyonun gömme işlevini kullanarak vektörü hesaplar ve ardından oluşturulan metin vektörlerini kullanarak sorguyu gerçekleştirir.
await koleksiyon.sorgu({
nResults: 10, // n_results
where: {"metadata_alanı": "buna_eşit"}, // where
queryTexts: ["doc10", "thus spake zarathustra", ...], // query_text
})
Ayrıca, koleksiyondan veri sorgulamak için .geti de kullanabilirsiniz.
await koleksiyon.get({
ids: ["id1", "id2", "id3", ...], //ids
where: {"stil": "stil1"} // where
})
.get ayrıca where ve where_document filtrelerini de destekler. Eğer bir id sağlanmazsa, where ve where_document filtrelerine uyan koleksiyondaki tüm verileri döndürecektir.
Döndürülen Alanların Belirtilmesi
get veya query kullanırken, döndürülecek veri alanlarını belirtmek için include parametresini kullanabilirsiniz. Vektör verileri, belgeler ve metadatalarda bulunan herhangi bir veriyi döndürmek için varsayılan olarak, Chroma belgeleri, metadataları ve vektör mesafelerini döndürür. include parametresine alan adlarının bir dizisini ileterek döndürülecek alanları belirleyebilirsiniz.
collection.get(
include=["belgeler"]
)
collection.query(
query_embeddings=[[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...],
include=["belgeler"]
)
Filtrelerin Kullanımı
Chroma, metadatalara ve belge içeriğine dayalı sorguları filtrelemeyi destekler. where filtresi metadataları filtrelemek için, where_document filtresi ise belge içeriğini filtrelemek için kullanılır. Aşağıda, filtreleme koşul ifadelerini nasıl yazılacağını açıklıyoruz.
Metadatalara Göre Filtreleme
Metadataları filtrelemek için, sorgu için bir where filtre sözlüğü sağlanmalıdır. Sözlüğün aşağıdaki yapısı olmalıdır:
{
"metadata_alanı": {
<Operatör>: <Değer>
}
}
Metadataları filtreleme, aşağıdaki operatörleri destekler:
- $eq - Eşittir (string, integer, float)
- $ne - Eşit değil (string, integer, float)
- $gt - Büyüktür (int, float)
- $gte - Büyük veya eşit (int, float)
- $lt - Küçüktür (integer, float)
- $lte - Küçük veya eşit (int, float)
$eq operatörünü kullanmak, where filtreyi kullanmakla eşdeğerdir.
{
"metadata_alanı": "arama_metni"
}
{
"metadata_alanı": {
"$eq": "arama_metni"
}
}
Belge İçeriğine Göre Filtreleme
Belge içeriğini filtrelemek için, sorgu için bir where_document filtre sözlüğü sağlanmalıdır. Sözlüğün aşağıdaki yapısı olmalıdır:
{
"$contains": "arama_metni"
}
Mantıksal Operatörleri Kullanma
Çeşitli filtreleri birleştirmek için $and ve $or mantıksal operatörlerini de kullanabilirsiniz.
$and operatörü, listedeki tüm filtreleri karşılayan sonuçları döndürecektir.
{
"$and": [
{
"metadata_field": {
<Operatör>: <Değer>
}
},
{
"metadata_field": {
<Operatör>: <Değer>
}
}
]
}
$or operatörü, listedeki herhangi bir filtre koşulunu karşılayan sonuçları döndürecektir.
{
"$or": [
{
"metadata_field": {
<Operatör>: <Değer>
}
},
{
"metadata_field": {
<Operatör>: <Değer>
}
}
]
}
Veri Güncelleme
Chroma ayrıca mevcut veriyi güncelleyebilen ve veri mevcut değilse yeni veri ekleyebilen upsert işlemini desteklemektedir.
await collection.upsert({
ids: ["id1", "id2", "id3"],
embeddings: [[1.1, 2.3, 3.2], [4.5, 6.9, 4.4], [1.1, 2.3, 3.2]],
metadatas: [{"chapter": "3", "verse": "16"}, {"chapter": "3", "verse": "5"}, {"chapter": "29", "verse": "11"}],
documents: ["doc1", "doc2", "doc3"]
})
Veri Silme
Chroma, koleksiyondan id'ye göre veri silmek için .delete kullanımını desteklemektedir.
await collection.delete({
ids: ["id1", "id2", "id3",...], //ids
where: {"chapter": "20"} //where
})