Passkeys (WebAuthn) ile Şifresiz Giriş: Adım Adım Uygulama Rehberi

Şifrelerle boğuşmanın sonuna gelmek üzereyiz. Passkeys, yani FIDO2/WebAuthn tabanlı şifresiz kimlik doğrulama, hem kullanıcı deneyimini iyileştiriyor hem de oltalama saldırılarına karşı çok daha güçlü bir koruma sağlıyor. Bu rehberde, modern web uygulamalarına passkey desteğini nasıl ekleyebileceğinizi, mimari gereksinimleri ve en iyi uygulamaları sade bir dille anlatıyorum.

Neden Passkeys? Klasik parolalar tahmin edilebilir, tekrar kullanılır ve sızıntılarda kolayca ele geçirilir. Passkeys ise cihaz tabanlı, kök anahtarları donanımda korunan (Secure Enclave/TPM) bir anahtar çifti yaklaşımı kullanır. Özel anahtar cihazda kalır, sunucu yalnızca herkese açık anahtarı saklar. Giriş sırasında sunucu tarafından verilen bir “challenge” imzalanır; bu sayede oltalama siteleri doğru kök bağlamı oluşturamadığı için doğrulama başarısız olur.

Passkey Nedir? Kısa Teknik Özet

Passkeys, WebAuthn API’si ve FIDO2 standartlarının bir birleşimidir. Tarayıcı (veya mobil OS), “platform authenticator” (cihaz üzerindeki biyometri/PIN) ya da “cross-platform authenticator” (USB/NFC güvenlik anahtarı) kullanarak kullanıcıyı doğrular. Uyumlu tarayıcılar: Chrome, Safari, Edge, Firefox (bazı platform kısıtları olabilir). Uyumlu işletim sistemleri: iOS/iPadOS 16+, macOS Ventura+, Android 9+, Windows 10/11 (Güncel) vb.

Mimari ve Gereksinimler

- Zorunlu HTTPS: WebAuthn yalnızca güvenli kökenlerde çalışır. Geliştirme için localhost istisnası vardır.
- Relying Party ID (rpId): Genellikle alan adınız. rpId, kök alanla eşleşmeli ve alt alanlar için doğru yapılandırılmalı.
- Sunucu tarafı saklama: Kullanıcı başına credentialId, publicKey, signCount (veya counter), userHandle gibi alanlar güvenli biçimde saklanmalı.
- Oturum yönetimi: Başarılı doğrulama sonrası session veya JWT üretin. Session sabitleme ve CSRF’ye dikkat edin.

Kayıt (Registration) Akışı

1) Sunucu challenge üretir: Kullanıcı kayıt sayfasında “Passkey oluştur” dediğinde sunucu tek kullanımlık bir challenge (rastgele bayt dizisi) üretir ve front-end’e gönderir. Yanıtınız; rp (name, id), user (id, name, displayName), pubKeyCredParams (örn. -7 ES256), authenticatorSelection (residentKey=required, userVerification=required) gibi parametreleri içermeli.

2) İstemci credential oluşturur: Tarayıcı, navigator.credentials.create({ publicKey: ... }) çağrısıyla cihazın biyometrisi/PIN’i üzerinden kullanıcıyı doğrular ve bir credential üretir. Kullanıcı rızası alınır ve işlem OS düzeyinde güvenlidir.

3) Sunucu doğrular ve kaydeder: İstemciden dönen attestation ve clientDataJSON, sunucuda doğrulanır. Güvenilir bir kütüphane ile (Node.js: @simplewebauthn/server; Java: WebAuthn4J; Python: webauthn) kontrol edebilirsiniz. Başarılıysa credentialId, publicKey ve signCount veritabanına yazılır. Attestation politikasını “none” tutarak gizliliği artırabilir veya kurumsal senaryolarda belirli üreticileri zorunlu kılabilirsiniz.

Giriş (Authentication) Akışı

1) Sunucu challenge üretir: Giriş düğmesine basıldığında sunucu yeni bir challenge üretir ve istemciye gönderir. allowCredentials ile kayıtlı credentialId’leri listeleyebilir veya “discoverable credentials” kullanıyorsanız listeyi boş bırakabilirsiniz.

2) İstemci imza oluşturur: navigator.credentials.get({ publicKey: ... }) çağrısı yapılır. Kullanıcı biyometri/PIN ile onay verir ve cihaz challenge’ı imzalar.

3) Sunucu imzayı doğrular: clientDataJSON ve authenticatorData içindeki rpIdHash, origin, flags (UP, UV), signCount ve signature doğrulanır. counter artışı kontrol edilerek tekrar oynatma (replay) engellenir. Başarılıysa oturum başlatılır.

Senkrone ve Cihaza Bağlı Passkeys

- Senkrone Passkeys: Apple, Google ve Microsoft ekosistemlerinde aynı hesabın bağlı cihazları arasında uçtan uca şifreli senkronizasyon yapılır. Kullanıcı için harika UX, ancak kurumsal ortamlarda veri politikaları gözden geçirilmeli.
- Cihaza Bağlı (Device-bound): Anahtar yalnızca oluşturulduğu cihazda bulunur. Daha sıkı güvenlik isteyen sektörlerde tercih edilir. Gerekirse ikisi bir arada desteklenebilir.

UX İpuçları ve Koşullu UI

- Koşullu UI: Chrome ve Safari, giriş formu odaklandığında otomatik passkey önerisi sunabilir. Bu, “parola yerine passkey” mesajını doğal şekilde yerleştirir.
- Adım adım benimsetme: İlk girişte kullanıcıya “Şifresiz giriş ekle (önerilir)” çağrısı yapın. Zorunlu kılmayın, alternatif bırakın.
- Geri dönüş planı: Kullanıcı cihazını kaybedebilir. E-posta/OTP veya destek kanalını yalnızca hesap kurtarma için sunun; normal girişte passkey’i önceliklendirin.
- Platform/cross-platform seçimi: Dizüstü kullanıcıları için platform authenticator yeterli olabilir; saha ekipleri için güvenlik anahtarları (USB/NFC) mantıklı.

Güvenlik ve Uyum

- Phishing direnci: rpId ve origin eşlemesi, yanlış etki alanıyla giriş yapılmasını engeller.
- Gizlilik: Attestation’ı çoğunlukla “none” tutarak cihaz damgalanmasını önleyin.
- Sertleştime: HSTS, COOP/COEP, güçlü TLS ayarları, zaman senkronizasyonu. Sunucu saat sapması doğrulamayı bozabilir.
- Uyumluluk: En güncel tarayıcı/OS sürümlerini hedefleyin. Eski cihazlar için parola + 2FA yedek planı bulundurun.

Uygulama İskeleti: Hızlı Kontrol Listesi

