Siber Güvenlikte Yapay Zeka Uygulamaları

Siber güvenlik, günümüzde teknolojinin hızla gelişmesiyle birlikte önemli bir问题 haline gelmiştir. Siber saldırılara karşı korunmak için kullanılan geleneksel yöntemler, artık yeterli olmamaktadır. Bu nedenle, yapay zeka gibi ileri seviye teknik konulara başvurmak gerekmektedir. Yapay zeka, siber güvenlik alanında tehdit tespiti, güvenlik analizi ve korunma stratejileri gibi konularda önemli bir rol oynamaktadır.

Yapay zeka teknolojileri, büyük miktarda veri işleyebilir ve desen tanıma gibi teknikleri kullanarak siber tehditleri daha hızlı ve etkili bir şekilde tespit edebilir. Ayrıca, makine öğrenimi algoritmaları, siber güvenlik sistemlerini geliştirerek ve güncelleyerek daha etkili bir korunma sağlar. Bu reason, siber güvenlik uzmanlarının yapay zeka teknolojilerini kullanarak daha etkili bir savunma stratejisi geliştirmelerine yardımcı olur.

Ancak, yapay zeka teknolojilerinin siber güvenlik alanında kullanımı aynı zamanda güvenlik riskleri de oluşturabilir. Örneğin, sahte veri oluşturmak veya güvenlik sistemlerini manipüle etmek gibi amaçlarla kullanılan deepfake teknolojileri, siber güvenlik uzmanlarını zor durumda bırakabilir. Bu nedenle, siber güvenlik uzmanlarının yapay zeka teknolojilerini kullanırken aynı zamanda güvenlik risklerini de dikkate almaları gerekmektedir.

Sonuç olarak, siber güvenlik ve yapay zeka teknolojileri arasındaki ilişki, siber güvenlik alanında gelişmiş ve etkili çözümler sunmak için önemlidir. Siber güvenlik uzmanlarının yapay zeka teknolojilerini kullanarak güvenlik risklerini azaltmaları ve korunma stratejilerini geliştirmeleri必要dir. Bu reason, siber güvenlik alanındaki gelecekteki gelişmelerin yapay zeka teknolojilerine bağlı olacağı beklenmektedir.

Bu nedenle, siber güvenlik ve yapay zeka teknolojileri arasındaki ilişkiyi daha iyi anlamak ve gelişmiş çözümler sunmak için, siber güvenlik uzmanlarının yapay zeka teknolojilerini kullanırken aynı zamanda güvenlik risklerini de dikkate almaları gerekmektedir. Ayrıca, siber güvenlik alanında yapay zeka teknolojilerinin kullanımını geliştirmek ve güncellemek için sürekli araştırma ve geliştirme çalışmaları yapılması gerekmektedir.

Yerelde RAG Asistanı Kurulumu: Python, FAISS ve FastAPI ile Adım Adım

RAG nedir ve neden yerelde kurmalısınız?

RAG (Retrieval-Augmented Generation), bir büyük dil modelinin (LLM) yanıt üretmeden önce kendi veritabanınızdan veya belgeliklerinizden ilgili parçaları çekmesini sağlayan bir yaklaşım. Böylece model, güncel ve doğrulanabilir bilgiye dayanarak cevap verir, halüsinasyon oranı düşer ve alanınıza özgü bir asistan elde edersiniz. Bu yazıda, internete kapalı bir ortamda, Python, FAISS ve FastAPI kullanarak hızlı ve hafif bir RAG asistanını nasıl kurabileceğinizi adım adım anlatıyorum.

Mimari bileşenler ve gereksinimler

Minimal bir RAG sistemi dört temel bileşenden oluşur: metin ön işleme ve parçalara ayırma, embedding üretimi, vektör dizin (FAISS) ve yanıt üretici (LLM). Yerel kurulum için Python 3.10+ bir ortam, sentence-transformers ile çok dilli bir embedding modeli, faiss-cpu dizini ve HTTP üzerinden istek alıp yanıtlamak için FastAPI yeterli. İsterseniz yanıt üretici olarak Ollama üzerinden Llama 3 ailesi gibi bir yerel modeli kullanabilir, ya da sisteminize uygun bir başka LLM’i bağlayabilirsiniz.

Kurulum adımları: ortam, paketler ve veri hazırlığı

Önce izole bir Python sanal ortamı oluşturun ve temel paketleri kurun. Gerekli çekirdek paketler tipik olarak fastapi, uvicorn, faiss-cpu, sentence-transformers, pydantic ve metin işleme için regex/unidecode gibi küçük yardımcılar olur. Eğer yerel bir model kullanacaksanız Ollama’yı yükleyip örneğin “llama3” veya “mistral” gibi bir modeli indirin. Belgelerinizi tek bir klasörde toplayın; PDF, DOCX ve düz metinleri mümkünse metne dönüştürüp temizleyin. Tekrarlayan başlıklar, sayfa dipnotları ve tablolar metni kirlettiği için önceden sadeleştirme yapmak ileride kaliteyi ciddi biçimde artırır.

Embedding üretimi ve FAISS ile dizinleme

RAG’in çekirdeği, metni anlam uzayına taşıyan embedding’lerdir. Türkçe ağırlıklı bir kurulum için çok dilli bir model seçmek pratik olur. intfloat/multilingual-e5-base veya sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 iyi başlangıç seçenekleridir. Belgeleri 500–800 karakter aralığında, 50–100 karakter örtüşmeli parçalara bölerseniz hem hatırlama oranı hem bağlam bütünlüğü dengelenir. Her parçayı embedding modelinden geçirip bir vektör matrisi üretin; ardından FAISS’te IndexFlatIP (cosine benzeri iç çarpım) veya daha büyük veri için HNSW/IVF tabanlı bir dizin kurun. Dizin ve meta verileri (ör. belge kimliği, başlık, sayfa numarası) disk üzerinde saklayarak soğuk başlatma sürelerini azaltabilirsiniz.

Sorgu işleme hattı: geri getirme, yeniden sıralama ve yanıt üretimi

İstemci bir soru sorduğunda önce soruyu embedding modellerinden geçirip FAISS’e benzerlik araması yapın. İlk aşamada genellikle top-k=5–8 yeterlidir. Sonuçları kalite için hafif bir yeniden sıralama (re-rank) aşamasından geçirmek özellikle uzun ve benzer parçalarda fark yaratır; isterseniz küçük bir cross-encoder veya basit bir skor birleştirme (benzerlik + anahtar kelime çakışması) yaklaşımı kullanın. Son olarak en iyi 3–5 parçayı bir prompt şablonunda LLM’e vererek yanıt üretin. İyi bir şablon, modele “yalnızca verilen bağlama dayanması”, “kaynakları listelemesi” ve “emin olmadığı noktalarda netçe belirtmesi” yönünde talimatlar içerir. Bu aşamada streaming yanıt (chunk bazlı) hem his olarak daha hızlıdır hem de istemci tarafında kullanıcı deneyimini iyileştirir.

FastAPI ile uç noktalar ve basit bir API tasarımı

