Spring AI ve Oracle Veritabanı: Bir Yapay Zekâ Ajanına Hafıza Kazandırma

Her LLM'in aynı sorunu var: Sohbet biter bitmez her şeyi unutuyor, hatta bazen uzun sohbetlerin ortasında bile. Yirmi dakika boyunca proje kurulumunuzu, kısıtlarınızı ve tercihlerinizi anlatın; yanıtı tam isabet olur. Sekmeyi kapatın, yeni bir oturum açın; sizi yabancı gibi karşılar. Tüm o bağlam uçup gitmiş.

Eğer bir yapay zekâ ajanı geliştirmek istiyorsanız, yani gerçekten bağlamı hatırlayan ve alanınıza dair şeyleri bilen bir şey, ona hafıza vermeniz gerekir. Gerçek anlamda; söylediklerinizi gerçekten hatırlayan ve ona öğrettiğiniz bilgileri arayıp bulabilen türden.

Ben de tam olarak bunu yapmak için bir POC oluşturdum. Üç hafıza türü, tek veritabanı, az kod. Tüm kaynak kodu GitHub'da mevcut.

Spring AI ile Yapay Zekâ Ajan Mimarisi

Şekil 1. Spring AI ve Oracle AI Database 26ai ile uçtan uca ajan hafıza mimarisi

Yığın:

• Spring Boot 3.5.11 + Spring AI 1.1.2 arka uç için
• Ollama sohbet çıkarımı (qwen2.5) için, yerelde çalışıyor
• Oracle AI Database 26ai üç hafıza deposunun tümü için; semantik getiride Hibrit Vektör Dizinleri (vektör + anahtar sözcük araması, Reciprocal Rank Fusion ile birleştirilmiş) ve veritabanı içi gömme için yüklü bir ONNX modeli (all-MiniLM-L12-v2) için
• Streamlit hızlı ve pratik bir web arayüzü için (~100 satır Python)
• Java 21, Gradle 8.14

Üç Tür Yapay Zekâ Ajan Hafızası

Ajanlar için epizodik, semantik, işlemsel ve çalışma belleğinden söz edilir. 

Çalışma belleği sadece LLM'in bağlam penceresidir; mevcut istek için etkin bir "taslak" alanı. Kalıcı değildir, bu yüzden inşa edilecek bir şey yok. Diğer üçünü uyguladım:

Epizodik hafıza: Sohbet geçmişini kalıcılaştırma

Epizodik hafıza sohbet geçmişidir. Ajan, konuşmanın önceki kısımlarında söylediklerinizi hatırlar. 1. mesajda "Benim adım Victor" demek, 50. mesajda da adınızı bildiği anlamına gelir. Bu, ilişkisel bir tabloda satırlar olarak saklanır.

Şekil 2. Epizodik hafıza sohbet geçmişidir

Semantik hafıza: RAG entegrasyonu

Semantik hafıza alan bilgisidir. Ajana gerçekler (ürün dokümanları, şirket politikaları vb.) verirsiniz ve o da soruları yanıtlarken ilgili olanları getirir. 

Bu, RAG (Retrieval-Augmented Generation)'dir: metin, anlamı geometrik uzaya haritalayan yoğun vektörlere (gömmelere) dönüştürülür; böylece semantik olarak benzer metinler birbirine yakın konumlanır. 

Ancak saf vektör aramanın kör noktaları vardır; anlamı iyi yakalar ama sipariş kimlikleri veya ürün kodları gibi tam terimlerle zorlanır. 

Bu nedenle bu POC, Oracle'ın Hibrit Vektör Dizinlerini kullanıyor; bu dizinler, vektör benzerlik araması ve anahtar sözcük (leksik) aramasını paralel çalıştırıp iki sonuç listesini Reciprocal Rank Fusion (RRF) ile birleştiriyor. 

Sorgu anında hibrit arama, anlam veya tam terim eşleşmesine göre belgeleri bulur ve en üstteki sonuçları LLM istemine enjekte eder. Gömmeler, doğrudan Oracle'a yüklenen bir ONNX modeli (all-MiniLM-L12-v2, 384 boyut) ile veritabanı içinde hesaplanır; harici gömme API çağrısı yok. Aşağıda bunun nasıl çalıştığına dair daha fazlası var.

Şekil 3. Alan bilgisi olarak semantik hafıza

İşlemsel hafıza: LLM araç çağrıları

