ChromaDB Nedir ve Nasıl Kullanılır?

Yapay zeka ve makine öğrenmesi uygulamalarının hızla yaygınlaştığı günümüzde, vektör veritabanları kritik bir altyapı bileşeni haline geldi. Bu yazıda, açık kaynaklı ve kullanımı kolay bir vektör veritabanı olan ChromaDB’yi detaylı şekilde inceleyeceğiz.

Vektör Veritabanı Nedir?

Geleneksel veritabanları, yapılandırılmış verileri tablolar ve satırlar halinde depolar. Ancak metin, görsel veya ses gibi yapılandırılmamış verileri anlamlandırmak için bu yaklaşım yetersiz kalır. İşte bu noktada vektör veritabanları devreye girer.

Vektör veritabanları, verileri yüksek boyutlu sayısal diziler (embedding) olarak depolar. Bu embeddingler, verilerin anlamsal temsillerini içerir ve benzerlik aramalarını son derece hızlı hale getirir. Örneğin “kedi” ve “köpek” kelimeleri vektör uzayında birbirine yakın konumlanırken, “araba” kelimesi bunlardan uzakta yer alır.

ChromaDB’ye Giriş

ChromaDB, özellikle LLM (Large Language Model) uygulamaları için tasarlanmış açık kaynaklı bir vektör veritabanıdır. 2022 yılında piyasaya sürülen ChromaDB, basitliği ve hızlı entegrasyonu sayesinde kısa sürede popülerlik kazandı.

Temel Özellikler

ChromaDB’nin öne çıkan özellikleri şunlardır: hafif ve hızlı kurulum, yerleşik embedding desteği, kalıcı ve geçici depolama seçenekleri, Python ve JavaScript SDK’ları, LangChain ve LlamaIndex ile kolay entegrasyon, ve Apache 2.0 lisansı altında tamamen ücretsiz kullanım.

Kurulum

Python ile Kurulum

ChromaDB’yi pip ile kolayca kurabilirsiniz:

pip install chromadb

Docker ile Kurulum

Docker kullanarak ChromaDB’yi sunucu modunda çalıştırabilirsiniz. Bu yaklaşım, özellikle production ortamları ve birden fazla istemciden erişim için önerilir. Benim bilgisayarımda 8000 portunda farklı bir servis çalıştığı için ben hostu 6330 olarak güncelledim.

Temel Kurulum:

docker pull chromadb/chroma
docker run -d -p 6330:8000 \
  -e CHROMA_SERVER_AUTHN_PROVIDER="" \
  chromadb/chroma
Code language: JavaScript (javascript)

Kalıcı Depolama ile Kurulum (Önerilen):

Verilerinizin container yeniden başlatıldığında kaybolmaması için volume kullanın:

docker run -d -p 6330:8000 \
  -e CHROMA_SERVER_AUTHN_PROVIDER="" \
  -v $(pwd)/chroma-data:/chroma/chroma \
  chromadb/chroma
Code language: JavaScript (javascript)

Windows için:

docker run -d -p 6330:8000 ^
  -e CHROMA_SERVER_AUTHN_PROVIDER="" ^
  -v %cd%/chroma-data:/chroma/chroma ^
  chromadb/chroma
Code language: JavaScript (javascript)

Docker Compose ile Kurulum:

Daha yönetilebilir bir yapı için docker-compose.yml oluşturun:

version: '3.8'
services:
  chromadb:
    image: chromadb/chroma
    container_name: chromadb
    ports:
      - "6330:8000"
    environment:
      - CHROMA_SERVER_AUTHN_PROVIDER=
    volumes:
      - ./chroma-data:/chroma/chroma
    restart: unless-stopped
Code language: JavaScript (javascript)

Başlatmak için:

docker-compose up -d

Önemli Notlar:

• CHROMA_SERVER_AUTHN_PROVIDER="" parametresi, authentication olmadan bağlanmayı sağlar
• ChromaDB container içinde 8000 portunda çalışır, bunu dışarıya 6330 olarak publish ediyoruz