- Alan adınızı ve rpId’nizi netleştirin, HTTPS zorunludur.
- Veritabanında kullanıcı tablo şemasına credentialId (base64url), publicKey (COSE), signCount, createdAt, lastUsed alanlarını ekleyin.
- Kayıt ve giriş için ayrı endpoint’ler tanımlayın; her ikisi de nonce/challenge üretmeli ve kısa süreli saklamalı.
- Kütüphane seçin: Node.js için @simplewebauthn, Java için WebAuthn4J, Python için webauthn gibi olgun çözümler kullanın.
- Test: Chrome DevTools “Virtual Authenticator” ile farklı senaryoları (resident key, UV required) test edin.
- Telemetri: Başarı/başarısızlık oranlarını, tarayıcı/OS kırılımını izleyin; eğitim içerikleriyle dönüşümü artırın.

Sık Karşılaşılan Hatalar

- origin/rpId uyuşmazlığı: www ve çıplak alanı karıştırmayın; üretimde tek bir kök alan belirleyin.
- HTTP yerine HTTPS: Geliştirme dışında çalışmaz; sertifikayı doğru kurun.
- Yanlış COSE algoritması: Sunucu ve istemci aynı algoritmaları kabul etmeli (ör. ES256).
- Counter tutarsızlığı: signCount geriye düşerse cihaza güveni düşürün ve yeniden kayıt isteyin.

Özetle, passkeys hem güvenlik hem de kullanıcı deneyimi açısından önümüzdeki yılların standardı olacak. Doğru mimariyle kurguladığınızda, kullanıcılarınızın parolaları hatırlamasını istemez, oltalama riskini azaltır ve destek taleplerini düşürürsünüz. Küçük bir PoC ile başlayın, slayt yerine gerçek kullanıcı akışı tasarlayın ve dönüşüm metriklerini yakından takip edin. Bir kez oturduğunda, “Şifremi unuttum” döneminin kapandığını hissedeceksiniz.

Passkey (WebAuthn) ile Parolasız Giriş: Node.js ve SimpleWebAuthn ile Adım Adım Entegrasyon

Passkey (WebAuthn) ile Parolasız Giriş: Neden ve Nasıl?

Parolasız giriş dünyasında Passkey teknolojisi (WebAuthn/FIDO2) hızla standart hâline geliyor. Kimlik avı direnci, cihazlar arası senkronizasyon ve hızlı kullanıcı deneyimi sayesinde klasik parolaların yerini alıyor. Bu yazıda, Node.js ve @simplewebauthn kütüphanesini kullanarak bir web uygulamasına Passkey tabanlı kimlik doğrulamayı nasıl entegre edeceğinizi adım adım anlatıyorum. Rehber, modern tarayıcılar (Chrome, Safari, Edge) ve platformlar (iOS, Android, macOS, Windows) ile uyumludur.

Ön Koşullar ve Genel Mimari

Başlamadan önce Node.js 18+ sürümü, HTTPS ile çalışan bir alan adı (localhost için self-signed sertifika), temel Express.js bilgisi ve veri saklamak için bir veritabanı (ör. PostgreSQL, MongoDB veya basit bir bellek deposu) gerekli. Mimari olarak iki akış vardır: Kayıt (Registration) ve Giriş (Authentication). Kayıtta sunucu, kullanıcıya bir challenge üretir ve tarayıcı navigator.credentials.create() ile güvenli bir anahtar çifti oluşturur. Girişte ise sunucu yeni bir challenge üretir ve tarayıcı navigator.credentials.get() ile imza üretip doğrulatır.

Proje Kurulumu

mkdir passkey-demo && cd passkey-demo komutlarıyla klasörü oluşturun. Ardından npm init -y ve npm i express @simplewebauthn/server cors cookie-session komutlarını çalıştırın. Geliştirme için npm i -D typescript ts-node @types/express @types/cookie-session ekleyebilirsiniz. HTTPS için bir ters proxy ya da self-signed sertifika kullanın; WebAuthn çoğu senaryoda güvenli köken (https) ister.

Sunucu Tarafı: Temel Ayarlar

Express uygulamasında kök alan adınızı rpID olarak tanımlayın (ör. example.com). origin değeri tam protokol ve alan adını içermeli (ör. https://example.com). Kullanıcı oturumunda veya Redis gibi bir depoda challenge saklayın.

import express from 'express';
import { generateRegistrationOptions, verifyRegistrationResponse, generateAuthenticationOptions, verifyAuthenticationResponse } from '@simplewebauthn/server';
import session from 'cookie-session';

const app = express();
app.use(express.json());
app.use(session({ name: 'sess', keys: ['secret'], maxAge: 600000 }));

const rpID = 'example.com';
const origin = 'https://example.com';

Kayıt Akışı (Registration)

1) Options uç noktası: Kullanıcı kayıt olurken sunucu challenge üretir ve istemciye gönderir. Kullanıcı tanımlayıcısını (user.id) kalıcı bir değerden oluşturun.

app.post('/register/options', async (req, res) => {
  const { username, displayName } = req.body;
  const userId = 'user-' + username; // Örnek amaçlı
  const options = await generateRegistrationOptions({
    rpName: 'Passkey Demo',
    rpID,
    userID: userId,
    userName: username,
    userDisplayName: displayName || username,
    attestationType: 'none',
  });
  req.session.challenge = options.challenge;
  res.json(options);
});

2) Doğrulama uç noktası: İstemci, navigator.credentials.create() sonucunu bu uç noktaya gönderir. Sunucu doğrular, credential’ı veritabanına kaydeder.

app.post('/register/verify', async (req, res) => {
  const body = req.body; // client response
  const expectedChallenge = req.session.challenge;
  const verification = await verifyRegistrationResponse({
    response: body,
    expectedChallenge,
    expectedOrigin: origin,
    expectedRPID: rpID,
  });
  if (!verification.verified) return res.status(400).json({ ok: false });
  // credential kaydet: id, publicKey, counter, transports
  res.json({ ok: true });
});

Giriş Akışı (Authentication)

1) Options uç noktası: Sunucu, kullanıcıya bağlı mevcut credential’lara göre allowCredentials ile bir challenge üretir.

app.post('/login/options', async (req, res) => {
  const { username } = req.body;
  const userCreds = await loadUserCredentials(username); // DB'den çekin
  const options = await generateAuthenticationOptions({
    rpID,
    allowCredentials: userCreds.map(c => ({ id: c.id, type: 'public-key' })),
  });
  req.session.challenge = options.challenge;
  res.json(options);
});

2) Doğrulama uç noktası: İstemciden gelen imzayı doğrulayın, sayaç değerini güncelleyin ve oturumu başlatın.

app.post('/login/verify', async (req, res) => {
  const body = req.body;
  const expectedChallenge = req.session.challenge;
  const user = await findUserByCredentialId(body.rawId);
  const verification = await verifyAuthenticationResponse({
    response: body,
    expectedChallenge,
    expectedOrigin: origin,
    expectedRPID: rpID,
    authenticator: user.authenticator, // publicKey & counter
  });
  if (!verification.verified) return res.status(401).json({ ok: false });
  // counter güncelle, session başlat
  res.json({ ok: true });
});

İstemci Tarafı: WebAuthn API Kullanımı

Kayıt sırasında sunucudan aldığınız PublicKeyCredentialCreationOptions nesnesini navigator.credentials.create() içine verin. Tarayıcı, platform anahtarı (ör. iCloud Anahtar Zinciri, Google Password Manager) veya güvenlik anahtarı (YubiKey) ile cihaz üzerinde anahtar üretir.