İşlemsel hafıza "nasıl"dır; ajanın nasıl yürüteceğini bildiği adım adım iş akışlarıdır. Bir siparişi aramak, iade başlatmak, desteğe eskalasyon yapmak. Spring AI'de bunlar, LLM'in bir görevin sadece yanıt değil eylem gerektirdiğine karar verdiğinde çağırabileceği @Tool ile işaretlenmiş yöntemlerdir.

Şekil 4. İşlemsel hafızanın eylemdeki hali; ajan araç çağrılarını kullanarak canlı sipariş verilerini sorguluyor ve göreve özgü sonuçlar döndürüyor.

Şekil 5. AgentController üzerinden istek akışı; epizodik, semantik ve işlemsel hafıza Oracle AI Database tablolarından birleştirilip Ollama ile yanıt üretilmeden önce toplanıyor.

Her iki tablo da aynı Oracle Veritabanında bulunur. Pinecone yok. Redis yok. İkinci veritabanı yok. Tek bağlantı havuzu, tek kimlik bilgisi seti, izlenecek tek şey.

Spring AI Araçlarını Uygulama

İşlemsel hafıza, gerçek veritabanı tablolarını sorgulayan bir Spring bileşenindeki @Tool ile işaretlenmiş yöntemler olarak uygulanır. Burada, anlaşılırlık için basitleştirilmiş iki temsilci yöntem var; tam sınıfta toplam altı araç bulunur (bkz. AgentTools.java):

@Tool(description = "Look up the status of a customer order by its order ID. " +
        "Returns the current status including shipping information.")
public String lookupOrderStatus(
        @ToolParam(description = "The order ID to look up, e.g. ORD-1001") String orderId) {
    // Fetches order from DB via JPA, returns formatted status string
}

@Tool(description = "Initiate a product return for a given order. " +
        "Validates the order exists, checks that it is in DELIVERED status, " +
        "and verifies the return is within the 30-day return window.")
public String initiateReturn(
        @ToolParam(description = "The order ID to return") String orderId,
        @ToolParam(description = "The reason for the return") String reason) {
    // Validates order exists, checks DELIVERED status and 30-day window, updates status via JPA
}Altyapı:

@Tool açıklaması, LLM'e her bir yöntemi ne zaman kullanacağını söyler ve @ToolParam argümanları açıklar. Kullanıcı "ORD-1001 siparişini iade etmek istiyorum" dediğinde, LLM araç açıklamalarını okur, initiateReturn yönteminin doğru prosedür olduğuna karar verir, argümanları konuşmadan çıkarır, yöntemi çağırır ve sonucu yanıtına dahil eder.

Diğer dört araç şunlardır: getCurrentDateTime (geçerli tarih/saat bilgisini veritabanından çeker), listOrders, escalateToSupport ve listSupportTickets. Aynı deseni izlerler: JPA veya JDBC ile veritabanı sorguları. LLM ne zaman eyleme geçeceğine karar verir; Java yöntemleri ise nasılı tanımlar.

Spring Boot Denetleyicisini (Controller) Oluşturma

Denetleyici her şeyi birbirine bağlar; iki advisor, altı araç, bir ChatClient. İşte anlaşılırlık için sadeleştirilmiş çekirdeği (tam sürüm girdi doğrulaması, hata işleme ve konuşma yönetimi uç noktaları ekler. Bkz. AgentController.java):

@RestController
@RequestMapping("/api/v1/agent")
public class AgentController {

    public AgentController(ChatClient.Builder builder,
                           JdbcChatMemoryRepository chatMemoryRepository,
                           JdbcTemplate jdbcTemplate,
                           AgentTools agentTools) {
        // Builds a ChatClient with:
        //   - MessageChatMemoryAdvisor (episodic: last 100 messages per conversation)
        //   - RetrievalAugmentationAdvisor + OracleHybridDocumentRetriever (semantic: hybrid search)
        //   - AgentTools via .defaultTools() (procedural: 6 @Tool methods)
        //   - System prompt defining the agent persona and tool usage rules
    }

    @PostMapping("/chat")
    public ResponseEntity<String> chat(
            @RequestBody String message,
            @RequestHeader("X-Conversation-Id") String conversationId) {
        // Sends message to ChatClient with conversation ID, returns LLM response
    }

    @PostMapping("/knowledge")
    public ResponseEntity<String> addKnowledge(@RequestBody String content) {
        // Inserts text into POLICY_DOCS table via JDBC (hybrid index handles embedding)
    }
}Altyapı:

İki uç nokta, iki advisor, altı araç, bir ChatClient. Üç hafıza türünü parçalayalım.

Spring Advisor'larıyla sohbet hafızasını yönetme

Spring AI'in advisor deseni sihrin gerçekleştiği yerdir. Advisor'lar LLM'e yapılan her çağrıyı yakalar ve istem gönderilmeden önce düzenleyebilir, yanıt döndüğünde de işleyebilir.

MessageChatMemoryAdvisor epizodik hafızayı yönetir. Her LLM çağrısından önce, mevcut konuşma için son 100 mesajı SPRING_AI_CHAT_MEMORY tablosundan yükler ve istemin başına ekler. Yanıttan sonra yeni etkileşimi kaydeder. Konuşma, X-Conversation-Id başlığı ile tanımlanır: farklı kimlik, farklı hafıza.

Belge getiricilerle RAG uygulama

RetrievalAugmentationAdvisor semantik hafızayı yönetir. Her LLM çağrısından önce, özel bir OracleHybridDocumentRetriever DBMS_HYBRID_VECTOR.SEARCH çağrısı yapar; bu çağrı vektör benzerliği araması ve Oracle Text anahtar sözcük aramasını paralel çalıştırır ve sonuçları Reciprocal Rank Fusion (RRF) ile birleştirir. 

İlk 5 eşleşen belge, özel bir ContextualQueryAugmenter aracılığıyla bağlam olarak isteme enjekte edilir; bu artırıcı belgeleri tamamlayıcı olarak ele alır; LLM'e bunları yalnızca politika soruları için kullanması, eylem talepleri veya sohbet bağlamı için kullanmaması söylenir. Bu, RAG bağlamının sohbet geçmişini ezmesini veya araç çağrılarını bastırmasını engeller.

Neden saf vektör arama yerine hibrit? Yoğun gömmeler anlamı yakalar: "iade politikası" ile ilgili bir sorgu, bu kelimeler geçmese bile iade ve değişimle ilgili belgelerle eşleşir. 

Ama tam terimlerde zayıftırlar: "ORD-1001" araması, gömme modelinin anahtar sözcükleri değil semantiği kodlaması nedeniyle zayıflar. Hibrit arama her ikisini karşılar: vektör tarafı anlamı, anahtar sözcük tarafı tam eşleşmeleri yakalar ve RRF, uyumsuz puanları normalize etmeye çalışmak yerine iki sonuç listesini sıralama pozisyonuna göre birleştirir.

Ajan araçlarının kaydedilmesi

AgentTools işlemsel hafızayı yönetir. .defaultTools(agentTools) çağrısı, bileşendeki altı @Tool ile işaretlenmiş yöntemin tümünü kaydeder. Her istekte, LLM kullanıcı mesajıyla birlikte araç açıklamalarını alır. Görev yalnızca bilgi getirimi değil eylem gerektiriyorsa, LLM uygun aracı çağırır, sonucu alır ve yanıtına işler. Spring AI araç çağrısı protokolünü otomatik olarak yönetir.

Üç hafıza türü de her istekte çalışır. Ajan aynı anda söylediklerinizi hatırlar, ilgili bilgiyi arar ve görevleri nasıl yerine getireceğini bilir.

Şekil 6  Sohbet geçmişi, hibrit RAG bağlamı ve isteğe bağlı araç çağrılarının birleştirilerek nihai yanıtın üretilip kalıcılaştırıldığı uçtan uca istek sıralaması.

Bir RAG bilgi uç noktası oluşturma

/knowledge uç noktası basit: Bir metni POST edin, JDBC aracılığıyla POLICY_DOCS tablosuna eklenir. Hibrit vektör indeksi, veritabanı içi ONNX modeli kullanarak gömmeyi otomatik olarak halleder; harici bir gömme API çağrısı gerekmez. Sonraki benzer sorularda hibrit arama bunu bulacaktır.

Oracle AI veritabanını tohumlama

Bir DataSeeder (Spring CommandLineRunner) başlangıçta veritabanını 8 demo sipariş ve 12 politika belgesiyle (iade, gönderim, destek, garanti, ödeme, iptal, değişim, uluslararası gönderim, gizlilik, promosyonlar, ürün garantisi ve toplu sipariş politikaları) doldurur. Politikalar bir policies.json kaynak dosyasından yüklenir ve JDBC ile POLICY_DOCS tablosuna eklenir. Siparişler, demoda 30 günlük iade penceresi mantığının her zaman çalışması için göreli tarihler kullanır. Tohumlayıcı, yeniden başlatmalarda yinelenmeleri önlemek için mevcut sayıları kontrol eder.