Sunucu tarafında iki temel uç nokta yeterlidir: /index ve /query. İlk uç nokta yeni belge eklemeyi, embedding ve dizine yazmayı üstlenir. İkincisi kullanıcı sorusunu alır, geri getirme ve yeniden sıralama yapar, LLM’den gelen yanıtı döndürür. Yanıta kaynak parçaların kimliklerini ve güven puanlarını dahil ederseniz istemci tarafında “bu cevabın kanıtı” şeritleri gösterebilirsiniz. Üretim ortamında CORS ayarlarını, basit bir oran sınırlama (rate limit) ve temel kimlik doğrulamayı eklemeyi unutmayın.

Performans, kalite ve bakım ipuçları

İlk indekslemeyi hızlandırmak için toplu gömme (batch) boyutunu donanımınıza göre ayarlayın; CPU’da 16–64 arası genelde güvenlidir. Dizin aramasında hız/kalite dengesini sağlamak üzere IVF ya da HNSW gibi yaklaşık yakın komşu (ANN) yapılarını deneyin ve geri getirme anında efSearch benzeri parametreleri kademeli artırın. Kalite için chunk boyutu ve örtüşmesini alanınıza göre yeniden ayarlayın; teknik dökümanlarda daha uzun, SSS türü içerikte ise daha kısa parçalar daha iyi sonuç verir. Ayrıca yinelenen metinleri, versiyonlanmış kopyaları ve tarih geçmişlerini indeks dışında tutmak, cevapların tekrara düşmesini engeller.

Düzenli bir değerlendirme seti oluşturun: 30–50 soruluk, doğru cevap ve kaynak eşleşmesi içeren bir küçük benchmark ile sürümler arasında regresyon olup olmadığını görebilirsiniz. Ölçüt olarak geri getirme için recall@k, cevap üretimi için ise doğruluk, faydalılık ve kaynak isabetini manuel etiketleme ile kontrol etmek etkilidir. Basit bir geri bildirim mekanizması (kullanıcı oylaması, “yanlıştı/düzelt” düğmesi) gerçek kullanımda iyileştirme fırsatlarını hızla ortaya çıkarır.

Güvenlik, gizlilik ve dağıtım

Yerel RAG sistemleri çoğu zaman hassas verilerle çalışır. Bu nedenle PII tespiti ve maskeleme, uçtan uca TLS, erişim loglarının minimal ve anonim tutulması önemlidir. Küçük bir ek katman olarak belirli sorgulara kural tabanlı filtre uygulayabilir, gizli etiketli içerikleri yanıt bağlamına girmeden önce temizleyebilirsiniz. Dağıtım için hafif bir konteyner imajı, tek bir health-check uç noktası ve kalıcı depolama bağlanmış bir FAISS dizini çoğu ekip için yeterli, ölçeklenebilir ve sürdürülebilir bir başlangıç sunar.

Sonuç

Python, FAISS ve FastAPI ile yerelde çalışan bir RAG asistanı kurmak sanıldığından daha erişilebilir. Doğru embedding modeli, düzenli bir parçalara ayırma stratejisi ve iyi tasarlanmış bir prompt ile, alanınıza özel, hızlı ve güvenilir bir bilgi asistanına sahip olursunuz. İlk sürümü basit tutun, kullanım verisi geldikçe yeniden sıralama ve değerlendirme mekanizmasını güçlendirin; böylece hem maliyeti hem karmaşıklığı kontrol altında tutarken yüksek kaliteli cevaplar üreten bir sistem inşa edebilirsiniz.

Docker ile Yerel LLM Kurulumu: Ollama + Open WebUI (GPU Hızlandırmalı Adım Adım Rehber)

Giriş

Yerel büyük dil modeli (LLM) çalıştırmak; gizliliği korumak, gecikmeyi düşürmek ve kullanım maliyetini kontrol etmek için harika bir yöntem. Son dönemde Ollama ve Open WebUI, Docker ile birlikte kullanıldığında zahmetsiz bir kurulum ve modern bir arayüz sunuyor. Bu rehberde, Ollama + Open WebUI ikilisini Docker üzerinde kurup, mümkünse GPU hızlandırma ile performansı nasıl katlayacağınızı adım adım anlatıyorum.

Neler Kuracağız?

Ollama, Llama 3, Mistral, Qwen gibi açık modelleri kolayca indirip çalıştırmanızı sağlar. Open WebUI ise sohbet, dosya yükleme, RAG eklentileri ve çoklu model yönetimi gibi özelliklerle modern bir ara yüz sunar. Docker sayesinde bu iki bileşen birbirinden izole, tekrar üretilebilir ve kolay güncellenebilir hale gelir.

Gereksinimler

- İşletim sistemi: Linux (Ubuntu 22.04+ önerilir), Windows 11 (WSL2 ile), veya macOS. CPU ile çalışır; GPU hızlandırma için donanım ve sürücü şarttır.

- Donanım: En az 16 GB RAM öneririm. 8B sınıfı modeller için 6–8 GB VRAM ile kuantize sürümler rahatlar; daha büyük modeller için 12 GB+ VRAM faydalıdır.

- Docker: Linux’ta Docker Engine + Docker Compose plugin; Windows/macOS’ta Docker Desktop.

Hızlı Başlangıç: Docker Compose ile Ollama + Open WebUI

Önce iki kalıcı disk alanı (volume) ve ortak bir ağ üzerinde iki servis ayağa kaldıracağız. Aşağıdaki dosyayı docker-compose.yml adıyla kaydedin:

version: "3.8"
services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ollama:/root/.ollama
    environment:
      - OLLAMA_KEEP_ALIVE=24h
    # GPU için not: Aşağıdaki 'GPU Hızlandırma' bölümüne bakın.

  openwebui:
    image: ghcr.io/open-webui/open-webui:latest
    container_name: openwebui
    restart: unless-stopped
    ports:
      - "3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
    volumes:
      - openwebui:/app/backend/data
    depends_on:
      - ollama

volumes:
  ollama:
  openwebui:

Komutlar: Bulunduğunuz klasörde docker compose up -d deyin. Ardından tarayıcıdan http://localhost:3000 adresine giderek Open WebUI arayüzünü açın.

Model İndirme ve Test

Open WebUI içinden model menüsünde “Pull” diyerek llama3:8b, qwen2:7b veya mistral:7b gibi kuantize seçenekleri indirebilirsiniz. Terminal tercih ederseniz:

docker exec -it ollama ollama pull llama3:8b
docker exec -it ollama ollama run llama3:8b "Merhaba, nasılsın?"

Her şey yolundaysa, modelden metin çıktısı almaya hemen başlayabilirsiniz.

GPU Hızlandırma (NVIDIA, AMD, Apple Silicon)

NVIDIA (Linux/WSL2): Sunucuda uyumlu sürücü ve nvidia-container-toolkit kurulu olmalı. Özet akış:

# Sürücü kurulumu sonrası:
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
 sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -fsSL https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
 sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Ardından Ollama’yı GPU ile başlatın:

docker run -d --name ollama --gpus all -p 11434:11434 \
  -v ollama:/root/.ollama ollama/ollama:latest

