TROIA'nın "eski" ve "yeni" entegrasyon dünyaları aynı çatı altında

Bir CANIAS danışmanı olarak birkaç yıl önce entegrasyon dendiğinde aklıma gelen ilk şeyler FTP, web servis ve dosya alışverişiydi. Bugün aynı platformda Kafka, RabbitMQ ve vektör veritabanlarına bağlanabiliyor olmak — özellikle RAG (Retrieval-Augmented Generation) tabanlı LLM entegrasyonları için — TROIA'nın hâlâ aktif geliştirilen bir platform olduğunun somut kanıtı. Bunların hepsi tek bir ortak altyapı üzerinden yönetiliyor: Endpoint.

Endpoint nedir, neden ayrı bir soyutlama katmanı var

Belgelerin tanımıyla bir endpoint, "TROIA sunucusu dışındaki bir şeye erişmek istediğinizde oluşturmanız gereken bir tanım." Pratikte bunun anlamı: bağlantı bilgilerini (sunucu adresi, kimlik bilgileri, port) kod içine gömmek yerine merkezi bir tanıma (SYSENDPOINTS) taşıyorsunuz — tıpkı 26Domains yazısında anlattığım domain kavramının veri alanları için yaptığını, endpoint bağlantılar için yapıyor. Bu ayrıca kullanıcı/profil bazlı yetkilendirme de sağlıyor: hangi kullanıcının hangi dış sisteme erişebileceğini merkezi olarak kontrol edebiliyorsunuz.

Desteklenen ana endpoint tipleri: Qdrant, RabbitMQ, Kafka, RedPanda, Mongo. Build'e göre bu liste genişleyebiliyor; güncel listeyi kod içinden GETENDPOINTTYPES() fonksiyonuyla sorgulayabilirsiniz.

Bağlantı açma ve kapama

MAKEENDPOINTCONNECTION {baglantiadi} ENDPOINTID {endpointid} [TIMEOUT {zamanasimi}];
CLOSEENDPOINTCONNECTION {baglantiadi};

Tüm konfigürasyon detayları (SYSENDPOINTS'teki tanımdan) otomatik okunuyor — koda sadece hangi endpoint tanımını kullanacağınızı (ENDPOINTID) veriyorsunuz. Belgelerdeki uyarı net: "bir bağlantı açtığınızda, mümkün olan en kısa sürede kapatmalısınız." Transaction sona erdiğinde açık kalan bağlantılar otomatik kapanıyor olsa da, bu bir güvenlik ağı, alışkanlık değil.

Vektör veritabanı: koleksiyon yönetimi ve arama

Vektör veritabanları, metni "embedding" adı verilen sayısal vektörlere çevirip anlam benzerliğine göre arama yapmayı sağlıyor — bir LLM'e soru sormadan önce ilgili bağlamı bulmak (RAG) için kullanılan standart teknik. TROIA, VECTORDBACTION komutuyla koleksiyon yönetimini (COLLECTIONEXISTS, COLLECTIONLIST, CREATECOLLECTION, DELETECOLLECTION) ve arama işlemlerini kapsıyor.

/* Embedding hesapla, koleksiyona ekle, sonra ara. */
LOCAL:
    STRING EMBEDDINGDEGERI;
    TABLE CHUNKS(ID CHAR(50), CONTENT CHAR(2000), EMBEDDINGS CHAR(4000));

MAKEENDPOINTCONNECTION VECTORBAGLANTI ENDPOINTID 51;

LLMACTION GETEMBEDDINGS CONNECTIONNAME VECTORBAGLANTI
    MODELID 'text-embedding-3' PROMPT 'CANIAS ERP nedir?' TO EMBEDDINGDEGERI;

/* CHUNKS tablosunu ID/CONTENT/EMBEDDINGS ile doldurduğunuzu varsayalım */
VECTORDBACTION ADDEMBEDDINGS CONNECTIONNAME VECTORBAGLANTI
    COLLECTIONNAME 'dokumanlar' CHUNKSTABLE CHUNKS;

VECTORDBACTION SEARCH CONNECTIONNAME VECTORBAGLANTI
    COLLECTIONNAME 'dokumanlar' EMBEDDINGS EMBEDDINGDEGERI
    LIMIT 5 THRESHOLD 0.80 INTO SONUCLAR;

CLOSEENDPOINTCONNECTION VECTORBAGLANTI;

RELATEDPOINTKEY ile gelişmiş bir arama modu da var: benzerlik araması sonrası, sonuçlardan birinin belirttiğiniz kolonda (örneğin BOOKID) aynı değere sahip tüm kayıtları da getiriyor — bir dokümanın bir parçası eşleştiğinde, o dokümanın diğer parçalarını da otomatik toplamak istediğinizde işe yarıyor.

Kritik pratik not: Yazma ve arama sırasında aynı embedding modelini kullanmak zorunludur — farklı modellerle üretilmiş vektörler aynı koordinat sisteminde anlam ifade etmez, benzerlik skorları anlamsız çıkar. Bir koleksiyona veri eklerken hangi modeli kullandığınızı not almadan aylar sonra farklı bir modelle arama yapmaya çalışmak, sessizce kötü sonuçlar üretir.

Sık yapılan hatalar

  • Bağlantıyı kapatmayı ihmal etmek — belgelerin özellikle vurguladığı nokta bu; açık kalan endpoint bağlantıları, özellikle Kafka/RabbitMQ gibi mesajlaşma sistemlerinde sunucu tarafında kaynak tüketimine yol açabilir.
  • Yazma ve arama embedding modelini farklı tutmak — yukarıda değindiğim gibi bu, benzerlik aramasının sessizce anlamsız sonuçlar döndürmesine yol açan en sinsi hatalardan biri.
  • Endpoint ID'yi yanlış vermek ya da aynı bağlantı adını tekrar kullanmak — belgeler bunu yaygın sorunlar arasında sayıyor; hata durumunda SYS_STATUS/SYS_STATUSERROR her zaman kontrol edilmeli.
  • Sunucu seviyesinde endpoint erişiminin açık olduğunu varsaymak — bir endpoint tanımlı olsa bile, sunucu ya da kullanıcı seviyesinde erişim izni yoksa bağlantı reddedilir; "tanım var ama bağlanamıyorum" şikayetinde yetki kontrolü ilk durak olmalı.

Sıradaki adım

XML/JSON ayrıştırmayı (özellikle web servis yanıtlarını işlemek için) bir sonraki yazıda ele alacağım.