const opts = await fetch('/register/options', { method: 'POST', body: JSON.stringify({ username }) }).then(r => r.json());
const cred = await navigator.credentials.create({ publicKey: opts });
await fetch('/register/verify', { method: 'POST', body: toJSON(cred) });

Girişte navigator.credentials.get() çağrısı yapılır. Sunucunun sağladığı PublicKeyCredentialRequestOptions ile imza üretilir ve doğrulama uç noktasına gönderilir.

const opts = await fetch('/login/options', { method: 'POST', body: JSON.stringify({ username }) }).then(r => r.json());
const assertion = await navigator.credentials.get({ publicKey: opts });
await fetch('/login/verify', { method: 'POST', body: toJSON(assertion) });

Test, Hata Ayıklama ve Uyumluluk

Geliştirmede https zorunludur; aksi takdirde tarayıcı çağrıları reddedebilir. Mobil cihazlarda test için aynı ağda çalışan https bir endpoint kullanın veya tünelleme (ngrok, Cloudflare Tunnel) tercih edin. Safari’de rpID uyumsuzluğu sık görülür; alan adınız ile origin’iniz birebir eşleşsin. Hata mesajlarını ayrıntılarıyla log’layın; özellikle challenge uyuşmazlığı, origin hatası ve RP ID hataları en yaygın sorunlardır.

Güvenlik ve UX İpuçları

- Challenge değerlerini tek kullanımlık ve kısa ömürlü saklayın; oturum veya Redis idealdir.

- Kullanıcı başına birden fazla credential kaydına izin verin; cihaz değişimlerinde deneyimi iyileştirir.

- resident key ve user verification politikalarını ihtiyaca göre ayarlayın; güçlü güvenlik için required tercih edin.

- Geriye dönük uyumluluk için geçici olarak sihirli bağlantı (magic link) veya tek kullanımlık kodları sunabilirsiniz.

- Üretimde anahtar materyalini ve sayaç değerlerini güvenilir bir veritabanında şifreli saklayın; yedeklemeleri planlayın.

Sonuç

Passkey (WebAuthn/FIDO2) ile parolasız giriş, hem güvenliği hem de kullanıcı deneyimini ileriye taşır. Node.js ve @simplewebauthn ile kurulum birkaç uç nokta ve doğru yapılandırma ile tamamlanabilir. Doğru rpID/origin eşleşmesi, güvenli challenge yönetimi ve çoklu credential desteği ile modern, kimlik avına dayanıklı ve hızlı bir giriş akışı elde edersiniz. Ürününüz büyüdükçe; cihaz senkronizasyonu, kurtarma stratejileri ve kurumsal güvenlik anahtarları ile çözümü olgunlaştırabilirsiniz.

Tarayıcıda WebGPU ile ONNX Runtime Web Kullanarak YOLOv8 Nesne Tanıma: Adım Adım Kurulum ve Performans İpuçları

Giriş

Tarayıcıda çalışan yapay zeka uygulamaları artık sadece demolarla sınırlı değil. WebGPU ve ONNX Runtime Web sayesinde, YOLOv8 gibi modern nesne tanıma modellerini doğrudan kullanıcıların cihazlarında, sunucuya ihtiyaç duymadan ve düşük gecikmeyle çalıştırmak mümkün hale geldi. Bu yazıda, YOLOv8 modelini ONNX formatına dönüştürüp WebGPU yürütücüsüyle tarayıcıda nasıl çalıştırabileceğinizi, performans odaklı pratik ipuçlarıyla adım adım anlatıyorum.

Neden WebGPU + ONNX Runtime Web?

WebGPU, modern GPU mimarilerine daha yakın bir API sunduğu için WebGL/Canvas tabanlı yaklaşımlara göre çok daha yüksek paralellik ve verimlilik sağlar. ONNX Runtime Web ise modelleri tarayıcıda WebGPU ya da WASM yürütücüleri ile çalıştırır. Bu ikili; hız, taşınabilirlik ve gizlilik avantajlarını aynı anda sunar: veriler tarayıcıdan çıkmaz, gecikme düşer, CDN üzerinden servis edilen statik dosyalarla ölçeklenebilir bir dağıtım sağlanır.

Ön Koşullar

Güncel bir Chromium tabanlı tarayıcı (Chrome/Edge 121+), WebGPU desteği açık bir ortam (HTTPS zorunlu), Node.js 18+ ve temel TypeScript/JavaScript bilgisi yeterli. Geliştirme için Vite ile hafif bir proje yapısı kuracağız.

Modeli Hazırlama (YOLOv8 → ONNX)

Ultralytics YOLOv8 modelini ONNX’e aktarmak için Python tarafında şu adımı izleyebilirsiniz: pip install ultralytics komutuyla paketi kurun ve ardından yolo export model=yolov8n.pt format=onnx opset=12 imgsz=640 komutunu çalıştırın. Bu işlem sonunda yolov8n.onnx dosyasını elde edersiniz. Alternatif olarak resmi depolardan hazır ONNX sürümlerini indirebilir ve doğrudan statik olarak sunabilirsiniz.

Projeyi Kurma (Vite + TypeScript)

Yeni bir proje başlatmak için şu komutu çalıştırın: npm create vite@latest onnx-webgpu -- --template vanilla-ts. Proje klasörüne geçip npm i onnxruntime-web komutuyla ONNX Runtime Web’i ekleyin. Modeli ve etiket dosyalarını public/models klasörüne kopyalayın. Geliştirme sunucusunu başlatmak için npm run dev yeterli olacaktır.

WebGPU Yürütücü ile İnferans

Tarayıcı tarafında WebGPU yürütücüsünü etkinleştirmek için modülü içeri aktarın: import 'onnxruntime-web/webgpu' ve ardından import { InferenceSession, Tensor } from 'onnxruntime-web'. Oturum oluştururken yürütücüyü belirtebilirsiniz: const session = await InferenceSession.create('/models/yolov8n.onnx', { executionProviders: ['webgpu'], graphOptimizationLevel: 'all' }). Eğer cihazda WebGPU uygun değilse bir yakalama bloğunda ['wasm'] ile geriye dönük destek sunmak mümkündür.

Görüntüyü tensöre dönüştürmek için bir <canvas> referansı yeterli. Görüntünün 640x640 boyutuna mektup kutusu (letterbox) ile ölçeklenmesi, ardından piksel verisinin Float32 tensöre [1, 3, H, W] düzeninde (RGB, kanal-öncelikli) aktarılması gerekir. Normalizasyon için genellikle 0–1 aralığı ve gerekiyorsa modelin beklediği ortalama/sapma değerleri kullanılır. Örnek akış: görüntüyü canvas’a çiz, getImageData ile veriyi al, Float32Array’e yaz ve new Tensor('float32', data, [1,3,640,640]) oluştur. Ardından await session.run({ images: inputTensor }) ile çıktıları alabilirsiniz.