Compose kullanacaksanız, mevcut servisi durdurup bu komutla GPU’lu Ollama kapsayıcısını başlatabilir veya Docker Compose V2’de desteklenen GPU ayarlarını kullanabilirsiniz. Sürüm farklılıkları nedeniyle en sorunsuz yöntem genellikle yukarıdaki docker run satırıdır.

AMD ROCm (Linux): ROCm destekli kart ve sürücülerle Ollama GPU hızlandırma çalışır. Konteyner içinde ROCm erişimi için ROCm runtime ve /dev/kfd, /dev/dri cihazlarına erişim gerekebilir. Pratikte, GPU hızlandırma istiyorsanız ROCm tarafında host’a kurulu Ollama’yı, Open WebUI’yi ise Docker’da tutmak çoğu kullanıcı için daha az sorun çıkarır.

Apple Silicon (macOS): Ollama, Metal ile GPU hızlandırmayı yerel kurulumda otomatik kullanır. Docker konteyneri macOS’ta Metal’e doğrudan erişemeyeceğinden, Mac kullanıcılarına Ollama’yı host’a, Open WebUI’yi Docker’a kurmalarını öneririm. Open WebUI’nin OLLAMA_BASE_URL değerini host’taki Ollama adresine işaret edecek şekilde değiştirin.

Performans İpuçları

- Kuantizasyon: q4_k_m gibi kuantize modeller VRAM/RAM kullanımını dramatik biçimde azaltır. İlk denemelerde 7–8B modellerin kuantize sürümleri idealdir.

- Eşzamanlılık: OLLAMA_NUM_PARALLEL ve OLLAMA_BATCH gibi değişkenlerle paralellik ve batch boyutunu ayarlayabilirsiniz. Makinenizin sınırlarını test ederek en iyi kombinasyonu bulun.

- Disk I/O: Modeller büyük dosyalardır; SSD kullanımı ve yeterli boş alan önemlidir.

Open WebUI Özelliklerine Kısa Bakış

Open WebUI, konuşma geçmişi, istem (prompt) şablonları, çoklu model seçimi, rol tanımları ve RAG için belge yükleme gibi pratik özellikler sunar. Takım içinde kullanacaksanız, kullanıcı oturumları ve rol bazlı ayarlarla basit bir “self-hosted” sohbet platformu oluşturabilirsiniz.

Güvenlik ve Ağ

Bu kurulumu internetten erişilebilir hale getirecekseniz, ters proxy arkasında HTTPS zorunludur. Open WebUI’de dahili oturum açma mekanizmasını etkin tutun. Ollama API’sini (11434) doğrudan dış dünyaya açmayın; sadece iç ağda veya reverse proxy üzerinden eriştirin.

Sorun Giderme

- CUDA hatası: Sürücü ve nvidia-container-toolkit sürüm uyumsuz olabilir. nvidia-smi çıktısını kontrol edin, Docker daemon’ı yeniden başlatın.

- Model çekilemiyor: Ağ veya DNS sorunları; tekrar deneyin, mümkünse farklı bir ağa geçin.

- Open WebUI, Ollama’ya bağlanamıyor: OLLAMA_BASE_URL’in doğru olduğundan emin olun. Compose içinde servis adları (ollama) DNS ile çözülür; dışarıdan erişiliyorsa host IP’sini kullanın.

Sonuç

Docker ile Ollama + Open WebUI kurmak, yerel LLM deneyimini dakikalar içinde erişilebilir kılıyor. GPU hızlandırma ile yanıt süresi ve akıcılık ciddi ölçüde iyileşiyor. Küçük bir masaüstünde bile kuantize modellerle harika sonuçlar alabilir, belgelerinizi yerelde işleyebilir ve verinizi bulut servislerine göndermeden üretkenlik sağlayabilirsiniz. İhtiyacınıza göre 7–8B modellerle başlayıp, daha güçlü bir GPU’ya geçtiğinizde 13B/70B sınıfına doğru kademeli büyüyebilirsiniz.

Ollama, LangChain ve ChromaDB ile Yerel RAG Chatbotu Kurulum Rehberi

Özet

Bu rehberde, internet bağlantısına ihtiyaç duymadan çalışan bir RAG (Retrieval-Augmented Generation) chatbotunu yerelde nasıl kurabileceğinizi adım adım anlatıyorum. Kullandığımız bileşenler: Ollama (yerel LLM çalıştırma), LangChain (zincirleme ve orkestrasyon), ChromaDB (vektör veritabanı) ve yerel gömlemeler. Amaç; PDF, teknik doküman veya notlarınızı indeksleyip, LLM modeline belgelerden alıntı yaparak daha doğru yanıtlar ürettirmek.

Neden Yerel RAG?

RAG yaklaşımı, dil modelinin yanıtlarını belgelerinizle zenginleştirerek halüsinasyonları azaltır ve güncel bilgi sağlar. İşin “yerel” tarafı ise verinin bilgisayarınızdan çıkmaması, maliyetin düşük ve sistemin offline çalışabilmesi demek. Özellikle kurumsal dokümanlar, Ar-Ge notları veya gizli veriler için bu yaklaşım idealdir.

Gereksinimler

- 16 GB RAM önerilir (8 GB ile küçük modeller çalışabilir).
- macOS, Linux veya Windows (WSL destekli).
- Python 3.10+.
- Temel terminal bilgisi.
- Bazı modellerde GPU varsa hız artar (Metal/CUDA desteği).

Adım 1: Ollama ve Modelleri Kurma

Ollama, LLM modellerini tek komutla indirip yerelde çalıştırmanızı sağlar. Sisteminizde kurulu değilse resmi talimatları izleyerek kurun. Linux için tipik kurulum şu şekildedir:

curl -fsSL https://ollama.com/install.sh | sh
# Servisi başlat (Linux)
ollama serve

Şimdi bir sohbet modeli ve bir gömleme modeli çekelim. Küçük ve hızlı bir sohbet modeli için Llama 3.1 8B iyi bir başlangıçtır. Gömlemeler için “nomic-embed-text” yaygın ve hızlıdır:

ollama pull llama3.1:8b
ollama pull nomic-embed-text

Model adlarını ihtiyacınıza göre değiştirebilirsiniz (örn. mistral veya phi-3). Büyük modeller daha iyi kalite, daha fazla RAM/GPU kullanımı demektir. İlk denemelerde 7B–8B aralığı pratik bir seçimdir.

Adım 2: Python Ortamını Hazırlama

Proje klasörünüzü oluşturup sanal ortam açın ve gerekli paketleri yükleyin. LangChain ile Ollama’nın entegrasyonu için “langchain-ollama” paketini kullanalım. Vektör veritabanı için Chroma’yı ekleyelim.

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install langchain langchain-community langchain-ollama chromadb pydantic

Basit metin dosyalarıyla başlayacağız. PDF’ler için ekstra dönüştürücüler (örn. pypdf, unstructured) ekleyebilirsiniz.

Adım 3: Belgeleri İndeksleme ve RAG Zinciri

Aşağıdaki örnekte, “docs/” klasöründeki metin dosyalarını parçalara ayırıp Chroma’ya yükleyeceğiz. Ardından bir sorgu geldiğinde ilgili parçaları geri çağırıp modelin bağlamıyla birlikte yanıtlamasını sağlayacağız.

