Skip to main content

microvectordb 🚀

PyPI version License: MIT Python 3.8+ Dependencies: NumPy

microvectordb, harici ağır ve hantal bağımlılıklara ihtiyaç duymadan çalışan, ChromaDB ve FAISS benzeri temiz bir API sunan, son derece hızlı, hafif ve kalıcı (persistent) bir Python Vektör Veritabanıdır.


🎯 Neden microvectordb?

Yapay zeka, RAG (Retrieval-Augmented Generation) veya semantik arama projelerinde çoğu geliştirici iki zorlukla karşılaşır:

  1. ChromaDB: Çok yeteneklidir ancak yüzlerce megabaytlık bağımlılık (ONNX Runtime, Pydantic vb.) indirir, bazen Windows veya hafif ortamlarda kurulum/derleme hataları verir.
  2. FAISS: Facebook'un geliştirdiği harika bir hız kütüphanesidir; ancak bir veritabanı değildir. Doküman saklayamaz, metadata filtreleyemez (where={"kategori": "ai"}) ve C++ derleyicisi gerektirir.

microvectordb tam bu noktada devreye girer:

ChromaDB'nin kullanım kolaylığı ve zengin veritabanı yeteneklerini, FAISS'in hafiflik ve indeksleme felsefesiyle birleştirir; üstelik sadece numpy kullanarak!


🥊 Karşılaştırma: microvectordb vs ChromaDB vs FAISS

Kriter 🚀 microvectordb (v0.2.0) 🔵 ChromaDB 🟣 FAISS
Bağımlılık Ağırlığı 🟢 Sadece numpy (~1 MB) 🟡 10+ kütüphane (~300-500 MB) 🔴 C++ derleyicisi / Conda zorunlu
Kurulum Hızı ⚡ 2 saniye (pip install .) ⏳ 1-3 dakika ⚠️ Platforma göre zor
Kullanım Amacı Tam Vektör Veritabanı Tam Vektör Veritabanı Sadece Vektör Arama Kütüphanesi
Metadata Filtreleme ✅ Zengin ($eq, $in, $gte vb.) ✅ Zengin ❌ Yok
Doküman Saklama ✅ Dahili (SQLite destekli) ✅ Dahili ❌ Yok
Disk Kalıcılığı ✅ Dahili (.npy + SQLite) ✅ Dahili ❌ Manuel indeks kaydetme
Arama Algoritmaları ✅ Exact (Flat) + IVF Kümeleme HNSW (Approximate) Flat, IVF, HNSW, PQ
Bellek Sıkıştırma ✅ Skalar Kuantizasyon (int8) ❌ Yok ✅ Var
Büyük Veri Desteği ✅ Memory-Mapped (use_mmap=True) ❌ (RAM tüketir) ✅ Var
Cross-Platform ✅ Windows/Mac/Linux/Raspberry Pi ⚠️ Bazen Windows'ta derleme hatası ⚠️ Derleme/ortam bağımlı
Öğrenme Eğrisi ⭐ Sıfır (ChromaDB API uyumlu) ⭐ Kolay ⚠️ Karmaşık

✨ Temel Özellikler

  • Sıfır Hantal Bağımlılık: Sadece numpy gerektirir. Derleyici (C/C++) zorunluluğu yoktur, her sistemde kutudan çıktığı gibi çalışır.
  • Kalıcı (Persistent) & Bellek İçi (In-Memory) Mod:
    • PersistentClient(path="./my_db"): Verileri diske (.npy + SQLite) yazar, oturumlar arasında korur.
    • EphemeralClient(): Testler ve geçici oturumlar için tamamen RAM'de çalışır.
  • Yüksek Hızlı Arama Optimizasyonları (v0.2.0):
    • argpartition Top-K: Mesafeleri $O(N \log N)$ yerine $O(N)$ sürede kısmi sıralar (3-10x sıralama hızı).
    • Normalizasyon Cache: Kosinüs benzerliğinde tekrar eden sorgularda %30-40 hız artışı.
    • IVFIndex (Inverted File Index): 100K+ vektörlük büyük veri setlerinde K-Means kümelemesi ile 10-50x hızlanma.
    • ScalarQuantizer: Vektörleri float32'den int8'e sıkıştırarak %75 bellek tasarrufu (4x az RAM).
    • Memory-Mapped Arrays: RAM'den büyük dev veri setlerini diskten doğrudan arayabilme.
  • Zengin Benzerlik Metrikleri: cosine, dot_product, euclidean.
  • Güçlü Metadata Filtreleme (where): $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin.
  • ChromaDB Uyumlu API: add(), upsert(), query(), get(), delete(), count().