YOLOv8 ONNX çıkışında genellikle [1, N, 84] benzeri bir matris döner (ilk 4 değer kutu, takip eden skorlar/sınıflar). Sonuçları yorumlarken skor eşiğini (örneğin 0.25) ve IoU tabanlı NMS adımını uygulayın. Basit bir döngü ile her satırı okuyup en yüksek sınıf skorunu, kutu koordinatlarını ölçekleyerek orijinal görüntü boyutuna geri projekte edebilirsiniz.

Performans ve Optimizasyon İpuçları

Isınma (warm-up): Uygulama açılışında bir kez sahte bir tensörle session.run yaparak JIT derleme/önbellek süreçlerini tetikleyin. Bu, ilk gerçek karedeki gecikmeyi ciddi ölçüde azaltır.

WASM geri dönüşü: WebGPU desteklenmeyen cihazlarda otomatik olarak WASM’a düşmek kullanıcı kapsamını artırır. executionProviders: ['webgpu', 'wasm'] sıralaması pratik bir stratejidir.

Kantizasyon ve hafif modeller: INT8 kantize edilmiş ONNX modelleri bellek ve bant genişliği tüketimini düşürür. Eğer doğruluk kabul edilebilir seviyede kalıyorsa yolov8n veya yolov8s gibi küçük türevleri tercih edin.

Web Worker / OffscreenCanvas: Ön işleme ve NMS’i Web Worker’a taşıyarak ana iş parçacığını serbest bırakabilir, kare atlamalarını azaltabilirsiniz. Destek varsa OffscreenCanvas ile piksel işlemlerini işçi tarafında yapın.

Toplu işleme ve kadans kontrolü: Canlı kamera akışında her kareyi çalıştırmak yerine zamanlayıcıyla kadansı sınırlayın (ör. 30 FPS yerine 15 FPS). Sabit görüntü yükleme senaryolarında, aynı anda birden fazla resmi işlemek yerine küçük partiler halinde ilerleyin.

Bellek yönetimi: Tekrar kullanılan tensör ve arabellekleri yeniden oluşturmak yerine mümkün olduğunca yeniden kullanın. Büyük Float32Array tahsislerinden kaçınmak çöp toplayıcı baskısını azaltır.

Sık Karşılaşılan Hatalar ve Çözümler

GPUUnavailableError: Tarayıcıda chrome://flags altında WebGPU kapalı olabilir veya sayfa HTTPS üzerinden servis edilmiyor olabilir. Yerel geliştirme için localhost genellikle güvenilir sayılır.

Model uyumsuzluğu: ONNX opset sürümü çok düşük/yüksek olduğunda düğümler çözümlenmeyebilir. Çoğu güncel senaryoda opset 12–13+ güvenlidir; export sırasında opseti açıkça belirtin.

Çapraz kaynak sorunları: Model dosyaları farklı bir origin’den yükleniyorsa CORS başlıklarını doğru ayarlayın. Üretimde model ve varlıkları aynı domain/CDN kökünden sunmak en pratik yoldur.

Sonuç

WebGPU ve ONNX Runtime Web ile YOLOv8’i tarayıcıda çalıştırmak, gerçek zamanlı nesne tanımayı istemci tarafında güvenli ve hızlı bir şekilde sunmanıza olanak verir. Doğru ön işleme, hafif model seçimi ve ısınma/optimizasyon teknikleri ile orta seviye cihazlarda bile akıcı deneyim elde edebilirsiniz. Bu yaklaşım; gizlilik, ölçeklenebilirlik ve kullanıcı deneyimi açısından modern web uygulamalarına güçlü bir kapı aralıyor. Birkaç küçük adımla siz de modelinizi WebGPU üzerinde hayata geçirebilirsiniz.

Yerelde RAG Kurulumu: Ollama ve FAISS ile Belgelerinizden Akıllı Arama

RAG nedir, neden yerel çalıştırmalıyım?

Büyük dil modelleri etkileyici cevaplar üretebiliyor ancak kaynaklara dayanmayan “halüsinasyon” üretme eğilimleri var. Retrieval-Augmented Generation (RAG), modelin yanıtlarını gerçek belgelerinizden çekilen parçalarla destekleyerek bu sorunu azaltır. Yerel RAG, tüm süreci bilgisayarınızda çalıştırarak gizlilik, düşük gecikme ve maliyet avantajı sağlar. Bu yazıda Ollama + FAISS ikilisiyle, PDF’leriniz, notlarınız veya wiki sayfalarınız üzerinde çalışan pratik bir yerel RAG kurulumunun yolunu göstereceğim.

Mimari bileşenler

1) LLM (Yanıtlayıcı): Yerelde çalıştırmak için Ollama üzerinden Llama 3, Mistral veya benzeri açık modellerden birini seçebilirsiniz. Kuantize edilmiş sürümler (ör. Q4_K_M) düşük donanımda bile kabul edilebilir hız sunar.

2) Vektörleştirici (Embedding): Metni sabit boyutlu vektörlere dönüştürür. Türkçe desteği güçlü olan bge veya e5 tabanlı modeller iyi sonuç verir. Embedding modeli LLM’den ayrı olabilir; bu esneklik performansı artırır.

3) Vektör Veritabanı (FAISS): Belgelerinizin vektörlerini indeksleyip en benzer parçaları hızla getirir. FAISS hafif, açık kaynak ve yerel kurulum için idealdir.

4) Orkestrasyon: Basit bir RAG için ek çerçeve şart değil. Sıra; sorguyu vektörleştir, FAISS’ten en yakın doküman parçalarını getir, bu parçaları bağlam olarak LLM’e ver ve yanıtı oluştur şeklinde ilerler. İsterseniz LangChain veya LlamaIndex kullanabilirsiniz; ancak bu yazı minimal ve anlaşılır yaklaşımı tercih ediyor.

Adım adım kurulum

Önkoşullar: 8–16 GB RAM, modern bir CPU yeterli. GPU varsa daha hızlı olur. İşletim sistemi olarak macOS, Windows (WSL dahil) veya Linux uygundur.

1) Ollama’yı kurun: Ollama resmi sitesinden sisteminize uygun kurulum paketini indirin ve kurun. Terminalde “ollama run llama3” gibi bir komutla modeli test edebilirsiniz. İlk çalıştırmada model indirilecektir.

2) Embedding modelini hazırlayın: Python ortamı kurup sentence-transformers gibi bir kütüphane ile bge veya e5 tabanlı çok dilli bir modeli indirin. Türkçe metinler için bu aileler genellikle dengeli sonuç verir. Üretimde aynı tokenizer ve model sürümünü koruyarak tutarlılık sağlayın.

3) Belgeleri içe aktarın ve parçalara bölün: PDF, Markdown veya HTML kaynaklarınızı metne dönüştürün. Chunking stratejinizi belirleyin: 400–800 kelime aralığı ve %10–20 örtüşme (overlap) çoğu senaryo için iyi bir başlangıçtır. Başlık, bölüm, sayfa numarası gibi meta verileri saklamayı unutmayın.

4) FAISS ile indeks oluşturun: Her parçayı embedding modele verip vektörünü alın ve FAISS’e ekleyin. Büyük veri için IVF+PQ gibi yapılandırmalar disk ve bellek kullanımını dengeler. Küçük veri setlerinde düz L2 veya kosinüs benzerliği yeterli olur.