Semantik Hafızayı Yükseltme: Hibrit Arama

Bu POC'nin ilk sürümü, OracleVectorStore ile Spring AI'in QuestionAnswerAdvisor'unu kullanıyordu: kosinüs eşiğiyle saf vektör benzerlik araması. Politikalara dair temiz, iyi ifade edilmiş sorularda işe yaradı. Ancak tam terimler ve yazım hatalarında dağıldı. "ORD-1001 siparişi" sorgusu, anlamsal olarak politika belgeleriyle eşleşmeye çalışıyordu ki bu mantıksız. Yanlış yazılmış "retrun polcy" ise benzerlik puanını kaybediyordu çünkü gömme modeli bunun bir yazım hatası olduğunu bilmiyor.

Oracle hibrit vektör indeksleri oluşturma

Oracle 26ai, DBMS_HYBRID_VECTOR.SEARCH sağlar; tek bir PL/SQL çağrısıyla vektör benzerlik araması ve Oracle Text anahtar sözcük araması paralel çalıştırılır, ardından sonuçlar birleştirilir.

Temel içgörü Reciprocal Rank Fusion'dır (RRF): kosinüs benzerlik puanlarını (0-1 aralığında) BM25 anahtar sözcük puanlarına (sınırsız) normalize etmeye çalışmak yerine, belgeleri her sonuç listesindeki pozisyonlarına göre sıralar. 

Vektör sonuçlarında #1, anahtar sözcük sonuçlarında #3 olan bir belgenin, her iki sinyali de yansıtan birleşik bir sırası olur.

Kurulum, Oracle AI Database'e bir ONNX gömme modelini yükleyen ve bir hibrit dizin oluşturan tek seferlik bir SQL betiğidir:

/SQL
-- Load the ONNX model for in-database embeddings
BEGIN
  DBMS_VECTOR.LOAD_ONNX_MODEL(
    directory  => 'DM_DUMP',
    file_name  => 'all_MiniLM_L12_v2.onnx',
    model_name => 'ALL_MINILM_L12_V2'
  );
END;
/

-- Create a hybrid index: vector similarity + Oracle Text keyword search
CREATE HYBRID VECTOR INDEX POLICY_HYBRID_IDX
ON POLICY_DOCS(content)
PARAMETERS('MODEL ALL_MINILM_L12_V2 VECTOR_IDXTYPE HNSW');Altyapı:

Dizin oluşturulduktan sonra, satırlar eklendiğinde gömmeler otomatik olarak hesaplanır — harici bir gömme API çağrısı gerekmez.

Spring AI getirme entegrasyonu

Spring AI'in QuestionAnswerAdvisor'ı yalnızca VectorStore.similaritySearch() sarmalamasını yapar; saf vektör araması, başka bir şey değil. Hibrit aramayı kullanmak için RetrievalAugmentationAdvisor'a geçtim; bu, modüler alternatiftir: özel bir DocumentRetriever ve alınan belgelerin isteme nasıl enjekte edileceğini kontrol eden özel bir QueryAugmenter kabul eder.

Özel OracleHybridDocumentRetriever, DocumentRetriever uygular ve hibrit dizin adını, RRF değerlendiricisini ve bir anahtar sözcük eşleşmesini belirten bir JSON parametresi geçirerek JDBC aracılığıyla DBMS_HYBRID_VECTOR.SEARCH çağrısı yapar:

public List<Document> retrieve(Query query) {
    // Builds a JSON spec with hybrid index name, RRF scorer, vector + text search clauses
    // Calls DBMS_HYBRID_VECTOR.SEARCH via JDBC, parses JSON results into List<Document>
}Altyapı:

Bu yaklaşım, getirme için OracleVectorStore kullanımını tamamen atlar. text.contains ifadesi, 2 karakterden uzun kelimelerde düz anahtar sözcük OR eşleşmesi kullanır; Oracle Text'in yerleşik gövdeleme (stemming) özelliği varyasyonları ele alır.

Hibrit arama, yapay zekâ ajanlarını neden iyileştirir