Temel Kullanım

İstemci Oluşturma

ChromaDB’yi kullanmaya başlamak için önce bir istemci oluşturmanız gerekir:

import chromadb

# Geçici (in-memory) istemci
client = chromadb.Client()

# Kalıcı istemci (veriler diske kaydedilir)
client = chromadb.PersistentClient(path="/path/to/persist")

# HTTP istemci (Docker üzerinden sunucu modunda çalışırken)
client = chromadb.HttpClient(host="localhost", port=6330)
Code language: PHP (php)

Koleksiyon Oluşturma

Koleksiyonlar, ChromaDB’de verilerin organize edildiği temel birimlerdir:

# Yeni koleksiyon oluştur
collection = client.create_collection(name="makaleler")

# Varolan koleksiyonu al veya yoksa oluştur
collection = client.get_or_create_collection(name="makaleler")

# Koleksiyonu sil
client.delete_collection(name="makaleler")
Code language: PHP (php)

Veri Ekleme

Koleksiyona veri eklemek oldukça basittir:

collection.add(
    documents=[
        "Yapay zeka günlük hayatımızı dönüştürüyor.",
        "Makine öğrenmesi veri biliminin temel taşıdır.",
        "Derin öğrenme görüntü işlemede devrim yarattı."
    ],
    metadatas=[
        {"kaynak": "blog", "yil": 2024},
        {"kaynak": "makale", "yil": 2023},
        {"kaynak": "kitap", "yil": 2022}
    ],
    ids=["doc1", "doc2", "doc3"]
)
Code language: JavaScript (javascript)

ChromaDB, varsayılan olarak Sentence Transformers modelini kullanarak metinleri otomatik olarak embedding’e dönüştürür. İsterseniz kendi embedding’lerinizi de sağlayabilirsiniz:

collection.add(
    embeddings=[[0.1, 0.2, 0.3, ...], [0.4, 0.5, 0.6, ...]],
    metadatas=[{"kaynak": "ozel"}, {"kaynak": "ozel"}],
    ids=["emb1", "emb2"]
)
Code language: JavaScript (javascript)

Sorgulama

ChromaDB’nin en güçlü yanı semantik arama yapabilmesidir:

# Metin tabanlı sorgu
results = collection.query(
    query_texts=["yapay zeka uygulamaları"],
    n_results=2
)

print(results)
# Çıktı: En benzer 2 doküman ve meta verileri
Code language: PHP (php)

Metadata filtreleme ile sorguları daraltabilirsiniz:

results = collection.query(
    query_texts=["veri bilimi"],
    n_results=5,
    where={"yil": {"$gte": 2023}},  # 2023 ve sonrası
    where_document={"$contains": "öğrenme"}  # "öğrenme" içeren
)
Code language: PHP (php)

Veri Güncelleme ve Silme

# Güncelleme
collection.update(
    ids=["doc1"],
    documents=["Güncellenmiş içerik"],
    metadatas=[{"kaynak": "blog", "yil": 2024, "guncellendi": True}]
)

# Silme
collection.delete(ids=["doc2", "doc3"])

# Koşullu silme
collection.delete(where={"yil": {"$lt": 2020}})
Code language: PHP (php)

Özel Embedding Modelleri Kullanma

ChromaDB, farklı embedding modelleriyle çalışabilir:

from chromadb.utils import embedding_functions

# OpenAI embeddings
openai_ef = embedding_functions.OpenAIEmbeddingFunction(
    api_key="your-api-key",
    model_name="text-embedding-ada-002"
)

# HuggingFace modelleri
huggingface_ef = embedding_functions.HuggingFaceEmbeddingFunction(
    api_key="your-api-key",
    model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
)

# Koleksiyonu özel embedding fonksiyonu ile oluştur
collection = client.create_collection(
    name="turkce_makaleler",
    embedding_function=huggingface_ef
)
Code language: PHP (php)

Docker ile Tam Uygulama Örneği

Docker üzerinde ChromaDB çalıştırıp Python’dan bağlanmanın tam bir örneği:

1. Docker Container’ı Başlatın:

docker run -d -p 6330:8000 \
  -e CHROMA_SERVER_AUTHN_PROVIDER="" \
  -v $(pwd)/chroma-data:/chroma/chroma \
  --name chromadb \
  chromadb/chroma
Code language: JavaScript (javascript)

2. Container’ın Çalıştığını Kontrol Edin:

docker ps
# CONTAINER ID   IMAGE             PORTS                    NAMES
# e1b107c41199   chromadb/chroma   0.0.0.0:6330->8000/tcp   chromadb
Code language: PHP (php)

3. Python’dan Bağlanın ve Kullanın:

import chromadb

# Docker üzerindeki ChromaDB'ye bağlan
client = chromadb.HttpClient(host="localhost", port=6330)

# Koleksiyon oluştur
collection = client.get_or_create_collection(name="makaleler")

# Veri ekle
collection.add(
    documents=[
        "Yapay zeka günlük hayatımızı dönüştürüyor.",
        "Makine öğrenmesi veri biliminin temel taşıdır.",
        "Derin öğrenme görüntü işlemede devrim yarattı."
    ],
    metadatas=[
        {"kaynak": "blog", "yil": 2024},
        {"kaynak": "makale", "yil": 2023},
        {"kaynak": "kitap", "yil": 2022}
    ],
    ids=["doc1", "doc2", "doc3"]
)

print(f"Collection'a {collection.count()} belge eklendi")

# Semantik arama yap
results = collection.query(
    query_texts=["yapay zeka uygulamaları"],
    n_results=2
)

print("\nEn benzer dökümanlar:")
for i, doc in enumerate(results['documents'][0]):
    metadata = results['metadatas'][0][i]
    distance = results['distances'][0][i]
    print(f"\n{i+1}. Döküman:")
    print(f"   İçerik: {doc}")
    print(f"   Metadata: {metadata}")
    print(f"   Benzerlik Skoru: {1 - distance:.3f}")
Code language: PHP (php)

Çıktı:

Collection'a 3 belge eklendi

En benzer dökümanlar:

1. Döküman:
   İçerik: Yapay zeka günlük hayatımızı dönüştürüyor.
   Metadata: {'kaynak': 'blog', 'yil': 2024}
   Benzerlik Skoru: 0.892

2. Döküman:
   İçerik: Makine öğrenmesi veri biliminin temel taşıdır.
   Metadata: {'kaynak': 'makale', 'yil': 2023}
   Benzerlik Skoru: 0.785
Code language: PHP (php)

4. Container’ı Yönetme:

# Container'ı durdur
docker stop chromadb

# Container'ı başlat (verileriniz korunur)
docker start chromadb

# Container'ı sil (dikkat: veriler kaybolur, volume'deki veriler korunur)
docker rm chromadb

# Logları görüntüle
docker logs chromadb
Code language: PHP (php)

Pratik Örnek: Basit RAG Sistemi

Retrieval-Augmented Generation (RAG) sistemleri, LLM’lerin dış bilgi kaynaklarına erişmesini sağlar. İşte ChromaDB ile basit bir RAG örneği:

import chromadb
from openai import OpenAI

# LM Studio yapılandırması
LM_STUDIO_URL = "http://localhost:1234/v1"  # LM Studio'nun varsayılan adresi
LM_STUDIO_MODEL = "local-model"  # LM Studio'da yüklü model adı (değiştirin)

# ChromaDB istemcisi
chroma_client = chromadb.PersistentClient(path="./rag_db")
collection = chroma_client.get_or_create_collection("bilgi_bankasi")

# Bilgi bankasına döküman ekleme
documents = [
    "Python 1991 yılında Guido van Rossum tarafından geliştirildi.",
    "ChromaDB açık kaynaklı bir vektör veritabanıdır.",
    "LangChain, LLM uygulamaları geliştirmek için bir framework'tür.",
    "Transformer mimarisi 2017 yılında Google tarafından tanıtıldı."
]

