Platform Mimarisi

Knowentra; kurumsal bilgi, üretken yapay zekâ, agent araçları ve workflow otomasyonunu aynı yönetişim sınırları içinde birleştirir. Platform tek bir “AI uygulaması” değildir: kullanıcı deneyimi, kimlik ve politika, bilgi erişimi, model güvenliği, workflow yürütme ve entegrasyon katmanlarının birlikte çalıştığı bir sistemdir.

Bu rehber, bileşenlerin mantıksal sorumluluklarını ve aralarındaki güven sınırlarını açıklar. Fiziksel topoloji; şirket içi, hibrit veya yönetilen kurulum modeline göre değişebilir.

KaynaklarBelgeler · DB · API

GüvenlikKimlik · Politika · DLP

Bilgiİndeks · Arama · Kaynak

OrkestrasyonWorkflow · Onay · Retry

DeneyimChat · Agent · API

Tasarım ilkeleri

Platform mimarisi beş temel ilkeye dayanır:

1. Kimlik önce gelir. Bilgiye, agent'a veya araca erişim kullanıcı kimliği ve kurumsal üyelik bağlamı kurulmadan değerlendirilmez.
2. Politika modelden önce uygulanır. Veri sınıflandırma, maskeleme ve egress kararları model çağrısından önce verilir.
3. Tanım ile çalıştırma ayrılır. Agent ve workflow tanımları kontrol düzleminde yönetilir; gerçek çalıştırmalar ayrı yürütme sınırlarında izlenir.
4. Etkiler açıkça sınırlandırılır. Salt-okunur bilgi erişimi ile dış sistemde değişiklik yapan araçlar aynı risk sınıfında değerlendirilmez.
5. Bileşenler değiştirilebilir. Model sağlayıcısı, vektör veritabanı, dosya depolama veya entegrasyon seçimi platformun bütününü yeniden tasarlamayı gerektirmez.

Mantıksal katmanlar

1. Deneyim katmanı

Kullanıcının doğrudan gördüğü yüzeyleri içerir:

• Chat ve kaynak gösterimli yanıtlar
• Knowledge Hub ve Space yönetimi
• Agent oluşturma, test etme ve yayınlama
• Workflow tasarım alanı
• AI Feed, bildirimler ve çalıştırma sonuçları
• Yönetim ekranları ve API erişimi

Deneyim katmanı bir yetkilendirme kaynağı değildir. Arayüzde bir düğmenin gizlenmesi güvenlik kontrolü sayılmaz; her hassas işlem sunucu tarafında yeniden doğrulanır.

2. Kontrol düzlemi

Kontrol düzlemi, sistemin “neye izin verildiğini” tanımlar:

• Organizasyon, departman, Space ve üyelikler
• Rol tabanlı yetkiler
• Agent tanımları, sürümleri ve yayın durumu
• Workflow tanımları, tetikleyicileri ve bağlantıları
• Model ve güvenlik politikaları
• Connector yapılandırmaları ve credential referansları

Credential değerlerinin workflow veya agent tanımına düz metin olarak gömülmemesi gerekir. Tanımlar bir gizli değer referansı taşır; gerçek değer yalnızca yetkili çalıştırma anında çözülür.

3. Bilgi katmanı

Bilgi katmanı, kaynaktan yanıta uzanan RAG yaşam döngüsünü yönetir:

Kaynak → Alma → Ayrıştırma → Bölümleme → Embedding → İndeks
                                                     ↓
Yanıt ← Kaynaklandırma ← Bağlam oluşturma ← Yetkili retrieval

Connector bir kaynağı senkronize eder; ayrıştırıcı içeriği kullanılabilir metne dönüştürür; embedding servisi metni vektörleştirir; indeks ise erişim filtreleriyle birlikte arama yapar. Retrieval sonucunun bulunması, kullanıcının belgeyi görmeye yetkili olduğu anlamına gelmez. Space, departman ve belge seviyesi filtreler sorgu sırasında uygulanmalıdır.

Knowentra dağıtıma göre PGVector, Qdrant, Milvus veya Chroma gibi farklı vektör depolarıyla çalışabilir. Bu nedenle “vektör veritabanı” mantıksal bir sorumluluktur, tek bir zorunlu ürün değildir.

4. Model ve güvenlik katmanı

Model çağrısı, özellikle harici sağlayıcı kullanıldığında, açık bir egress sınırından geçer. Tipik sıra şöyledir:

İstek → Yetki → Veri politikası → LLM Secure Gateway → Model endpoint'i
Yanıt ← Çıktı politikası / guardrail ← Model yanıtı