5) Sorgu akışı: Kullanıcı sorusunu embedding’e çevirin, FAISS’ten top-k (ör. k=5) en yakın parçayı çekin. Bu parçaları bir “bağlam” şablonunda birleştirip Ollama’ya aktarın. Prompt içinde “Sadece aşağıdaki bağlamdan yararlan” gibi net yönergeler verin. Yanıtı kaynak bağlantılarıyla birlikte sunmak güven yaratır.

6) Hafif bir API ekleyin: FastAPI gibi bir çerçeveyle tek uç noktalı bir servis hazırlayabilirsiniz. İstek geldiğinde sorguyu vektörleştirir, FAISS’ten bağlamı getirir, Ollama’ya iletir ve akışlı yanıtı geri döndürür. Böylece masaüstü, web veya mobil istemciler kolayca entegre olur.

7) Değerlendirme ve iyileştirme: Kaliteyi ölçmek için sık sorulan 20–30 soruluk bir test seti hazırlayın. Cevap doğruluğu, kaynak kapsama (coverage) ve ilk token gecikmesi gibi metrikleri izleyin. Top-k, chunk boyutu, MMR (çeşitlilik odaklı getirme) ve sıcaklık (temperature) ayarlarını kademeli değiştirerek A/B testleri yapın.

Performans ve pratik ipuçları

Kuantizasyon: LLM’i Q4 seviyesinde çalıştırmak performans/kalite dengesini iyileştirir. CPU’da dahi kabul edilebilir yanıt hızları elde edilir.

Prompt mühendisliği: Türkçe bağlam sağladığınızda, talimatları da Türkçe verin. “Kaynaklardan alıntı yap, emin değilsen belirt” gibi yönlendirmeler halüsinasyonu azaltır.

Önbellekleme: Sık soruların embedding ve arama sonuçlarını disk üzerinde önbelleğe alın. Bu, hem gecikmeyi hem de CPU yükünü düşürür.

Filtreler: FAISS yanında meta veri filtreleri tutarak tarih, yazar, kategori gibi sınırlamalarla daha doğru sonuçlar alabilirsiniz.

Türkçe desteği: Embedding modelinin Türkçe kapsaması kritiktir. İlk denemelerde Türkçe/multilingual modelleri karşılaştırın; bazen küçük ama iyi eğitilmiş bir embedding modeli büyük bir fark yaratır.

Gizlilik, güvenlik ve bakım

Yerel RAG’in en büyük artısı, belgelerinizin makine dışına çıkmamasıdır. Yine de PII içeren veri setlerini şifreli depolamak, cihazınızda tam disk şifreleme kullanmak ve indeks dosyalarına erişimi kısıtlamak önemlidir. Modelleri ve bağımlılıkları düzenli güncelleyin; embedding modelini değiştirdiğinizde indeksinizi yeniden oluşturmanız gerektiğini unutmayın.

Sorun giderme

İndeks tutarsızlığı: Farklı embedding model veya sürüm değişikliği, alakasız sonuçlar doğurur. Tek sürüm standardı belirleyin.

Dil karışması: Çok dilli veri setlerinde karışık diller zayıf eşleşmeye yol açabilir. Belgeleri dil bazında ayrı indekslemek kaliteyi yükseltir.

Kaynak tüketimi: RAM yetmiyorsa daha agresif chunking veya IVF+PQ yapılandırmasına geçin. LLM tarafında daha küçük bir model deneyin.

Sonuç

Ollama ve FAISS ile kurulan yerel RAG, gizliliğe duyarlı ortamlarda hızlı ve güvenilir bir bilgi erişim katmanı sunar. Doğru embedding seçimi, iyi bir chunking stratejisi ve disiplinli değerlendirmeyle; şirket içi dokümantasyondan akademik arşivlere kadar pek çok kullanım senaryosunda arama ve soru-cevap kalitesini belirgin biçimde artırabilirsiniz. Küçük adımlarla başlayın, metriklerle ölçün ve yapı taşlarını gerektikçe büyütün; kısa sürede günlük iş akışınızda fark yaratacaktır.

Tailscale ile Zero Trust Uzaktan Erişim: Adım Adım Kurulum ve İleri Düzey Ayarlar (2025)

Tailscale nedir ve neden Zero Trust?

Tailscale, WireGuard tabanlı güvenli bir ağ katmanı (overlay network) oluşturmanızı sağlayan, modern ve bulut tabanlı bir çözüm. Geleneksel VPN’lerin aksine, Zero Trust yaklaşımını benimser: Her cihaz kimlik tabanlı olarak yetkilendirilir, erişimler ince taneli politikalarla (ACL) kısıtlanır ve istemciler doğrudan birbirine şifreli tüneller kurar. Bu model; uzaktan çalışma, ev-ofis lab’ları, geliştirici ortamları ve çok lokasyonlu küçük işletmeler için yüksek güvenlik ve düşük gecikme sağlar.

Bu rehberde Tailscale’i adım adım kurup; MagicDNS, Subnet Router, Exit Node, ACL (Access Control Lists) ve Tailscale SSH gibi ileri düzey özellikleri etkinleştirerek pratik bir Zero Trust mimarisi kuracağız. Anlatım, sade ve SEO uyumlu olacak; ancak kritik ipuçlarını ve sık yapılan hataları da not edeceğim.

Ön koşullar ve hazırlık

Başlamak için bir Tailscale hesabı (Google, Microsoft, GitHub, OIDC vb. ile giriş yapılabiliyor), en az iki cihaz (ör. bir dizüstü ve bir sunucu ya da NAS) ve yönetici konsoluna erişim gerekiyor. Eğer ofis ağını uzaktan erişilebilir kılmak istiyorsanız, LAN tarafında sürekli açık kalacak hafif bir Linux makine veya küçük bir cihaz (ör. Raspberry Pi) işinizi görür.

Kurulum: Adım adım

1) Hesap oluşturma ve oturum açma: tailscale.com’a gidip bir hesap oluşturun. Mümkünse kurumsal tekil oturum açma (SSO) kullanın ve çok faktörlü kimlik doğrulamayı (MFA) zorunlu kılın. Güvenlik stratejinizin temeli burasıdır.

2) İstemci kurulumu: Windows, macOS, Linux ve mobil (iOS/Android) istemcileri indirin ve giriş yapın. Linux tarafında kurulum sonrası “sudo tailscale up” komutuyla ağı etkinleştirirsiniz. Bu komuta ileride gelişmiş bayraklar ekleyeceğiz.

3) MagicDNS ve kendi kendine TLS: Yönetim panelinde DNS bölümünden MagicDNS’i açın. Bu sayede cihazlara makine-adı.tailnet-adınız.ts.net gibi kolay adlarla erişirsiniz. İsteğe bağlı olarak Tailscale’in otomatik TLS sertifikalarını açıp dahili servisleri HTTPS üstünden güvenle kullanabilirsiniz.

