Python Chromadb Detaylı Geliştirme Kılavuzu
Kurulum
pip install chromadb
Chromadb Verilerinin Kalıcı Hale Getirilmesi
import chromadb
Chroma veritabanı dosyası için depolama yolunu belirtebilirsiniz. Veri mevcutsa, veritabanı dosyası otomatik olarak program başladığında yüklenecektir.
client = chromadb.PersistentClient(path="/veri/tizi365.db")
path parametresi, Chroma veritabanı dosyasının yoludur.
Not: Bir Chroma veritabanı için bir kez istemci nesnesi oluşturmak yeterlidir. Aynı yolda birden çok istemciyi yüklemek ve kaydetmek, veri silme de dahil olmak üzere beklenmeyen davranışlara yol açabilir. Genellikle, uygulamada yalnızca bir Chroma istemcisi oluşturulmalıdır.
İstemci nesnesinin bazı yaygın olarak kullanılan işlevleri:
client.reset() # Veritabanını temizler ve tamamen sıfırlar
Koleksiyon İşlemleri
Chromadb, vektör verilerinin koleksiyonlarını yönetmek için collection prensibini kullanır, bu MYSQL'deki tablolara benzetilebilir.
Koleksiyon Oluşturma, Görüntüleme ve Silme
Chroma, URL'de koleksiyon adını kullanır, bu nedenle bazı adlandırma kısıtlamalarına sahiptir:
- Ad uzunluğu 3 ile 63 karakter arasında olmalıdır.
- Ad, küçük harf veya sayı ile başlamalı ve bitmeli ve arada nokta, tire ve alt çizgi içerebilir.
- Ad ardışık iki nokta içeremez.
- Ad geçerli bir IP adresi olamaz.
Koleksiyon oluşturmak için, koleksiyon adını ve isteğe bağlı bir vektör hesaplama işlevini (ayrıca gömme işlevi olarak da bilinir) belirtmeniz gerekir. Bir gömme işlevi sağlanıyorsa, her erişildiğinde sağlanmalıdır.
Not: Vektör hesaplama işlevinin (gömme işlevi) amacı metin vektörünü hesaplamaktır.
collection = client.create_collection(name="benim_koleksiyonum", embedding_function=emb_fn)
collection = client.get_collection(name="benim_koleksiyonum", embedding_function=emb_fn)
Gömme işlevi metin alır ve hesaplanmış bir vektör döndürür.
Not: Başlangıç seviyesindeki kullanıcılar metin gömme modeli öğreticilerini öğrenebilirler.
Mevcut bir koleksiyona .get_collection işleviyle başvurabilir ve bir koleksiyonu silmek için .delete_collection işlevini kullanabilirsiniz. Ayrıca, bir koleksiyona başvurmak için .get_or_create_collection kullanabilirsiniz (varsa) veya varsa oluşturabilirsiniz.
collection = client.get_collection(name="tizi365")
collection = client.get_or_create_collection(name="tizi365")
client.delete_collection(name="tizi365")
Diğer sık kullanılan koleksiyon işlemleri:
collection.peek() # Koleksiyondaki ilk 10 veri listesini döndürür
collection.count() # Koleksiyondaki toplam veri sayısını döndürür
collection.modify(name="yeni_ad") # Koleksiyonun adını değiştirir
Vektör Mesafesi Hesaplama Yöntemi Belirleme
create_collection işlevi ayrıca isteğe bağlı bir metadata parametresi içerir. hnsw:space değerini cosine gibi özelleştirilmiş vektör uzayı mesafesi hesaplama yöntemi için ayarlayarak vektör uzayı mesafesi hesaplama yöntemini özelleştirebilirsiniz.
Not: Vektör verileri, vektörler arasındaki mekansal mesafeyi hesaplayarak vektörler arasındaki benzerliği temsil eder. Mesafe ne kadar yakınsa, benzerlik o kadar yüksek olur, tersi de geçerlidir.
collection = client.create_collection(
name="koleksiyon_adı",
metadata={"hnsw:space": "cosine"} # l2 varsayılan hesaplama yöntemidir
)
hnsw:space için geçerli seçenekler "l2", "ip" veya "cosine" dır. Varsayılan "l2" dir.
Bir Koleksiyona Veri Ekleme
.add yöntemini kullanarak Chroma'ya veri ekleyin.
Belge vektörlerini belirtmeden doğrudan veri ekleyin:
collection.add(
documents=["lorem ipsum...", "doc2", "doc3", ...],
metadatas=[{"bölüm": "3", "ayet": "16"}, {"bölüm": "3", "ayet": "5"}, {"bölüm": "29", "ayet": "11"}, ...],
ids=["id1", "id2", "id3", ...]
)
Chroma'ya bir belge listesi gönderilirse, 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ılır). Chroma ayrıca belgeleri kendisi depolayacaktır. Seçilen gömme işleviyle hesaplanacak belge çok büyükse, bir istisna meydana gelecektir.
Her belgenin benzersiz bir kimliği (ids) olmalıdır. Aynı kimliği iki kez eklemek, yalnızca ilk değerini depolamakla sonuçlanacaktır. İsteğe bağlı olarak, her belge için ekstra bilgi depolamak için bir liste meta veri sözlüğü (metadatas) sağlayabilir ve bunlar sorgulama sırasında veri filtreleme için kullanılabilir.
Alternatif olarak, belgenin ilgili vektör verilerinin bir listesini doğrudan sağlayabilir ve Chroma otomatik olarak vektörleri hesaplama yerine sağladığınız vektör verilerini kullanacaktır.
collection.add(
documents=["doc1", "doc2", "doc3", ...],
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"}, ...],
ids=["id1", "id2", "id3", ...]
)
Sağlanan vektör veri boyutları (uzunluk) koleksiyonun boyutlarıyla eşleşmiyorsa bir istisna meydana gelecektir.
Ayrıca belgeleri başka bir yerde depolayabilir ve Chroma'ya vektör verileri ve meta veri listesi sağlayabilirsiniz. Vektörleri başka bir yerde depolanan belgelerle ilişkilendirmek için ids kullanabilirsiniz.
collection.add(
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"}, ...],
ids=["id1", "id2", "id3", ...]
)
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ı gerekli filtreleme özelliklerini vektör veritabanında depolamayı seçebiliriz. Diğer veriler, makale içeriği gibi, MYSQL gibi veritabanlarında depolanabilir, yeter ki bunlar kimlikler aracılığıyla ilişkilendirilmiş olsun.
Koleksiyon Verilerini Sorgulama
.query yöntemi, Chroma veri setlerini çeşitli şekillerde sorgulamak için kullanılabilir.
Sorguyu, bir dizi sorgu gömülmesi (vektör verisi) kullanarak yapabilirsiniz.
İpucu: Gerçek geliştirme senaryolarında, sorgu gömmeleri genellikle öncelikle bir metin gömme modeli aracılığıyla kullanıcının sorgusunun vektörünü hesaplayarak elde edilir ve ardından bu vektörü benzer içerikleri sorgulamak için kullanır.
collection.query(
query_embeddings=[[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...],
n_results=10,
where={"metadata_field": "buna_eşit"},
where_document={"$contains":"arama_metni"}
)
Sorgu, her sorgu vektörüne (query_embedding) en iyi eşleşen n_results sonucunu sırayla döndürecektir. Her belgeyle ilişkili metadata'ya göre sonuçları filtrelemek için isteğe bağlı bir where filtre sözlüğü sağlanabilir. Ayrıca, belge içeriğine göre sonuçları filtrelemek için isteğe bağlı bir where_document filtre sözlüğü sağlanabilir.
Eğer sağlanan query_embeddings, koleksiyonun boyutlarıyla tutarsızsa, bir istisna oluşacaktır. Tutarsız vektör boyutları için aynı metin gömme modelini kullanarak vektörleri hesaplamak için kullanın.
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ü hesaplayacak ve sonra oluşturulan metin vektörlerini kullanarak sorgulama yapacaktır.
collection.query(
query_texts=["belge10", "böyle dedi zerdüşt", ...],
n_results=10,
where={"metadata_field": "buna_eşit"},
where_document={"$contains":"arama_metni"}
)
Ayrıca, koleksiyondan id'ye göre veri sorgulamak için .get'i de kullanabilirsiniz.
collection.get(
ids=["id1", "id2", "id3", ...],
where={"stil": "stil1"}
)
.get, aynı zamanda where ve where_document filtrelerini destekler. Eğer bir id sağlanmazsa, where ve where_document filtrelerine uyan koleksiyondaki tüm öğeleri döndürecektir.
Dönüş Alanlarını Belirtme
get veya query kullanırken, dönüş alanını belirtmek için include parametresini kullanabilirsiniz--gömmelemeler, belgeler, veya metadatalar, ve sorgular için mesafe verilerinin döndürülmesi gerekir. Varsayılan olarak, Chroma belgeleri ve metadataları döndürür, ve sorgular için mesafe verilerini döndürür, "ids" ise her zaman döndürür. Sorgunun veya get yönteminin includes parametresine alan adları dizisini geçirerek döndürülecek alanları belirtebilirsiniz.
collection.get(
include=["documents"]
)
collection.query(
query_embeddings=[[11.1, 12.1, 13.1],[1.1, 2.3, 3.2], ...],
include=["documents"]
)
Filtre Kullanımı
Chroma, metadatalara ve belge içeriğine dayalı sorguları filtrelemeyi destekler. where filtresi, metadataları filtrelemek için kullanılır ve where_document filtresi belge içeriğini filtrelemek için kullanılır. Aşağıdaki açıklamalar, filtre koşul ifadelerinin nasıl yazılacağını açıklar.
Metadatalara Göre Filtreleme
Metadataları filtrelemek için sorgu için bir where filtre sözlüğü sağlamanız gerekir. Sözlüğün aşağıdaki yapısına sahip olması gerekmektedir:
{
"metadata_alanı": {
<Operatör>: <Değer>
}
}
Metadataları filtreleme şu operatörleri destekler:
- $eq - eşittir (string, tamsayı, ondalıklı sayı)
- $ne - eşit değil (string, tamsayı, ondalıklı sayı)
- $gt - büyüktür (tamsayı, ondalıklı sayı)
- $gte - büyük eşit (tamsayı, ondalıklı sayı)
- $lt - küçüktür (tamsayı, ondalıklı sayı)
- $lte - küçük eşit (tamsayı, ondalıklı sayı)
$eq operatörünü kullanmak, where filtresini 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ğlamanız gerekir. Sözlüğün aşağıdaki yapısına sahip olması gerekmektedir:
{
"$contains": "arama_metni"
}
Mantıksal Operatörlerin Kullanımı
Birden fazla filtreleme işlemini birleştirmek için $and ve $or mantıksal operatörlerini de kullanabilirsiniz.
$and operatörü, listedeki tüm filtreleri sağlayan sonuçları döndürecektir.
{
"$and": [
{
"metadata_alanı": {
<Operatör>: <Değer>
}
},
{
"metadata_alanı": {
<Operatör>: <Değer>
}
}
]
}
$or operatörü ise listedeki herhangi bir filtre koşulunu sağlayan sonuçları döndürecektir.
{
"$or": [
{
"metadata_alanı": {
<Operatör>: <Değer>
}
},
{
"metadata_alanı": {
<Operatör>: <Değer>
}
}
]
}
Bir Koleksiyondaki Verileri Güncelleme
.update kullanarak bir koleksiyondaki verilerin herhangi bir özelliğini güncellemenize olanak tanır.
collection.update(
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=["belge1", "belge2", "belge3", ...],
)
Bir id koleksiyonda bulunamadığı takdirde, bir hata kaydedilir ve güncelleme görmezden gelinir. Sağlanan belgenin karşılık gelen bir vektörü yoksa, koleksiyonun gömme işlevi vektörü hesaplamak için kullanılacaktır.
Sağlanan vektör verisi, koleksiyonun boyutundan farklı bir boyutta ise bir istisna oluşacaktır.
Chroma ayrıca var olan verileri güncellemeye ve var olmayan verileri eklemeye olanak tanıyan upsert işlemini desteklemektedir.
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=[{"bölüm": "3", "ayet": "16"}, {"bölüm": "3", "ayet": "5"}, {"bölüm": "29", "ayet": "11"}, ...],
documents=["belge1", "belge2", "belge3", ...],
)
Koleksiyon Verilerini Silme
Chroma, her bir veriye id ile koleksiyondan veri silmek için .delete kullanımını destekler. Her bir veriye ilişkin vektörler, belgeler ve metaveriler de silinecektir.
collection.delete(
ids=["id1", "id2", "id3",...],
where={"bölüm": "20"}
)
.delete ayrıca bir where filtresini destekler. Eğer hiçbir id sağlanmazsa, where filtresi ile eşleşen koleksiyondaki tüm öğeleri silecektir.