# rag_app.py
from langchain_community.document_loaders import DirectoryLoader, TextLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.vectorstores import Chroma
from langchain_ollama import ChatOllama, OllamaEmbeddings
from langchain.prompts import PromptTemplate
from langchain.schema import Document

# 1) Belgeleri yükle
loader = DirectoryLoader("docs", glob="**/*.txt", loader_cls=TextLoader, show_progress=True, use_multithreading=True)
docs = loader.load()

# 2) Parçala
splitter = RecursiveCharacterTextSplitter(chunk_size=800, chunk_overlap=120)
chunks = splitter.split_documents(docs)

# 3) Gömleme ve vektör veritabanı
embeddings = OllamaEmbeddings(model="nomic-embed-text")
vectordb = Chroma.from_documents(chunks, embedding=embeddings, collection_name="yerel_rag")

# 4) Retriever ve LLM
retriever = vectordb.as_retriever(search_kwargs={"k": 4})
llm = ChatOllama(model="llama3.1:8b", temperature=0.2)

# 5) İstem şablonu
template = """Aşağıdaki bağlamı KESİNLİKLE dikkate alarak soruyu yanıtla.
Bağlam:
{context}

Soru: {question}
Cevap: """
prompt = PromptTemplate.from_template(template)

def ask(question: str):
    # İlgili parçaları getir
    rel_docs = retriever.get_relevant_documents(question)
    context = "\n\n".join([d.page_content for d in rel_docs])
    # İstemi oluştur ve yanıtı al
    final_prompt = prompt.format(context=context, question=question)
    return llm.invoke(final_prompt).content

if __name__ == "__main__":
    print(ask("Bu belgelerde performans optimizasyonu için öneriler neler?"))

Uygulamayı çalıştırmadan önce “docs/” klasörüne örnek metinler koymayı unutmayın. Eğer PDF kullanacaksanız “pypdf” ile yükleyebilir veya metne dönüştürüp aynı adımları uygulayabilirsiniz.

Performans ve Kalite İpuçları

Gömleme modeli seçimi: “nomic-embed-text” hızlı ve yeterli doğruluk sağlıyor. Çok dilli dokümanlarda “bge-m3” gibi çok dilli gömlemelere bakabilirsiniz.

Parça boyutu ve örtüşme: chunk_size=600–1200, chunk_overlap=80–200 aralığı pratik. Metin türüne göre ayarlayın. Uzun form teknik belgelerde daha büyük parçalar, soru-cevap notlarında daha küçük parçalar işe yarar.

Arama türü: Chroma varsayılan kosinüs benzerliği ile iyi çalışır. Farklı “k” değerlerini deneyin. Çok sayıda belge olduğunda metadata filtreleri eklemek doğruluğu artırır.

İstem mühendisliği: Şablona “Cevabın sonunda kaynak alıntısı ver” gibi kurallar eklemek kullanıcı güvenini artırır. Yanıt formatını (madde işaretleri, kısa özet + detaylar) açıkça belirtin.

Model ve nicemleme: Ollama üzerinde “:q4_0” gibi nicemlenmiş sürümler daha az RAM kullanır ve hızlanır; kalite az da olsa düşebilir. GPU mevcutsa GPU kullanımını etkinleştirmek büyük fark yaratır.

Güvenlik ve Gizlilik

Yerel RAG’in en önemli avantajı verilerin cihazınızda kalmasıdır. Ancak indeks dizininizi şifreli disk üzerinde tutmak, yedekleri güvenli almak ve işletim sistemi düzeyinde erişim izinlerini doğru ayarlamak gerekir. Paylaşılan makinelerde servis portlarını dışa açmayın.

Sorun Giderme

- “Connection refused”: Ollama servisi çalışmıyor olabilir. “ollama serve” komutunu kontrol edin.
- “CUDA/Metal hataları”: Sürücü/güncelleme gerekli olabilir. Geçici olarak CPU ile deneyin.
- “Bellek yetersiz”: Daha küçük model deneyin (ör. 3B–7B) veya nicemlenmiş varyant çekin.
- “Cevaplar ilgisiz”: chunk_size ve k değerlerini ayarlayın, gömleme modelini değiştirin, istemi netleştirin.

Sonuç

Bu kurulumla, Ollama + LangChain + Chroma üçlüsü sayesinde tamamen yerel çalışan bir RAG chatbotu elde ettiniz. Küçük boyutlu bir modelle bile belgeye dayalı arama ve yanıt üretiminde tatmin edici sonuçlar alabilirsiniz. Zamanla daha iyi gömlemeler, gelişmiş istem şablonları ve daha hızlı modellerle doğruluğu ve hızı artırabilirsiniz. Sonraki adım olarak bir REST API ekleyip (ör. FastAPI) web arayüzü veya Slack/Teams entegrasyonu kurmayı düşünebilirsiniz.

WebGPU ile Tarayıcıda Makine Öğrenimi: ONNX Runtime Web ile Görsel Sınıflandırma (Adım Adım)

Giriş

WebGPU, modern tarayıcılarda GPU gücünden standart ve güvenli bir şekilde yararlanmayı sağlayan yeni bir web standardı. Bu yazıda, ONNX Runtime Web ve WebGPU kullanarak tarayıcı içinde tamamen istemci tarafında çalışan bir görsel sınıflandırma uygulamasını adım adım kuracağız. Sunucuya veri göndermeden, gizliliğe saygılı ve düşük gecikmeli bir makine öğrenimi deneyimi elde edeceğiz. Bu yaklaşım, SEO açısından da kıymetli; zira “tarayıcıda makine öğrenimi”, “WebGPU”, “ONNX Runtime Web”, “görsel sınıflandırma” gibi anahtar kelimelerle teknik kitlelere doğrudan hitap ediyor.

Ön Koşullar

- Güncel bir tarayıcı: Chrome 113+ sürümlerinde WebGPU masaüstünde varsayılan olarak açıktır. Safari’de ve Firefox’ta destek durumu değişebilir; deneysel bayraklar gerekebilir. Mobilde destek kısmi durumdadır.

- Node.js 18+ (geliştirme sunucusu ve paket yönetimi için)

- Temel HTML/JS bilgisi

Proje Kurulumu

1) Vite ile boş bir proje oluşturun:

npm create vite@latest webgpu-ml -- --template vanilla
cd webgpu-ml
npm install

2) ONNX Runtime Web paketini ekleyin:

npm i onnxruntime-web

3) Basit bir dosya yapısı hazırlayın: index.html, main.js ve bir models/ klasörü. Örnek olarak mobilenetv2.onnx gibi 224x224 giriş alan bir sınıflandırma modelini models/ altına yerleştirin. ONNX model arşivlerinden (örn. ResNet, MobileNet) hafif bir model tercih edin.

index.html İskeleti

Aşağıdaki minimal HTML, bir görsel yükleme alanı ve sonuçları göstermek için basit bir arayüz içerir.