4) Subnet Router ile LAN’ı yayınlama: Ev/ofis ağınızdaki servisleri (NAS, yazıcı, IoT) yollamak için bir Linux makinede Subnet Router yapın. Örneğin 192.168.1.0/24 ağınızı yayınlamak için istemcide --advertise-routes=192.168.1.0/24 bayrağını kullanın. Yönetim panelinde bu rotayı onaylamayı unutmayın. Bu adım, NAT ya da CGNAT arkasında olsanız bile tüm ağa erişim sunar.

5) Exit Node (tüm trafiği yönlendirme): Seyahatteyken trafiğinizi güvenilir bir noktadan (ör. ev ofisi) çıkarmak istiyorsanız bir cihazı Exit Node olarak işaretleyin. İstemci tarafında ilgili ayarı seçerek tüm internet trafiğinizi o cihaz üzerinden geçirebilirsiniz. Bu yöntem, halka açık Wi‑Fi güvenliği ve bölgesel kısıtları aşma senaryolarında idealdir.

6) Tailscale SSH ile bastion’sız erişim: Yönetim panelinden Tailscale SSH’yi açın ve sadece etiketlenmiş sunuculara belirli kullanıcıların erişmesine izin verin. Böylece ayrı bir bastion host ya da 22 numaralı port için NAT/port yönlendirmesi gerekmiyor; anahtar yönetimi de merkezi hale geliyor.

7) İnce taneli ACL politikaları: ACL’leri kullanarak “kim, nereye, hangi porta, hangi protokolle” erişebilir sorusunu kesin çizgilerle belirleyin. Pratik bir başlangıç: Geliştirici grubuna yalnızca staging sunucular, DevOps’a ise prod ortamlar; IoT cihazlarına ise sadece NAS’ın erişmesi gibi kartopu mantığında kurallar yazın. Etiketler ve gruplar burada en büyük yardımcınız olacak.

Güvenlik, performans ve pratik ipuçları

- Anahtar yaşam döngüsü: Cihaz anahtarları için sona erme (key expiry) politikası belirleyin. Kısa ömürlü (ephemeral) anahtarlar CI/CD ajanları ve geçici sunucular için idealdir.

- Port açmayın, UPnP’yi kapatın: Tailscale ile NAT/port yönlendirmesi gereksiz. Modem üzerindeki UPnP’yi devre dışı bırakmak saldırı yüzeyini azaltır.

- Performans ve DERP: Doğrudan eşler arası bağlantı kurulamadığında Tailscale, en yakın DERP rölelerini kullanır. Farklı ülkelerde cihazlarınız varsa birden fazla DERP bölgesinde iyi performans elde edersiniz. Yüksek bant genişliği gereken durumlarda doğrudan bağlantı kurulduğundan emin olmak için istemci üzerinde bağlantı testleri yapın.

- Görüntüleme ve denetim: Yönetim panelindeki audit log’larını düzenli kontrol edin. Şirket ortamında SSO ve zorunlu MFA ile birlikte cihaz uyumluluk kuralları (ör. disk şifreleme, ekran kilidi) uygulayın.

Sorun giderme: En sık karşılaşılan durumlar

Doğrudan bağlantı kurulamıyorsa önce istemci saatlerinin doğru olduğundan emin olun. Saat drift’i sertifika doğrulamalarında sorun çıkarır. Ardından uç noktalarda gelen/giden UDP trafiğini (özellikle 41641 ve STUN/3478) engelleyen bir güvenlik duvarı olup olmadığını kontrol edin. Çok katmanlı NAT ya da kurumsal proxy arkasındaysanız bağlantı DERP üzerinden sağlanır; bu normaldir. Bağlantı kalitesini anlamak için istemci uygulamasındaki “netcheck” veya “ping” testlerinden yararlanabilirsiniz. Subnet Router sonrası erişemediğiniz bir cihaz varsa, o cihazın yerel güvenlik duvarında Tailscale’den gelen trafiğe izin verildiğini doğrulayın.

Sonuç: ZTNA’yı pratik şekilde hayata geçirmek

Tailscale, Zero Trust felsefesini günlük iş akışına sokmak isteyen bireyler ve ekipler için düşük sürtünmeli bir seçenek. MagicDNS, Subnet Router, Exit Node ve Tailscale SSH gibi özellikler; güvenliği artırırken operasyonel karmaşıklığı azaltıyor. Birkaç saatlik kurulum ve iyi düşünülmüş ACL politikalarıyla, klasik VPN’lerde haftalar alan işleri dakikalar içinde çözebilirsiniz. 2025 itibarıyla hibrit ve uzaktan çalışmanın standart olduğu bir dünyada, esnek ve güvenli ağ erişimi rekabet avantajı sağlıyor. Küçük başlayın, cihazları etiketleyin, kuralları kademeli sıkılaştırın; ihtiyacınız olan Zero Trust temelleri böylece yerli yerinde olur.

RAG ile Türkçe Dokümanlarınıza Özel Yapay Zekâ Asistanı Kurulumu (2025 Rehberi)

RAG nedir ve neden gerekli?

Kurumsal veriler üzerine çalışan yapay zekâ asistanlarının en büyük sorunlarından biri, modelin eğitim verisinde olmayan bilgiler hakkında uydurma (hallucination) üretmesidir. RAG (Retrieval-Augmented Generation) yaklaşımı, üretken modelden önce güvenilir kaynaklardan ilgili parçaları arayıp getirir, ardından bu bağlam ile yanıt oluşturur. Böylece cevaplar hem daha doğru hem de kaynaklanabilir olur. Bu yazıda, Türkçe dokümanlarınız için RAG tabanlı bir asistanı sıfırdan nasıl kurabileceğinizi adım adım anlatıyorum.

Mimari bileşenler

1) Doküman alımı ve ayrıştırma: PDF, Word, e-posta arşivi ya da Confluence/Jira gibi bilgi tabanlarından veriyi çekin. PDF’lerde metin çıkarımı için OCR gerekebilir. Tablo ve görselleri metne dönüştürürken bağlamı kaybetmemeye dikkat edin.

2) Temizleme ve parçalama (chunking): Türkçe metinlerde noktalama ve büyük/küçük harf (İ/ı) uyumuna dikkat edin. Belgeyi 300–500 kelimelik, %10–15 örtüşmeli parçalara ayırın. Başlık ve bölüm bilgilerini her parçaya meta veri olarak ekleyin.

3) Vektörleştirme (embedding): Türkçe desteği güçlü gömlemeler kullanın. Bulut tabanlı text-embedding-3-large (OpenAI) veya açık kaynak bge-m3 ve multilingual-e5-large iyi seçeneklerdir. Gizlilik gereksinimi yüksekse modeli yerelde çalıştırın.

4) Vektör veritabanı: Chroma, Qdrant, Milvus ya da FAISS ile arama yapın. Üretim ortamı için Qdrant/Milvus, prototip için Chroma/FAISS tercih edilebilir. Metadata alanlarında belge tipi, sayfa, bölüm gibi sahaları tutun.

5) Sorgu işleme: Yalnızca vektör araması yerine hibrit arama (BM25 + vektör) ve bir yeniden sıralayıcı (ör. bge-reranker) ekleyin. Bu, Türkçe uzun sorgularda isabeti ciddi şekilde artırır.