📦 Kurulum

Projeyi sisteminize veya sanal ortamınıza (venv) kurmak için:

# Doğrudan kurulum:
pip install .

# Geliştirici (düzenlenebilir) modda kurulum:
pip install -e .

⚡ Hızlı Başlangıç (Quickstart)

import microvectordb

# 1. Kalıcı istemciyi başlatın
client = microvectordb.PersistentClient(path="./my_vectordb")

# 2. Koleksiyon oluşturun veya mevcut olanı açın
collection = client.get_or_create_collection(
    name="makaleler",
    dimension=3,       # İsteğe bağlı, ilk eklemede otomatik algılanır
    metric="cosine"    # "cosine", "dot_product" veya "euclidean"
)

# 3. Vektör, doküman ve metadata ekleyin
collection.add(
    ids=["doc1", "doc2", "doc3"],
    embeddings=[
        [0.9, 0.1, 0.0],
        [0.1, 0.8, 0.1],
        [0.0, 0.1, 0.9]
    ],
    documents=[
        "Yapay zeka ve LLM modelleri",
        "İlişkisel veritabanları mimarisi",
        "Web tasarımı ve kullanıcı arayüzü"
    ],
    metadatas=[
        {"kategori": "ai", "yazar": "Ahmet", "fiyat": 150},
        {"kategori": "veritabani", "yazar": "Mehmet", "fiyat": 200},
        {"kategori": "tasarim", "yazar": "Ayşe", "fiyat": 90}
    ]
)

# 4. Semantik arama yapın (Top-2 En Yakın Sonuç)
results = collection.query(
    query_embeddings=[[0.85, 0.15, 0.0]],
    n_results=2,
    where={"kategori": "ai"}  # İsteğe bağlı metadata filtresi
)

print("Bulunan ID'ler:", results.ids[0])
print("Dokümanlar:", results.documents[0])
print("Benzerlik Skorları:", results.similarities[0])

🔍 Gelişmiş Metadata Filtreleme (Where Syntax)

query(), get() ve delete() fonksiyonlarında gelişmiş filtreleme operatörlerini kullanabilirsiniz:

# Fiyatı 100 TL ve üzeri olanlar ($gte)
results = collection.query(query_embeddings=[...], where={"fiyat": {"$gte": 100}})

# Kategori listesinde 'ai' veya 'tasarim' olanlar ($in)
results = collection.query(query_embeddings=[...], where={"kategori": {"$in": ["ai", "tasarim"]}})

# Çoklu koşul (Hem kategori 'ai' hem fiyat >= 100)
results = collection.query(query_embeddings=[...], where={"kategori": "ai", "fiyat": {"$gte": 100}})

🚀 Büyük Veri & İleri Seviye Modüller (v0.2.0)

1. IVF Kümeleme İndeksi (100K+ Vektörde 10-50x Hız)

Büyük veri setlerinde yaklaşık en yakın komşu (ANN) araması yapmak için saf NumPy IVF indeksini kullanabilirsiniz:

from microvectordb import IVFIndex
import numpy as np

# 1. İndeksi oluşturun (64 küme, en yakın 4 kümede arama)
index = IVFIndex(n_clusters=64, nprobe=4)

# 2. Vektörlerle eğitin
vectors = np.random.randn(100000, 128).astype(np.float32)
index.train(vectors)

# 3. Işık hızında arayın
query = np.random.randn(128).astype(np.float32)
nearest_indices, distances = index.search(query, vectors, k=10)