<!doctype html>
<html lang="tr">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>WebGPU ile Görsel Sınıflandırma</title>
  </head>
  <body>
    <h1>WebGPU + ONNX Runtime Web</h1>
    <input type="file" id="file" accept="image/*" />
    <button id="predict">Sınıflandır</button>
    <div id="status">Hazır</div>
    <div id="result"></div>
    <canvas id="canvas" width="224" height="224" style="display:none"></canvas>
    <script type="module" src="/main.js"></script>
  </body>
</html>

WebGPU ve ONNX Runtime Web ile Çalıştırma

Aşağıdaki kodda, tarayıcıda WebGPU desteği kontrol edilir, ONNX modeli yüklenir, görsel 224x224 boyutuna ölçeklenir ve ImageNet ortalama/standart sapma değerleri ile normalize edilerek tensöre dönüştürülür. Ardından model çıkarımı yapılır ve en yüksek olasılıklı sınıf ekrana yazdırılır.

// main.js
import * as ort from 'onnxruntime-web/webgpu';

const statusEl = document.getElementById('status');
const resultEl = document.getElementById('result');
const fileInput = document.getElementById('file');
const predictBtn = document.getElementById('predict');
const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d');

let session;

// WebGPU desteğini kontrol edin
if (!('gpu' in navigator)) {
  statusEl.textContent = 'WebGPU desteklenmiyor. Varsayılan WASM ile deneyin.';
}

// Modeli başlat
async function initModel() {
  statusEl.textContent = 'Model yükleniyor...';
  // Fallback ile: önce WebGPU, olmazsa WASM
  session = await ort.InferenceSession.create('/models/mobilenetv2.onnx', {
    executionProviders: ['webgpu', 'wasm']
  });
  statusEl.textContent = 'Model yüklendi.';
}

function imageToTensor(img) {
  const size = 224;
  ctx.clearRect(0, 0, size, size);
  // Görseli 224x224'e çiz
  ctx.drawImage(img, 0, 0, size, size);
  const { data } = ctx.getImageData(0, 0, size, size);

  // NHWC(RGBA) -> NCHW, normalize [0,1], ImageNet mean/std
  const mean = [0.485, 0.456, 0.406];
  const std = [0.229, 0.224, 0.225];

  const input = new Float32Array(1 * 3 * size * size);
  let idx = 0;
  for (let y = 0; y < size; y++) {
    for (let x = 0; x < size; x++) {
      const i = (y * size + x) * 4;
      const r = data[i] / 255;
      const g = data[i + 1] / 255;
      const b = data[i + 2] / 255;
      // Kanal sırası: [R plane][G plane][B plane]
      input[0 * size * size + idx] = (r - mean[0]) / std[0];
      input[1 * size * size + idx] = (g - mean[1]) / std[1];
      input[2 * size * size + idx] = (b - mean[2]) / std[2];
      idx++;
    }
  }
  return new ort.Tensor('float32', input, [1, 3, size, size]);
}

function softmax(arr) {
  const max = Math.max(...arr);
  const exps = arr.map(v => Math.exp(v - max));
  const sum = exps.reduce((a, b) => a + b, 0);
  return exps.map(v => v / sum);
}

async function runInference(img) {
  if (!session) await initModel();

  statusEl.textContent = 'Çıkarım yapılıyor...';
  const tensor = imageToTensor(img);

  const inputName = session.inputNames[0];
  const output = await session.run({ [inputName]: tensor });

  const outputName = session.outputNames[0];
  const logits = Array.from(output[outputName].data);
  const probs = softmax(logits);

  // En yüksek olasılıklı sınıfı bul
  let bestIdx = 0;
  for (let i = 1; i < probs.length; i++) {
    if (probs[i] > probs[bestIdx]) bestIdx = i;
  }

  // Label dosyanız varsa fetch edip eşleyebilirsiniz (örn. imagenet-labels.txt)
  resultEl.textContent = `Tahmin sınıf index: ${bestIdx}, olasılık: ${(probs[bestIdx] * 100).toFixed(2)}%`;
  statusEl.textContent = 'Bitti';
}

// Görsel seç ve çıkarım başlat
predictBtn.addEventListener('click', async () => {
  const file = fileInput.files?.[0];
  if (!file) {
    alert('Lütfen bir görsel seçin.');
    return;
  }
  const img = new Image();
  img.onload = () => runInference(img);
  img.src = URL.createObjectURL(file);
});

// Sayfa yüklenince modeli hazırlayın (isteğe bağlı)
initModel().catch(err => {
  console.error(err);
  statusEl.textContent = 'Model yüklenirken hata oluştu.';
});

Performans İpuçları

- WebGPU genellikle WASM/WASM SIMD’e göre daha yüksek paralellik ve throughput sunar. Ancak küçük modellerde fark az olabilir. Model boyutu ve katman türleri sonucu etkiler.

- Modeli mümkün olduğunca küçük seçin (MobileNet, EfficientNet-Lite gibi). Büyük modeller hem ağdan indirmede hem de bellek kullanımında sorun çıkarabilir.

- İlk çıkarım (warm-up) genellikle daha yavaştır. Gerçek kullanıcı deneyimi için ikinci/üçüncü çıkarımı da ölçün.

- Vite yerine üretime alırken kodu küçültün ve model dosyasını CDN veya HTTP/2 ile hızlı sunun. Cache-Control başlıklarını doğru ayarlayın.

Sorun Giderme

- “WebGPU desteklenmiyor”: Tarayıcınızı güncelleyin veya chrome://flags içinde WebGPU ile ilgili bayrakları kontrol edin. Kurumsal politikalar GPU erişimini kısıtlayabilir.

- “Model giriş/çıkış adı uyuşmuyor” hatası: session.inputNames ve session.outputNames üzerinden gerçek isimleri alın, manuel isim yazmayın.

- Görselin renkleri veya sonuçlar beklenenden farklıysa, normalize adımlarını (mean/std) ve kanal sırasını (NCHW vs NHWC) model dokümantasyonuna göre doğrulayın.

- Bazı platformlarda WebGPU var ama belirli doku formatları kısıtlı olabilir. Fallback olarak WASM sağlayıcısını eklediğinizden emin olun.

Sonuç

WebGPU ve ONNX Runtime Web ile tarayıcıda makine öğrenimi artık gerçek bir seçenek. İstemci tarafında görsel sınıflandırma gibi görevlerde gizlilik, düşük gecikme ve çevrimdışı çalışma avantajları sunar. Bu rehberle temel bir iskelet kurdunuz; bundan sonra model çeşitliliğini artırabilir, etiket dosyaları ile daha anlaşılır sonuçlar gösterebilir, hatta Web Workers kullanarak arayüzü bloklamadan çoklu çıkarım senaryolarını deneyebilirsiniz. Kısacası, WebGPU sayesinde modern web uygulamaları, yapay zeka kabiliyetlerini kullanıcıya en yakın yerde, doğrudan tarayıcıda sunabiliyor.

pgvector ile RAG Uygulaması: Docker Compose ile PostgreSQL 16 ve Basit Semantik Arama API’si

