RAQS uçtan uca nasıl çalışır?

1. Adım — Tek satır script ve embed

Her şey sitenize eklediğiniz tek bir <script> satırıyla başlar. Bu betik tarayıcıda asenkron yüklenir, sayfanızın ağırlığını artırmaz ve kendi izole arayüzünü (orb veya 3D maskot) sayfaya yerleştirir. Betik, panelde tanımladığınız site anahtarınızı taşır; arka uç bu anahtarı kullanarak doğru kiracıyı (tenant) ve onun bilgi tabanını seçer.

Betik yüklenirken iki şey doğrulanır: isteğin geldiği origin'in izinli domainler listesinde (allowlist) olup olmadığı ve Cloudflare Turnstile ile kötüye kullanıma karşı koruma. Bu sayede başkaları sizin anahtarınızı kendi sitesine kopyalayıp kullanamaz. Arayüz hazır olduğunda ziyaretçi orb'a dokunabilir veya tarayıcı uyandırma kelimesini yakalayabilir.

<script async src="https://raqs.ai/v1/raqs.js"
  data-raqs="SİTE_ANAHTARINIZ"></script>

2. Adım — Uyandırma ve gerçek-zaman ses kanalı

Ziyaretçi konuşmaya başlamak için orb'a (ya da 3D maskota) dokunur; dilerseniz tarayıcının Web Speech API'siyle bir uyandırma kelimesi de dinlenir. Uyandırma kelimesi tamamen tarayıcı içinde çalışır, yani sürekli bir ses akışı sunucuya gönderilmez — yalnızca tetiklendiğinde oturum açılır. Bu hem gizlilik hem de gecikme için önemlidir.

Oturum açıldığında ses, düşük gecikmeli bir gerçek-zaman taşıma katmanı olan LiveKit üzerinden taşınır. LiveKit, WebRTC tabanlı çift yönlü bir kanal kurar: ziyaretçinin mikrofonundan gelen ses sunucuya, asistanın seslendirilmiş yanıtı da geri ziyaretçiye akışlı (streaming) olarak iletilir. Bu çift yönlü kanal, asistan konuşurken araya girebilme (barge-in) özelliğini mümkün kılar — ziyaretçi yarıda konuşmaya başladığında asistan susar ve dinlemeye geçer.

3. Adım — Konuşmayı metne çevirme (Azure STT)

Gerçek-zaman kanalına ulaşan ses, Pipecat tabanlı sesli işlem hattının (pipeline) ilk durağına girer ve Azure Speech ile metne dökülür (STT — speech to text). Azure STT akışlı çalışır: ziyaretçi cümlesini bitirmeden kelimeler çözülmeye başlar ve doğal duraklamalardan cümlenin bittiği anlaşılır. Bu, 'konuşmanın sonunu bekleyip sonra işleme alma' gecikmesini ciddi ölçüde azaltır.

Türkçe ve İngilizce desteklenir; hangi dilin konuşulduğu algılanır ve aynı dilde devam edilir. Çözümlenen metin, bir sonraki adımda hem bilgi tabanını sorgulamak hem de dil modeline soru olarak vermek için kullanılır.

4. Adım — Hibrit RAG ile sitenizin içeriğinden bilgi getirme

Bu adım RAQS'ın kalbidir ve 'RAG nasıl çalışır' sorusunun cevabıdır. RAG (Retrieval-Augmented Generation), dil modeline cevap ürettirmeden önce ona sizin içeriğinizden ilgili bölümleri bulup vermek demektir. Önceden bilgi tabanınızı hazırlamış olursunuz: sitenizi taratırsınız (sitemap + sayfalar; JS ile render edilen SPA siteleri için headless tarayıcı kullanılır; içerik trafilatura ile temiz çıkarılır; robots.txt'e uyulur; plana göre sayfa kotası vardır), ya da düz metin/SSS yapıştırır veya PDF, Word, TXT, MD, CSV dosyaları yüklersiniz.