2. Skalar Kuantizasyon (4 Kat Daha Az Bellek)

Vektörlerinizi 32-bit float yerine 8-bit integer'a sıkıştırın:

from microvectordb import ScalarQuantizer

sq = ScalarQuantizer()
sq.fit(vectors)

# float32 -> int8 sıkıştırma
compressed_vectors = sq.encode(vectors)
print(sq.memory_stats(n_vectors=100000, dimension=128))
# Tasarruf: %75 daha az RAM kullanımı!

📁 Proje Mimarisi

vector db/
├── pyproject.toml              # Modern pip yapılandırması
├── setup.py                    # setuptools yapılandırması
├── LICENSE                     # MIT Lisansı
├── README.md                   # Kapsamlı Dokümantasyon
├── requirements.txt            # Sadece numpy>=1.20
│
├── microvectordb/              # Çekirdek Kütüphane
│   ├── __init__.py             # Dışa aktarılan ana arayüz (v0.2.0)
│   ├── client.py               # PersistentClient & EphemeralClient
│   ├── collection.py           # Koleksiyon yönetimi, CRUD ve optimize Query
│   ├── distance.py             # Normalize cache'li Kosinüs, Dot ve Öklid çekirdekleri
│   ├── ivf_index.py            # Saf NumPy IVF Kümeleme İndeksi
│   ├── quantization.py         # Skalar int8 Kuantizasyon Motoru
│   ├── storage.py              # SQLite + .npy (Memory-Mapped destekli)
│   └── types.py                # Veri modelleri ve özel hata sınıfları
│
├── examples/                   # Çalışan Örnekler
│   ├── 01_quickstart.py        # Temel başlangıç
│   ├── 02_metadata_filter.py   # Gelişmiş filtreleme
│   ├── 03_rag_integration.py   # RAG Chatbot entegrasyonu
│   └── 04_benchmark.py         # QPS hız testi
│
├── tests/                      # Birim Testler (27/27 Geçti)
│   ├── test_microvectordb.py   # Temel işlev testleri
│   └── test_optimizations.py   # IVF, Kuantizasyon ve Cache testleri
│
└── kernels_experimental/       # Donanım Hızlandırma
    ├── avx2_dot_product.c      # AVX2 C/Assembly çekirdeği
    └── README.md               # Donanım hızlandırma rehberi

👨‍💻 Geliştirici & Yazar

Huneyn Kaya
GitHub: @Ahmet003-cod


📄 Lisans

Bu proje MIT Lisansı ile lisanslanmıştır. Ticari ve kişisel projelerinizde özgürce kullanabilir, değiştirebilir ve dağıtabilirsiniz.

Metadata

Release files for microvectordb 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for microvectordb 0.2.0
File Size Uploaded Provenance Actions
microvectordb-0.2.0.tar.gz 29.1 kB Without provenance Details for microvectordb-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for microvectordb 0.2.0
File Interpreter ABI Platform Actions
microvectordb-0.2.0-py3-none-any.whl Python 3 none any Details for microvectordb-0.2.0-py3-none-any.whl

Total release size: 52.4 kB

Release files / microvectordb-0.2.0.tar.gz

Download URL microvectordb-0.2.0.tar.gz
Size 29.1 kB
Tags Source
SHA-256 checksum
How to use checksums
6779dd6ef9b0e113c52917629587feee32991b124d0e782806d2662ff678cc61
BLAKE2b-256 checksum
How to use checksums
a3467d467af96134216b8c836761c759a9becc322bdbb16d097d0fa8a0a18b7a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Release files / microvectordb-0.2.0-py3-none-any.whl

Download URL microvectordb-0.2.0-py3-none-any.whl
Size 23.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
137c05eb7ddfc5c5bcc21439e2a99fb0ec75d4f7adc9292209a2d9809ab3f51b
BLAKE2b-256 checksum
How to use checksums
f773b30241610576d169b8e6ba8ba72f1e08642b3e51145f3ca9bed4846006f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.9

Security for microvectordb 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page