collection.add(
    documents=documents,
    ids=[f"doc_{i}" for i in range(len(documents))]
)


# Soru-cevap fonksiyonu
def cevapla(soru: str) -> str:
    # İlgili dökümanları bul
    results = collection.query(
        query_texts=[soru],
        n_results=2
    )

    # Bağlam oluştur
    context = "\n".join(results["documents"][0])

    # LM Studio'ya bağlan (OpenAI uyumlu API)
    client = OpenAI(
        base_url=LM_STUDIO_URL,
        api_key="lm-studio"  # LM Studio API key gerektirmez, dummy değer
    )

    response = client.chat.completions.create(
        model=LM_STUDIO_MODEL,
        messages=[
            {"role": "system", "content": f"Şu bilgilere dayanarak soruyu cevapla:\n{context}"},
            {"role": "user", "content": soru}
        ]
    )

    return response.choices[0].message.content


# Kullanım
if __name__ == "__main__":
    print("RAG Sistemi başlatılıyor...")
    print(f"LM Studio URL: {LM_STUDIO_URL}")
    print(f"Model: {LM_STUDIO_MODEL}")
    print(f"Collection'da {collection.count()} belge var\n")

    # Test sorusu
    soru = "ChromaDB ne işe yarar?"
    print(f"Soru: {soru}")
    print("=" * 50)

    try:
        cevap = cevapla(soru)
        print(f"\nCevap:\n{cevap}")
    except Exception as e:
        print(f"\nHATA: {e}")
        print("\nLM Studio'nun çalıştığından emin olun:")
        print("1. LM Studio'yu açın")
        print("2. Bir model yükleyin")
        print("3. 'Local Server' sekmesinde 'Start Server' butonuna tıklayın")Code language: PHP (php)

ChromaDB vs Diğer Vektör Veritabanları

ChromaDB’nin rakipleriyle karşılaştırması şöyle özetlenebilir:

Pinecone tamamen yönetilen bir bulut servisi olup ölçeklenebilirlik konusunda güçlüdür, ancak ücretlidir. Weaviate GraphQL desteği ve hibrit arama özellikleriyle öne çıkar. Qdrant Rust ile yazılmış olup yüksek performans sunar ve filtreleme yetenekleri gelişmiştir. Milvus kurumsal düzeyde ölçeklenebilirlik sağlar ancak kurulumu daha karmaşıktır. ChromaDB ise basitlik ve hızlı prototipleme için idealdir, öğrenme eğrisi düşüktür ve küçük-orta ölçekli projeler için mükemmel bir seçenektir.

En İyi Uygulamalar

ChromaDB kullanırken dikkat edilmesi gereken bazı noktalar vardır. Embedding modeli seçiminde kullanım senaryonuza uygun bir model tercih etmelisiniz; Türkçe için çok dilli modeller daha iyi sonuç verir. Metadata tasarımı konusunda, filtreleme ihtiyaçlarınızı önceden planlayarak metadata yapısını buna göre oluşturmalısınız. Kalıcı depolama için production ortamında mutlaka PersistentClient kullanmalısınız. Batch işlemler açısından, büyük veri setlerini eklerken batch’ler halinde işlem yapmanız performansı artıracaktır. Son olarak, ID stratejisi belirleyerek anlamlı ve benzersiz ID’ler kullanmalı, böylece güncelleme ve silme işlemlerini kolaylaştırmalısınız.

Sonuç

ChromaDB, vektör veritabanı dünyasına giriş yapmak isteyenler için mükemmel bir başlangıç noktasıdır. Basit API’si, zengin özellik seti ve aktif topluluğu ile RAG sistemleri, semantik arama motorları ve öneri sistemleri gibi pek çok uygulama için ideal bir seçenektir.

Projenizin ölçeği büyüdükçe Qdrant veya Milvus gibi daha kurumsal çözümlere geçiş yapabilirsiniz, ancak prototipleme ve küçük-orta ölçekli projeler için ChromaDB fazlasıyla yeterlidir.