6) Üretken model (LLM): Bulutta GPT-4o mini gibi hızlı/uygun maliyetli bir model veya yerelde Llama 3.1 8B, Mistral 7B gibi modelleri Ollama üzerinden çalıştırabilirsiniz.

Adım adım kurulum

Adım 1 – Ortam: Python 3.11 ile bir sanal ortam kurun. Gerekliyse Docker ile Qdrant/Milvus çalıştırın. Projede LangChain veya LlamaIndex gibi bir çatı kullanmanız geliştirmeyi hızlandırır.

Adım 2 – Veri toplama: Belgeleri tek bir dizinde toplayın. Yetkisiz içerikleri ayıklayın; erişim seviyesine göre dizinleri bölmek ileride yetkilendirme için işinize yarar.

Adım 3 – Ön işleme: PDF sayfa kırıkları, dipnotlar ve sayfa numaralarını temizleyin. Türkçe’de noktalama ve karakter dönüşümlerini (ör. apostrof, tırnak) normalize edin. Gereksiz boşlukları ve tarih/sürüm kalıntılarını ayıklayın.

Adım 4 – Parçalama: İçerik türüne göre strateji belirleyin. Teknik belgelerde başlık bazlı, SSS’lerde soru-cevap bazlı, politikalar/prosedürlerde paragraf bazlı parçalama daha başarılı olur. Her parçaya kaynak_linki, belge_türü, bölüm gibi meta verileri ekleyin.

Adım 5 – Embedding seçimi: Türkçe performansı yüksek bir modelle test yapın. Aynı veri üzerinde 10–20 örnek sorgu ile top-k isabetini ölçerek model seçimi yapın. Gizlilik gereksinimi varsa açık kaynak bir modelle yerelde kalın.

Adım 6 – Vektör veritabanı kurulumu: Chroma ile hızlı prototip, Qdrant/Milvus ile üretim kurulumu yapın. İndeks parametrelerinde HNSW grafı ve uygun M, efConstruction değerlerini deneyerek gecikme-doğruluk dengesini bulun.

Adım 7 – İndeksleme: Parçaları gömleyip veritabanına yazın. Versiyonlama yapın; her yüklemeye bir batch_id vererek geri alım (rollback) kolaylığı sağlayın. Büyük yüklemelerde artımlı (incremental) indekslemeyi tercih edin.

Adım 8 – Sorgu boru hattı: Kullanıcı sorgusunu önce query rewriting ile netleştirin (gerekiyorsa çoklu sorgu üretimi). Ardından hibrit arama yapın, ilk 20 sonucu alın, bir reranker ile en iyi 5–7 bağlamı seçin. MMR ile çeşitlilik sağlayın.

Adım 9 – Prompt tasarımı: Sistem mesajına “Sadece verilen bağlamdan yanıtla, emin değilsen ‘elimdeki kaynaklarda yok’ de” gibi kurallar koyun. Yanıt sonunda Kaynaklar bölümünde belge adı ve bölüm başlığını listeleyin.

Adım 10 – Değerlendirme: 50–100 soruluk altın set hazırlayın. Ölçütler: cevap alaka puanı, bağlam isabeti, kaynak doğruluğu, gecikme, maliyet. Otomatik değerlendirme için küçük bir script ile yanıt-kaynak uyuşumunu ölçebilirsiniz.

Adım 11 – Yayına alma: FastAPI ile bir servis oluşturun. Redis önbellekle sık soruların yanıtlarını tutun. Yüksek trafikte rate limit ve tamamlama uzunluğu sınırlamaları önemli. Gözlemlenebilirlik için OpenTelemetry ile izleme kurun.

Adım 12 – Güvenlik ve gizlilik: Hassas verileri indekslemeden önce PII maskesi uygulayın. Vektör veritabanını özel ağda tutun. Kullanıcı bazlı yetkilendirme yapıyorsanız sorgu sırasında metadata filtreleri ile erişim kısıtlayın.

Performans ipuçları

- Top-k değerini rastgele yükseltmek yerine hibrit arama + reranker kullanın; maliyeti ve gecikmeyi düşürür.

- Çok uzun bağlamlar yerine 5–7 yüksek kaliteli pasaj verin; LLM’ler daha odaklı yanıtlar üretir.

- Maliyet kritikse önce hızlı bir modelle taslak, ardından önemli akışlarda daha güçlü bir modelle doğrulama yapın.

- Türkçe’de eşanlam ve ekler önemlidir; sorgu genişletme (synonym expansion) ve kök bulma (stemming/lemmatization) deneyin.

Sık karşılaşılan hatalar

- Kaynak sızıntısı: Yanıtlarda kapalı belge adlarının görünmesi. Çözüm: metadata’yı kullanıcı rolüne göre filtreleyin ve prompt’ta kaynak gösterimini maskeleyin.

- Aşırı uzun parçalar: Gömlemelerin ayrıştırıcılığı düşer. 300–500 kelime aralığını aşmamaya çalışın.

- Zayıf gömleme modeli: Çok dilli ama Türkçe’de zayıf bir model, arama kalitesini bozar. Küçük bir değerlendirme seti ile model seçimi yapın.

Sonuç

RAG, Türkçe kurumsal dokümanlarda güvenilir ve kaynaklanabilir yanıtlar üretmenin en pratik yolu. Doğru gömleme, hibrit arama, reranking ve titiz prompt tasarımıyla, hem doğruluğu hem de kullanıcı güvenini önemli ölçüde artırabilirsiniz. Küçük bir prototiple başlayıp ölçümlere göre adım adım optimize edin; doğru mimariyle RAG tabanlı asistanınız kısa sürede üretim kalitesine ulaşacaktır.

RAG Tabanlı Kendi Yapay Zekâ Asistanınızı Kurun: LangChain ve LlamaIndex ile Adım Adım Rehber

Üretken yapay zekâ (GenAI) uygulamaları hızla yaygınlaşırken, doğru ve güncel bilgiye dayalı yanıtlar üretmek için en çok konuşulan yaklaşım RAG (Retrieval-Augmented Generation) oldu. Bu yazıda, RAG nedir, hangi durumlarda kullanılır, hangi araçları tercih etmelisiniz ve LangChain ile LlamaIndex kullanarak nasıl adım adım bir RAG hattı (pipeline) kurabilirsiniz sorularına pratik ve güncel bir rehberle yanıt vereceğim.

RAG nedir ve neden önemli? Klasik büyük dil modelleri yalnızca eğitim verisiyle sınırlıdır ve güncelliği hızla kaybedebilir. RAG, modelin yanıt üretmeden önce bir vektör veritabanından ilgili belgeleri geri çağırmasını (retrieval) sağlar. Bu sayede hem güncel hem de şirket içi özel bilgilere dayalı doğru, kaynaklı ve denetlenebilir yanıtlar üretirsiniz. Özellikle doküman asistanları, müşteri destek botları, teknik bilgi tabanı arayüzleri ve kurumsal arama projelerinde RAG çok etkili bir çözümdür.