Ajanın iyi kararlar alabilmesi için doğru getirme gerekir. Semantik hafıza yanlış veya düşük güvenli politika belgeleri döndürürse, LLM araç parametrelerini hayal edebilir ya da kullanması gereken bir aracı çağırmayı atlayabilir. 

Hibrit arama daha yüksek güvenli bağlam demektir; bu da daha iyi otonom kararlar anlamına gelir. Hem anlam hem tam terimler eşleştiğinde, ajanın bir politikayı yanlış aktarması veya ilgili bir belgeyi kaçırması olasılığı düşer.

Spring AI için Veritabanı Yapılandırması

Yapılandırma tek bir application.yaml dosyasında yaşar. Temel tasarım kararları: Hibernate JPA tablolarını otomatik oluşturur (ddl-auto: update), Spring AI sohbet hafızası tablosunu otomatik oluşturur (initialize-schema: always), POLICY_DOCS tablosu ve hibrit vektör dizini tek seferlik bir SQL betiğiyle (setup-hybrid-search.sql) oluşturulur ve Oracle UCP üç hafıza türünün tümü için tek bir bağlantı havuzunu paylaşır. 

Flyway yok, özel @Configuration sınıfları yok. Spring AI'in otomatik yapılandırması Oracle JDBC sürücüsünü algılar ve her şeyi bağlar. Depodaki tam application.yaml dosyasına bakın.

Streamlit Web Arayüzünü Oluşturma

Streamlit ön yüzü, mesajları arka uca gönderir ve yanıtları işler. İşte çekirdeği (tam uygulama hızlı başlangıç düğmeleri ve yeni konuşma özelliğini içerir. Bkz. app.py):

def send_message(prompt, url):
    # POSTs plain text to /api/v1/agent/chat with X-Conversation-Id header
    # Renders user message and assistant response in Streamlit chat UI

if prompt := st.chat_input("Type a message..."):
    send_message(prompt, backend_url)Altyapı:

Oturum başına konuşma kimliği için bir UUID üretir, düz metni arka uca gönderir ve yanıtı render eder. Hepsi bu.

Yapay Zekâ Ajan POC'sini Yerelde Çalıştırma

Kısa versiyon: Bir Oracle DB konteyneri başlatın, ONNX modelini yükleyin ve hibrit dizini oluşturun (tek seferlik kurulum), Ollama'yı kurun ve sohbet modelini çekin (qwen2.5), Spring Boot arka ucunu local profiliyle çalıştırın ve isteğe bağlı olarak Streamlit arayüzünü başlatın. Gömmeler, ONNX modeli tarafından veritabanı içinde gerçekleştirilir; Ollama gömme modeline gerek yoktur. Tam kurulum talimatları repo README'de.

curl ile hızlı test:

curl -X POST http://localhost:8080/api/v1/agent/chat \
  -H "Content-Type: text/plain" \
  -H "X-Conversation-Id: test-1" \
  -d "What orders do I have?"Altyapı:

Sonuç

Bu kurulum, Spring AI ve Oracle Veritabanı ile gerçek ajanlar oluşturmak için güçlü bir varsayılandır çünkü tüm hafıza katmanlarını tek bir operasyonel yığında tutar: epizodik bağlam, semantik getirme ve işlemsel eylemler. Spring AI, temiz soyutlamalar (Advisors + @Tool) sunar; böylece ajan davranışı okunabilir ve test edilebilir kalır; Oracle ise aynı sistemde hem işlemsel verileri hem hibrit getirimi yönetir; veritabanı içi gömmeler ve hem anlam hem tam terimlerde daha iyi hassasiyet için RRF sıralaması sağlar.

Ortaya çıkan şey pratiktir: daha az hareketli parça, daha az entegrasyon hatası, daha düşük gecikme ve daha kolay üretim operasyonları. Sohbet geçmişi, vektör arama, anahtar sözcük araması ve iş tabloları için ayrı sistemleri birleştirmek yerine tek bir platform üzerine kurar, yine de yüksek kaliteli getirme ve güvenilir araç yürütmesi elde edersiniz. Ajan özellikleri sunan ekipler için bu basitlik, doğruluk ve operasyonel kontrol birleşimini yenmek zordur.

Yapay zekâ ajanları ve nasıl çalıştıkları hakkında daha fazla bilgi edinmek için DataCamp'in AI Agent Fundamentals yetkinlik yolu'na göz atmanızı öneririm.