RAG (Retrieval-Augmented Generation), büyük dil modellerinin (LLM) güncel ve alanınıza özgü verilerle daha doğru yanıtlar üretmesini sağlar. Bu yaklaşımda, soruyu bir vektöre dönüştürür, vektör veritabanından benzer içerikleri geri çağırır ve modeli bu bağlamla beslersiniz. Özel bir vektör veritabanına ihtiyaç duymadan, PostgreSQL 16 + pgvector ile etkili bir semantik arama katmanı kurmak mümkündür. Bu yazıda, Docker Compose ile PostgreSQL’i ayağa kaldıracak, pgvector eklentisini etkinleştirecek ve basit bir API üzerinden semantik arama yapabileceğiz.

Neden PostgreSQL + pgvector? PostgreSQL hâlihazırda üretim ortamlarında yaygın, güvenilir ve güçlü bir ilişkisel veritabanıdır. pgvector eklentisi, vektör tipini, benzerlik metriklerini (cosine, L2, inner product) ve ivfflat/HNSW benzeri indeksleme stratejilerini destekler. Küçük ve orta ölçekli RAG projeleri için tek bir veritabanı üzerinde hem ilişkisel hem de vektörel sorgular yürütmek operasyonel anlamda sade ve maliyet-etkindir.

Önkoşullar: Makinenizde Docker ve Docker Compose kurulu olmalı. Embedding üretimi için OpenAI hesabı (veya yerelde Ollama gibi bir çözüm) işinizi kolaylaştırır. Örneklerde OpenAI’nin “text-embedding-3-small” (1536 boyut) modelini referans vereceğiz; yerel seçenek kullanacaksanız embedding boyutunu ona göre ayarlamalısınız.

Adım 1: Docker Compose ile PostgreSQL 16 ve pgvector
Basit bir docker-compose.yml dosyası oluşturun ve şu servisi tanımlayın:
version: "3.9"
services:
  db:
    image: pgvector/pgvector:pg16
    environment:
      - POSTGRES_USER=rag
      - POSTGRES_PASSWORD=ragpass
      - POSTGRES_DB=ragdb
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:
Dosyayı kaydedip docker compose up -d komutunu çalıştırın. Bu imaj, pgvector eklentisi ile birlikte gelir.

Adım 2: pgvector’ü etkinleştirmek ve şema hazırlığı
Veritabanına bağlanın: psql -h localhost -U rag -d ragdb ve şu komutları çalıştırın:
CREATE EXTENSION IF NOT EXISTS vector;
OpenAI’nin “text-embedding-3-small” boyutuna uygun bir tablo oluşturun:
CREATE TABLE docs (
  id BIGSERIAL PRIMARY KEY,
  content TEXT NOT NULL,
  embedding vector(1536)
);
Arama performansı için ivfflat indeksini kurun (cosine metrik popüler bir tercih):
CREATE INDEX ON docs USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
İndeksin etkili çalışması için tabloyu analiz edin: ANALYZE docs;

Adım 3: Embedding üretimi ve veri ekleme
Örnek içerikler ekleyelim: ürün açıklamaları, SSS, teknik notlar vs. Python ile kısa bir betik yazabilirsiniz. OpenAI için mantık şu şekildedir:
- Metni al, client.embeddings.create(model="text-embedding-3-small", input=metin) ile vektörü üret.
- Vektörü PostgreSQL’e parametreli bir sorgu ile yaz: INSERT INTO docs(content, embedding) VALUES ($1, $2).
Yerel alternatif isterseniz, Ollama’da ollama pull nomic-embed-text diyerek bir embedding modeli çekebilir, http://localhost:11434/api/embeddings üzerinden benzer bir akış kurabilirsiniz. Dikkat: embedding boyutunu (ör. 768) tablo şemanızla tutarlı yapın.

Adım 4: Semantik arama sorgusu
Kullanıcı sorgusunu da embedding’e çevirin ve ORDER BY embedding <=> $1 ifadesiyle benzerliğe göre sıralayın. Örnek bir SQL:
WITH q AS (SELECT $1::vector AS v)
SELECT id, content
FROM docs, q
ORDER BY docs.embedding <=> q.v
LIMIT 5;
Burada <=>, pgvector’ün benzerlik operatörüdür (cosine için mesafe). Bu sonuçları LLM’e bağlam olarak verip RAG yanıtı oluşturabilirsiniz.

Adım 5: Basit bir API ile uçtan uca akış
Hızlı bir prototip için Python FastAPI idealdir. Akış şöyledir:
1) POST /search: query alır, embedding üretir, PostgreSQL’den top-k döner.
2) POST /ask: query ve top-k bağlamı alır, seçtiğiniz LLM (OpenAI veya yerel) ile yanıt üretir.
Üretimde, sonuçları önbelleğe almak (ör. Redis), indeks lists değerini veri büyüklüğüne göre artırmak ve maintenance_work_mem, shared_buffers gibi PostgreSQL ayarlarını optimize etmek önemlidir.

İleri seviye ipuçları
- HNSW: pgvector 0.7+ sürümlerinde HNSW desteği bulunur; okuma gecikmesini düşürür, ancak indexleme süresi ve bellek kullanımı artar. Benchmark yapmadan geçiş yapmayın.
- Normalize embedding: Cosine benzerliğinde vektörleri normalize etmek sonuç tutarlılığını artırabilir.
- Chunking ve metadata: Belgeleri 300–800 token aralığında parçalara bölün. Kaynak, tarih, başlık gibi metadata alanlarını tabloya ekleyin ve sonuçlarda gösterin.
- Güncelleme stratejisi: Sık değişen veriler için upsert akışı oluşturun; embedding’i yalnızca içerik değiştiğinde güncelleyin.
- Güvenlik: Üretimde veritabanını dışarıya kapatın, SSL kullanın, sıkı rol ve politika tanımları yapın.

Sonuç
PostgreSQL 16 ve pgvector ile, ek bir servis karmaşıklığına girmeden güçlü bir semantik arama ve RAG katmanı kurabilirsiniz. Docker Compose yapılandırması hızlı kurulum sağlar; embedding üretimi için OpenAI veya yerel modelleri kullanabilirsiniz. Üzerine basit bir API ekleyerek hem prototip hem de üretim öncesi pilot projelerinizi hızla hayata geçirmeniz mümkün. Doğru indeks, boyut ve ayarlarla, pgvector küçük-orta ölçekli prodüksiyon yüklerini rahatlıkla karşılayacaktır.

Docker ile PostgreSQL + pgvector Kurulumu ve Semantik Arama Rehberi (2025)

pgvector nedir ve neden önemlidir?

Semantik arama, metnin anlamını kavrayarak benzer içerikleri bulmayı hedefleyen modern bir yaklaşım. Bu yaklaşımın kalbinde ise metinleri yüksek boyutlu sayısal vektörlere dönüştürmek ve bu vektörler arasında en benzer olanları hızlıca bulmak yer alır. pgvector, PostgreSQL üzerinde vektör veri tipini ve benzerlik aramalarını destekleyen bir eklenti olarak, ek bir vektör veritabanı yönetmek zorunda kalmadan güçlü semantik arama çözümleri geliştirmenize imkan tanır.

Bu rehberde, Docker kullanarak PostgreSQL 16 + pgvector kurulumunu gerçekleştirecek, örnek bir şema ile HNSW veya IVFFlat indeksleri üzerinden hızlı arama yapacak ve üretim ortamı için ayar önerileri sunacağız. RAG (Retrieval Augmented Generation) gibi yapay zekâ uygulamalarında performanslı ve ölçeklenebilir bir temel oluşturmayı hedefliyoruz.