Bu içerik anlamlı parçalara (chunk) bölünür, Azure embeddings (text-embedding-3-small) ile vektörlere çevrilir ve pgvector'da saklanır. Soru anında hibrit retrieval devreye girer: bir yandan anlamsal vektör araması (sorunun anlamına en yakın parçalar) yapılır, bir yandan Postgres tam-metin araması (FTS) ile birebir kelime/terim eşleşmeleri bulunur. İki liste RRF (Reciprocal Rank Fusion) ile birleştirilir; böylece hem 'aynı anlama gelen ama farklı kelimelerle yazılmış' içerik hem de 'tam o terimi içeren' içerik kaçırılmaz. Bir benzerlik eşiği, alakasız parçaları eler.

E-ticaret sitelerinde ürün sayfalarındaki schema.org JSON-LD verisi (ürün adı, marka, fiyat, stok, kategori) ayrıca yapılandırılmış şekilde çıkarılır. Böylece 'X ürünü stokta var mı, kaç para?' gibi sorular serbest metinden tahmin yerine gerçek ürün verisiyle yanıtlanır.

5. Adım — Azure OpenAI ile cevabı üretme

Getirilen ilgili içerik parçaları, ziyaretçinin sorusuyla birlikte Azure OpenAI gpt-4o-mini modeline verilir. Modelden kesin bir kural istenir: yalnızca verilen bağlamdan yanıt ver; bağlamda yoksa uydurma, 'bilmiyorum' de. Bu, RAQS'ın halüsinasyon görmemesinin (uydurmamasının) temel nedenidir — model serbestçe konuşmaz, elindeki sizin içeriğinizle sınırlıdır.

Yanıt akışlı (streaming) olarak üretilir; ilk kelimeler hazır olur olmaz bir sonraki adıma geçer, böylece ziyaretçi tüm cevabın üretilmesini beklemez. Asistanın tonu, persona'sı ve adı panelden ayarladığınız şekilde yanıta yansır.

6. Adım — Seslendirme (TTS) ve isteğe bağlı ajan aksiyonu

Üretilen metin Azure Speech ile sese çevrilir (TTS — text to speech) ve aynı LiveKit kanalı üzerinden ziyaretçiye akışlı olarak geri çalınır. Akışlı olması sayesinde asistan, cevabın tamamı yazılmadan konuşmaya başlayabilir; bu, algılanan gecikmeyi azaltan kritik bir noktadır.

Bazı turlarda cevap sadece konuşmak değildir. RAQS sayfayı 'görür' ve ajan aksiyonları yapabilir: ziyaretçiyi doğru ürüne veya sayfaya yönlendirir, listeden bir öğeyi gösterir, sepete ekleme gibi eylemleri tetikler. Burada bir güvenlik katmanı devrededir: ödeme, hesap veya silme gibi hassas işlemler her zaman ziyaretçinin açık onayını gerektirir — asistan bunları kendi başına yapmaz.

Gecikme, gizlilik ve her turda ne olur

Bir tur baştan sona şöyle akar: konuş → gerçek-zaman taşıma (LiveKit) → Azure STT → hibrit RAG retrieval (pgvector + FTS + RRF) → Azure OpenAI cevap → Azure TTS → isteğe bağlı ajan aksiyonu. Her aşamanın akışlı (streaming) olması, toplam gecikmeyi düşürmek için bilinçli bir tasarımdır; ziyaretçi, cevabın her parçasının önceki parça hazır olur olmaz başladığını duyar.

Gizlilik açısından iki ilke önemlidir. Birincisi, asistan yalnızca sizin bilgi tabanınızdan cevap verir; içerikte olmayan bir şey sorulduğunda uydurmak yerine bilmediğini söyler. İkincisi, mimari çok kiracılıdır ve veriler satır düzeyi güvenlik (RLS) ile izole edilir — bir müşterinin içeriği başka bir müşteriye asla sızmaz. Tarayıcı SSRF korumalıdır, origin allowlist ve Turnstile kötüye kullanımı engeller, barındırma Azure'un Avrupa bölgesindedir ve sistem KVKK ile GDPR farkındalığıyla tasarlanmıştır.