vecsai 0.1.3

Vecsai: vector db for everyone

vecsai

vecsai-db sunucusu için Python istemci kütüphanesi. Full-text arama, vektör araması, doküman CRUD, toplu import/export ve daha fazlasını destekler.

Kurulum

pip install vecsai

Hızlı Başlangıç

import vecsai

# İstemci oluştur
client = vecsai.client("localhost", 8137)

# Sağlık kontrolü
print(client.health())

Koleksiyon Oluşturma

Dict ile

schema = {
    "name": "movies",
    "vector_index_impl": "hnsw",
    "fields": [
        {"name": "title", "type": "string", "locale": "tr"},
        {"name": "genres", "type": "string", "facet": True},
        {"name": "rating", "type": "float", "sort": True},
        {"name": "overview", "type": "string"},
        {
            "name": "embedding",
            "type": "vector",
            "vector_dim": 768,
            "vector_model": "nomic-embed-text-v2-moe",
            "index": True,
            "vector_source_fields": ["title", "overview"],
        },
    ],
    "default_sorting_field": "rating",
}

client.create_collection(schema)

SchemaBuilder ile

from vecsai import SchemaBuilder

schema = (
    SchemaBuilder("movies")
    .field("title", "string", locale="tr")
    .field("genres", "string", facet=True)
    .field("rating", "float", sort=True)
    .field("overview", "string")
    .vector_field("embedding", dim=768, model="nomic-embed-text-v2-moe",
                  source_fields=["title", "overview"])
    .sorting_field("rating")
    .vector_index("hnsw")
    .build()
)

client.create_collection(schema)

Koleksiyon İşlemleri

# Koleksiyonları listele
collections = client.list_collections()

# Koleksiyon detayı
info = client.get_collection("movies")

# Koleksiyon sil
client.delete_collection("movies")

Doküman İşlemleri

# Tekil doküman ekle
doc = client.create_document("movies", {
    "title": "Inception",
    "genres": "Sci-Fi",
    "rating": 8.8,
    "overview": "A thief who steals corporate secrets..."
})

# Doküman getir
doc = client.get_document("movies", "doc_id_123")

# Doküman güncelle (kısmi)
client.update_document("movies", "doc_id_123", {"rating": 9.0})

# Tekil doküman sil
client.delete_document("movies", "doc_id_123")

# Filtreyle topluca sil
client.delete_documents_by_filter("movies", "rating:<5.0")

Toplu Import

# Python listesi ile
docs = [
    {"title": "Film 1", "rating": 7.5},
    {"title": "Film 2", "rating": 8.1},
]
results = client.import_documents("movies", docs, action="create")

# JSONL string ile
jsonl = '{"title":"Film 1","rating":7.5}\n{"title":"Film 2","rating":8.1}'
results = client.import_jsonl("movies", jsonl, action="upsert")

Dosya Yükleme (CSV/JSON/JSONL/Excel)

# CSV yükle (arka planda çalışır)
job = client.upload_documents("movies", "data/movies.csv", action="create", format="csv")
print(job)  # {"message": "...", "job_id": "abc123"}

# Excel yükle (belirli sayfa)
job = client.upload_documents("movies", "data/movies.xlsx", format="excel", sheet="Sheet1")

# İş durumunu takip et
status = client.get_job(job["job_id"])
print(status)  # {"status": "completed", "imported": 1000, ...}

Export

# Tüm dokümanları JSONL olarak al
jsonl_data = client.export_documents("movies")

Arama

Full-text Arama

results = client.search(
    "movies",
    q="inception",
    query_by="title,overview",
    filter_by="rating:>7.0",
    sort_by="rating:desc",
    facet_by="genres",
    page=1,
    per_page=10,
)

for hit in results["Hits"]:
    print(hit["Document"]["title"], hit["TextMatch"])

Vektör Araması (Embedding ile)

# Sunucu sorguyu otomatik embedding'e çevirir
results = client.vector_search(
    "movies",
    q="bilim kurgu uzay macerası",
    model="nomic-embed-text-v2-moe",
    k=5,
    filter_by="rating:>6.0",
)

Vektör Araması (Doğrudan vektör ile)

results = client.vector_search(
    "movies",
    vector=[0.1, 0.2, 0.3, ...],  # 768 boyutlu vektör
    k=10,
)

Collection Nesnesi (Zincirleme Kullanım)

movies = client.collection("movies")

# Doküman ekle
movies.add({"title": "Interstellar", "rating": 8.7})

# Arama
results = movies.search(q="interstellar", query_by="title")

# Vektör araması
results = movies.vector_search(q="uzay yolculuğu", k=5)

# Dosya yükle
job = movies.upload("data/movies.csv")

# Export
data = movies.export()

# Toplu import
movies.import_documents([{"title": "Film 1"}, {"title": "Film 2"}])

Hata Yönetimi

from vecsai import VecsaiError

try:
    client.get_collection("olmayan_koleksiyon")
except VecsaiError as e:
    print(e.status_code)  # 404
    print(e.message)      # hata mesajı

Metrikler

metrics = client.metrics()
print(metrics)  # Motor metrikleri (koleksiyon sayıları vb.)

API Referansı

Metod	Açıklama
health()	Sunucu sağlık kontrolü
metrics()	Motor metrikleri
create_collection(schema)	Koleksiyon oluştur
list_collections()	Koleksiyonları listele
get_collection(name)	Koleksiyon detayı
delete_collection(name)	Koleksiyon sil
collection(name)	Collection nesnesi al
create_document(col, doc)	Doküman oluştur
get_document(col, id)	Doküman getir
update_document(col, id, updates)	Doküman güncelle
delete_document(col, id)	Doküman sil
delete_documents_by_filter(col, filter)	Filtre ile toplu sil
import_documents(col, docs, action)	Toplu import (list)
import_jsonl(col, jsonl, action)	Toplu import (JSONL)
upload_documents(col, path, ...)	Dosya yükle
export_documents(col)	Dokümanları JSONL export
search(col, q, query_by, ...)	Full-text arama
vector_search(col, q, vector, ...)	Vektör araması
get_job(job_id)	İş durumu sorgula