Kişisel web siteme bir yapay zekâ asistanı eklemek istediğimde, hazır bir ChatGPT entegrasyonunun yetmeyeceğini biliyordum. Asistanın benim hakkımda doğru bilgi vermesi, projelerimi tanıması ve bilmediği bir şey sorulduğunda uydurmaması gerekiyordu. Çözüm RAG mimarisiydi. Bu yazıda hem RAG'ın ne olduğunu hem de kendi sitemde nasıl kurduğumu anlatıyorum.

Problem: dil modelleri sizi tanımıyor

Büyük dil modelleri, eğitim verilerinde olmayan bir konuda soru aldıklarında susmazlar — makul görünen bir cevap üretirler. Kişisel veya kurumsal bir asistan için bu kabul edilemez. "Gürkan Karaca hangi projeleri yaptı?" sorusuna modelin kendi bilgisiyle vereceği cevap, en iyi ihtimalle boş, en kötü ihtimalle yanlış olur.

İki çözüm yolu var: modeli kendi verinizle yeniden eğitmek (fine-tuning) veya modele cevap üretirken doğru belgeleri elinin altına vermek. İkincisi hem çok daha ucuz hem de bilgi değiştiğinde güncellemesi kolay. Buna Retrieval-Augmented Generation, kısaca RAG deniyor.

RAG nasıl çalışır?

Mantık aslında sade. Sistem, kullanıcıdan bir soru geldiğinde önce cevabı üretmez; önce arar.

• Hazırlık aşaması: Elinizdeki belgeler anlamlı parçalara bölünür, her parça bir embedding (sayısal vektör) haline getirilir ve vektör veritabanına yazılır.
• Soru geldiğinde: Sorunun kendisi de aynı yöntemle vektöre çevrilir ve veritabanında anlamca en yakın parçalar bulunur.
• Cevap üretimi: Bulunan parçalar, soruyla birlikte dil modeline bağlam olarak verilir. Model artık tahmin etmez, önüne konan metinden cevap yazar.

Kritik nokta şu: model yalnızca kendisine verilen bağlamdan cevap üretmeye yönlendirilir. Bağlamda cevap yoksa "bu bilgi elimde yok" demesi gerekir. Bunu sağlamak mimarinin en önemli parçası.

Sitemdeki kurulum

Kendi asistanımda kullandığım bileşenler:

• Vektör veritabanı: Pinecone — profil bilgilerimi, sık sorulan soruları ve proje detaylarını embedding olarak saklıyor
• Embedding modeli: OpenAI text-embedding-3-small — metinleri vektöre çeviriyor
• Dil modeli: GPT-4o-mini — bağlamı alıp doğal bir yanıt üretiyor
• Sunucu tarafı: Cloudflare Pages Functions — API uçlarını serverless olarak çalıştırıyor, API anahtarları tarayıcıya hiç inmiyor

Bilgi tabanının kaynağı olarak ayrı bir doküman seti tuttum: profil bilgileri, proje açıklamaları ve soru-cevap formatında hazırlanmış bir SSS dosyası. Bunları sitenin içeriğinden ayrı tutmak, chatbot'un ne bileceğini kontrol edebilmemi sağlıyor.

Uygulamada öğrendiklerim

Parçalama (chunking) sonucu doğrudan etkiliyor. Belgeleri çok büyük parçalara bölerseniz modele alakasız bilgi de gidiyor ve cevap dağılıyor. Çok küçük parçalara bölerseniz bu sefer bağlam kopuyor. Konu başlığı bütünlüğünü koruyacak şekilde bölmek en iyi sonucu verdi.

Bilgi tabanı, sitenin kendisinden daha kritik. Chatbot ne kadar iyi kurulursa kurulsun, beslediğiniz belge eksikse cevaplar da eksik oluyor. Zamanın büyük bölümü kod yazmaya değil, bilgi tabanını düzenlemeye gidiyor.