LLM Secure Gateway'in temel görevi hassas veriyi tespit etmek ve politikaya göre maskelemektir. Geri döndürülebilir modda izin verilen değerler yanıt sonrasında kontrollü biçimde geri yüklenebilir. Gateway; model yönlendirme, maliyet optimizasyonu veya anahtar kasasıyla aynı şey değildir. Bu sorumluluklar ayrı bileşenlerde tutulmalıdır.

Organizasyon politikası temel sınırı belirler. Departman politikası daha sıkı koruma ekleyebilir; üst seviyedeki korumayı zayıflatamaz. Politika bulunamadığında güvenli varsayılan davranış tercih edilir.

5. Agent ve araç katmanı

Agent; model, talimat, bilgi kapsamı ve izin verilen araçların sürümlenebilir birleşimidir. Bir araç çağrısı şu zincirin tamamını geçmelidir:

Kullanıcı → Organizasyon üyeliği → Departman/Space → Agent sürümü
         → Araç izni → İşlem izni → Credential kapsamı → Dış sistem

Araç kataloğunda bir işlemin görünmesi, her agent'ın onu kullanabileceği anlamına gelmez. Yayınlanan agent sürümü yalnızca açıkça atanmış araçları kullanır. Yazma veya silme etkisi olan işlemler ek onay, dar credential ve idempotency kontrolü gerektirebilir.

6. Workflow yürütme katmanı

Workflow motoru, çok adımlı süreçleri bloklardan oluşan bir yürütme grafiği olarak çalıştırır. Tetikleyici bir zamanlama, webhook, olay, API çağrısı veya kullanıcı eylemi olabilir.

Yürütme katmanı şunlardan sorumludur:

• Grafiği doğrulamak ve çalıştırılabilir adıma dönüştürmek
• Blok girdilerini ve çıktıları taşımak
• Retry, timeout ve hata yollarını uygulamak
• Çalıştırma durumunu kalıcılaştırmak
• Gerektiğinde insan onayı için duraklatmak ve devam ettirmek
• Sonucu, logları ve bildirimleri Knowentra yüzeyine iletmek

Workflow tasarım yüzeyi ile yürütme servisi aynı güven sınırında varsayılmamalıdır. Servisler arası çağrılar kısa ömürlü imza veya dahili API kimliğiyle doğrulanmalı; tarayıcıya dahili anahtar verilmemelidir.

7. Entegrasyon katmanı

Knowentra'da üç entegrasyon türünü ayırmak önemlidir:

Aynı SaaS ürünü hem bilgi connector'ı hem workflow entegrasyonu sağlayabilir. Ancak ilkinde amaç aranabilir bilgi üretmek, ikincisinde ise iş sürecinde kontrollü bir etki oluşturmaktır.

Veri ve depolama sorumlulukları

Redis ve gerçek zamanlı servisler küçük tek-node kurulumlarda zorunlu olmayabilir. Çoklu instance, paylaşımlı oturum, socket koordinasyonu veya yoğun arka plan işleri devreye girdiğinde ortak koordinasyon katmanı gerekir.

Temel istek akışları

RAG destekli bir soru

1. Kullanıcı oturumu ve organizasyon üyeliği doğrulanır.
2. Seçili agent ve Space erişimi kontrol edilir.
3. Sorgu, yalnızca izin verilen kaynak filtreleriyle vektör indeksinde aranır.
4. En ilgili bölümler, kaynak kimlikleri korunarak bağlama eklenir.
5. Veri politikası uygulanır; gerekiyorsa hassas alanlar maskelenir.
6. Model yanıt üretir.
7. Çıktı kontrol edilir ve kaynaklarla birlikte kullanıcıya sunulur.
8. Sorgu, kullanılan agent sürümü ve güvenlik kararları audit olayına bağlanır.

Agent araç çağrısı

1. Model yalnızca agent sürümüne atanmış araç şemalarını görür.
2. Önerilen araç girdisi sunucuda şemaya göre doğrulanır.
3. Kullanıcı, işlem ve credential kapsamları yeniden kontrol edilir.
4. Riskli eylem varsa workflow/onay sınırına aktarılır.
5. Entegrasyon çağrısı timeout ve idempotency politikasıyla yürütülür.
6. Sonuç modele geri verilir; dış sistem etkisi ayrıca kaydedilir.

Connector senkronizasyonu

1. Zamanlama veya olay senkronizasyon işi oluşturur.
2. Worker, connector credential'ını yetkili kapsamda çözer.
3. Yalnızca değişen içerik alınır; silinmiş kaynaklar işaretlenir.
4. İçerik ayrıştırılır, bölümleme ve embedding işlemleri yapılır.
5. Yeni indeks atomik veya sürümlü biçimde kullanılabilir hâle gelir.
6. Başarı, kısmi hata ve son checkpoint kaydedilir.

Workflow çalıştırması