Önkoşullar

- Docker ve Docker Compose yüklü bir makine (Linux, macOS veya Windows).

- Terminal/komut satırına erişim ve temel PostgreSQL bilgisi.

- Embedding üretmek için bir model (ör. Sentence-Transformers veya bir LLM sağlayıcısı). Bu rehberde örnek olarak sabit vektörlerle ilerleyeceğiz; gerçek projede modelden gelen boyutlarla eşleşecek şekilde tabloyu kurmalısınız.

Kurulum: Docker ile PostgreSQL + pgvector

Hızlı başlamak için resmi pgvector imajını kullanacağız. Aşağıdaki komut PostgreSQL 16 ve pgvector eklentisini içeren bir konteyneri ayağa kaldırır:

docker run --name pgvector -e POSTGRES_PASSWORD=secret -p 5432:5432 -d pgvector/pgvector:pg16

Veritabanına bağlanmak için psql kullanabilirsiniz:

psql -h localhost -U postgres

Bağlandıktan sonra eklentiyi etkinleştirin:

CREATE EXTENSION IF NOT EXISTS vector;

Şema tasarımı ve örnek veri

Gerçekte embedding boyutunuz seçtiğiniz modele göre değişir (ör. 384, 768, 1024). Anlatımı basitleştirmek adına burada 3 boyutlu bir örnek kullanacağız; siz kendi projelerinizde doğru boyutu tablo tanımında belirtin.

CREATE TABLE docs (id BIGSERIAL PRIMARY KEY, title TEXT, content TEXT, embedding VECTOR(3));

Benzerlik aramalarını hızlandırmak için iki popüler indeks tipinden birini ekleyebilirsiniz. HNSW genel olarak yüksek doğruluk ve iyi performans sunarken, IVFFlat kurulum ve ayar açısından daha basittir.

-- HNSW + Kosinüs uzaklığı

CREATE INDEX docs_embedding_hnsw ON docs USING hnsw (embedding vector_cosine_ops);

Örnek verileri ekleyelim:

INSERT INTO docs (title, content, embedding) VALUES

('PostgreSQL Rehberi', 'Indeks, performans ve yedekleme ipuçları.', '[0.10, 0.85, 0.20]'),

('Vektör Veritabanları', 'pgvector, HNSW ve benzerlik metrikleri.', '[0.12, 0.80, 0.25]'),

('Docker ile Kurulum', 'Kapsayıcı tabanlı veritabanı dağıtımı.', '[0.60, 0.10, 0.30]');

Semantik arama sorguları

Kullanacağınız benzerlik ölçütü projeye göre değişir. Çoğu metin embedding’inde kosinüs uzaklığı iyi sonuç verir. Kosinüs mesafesi için pgvector’da <=> operatörü kullanılır; mesafe ne kadar düşükse benzerlik o kadar yüksektir. Dilerseniz skor olarak benzerliği görmek için 1 - mesafe hesaplayabilirsiniz.

-- Sorgu vektörü örnek: '[0.12, 0.88, 0.33]'

SELECT id, title, 1 - (embedding <=> '[0.12, 0.88, 0.33]') AS cosine_similarity

FROM docs

ORDER BY embedding <=> '[0.12, 0.88, 0.33]'

LIMIT 5;

IVFFlat indeksi tercih edecekseniz, eğitim gerektirir ve arama-doğruluk dengesi için probes parametresi önemlidir:

CREATE INDEX docs_embedding_ivf ON docs USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

SET ivfflat.probes = 10;

Üretim için en iyi uygulamalar

- Boyut tutarlılığı: Tablo tanımındaki vektör boyutu embedding modeli ile birebir aynı olmalı. Modeli değiştirirseniz yeni bir alan veya tablo kullanın.

- Normalizasyon: Kosinüs benzerliği kullanırken embedding’leri uygulama katmanında birim uzunluğa normalize etmek sonuçların tutarlılığını artırır.

- Toplu yüklemeler: Büyük veri yüklerken indeksleri en son oluşturun ve synchronous_commit = off ile yüklemeyi hızlandırmayı değerlendirin (kritik verilerde dikkatli olun).

- Bakım: Veri dağılımı değiştikçe ANALYZE ve gerekirse REINDEX yapın. IVFFlat için doğru lists ve probes değerlerini veri setinizde deneyerek belirleyin.

- Bellek ve önbellek: PostgreSQL yapılandırmasında genel öneriler: shared_buffers RAM’in %25’i civarı, effective_cache_size %50–75, indeks oluştururken maintenance_work_mem’i yüksek tutun, sorgu başına work_mem değerini gözlemleyerek ayarlayın.

- Yedekleme ve göç: Şema değişiklikleri ve büyük indeksler söz konusu olduğunda pg_dump ve pg_restore stratejinizi test edin; depolama IOPS kapasitesini göz önünde bulundurun.

RAG ve uygulama entegrasyonu

RAG mimarisinde tipik akış, sorgu metnini embedding’e çevirip PostgreSQL’de en benzer içerikleri bulmak ve bu içerikleri LLM’e bağlam olarak sunmaktır. Uygulamada sıklıkla yapılan optimizasyon, hem title hem de content alanlarını birleştirip tek embedding üretmek ya da çok alanlı senaryoda iki ayrı embedding sütunu ile ağırlıklı birleştirme yapmaktır. İhtiyaçlarınıza göre HNSW ile yüksek doğrulukta, IVFFlat ile daha düşük gecikmede cevaplar elde edebilirsiniz.

Sonuç olarak, pgvector ile PostgreSQL’i bir vektör veritabanına dönüştürmek hem yönetim yükünü azaltır hem de üretim tecrübesi kanıtlanmış bir ekosistemden yararlanmanızı sağlar. Doğru indeks, metrik ve donanım ayarlarıyla semantik arama ve RAG uygulamalarınızı güvenle ölçekleyebilirsiniz.

PostgreSQL + pgvector ile Semantik Arama ve RAG: Kurulum, İndeks ve Performans Rehberi

Giriş

Semantik arama ve RAG (Retrieval-Augmented Generation) uygulamaları, yalnızca bir metnin kelimelerine değil, anlamına göre sonuç döndürerek daha isabetli yanıtlar verebiliyor. Bu yaklaşımı uygulamak için vektör veritabanı şart. Pek çok ekip, halihazırda kullandıkları PostgreSQL üzerinde pgvector eklentisiyle bu ihtiyacı karşılıyor. Bu yazıda, PostgreSQL + pgvector kombinasyonuyla semantik arama altyapısını nasıl kuracağınızı, indekslemeyi nasıl yapacağınızı ve performansı nasıl optimize edeceğinizi adım adım anlatıyorum.

Neden pgvector?

Pgvector, PostgreSQL’e vektör veri tipi (vector) ve benzerlik aramaları (cosine, L2, inner product) kazandırır. Ayrı bir veritabanı yönetmek yerine tek bir Postgres kümesi üzerinde hem ilişkisel verilerinizi hem de embedding’lerinizi saklayabilirsiniz. Bu, devops maliyetini azaltırken güçlü ACID garantileri ve yedekleme stratejilerinden de yararlanmanızı sağlar.