Çok dillilik baştan planlanmalı. Sitem Türkçe ve İngilizce çalışıyor. Bilgi tabanını iki dilde ayrı ayrı hazırlamak, tek dilde tutup çeviri yaptırmaktan çok daha tutarlı sonuç veriyor.

Sınırları yazılı olarak koymak gerekiyor. Sistem talimatında modelin neyi yapmayacağını açıkça belirtmezseniz, bağlam dışına çıkıp genel bilgi vermeye başlıyor.

Kimler için mantıklı?

RAG, elinde okunması zor miktarda belge olan herkes için anlamlı: mevzuat ve prosedür dokümanları, toplantı kararları, ürün kataloğu, teknik kılavuzlar, proje arşivi. Özellikle "bu bilgi bir yerde yazıyordu ama nerede olduğunu kimse bilmiyor" cümlesinin sık kurulduğu yerlerde geri dönüşü yüksek oluyor.

Kendi belgelerinizle çalışan bir asistan kurmayı düşünüyorsanız iletişim bölümünden yazabilirsiniz. Bu tür sistemleri birbirine bağlayan otomasyon tarafını n8n yazısında anlattım.

When I decided to add an AI assistant to my personal site, I knew an off-the-shelf ChatGPT integration would not be enough. The assistant had to give accurate information about me, know my projects, and — crucially — not invent an answer when asked something it did not know. The solution was a RAG architecture. This post covers what RAG is and how I built it on my own site.

The problem: language models don't know you

When a large language model is asked about something outside its training data, it does not stay silent — it produces a plausible-looking answer. For a personal or corporate assistant that is unacceptable. Asked "which projects has Gürkan Karaca delivered?", a model relying on its own knowledge will be empty at best and wrong at worst.

There are two ways out: retrain the model on your data (fine-tuning), or hand the model the right documents at answer time. The second is far cheaper and much easier to update when information changes. That approach is called Retrieval-Augmented Generation, or RAG.

How RAG works

The logic is straightforward. When a question arrives, the system does not answer first — it searches first.

• Preparation: your documents are split into meaningful chunks, each chunk is converted into an embedding (a numeric vector) and written to a vector database.
• On a question: the question itself is embedded the same way, and the semantically closest chunks are retrieved.
• Answer generation: those chunks are passed to the language model as context alongside the question. The model no longer guesses; it writes from the text in front of it.

The critical part: the model is instructed to answer only from the provided context. If the answer is not there, it should say so. Getting that behaviour right is the most important piece of the architecture.

The setup on my site

• Vector database: Pinecone — stores my profile information, FAQs and project details as embeddings
• Embedding model: OpenAI text-embedding-3-small
• Language model: GPT-4o-mini — takes the context and produces a natural answer
• Server side: Cloudflare Pages Functions — runs the API endpoints serverless, so API keys never reach the browser

I keep a separate document set as the knowledge source: profile information, project descriptions and an FAQ written in question-and-answer form. Keeping this separate from the site's own content lets me control exactly what the chatbot knows.

What I learned in practice

Chunking drives the result. Split documents too coarsely and irrelevant material reaches the model, blurring the answer. Split too finely and context breaks apart. Splitting along topic boundaries worked best.

The knowledge base matters more than the code. However well the chatbot is built, incomplete source documents produce incomplete answers. Most of the effort goes into curating the knowledge base, not writing code.

Plan for multiple languages from the start. My site runs in Turkish and English. Preparing the knowledge base separately in both languages gives far more consistent results than keeping one language and translating on the fly.

Boundaries have to be written down. Unless the system prompt states explicitly what the model must not do, it drifts outside the context and starts offering general knowledge.

Who is it for?

RAG makes sense for anyone sitting on more documentation than people can reasonably read: regulations and procedures, meeting decisions, product catalogues, technical manuals, project archives. The return is highest wherever someone regularly says "that was written down somewhere, but nobody knows where".

If you are considering an assistant grounded in your own documents, get in touch through the contact section. The automation layer that connects systems like this is covered in the n8n post.