1. Tetikleyici doğrulanır ve tekil bir çalıştırma kimliği üretilir.
2. Workflow'un yayınlanmış sürümü sabitlenir.
3. Her blok girdisi, yetkisi ve credential kapsamı değerlendirilir.
4. Ara durumlar kalıcılaştırılır; yeniden deneme aynı etkiyi çoğaltmamalıdır.
5. Onay adımı varsa yürütme güvenli bir snapshot ile duraklar.
6. Tamamlanma veya hata sonucu AI Feed, webhook ya da ilgili kanala iletilir.

Senkron ve asenkron sınır

Kullanıcının beklediği kısa model yanıtı veya salt-okunur araç sorgusu senkron ilerleyebilir. Uzun süren işler arka plan yürütmesine aktarılmalıdır:

• Büyük dosya ayrıştırma ve embedding
• Connector senkronizasyonu
• Uzun workflow'lar ve zamanlanmış işler
• Toplu bildirim veya raporlama
• Yeniden indeksleme ve veri yaşam döngüsü işlemleri

Asenkron işin API cevabı “tamamlandı” değil, izlenebilir bir iş kimliği vermelidir. Kullanıcı durumu sonradan görüntüleyebilmeli; retry işlemleri aynı dış etkiyi iki kez oluşturmamalıdır.

Güven sınırları

Arıza etkisi ve güvenli davranış

“Fail open” yalnızca belgelenmiş, düşük riskli ve bilinçli seçilmiş senaryolarda kullanılmalıdır. Özellikle kimlik, veri egress'i ve yazma etkili araçlarda varsayılan davranış kapalı kalmaktır.

Ölçekleme modeli

Ölçekleme ihtiyacı her katmanda aynı değildir:

• Web/API instance'ları mümkün olduğunca stateless tutulup yatay ölçeklenir.
• Workflow worker'ları iş yoğunluğu ve dış sistem limitlerine göre bağımsız ölçeklenir.
• Embedding ve model servisleri GPU/CPU kapasitesine göre ayrı ölçeklenir.
• Vektör deposu sorgu ve indeksleme yükü birlikte ölçülerek boyutlandırılır.
• Gerçek zamanlı bağlantılar ortak koordinasyon ve sticky-session ihtiyacı açısından test edilir.
• Arka plan işleri için queue depth, iş yaşı ve dead-letter sayısı izlenir.

Yatay ölçekleme, tek başına yüksek erişilebilirlik sağlamaz. Paylaşılan veritabanı, obje depolama, gizli değer yönetimi ve yedekleme katmanlarının da aynı hata alanına bağımlı olmaması gerekir.

Gözlemlenebilirlik

Bir kullanıcı işlemini katmanlar arasında takip edebilmek için ortak bir correlation veya trace kimliği kullanılmalıdır. En az şu olaylar ilişkilendirilebilir olmalıdır:

• Kullanıcı ve organizasyon bağlamı
• Agent ve workflow sürümü
• Retrieval sorgusu ve kaynak kimlikleri
• Uygulanan güvenlik politikası ve maskeleme kararı
• Model sağlayıcısı, gecikme ve token kullanımı
• Araç/connector işlemi ve dış sistem sonucu
• Onay veren kişi ve karar zamanı

Prompt, model yanıtı veya connector payload'ı loglanacaksa veri sınıflandırma ve saklama politikası uygulanmalıdır. Gözlemlenebilirlik, yeni bir hassas veri kopyası üretmemelidir.

Mimari inceleme kontrol listesi

Üretim tasarımını onaylamadan önce şu soruları yanıtlayın:

• Her ağ geçişinde kimlik doğrulayan taraf ve kullanılan servis kimliği belli mi?
• Harici modele hangi veri sınıflarının çıkabileceği açık mı?
• Organizasyon, departman ve Space filtreleri retrieval sırasında uygulanıyor mu?
• Yazma etkili araçlarda onay, idempotency ve en az ayrıcalık var mı?
• Credential değerleri tanımlardan ve loglardan ayrılmış mı?
• Uzun işler kalıcı ve izlenebilir asenkron çalıştırmalara dönüşüyor mu?
• Her kritik servisin timeout, retry ve fail-open/fail-closed davranışı tanımlı mı?
• Yedekten dönüş; ilişkisel veri, dosyalar ve vektör indeksinin tutarlılığıyla test edildi mi?
• Audit olayları bir kullanıcı isteğini model ve dış sistem etkisine kadar izleyebiliyor mu?
• Kapasite testi model, retrieval, workflow ve realtime katmanlarını ayrı ayrı ölçüyor mu?

Sonraki adımlar

• İlk ortamı hazırlamak için Hızlı Başlangıç
• Fiziksel topolojiyi seçmek için Dağıtım Modelleri rehberi
• Bilgi erişiminin ayrıntıları için RAG Sistemi
• Yetki yapısı için Organizasyon Modeli
• Politika uygulaması için LLM Güvenliği