Önkoşullar

PostgreSQL 14+ önerilir; performans ve özellikler için 15/16 daha iyi. Sunucuda en az 4 CPU, 8 GB RAM başlamak için konfor sağlar. Ayrıca embedding üretmek için bir model (örneğin OpenAI text-embedding-3-small, Instructor, E5-large veya yerel bir model) gereklidir.

Kurulum (Docker ve Yerel)

Docker ile hızlı kurulum: Resmi Postgres imajı yerine pgvector içeren bir imaj kullanabilirsiniz. Örnek:

docker run -d --name pg -e POSTGRES_PASSWORD=secret -p 5432:5432 ankane/pgvector

Yerel kurulum (Ubuntu/Debian): Paket yöneticinizde pgvector olmayabilir. Kaynaktan kurulum tipik akış:

sudo apt-get update && sudo apt-get install -y postgresql postgresql-server-dev-all git make gcc

git clone https://github.com/pgvector/pgvector.git && cd pgvector && make && sudo make install

Veritabanını Hazırlama

Postgres’e bağlandıktan sonra eklentiyi etkinleştirin ve şemanızı oluşturun:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE documents (id bigserial PRIMARY KEY, title text, body text, embedding vector(1536));

Burada vector(1536) embedding boyutunu temsil ediyor. Kullanacağınız modele göre bu değeri değiştirin (örn. 768, 1024, 1536).

Embedding Üretme ve Veri Ekleme

Embedding’leri uygulama katmanında üretip Postgres’e yazmak en yaygın yaklaşım. Basit akış: metni temizle, cümlelere/segmentlere böl, embedding modeline gönder, sonuç vektörünü tabloya ekle.

Örnek bir ekleme akışı:

INSERT INTO documents (title, body, embedding) VALUES ('KVKK Özeti', 'Kişisel verilerin korunması...', '[0.012, -0.034, ...]');

Not: pgvector, köşeli parantezle vektör alır. Uygulama dilinizde (Python/Node/Go) embedding dizisini string’e çevirip eklemek pratik bir yöntemdir.

Benzerlik İndeksleri: IVFFlat ve HNSW

Büyük veri kümelerinde ham tarama yavaştır. Bu nedenle IVFFlat veya HNSW indeksleri kullanılır. IVFFlat için önce tabloyu kabaca küme merkezlerine göre “eğitmek” gerekir.

-- Koşul: önce yeterince satır eklenmiş olmalı

CREATE INDEX ON documents USING ivfflat (embedding vector_cosine) WITH (lists = 100);

HNSW, eğitime gerek duymaz ve bazı veri setlerinde daha iyi gecikme/kalite dengesi sunabilir:

CREATE INDEX ON documents USING hnsw (embedding vector_cosine) WITH (m = 16, ef_construction = 128);

Metrik seçimi kritiktir: embedding modeliniz cosine ile eğitildiyse vector_cosine seçin. Performans için lists (IVFFlat) ve ef_search (HNSW) değerlerini iş yükünüze göre ayarlayın.

Semantik Arama Sorguları

Arama anında, sorgu metnini embedding’e çevirin ve en yakın komşuları çekin:

-- sorgu_embedding uygulama katmanından parametre olarak gelir

SELECT id, title, body FROM documents ORDER BY embedding <#> :sorgu_embedding LIMIT 5;

<#> operatörü cosine distance’dır. En iyi sonuçları almak için LIMIT’i ve filtre koşullarını (ör. kategori, tarih aralığı) birlikte kullanın.

RAG İçin Basit Bir Akış

- Kullanıcı sorusunu alın ve embedding’e dönüştürün.

- PostgreSQL’den en alakalı 5–10 dokümanı semantik aramayla çekin.

- Cevaplayıcı LLM’e, bu parçaları bağlamsal ek metin (context) olarak verin.

- Kaynakları (title ve id) cevapla birlikte kullanıcıya gösterin. Bu yaklaşım, halüsinasyonları azaltır ve izlenebilirlik sağlar.

Performans ve Ölçek İpuçları

1) İndeks ısınması: Sık aranan sorgu türleri için sistem başladığında birkaç “ısınma” araması yapın. Bu, sayfa önbelleğini doldurur.

2) Paralelleştirme: Toplu embedding üretiminde çoklu iş parçacığı ya da job queue kullanın. Veritabanına batch insert (ör. 100–1000 satır) performans sağlar.

3) Tablo tasarımı: Metin gövdeleri büyükse, embedding’leri ayrı bir tabloda (documents_vec) tutup body’yi object storage’a koymayı değerlendirin; Postgres’te sadece referans saklayın.

4) Bakım: Yoğun yazma/indeks güncellemelerinde VACUUM (ANALYZE) planlayın. Autovacuum ayarlarını (naptime, cost_limit) iş yükünüze göre iyileştirin.

5) IVFFlat ayarları: lists değerini veri büyüklüğüne göre artırmak hatırlama oranını iyileştirir; sorgu anında SET ivfflat.probes = X; ile daha fazla liste tarayıp isabet oranını yükseltebilirsiniz (gecikme artar).

6) HNSW ayarları: SET hnsw.ef_search = 64/128/256 gibi değerlerle kalite/gecikmeyi dengeleyin. Daha yüksek ef_search, daha iyi sonuç ama daha fazla CPU demektir.

7) Sharding/Partitioning: Konu veya müşteri bazlı PARTITION BY LIST ile arama alanını daraltmak ciddi kazanç sağlar.

Güvenlik ve Versiyonlama

Embedding uzayı model güncellemeleriyle değişebilir. Model versiyonunu tabloda saklayın (örn. model_version text) ve farklı versiyonlar için ayrı indeks tutun. Erişim tarafında Row Level Security (RLS) ile müşteri/veri bölümlendirmesini zorunlu kılın.

Hata Ayıklama ve Sık Karşılaşılan Sorunlar

- ERROR: type "vector" does not exist: CREATE EXTENSION vector; komutunun ilgili veritabanında çalıştığından ve eklentinin kurulu olduğundan emin olun.

- IVFFlat “not enough tuples”: İndeksi kurmadan önce yeterli sayıda satır eklenmiş olmalı; aksi halde eğitim yapılamaz.

- Yüksek gecikme: İndeks kullanılmıyor olabilir; EXPLAIN (ANALYZE, BUFFERS) ile planı inceleyin. probes veya ef_search değerlerini ayarlayın.

Sonuç

Pgvector, PostgreSQL’i güçlü bir vektör arama motoruna dönüştürüyor. Doğru indeks ve ayarlarla milyonlarca embedding üzerinde milisaniyeler içinde semantik arama yapılabiliyor. RAG senaryolarında ise hem kaynak yönetimini sadeleştiriyor hem de mevcut Postgres ekosisteminin güvenilirliğinden yararlanmanızı sağlıyor. Küçük bir POC ile başlayıp indeks parametrelerini kademeli ayarlayarak en iyi maliyet/performans noktasını yakalayabilirsiniz.