Gereksinimler ve genel mimari Basit bir RAG hattı için üç bileşen gerekir: (1) Metinlerinizi parçalara (chunk) ayırıp sayısal vektörlere dönüştüren bir gömme (embedding) modeli; (2) Bu vektörleri saklayıp benzerlik araması yapan bir vektör veritabanı; (3) Geri çağrılan metinleri kullanıp yanıt üreten bir LLM. Ek olarak, yeniden sıralama (reranking), sorgu genişletme (query expansion) ve değerlendirme (eval) katmanlarıyla kaliteyi artırabilirsiniz.

Vektör veritabanı seçimi Başlangıç için gömülü ve kurulumu kolay Chroma iyi bir seçenek. Hafif, hızlı ve yerelde deney yapmak için ideal. FAISS, tek makinede yüksek performanslı aramalar için tercih edilebilir. Üretim ortamlarında ise Pinecone, Weaviate, Qdrant gibi servisler ölçeklenebilirlik ve yönetim kolaylığı sunar. Seçimde verinizin büyüklüğü, gecikme ihtiyaçları, bütçe ve regülasyon gereksinimlerini dikkate alın.

Embedding modeli seçimi Ücretli ve yüksek kaliteli bir seçenek arıyorsanız OpenAI’nin text-embedding-3-large modeli güçlü bir taban sunar. Açık kaynak tarafta bge-large, e5-large veya instructor-xl aileleri yaygın ve iyi sonuç veriyor. Türkçe performansı kritikse çok dilli destek sunan modelleri tercih edin ve mümkünse küçük bir doğrulama kümesi üzerinde kısa bir A/B testi yapın.

Parçalama stratejisi (chunking) Parça boyutu ve bindirme (overlap) kaliteyi doğrudan etkiler. 300–800 karakter aralığı genelde güvenli bir başlangıçtır; teknik belgelerde 1000–1500 karaktere çıkmak bağlam bütünlüğünü korumaya yardımcı olabilir. 10–20% arası bindirme, cümlelerin iki parça arasında bölünmesini yumuşatır.

LangChain ile hızlı başlangıç

LangChain, veri yükleme, parçalama, embedding, vektör dizinleme ve sorgulama adımlarını modüler şekilde birleştirmenizi kolaylaştırır. Pratik akış şu şekildedir: Belgeleri yükleyin, metinleri parçalara ayırın, embedding üretin, Chroma’ya kaydedin, ardından bir RetrievalQA zinciri oluşturun. Örnek kurulum adımı olarak komut satırında pip install langchain chromadb sentence-transformers komutunu kullanabilirsiniz. Basit bir sorgu akışı ise şu mantıkta ilerler: retriever.get_relevant_documents(soru) ile ilgili parçaları alın, ardından llm.invoke(prompt + bağlam) ile yanıt üretin. LangChain’in Runnable ve LCEL (LangChain Expression Language) soyutlamaları, üretim ortamında gözlemlenebilir, loglanabilir ve test edilebilir zincirler kurmayı kolaylaştırır.

Artıları: Zengin entegrasyon ekosistemi, güçlü zincir soyutlamaları, hızlı prototipleme. Eksileri: Çok modüllü yapı karmaşıklığa yol açabilir; versiyon uyumluluğuna dikkat etmek gerekir.

LlamaIndex ile belgeden yanıta

LlamaIndex, endekse odaklı bir tasarım sunar ve doküman odaklı akışlarda sade bir deneyim sağlar. Document ve Node yapılarıyla parça yönetimi şeffaftır; ServiceContext ile LLM ve embedding ayarlarını merkezi olarak kontrol edersiniz. Özet akış şudur: Belgeleri okuyun, VectorStoreIndex oluşturun, ardından query_engine veya chat_engine üzerinden sorgulayın. Basit bir kurulum için pip install llama-index chromadb yeterlidir. LlamaIndex ayrıca reranker ve response synthesizer yapılarıyla çıktı kalitesini artırmak için gömülü seçenekler sunar.

Artıları: Doküman merkezli tasarım, hızlı “belgeden yanıta” kurulum, iyi dokümantasyon. Eksileri: Çok özel iş akışlarında esneklik için ek özelleştirme gerekebilir; bazı ileri seviye özellikler sürümlere göre değişebilir.

Kaliteyi artırma teknikleri

Sorgu genişletme: Kullanıcının kısa sorusunu, olası eşanlamlılar ve bağlamla zenginleştirerek arama kalitesini artırabilirsiniz. RAG-Fusion veya çoklu sorgu tekniğiyle farklı varyantları arayıp birleştirmek iyi sonuç verir.

HyDE (Hypothetical Document Embeddings): Modelden, soruya dair “varsayımsal bir cevap” üretmesini isteyip bunu embedding’e çevirerek arama yapın; özellikle belgenin dili ile soru dili farklı olduğunda işe yarar.

Yeniden sıralama (Reranking): İlk 10 sonucu aldıktan sonra bir reranker modeliyle en iyi 3–5 sonucu seçin. Açık kaynak bge-reranker veya bulut tabanlı hizmetler (ör. Cohere Rerank) yaygın tercih edilir.

İstem (prompt) şablonları: Kaynakları listelemeyi zorunlu kılan, halüsinasyonu azaltan net yönergeler kullanın. Örnek: “Yanıtlarken yalnızca verilen bağlamı kullan. Emin değilsen ‘Bu bilgi bağlamda yok’ de. En sonda kullandığın kaynak başlıklarını sırala.”

Değerlendirme ve gözlemlenebilirlik

RAG projelerinde değerlendirme kritik önemdedir. Küçük ama temsil gücü yüksek bir test seti oluşturun. Doğruluk, alaka, kaynak kapsamı, yanıt uzunluğu ve gecikme gibi metrikleri izleyin. RAGAS gibi değerlendirme çerçeveleri yararlıdır. Üretimde ise isabet oranı, geri çağırma (recall), oturum başına iyi yanıt oranı ve kullanıcı memnuniyeti (thumbs up/down) gibi iş metriklerini takip edin.

Güvenlik, maliyet ve gizlilik

Kurumsal verilerle çalışırken erişim kontrolü, PII maskeleme ve denetim kayıtları (audit logs) şarttır. Maliyet tarafında embedding üretimi ve vektör arama en büyük kalemler olabilir; partisyonlama, sıkıştırma (PQ/IVF) ve önbellekleme ile maliyeti düşürün. Gizlilik gereksinimi yüksekse açık kaynak embedding ve yerel vektör veritabanı ile tamamen şirket içi (on-prem) kurulum yapılabilir.

Sonuç RAG, üretken yapay zekâyı pratik ve güvenilir hale getiren güçlü bir yöntemdir. Hızlı prototipleme için LangChain ve LlamaIndex iki sağlam seçenektir: İlki geniş entegrasyonları ve zincir mimarisiyle esneklik sunarken, ikincisi doküman odaklı basitliğiyle hızlı değer üretir. Doğru embedding, uygun vektör veritabanı, dikkatli chunking ve iyi bir değerlendirme disipliniyle kısa sürede, şirket verinizle konuşabilen sağlam bir asistan inşa edebilirsiniz.