Birden Fazla Model ile AI Agent'lar Geliştirmek: Pratik Bir Mimari Rehberi

Çoğu yapay zeka ajanı, yürütmenin her aşamasını yönetmek için tek bir modele güvenir. Planlama adımı, araç çağrıları, veri çıkarma, özetleme ve hata kurtarma süreçlerinin tamamı aynı LLM üzerinden geçer. Bu yaklaşım ilk prototipler için basit olsa da, üretim ortamlarında önemli verimsizliklere yol açar.

Derin muhakeme gerektiren bir planlama adımı, temel bir JSON çıkarma adımıyla aynı modele ihtiyaç duymaz. Bir kod oluşturma görevinin gereksinimleri, bir sınıflandırma görevinden farklıdır. Bir tarih dizesini biçimlendirmek için Claude Fable 5 veya Claude Opus 4.8 gibi üst düzey bir muhakeme modeli kullanmak, kaynakların pahalı ve yanlış bir şekilde tahsis edilmesidir.

Birden fazla modelle yapay zeka ajanları oluşturmak, bir iş akışının her adımını o görev için en uygun modele yönlendirmenize olanak tanır. Bu rehber, bu çok modelli mimarilerin nasıl tasarlanacağını, uygulanacağını ve yönetileceğini incelemektedir.

Eğer ajan orkestrasyon katmanı yerine API katmanı üzerinde çalışıyorsanız, bu rehberin yanı sıra Agent-First API Tasarımı ve Ekipler Neden Doğrudan Model API'lerinden Birleşik Bir Yapay Zeka API'sine Geçiyor? başlıklı yazılarımıza göz atın. Çok modelli ajanlar, alttaki API yüzeyi orkestrasyon kodunu yeniden yazmadan modelleri değiştirebilecek kadar kararlı olduğunda en güvenilir şekilde çalışır.

:::info

Önemli Çıkarımlar

1. Modeli Görev Karmaşıklığıyla Eşleştirin: Yönlendirme, çıkarma ve biçimlendirme için küçük, hızlı modeller kullanın; daha büyük muhakeme modellerini ise planlama ve karmaşık analizler için saklayın.
2. Şemaları Standartlaştırın: Farklı model sağlayıcıları arasında geçiş yaparken sözleşme sapmalarını (contract drift) önlemek için her devir teslim noktasında (Pydantic gibi) katı çıktı doğrulaması uygulayın.
3. Yedekleme (Fallback) İçin Tasarlayın: Hız sınırlarını, sağlayıcı kesintilerini veya gecikme artışlarını ajan iş akışını bozmadan yönetmek için otomatik yedekleme yolları oluşturun.
4. Telemetriyi Merkezileştirin: Yönlendirme mantığınızı sürekli optimize etmek için gecikmeyi, giriş/çıkış token sayılarını ve adım başına maliyeti takip edin. :::

---

Çok Modelli Ajan Mimarisi

Çok modelli bir ajan mimarisi, görevleri karmaşıklık, maliyet ve gecikme gereksinimlerine göre uzmanlaşmış modellere dağıtır.

Kullanıcı İsteği
    │
    ▼
┌─────────────┐
│   Yönlendirici │  ← Görev karmaşıklığını sınıflandırır
│  (hızlı model)│
└──────┬──────┘
       │
   ┌───┴───┐
   ▼       ▼
┌──────┐ ┌──────┐
│Basit  │ │Karmaşık│
│Model  │ │Model   │
└──┬───┘ └──┬───┘
   │        │
   ▼        ▼
┌─────────────┐
│  Toplayıcı   │  ← Sonuçları birleştirir
│  (hızlı model)│
└─────────────┘

Temel mimari beş ana bileşenden oluşur:

1. Yönlendirici (Router): Gelen görevleri karmaşıklık ve niyete göre sınıflandıran hızlı, düşük maliyetli bir model.
2. Model Havuzu: Farklı görev türleriyle (muhakeme, çıkarma veya kod oluşturma gibi) eşleştirilmiş modeller koleksiyonu.
3. Toplayıcı (Aggregator): Paralel adımlardan gelen sonuçları nihai bir yanıtta birleştiren hızlı bir model.
4. Yedekleme Politikası (Fallback Policy): Birincil seçimin başarısız olması, zaman aşımına uğraması veya hız sınırlarına takılması durumunda hangi modelin kullanılacağını belirleyen kurallar.
5. Telemetri Katmanı: Model seçimlerini, gecikmeyi ve adım başına kesin token maliyetlerini kaydeden bir günlükleme sistemi.

Yedekleme politikaları ve telemetri olmadan, çok modelli bir ajanda hata ayıklamak zorlaşabilir; gecikme ve maliyet profilleri öngörülemez hale gelebilir.

---

OpenAI SDK ile Uygulama

Birleşik bir API ağ geçidi kullanmak, tek bir SDK ve API anahtarı kullanarak farklı sağlayıcılardan modellere erişmenizi sağlar. Bu, model değiştirmeyi ve yönlendirmeyi basitleştirir.

Aşağıdaki örnek, temel bir yönlendirme uygulamasını göstermektedir. Model kullanılabilirliği ve fiyatlandırma TokenLab model dizini üzerinden doğrulanmalıdır.

from openai import OpenAI

client = OpenAI(
    api_key="sk-tokenlab-xxx",
    base_url="https://api.tokenlab.sh/v1"
)

# Maliyet ve yetenek katmanlarına sahip model havuzu
MODELS = {
    "router": "deepseek-v4-flash",        # Hızlı sınıflandırma
    "simple": "deepseek-v4-flash",        # Çıkarma, biçimlendirme
    "reasoning": "claude-sonnet-5",       # Planlama, analiz
    "complex": "gpt-5.5",                 # Kod oluşturma, karmaşık mantık
    "budget": "deepseek-v4-flash",        # Toplu işleme
}

def route_task(task: str) -> str:
    """Görev karmaşıklığını sınıflandırmak için düşük maliyetli bir model kullanın."""
    response = client.chat.completions.create(
        model=MODELS["router"],
        messages=[
            {"role": "system", "content": """Bu görevi tam olarak bir kategoriye sınıflandırın:
- simple: veri çıkarma, biçimlendirme, çeviri
- reasoning: analiz, planlama, karşılaştırma
- complex: kod oluşturma, çok adımlı problem çözme
- budget: toplu işleme, kritik olmayan görevler
Sadece küçük harflerle kategori adını yanıtlayın."""},
            {"role": "user", "content": task}
        ],
        max_tokens=10
    )
    category = response.choices[0].message.content.strip().lower()
    return MODELS.get(category, MODELS["simple"])

def execute_task(task: str, context: str = "") -> str:
    """Görevi seçilen modele yönlendirin ve yürütün."""
    model = route_task(task)
    messages = []
    if context:
        messages.append({"role": "system", "content": context})
    messages.append({"role": "user", "content": task})

    response = client.chat.completions.create(
        model=model,
        messages=messages
    )
    return response.choices[0].message.content

---

Gerçek Dünya Ajanı: Kod İnceleme Hattı

Birden fazla modelle yapay zeka ajanları oluşturmanın pratik etkisini görmek için, pull request (PR) incelemek üzere tasarlanmış bir hattı düşünün. Bu iş akışı, tüm kod farkını tek bir pahalı modele göndermek yerine incelemeyi uzmanlaşmış adımlara böler.

def review_pr(diff: str) -> dict:
    """Çok modelli PR inceleme hattı."""

    # 1. Adım: Hızlı, düşük maliyetli bir model kullanarak değişiklikleri sınıflandırın
    classification = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=[{
            "role": "user",
            "content": f"Bu kod değişikliklerini sınıflandırın: {diff[:2000]}\n"
                       "Kategoriler: bugfix, feature, refactor, docs, test"
        }],
        max_tokens=20
    ).choices[0].message.content

    # 2. Adım: Güçlü bir muhakeme modeli kullanarak güvenlik taraması yapın
    security = client.chat.completions.create(
        model="claude-sonnet-5",
        messages=[{
            "role": "system",
            "content": "Bir güvenlik incelemecisisiniz. Şunları kontrol edin: "
                       "SQL injection, XSS, yetkilendirme atlatma, koddaki gizli bilgiler, "
                       "güvensiz serileştirme. Satır numaraları konusunda spesifik olun."
        }, {
            "role": "user",
            "content": f"Bu diff'i güvenlik sorunları açısından inceleyin:\n{diff}"
        }]
    ).choices[0].message.content

    # 3. Adım: Genel amaçlı bir model kullanarak kod kalitesini analiz edin
    quality = client.chat.completions.create(
        model="gpt-5.5",
        messages=[{
            "role": "user",
            "content": f"Kod kalitesini inceleyin: isimlendirme, yapı, "
                       f"hata yönetimi, test kapsamı.\n{diff}"
        }]
    ).choices[0].message.content

    # 4. Adım: Hızlı, düşük maliyetli bir model kullanarak özet oluşturun
    summary = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=[{
            "role": "user",
            "content": f"Bu PR incelemesini 3 madde halinde özetleyin:\n"
                       f"Tür: {classification}\n"
                       f"Güvenlik: {security[:500]}\n"
                       f"Kalite: {quality[:500]}"
        }]
    ).choices[0].message.content

    return {
        "classification": classification,
        "security": security,
        "quality": quality,
        "summary": summary
    }

Maliyet ve Verimlilik Optimizasyonu

Aşağıdaki tablo, bu hat için model tahsisini özetlemektedir. Kesin fiyatlandırma sağlayıcıya ve hacme göre değişir; güncel oranları TokenLab model dizini üzerinden doğrulayın.

Adım	Model	Giriş Tokenları	Rol / Uzmanlık
1. Sınıflandırma	DeepSeek V4 Flash	~2,100	Hızlı sınıflandırma, düşük maliyetli yönlendirme
2. Güvenlik	Claude Sonnet 5	~2,500	Derin muhakeme, güvenlik analizi
3. Kalite	GPT-5.5	~2,500	Gelişmiş kod kalitesi ve yapısal inceleme
4. Özet	DeepSeek V4 Flash	~1,200	Hızlı, düşük maliyetli metin toplama

Dört adımın tamamını Claude Sonnet 5 veya GPT-5.5 gibi amiral gemisi bir muhakeme modeliyle çalıştırmak maliyetleri önemli ölçüde artırırdı. Daha basit görevleri DeepSeek V4 Flash gibi daha düşük maliyetli modellere yönlendirerek, çok modelli hat genel token harcamasını azaltırken kritik güvenlik analizi adımı için derin muhakeme yeteneğini korur.

---

Sadece Fiyata Göre Değil, Yeteneğe Göre Yönlendirme

Maliyet düşürme ortak bir hedef olsa da, yönlendirme kararları belirli model yeteneklerini de hesaba katmalıdır. Sağlam bir yönlendirme politikası, modelleri dört temel boyutta değerlendirir:

• Muhakeme Derinliği: Karmaşık mantık, planlama ve çok adımlı çıkarım.
• Bağlam Penceresi (Context Window): Görev için gereken arka plan bilgisi veya kod hacmi.
• Araç Kullanım Güvenilirliği: Fonksiyon çağırma ve yapılandırılmış çıktı oluşturma doğruluğu.
• Gecikme Hassasiyeti: Kullanıcıya dönük uygulamanın hız gereksinimleri.

Bu boyutlar net yönlendirme kuralları oluşturmaya yardımcı olur:

• Ayrıştırma ve planlama görevleri muhakeme ağırlıklı modellere yönlendirilir.
• Veri çıkarma ve biçimlendirme görevleri hızlı, düşük maliyetli modellere yönlendirilir.
• Kod oluşturma ve sözdizimi analizi, kodlama görevleri için optimize edilmiş modellere yönlendirilir.
• Depo genelinde analiz görevleri, geniş bağlam pencerelerine sahip modellere yönlendirilir.

Yönlendiricinizi bu gereksinimlerle uyumlu hale getirmek için, iş akışı adımlarınızı güncel model kıyaslamalarıyla eşleştirmek adına kodlama modeli karşılaştırmasına ve fiyatlandırma karşılaştırmasına göz atın.

---

LangChain Entegrasyonu

Çok modelli yönlendirmeyi LangChain gibi orkestrasyon çerçeveleri içinde de uygulayabilirsiniz. Aşağıdaki örnek, birleşik bir API temel URL'si kullanarak farklı modelleri yapılandırır:

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# Modelleri farklı yapılandırmalarla başlatın
fast_model = ChatOpenAI(
    model="deepseek-v4-flash",
    api_key="sk-tokenlab-xxx",
    base_url="https://api.tokenlab.sh/v1"
)

reasoning_model = ChatOpenAI(
    model="claude-sonnet-5",
    api_key="sk-tokenlab-xxx",
    base_url="https://api.tokenlab.sh/v1"
)

# Uzmanlaşmış zincirleri tanımlayın
classify_chain = ChatPromptTemplate.from_template(
    "Bu isteğin niyetini sınıflandırın: {input}"
) | fast_model

analyze_chain = ChatPromptTemplate.from_template(
    "Bu sorunun detaylı bir analizini yapın: {input}"
) | reasoning_model

---

Çok Modelli Ajanlar Ne Zaman Kullanılmalı?

Birden fazla model eklemek mimari karmaşıklığı artırır. Bu yaklaşım genellikle şu durumlarda en faydalıdır:

• Çeşitli Görev Gereksinimleri: Ajan, basit görevler (sınıflandırma veya biçimlendirme gibi) ile karmaşık görevlerin (stratejik planlama veya kod oluşturma gibi) bir karışımını yönetir.
• Yüksek Hacim ve Maliyet: Aylık API harcamaları, optimizasyonun anlamlı tasarruflar sağlayacağı kadar yüksektir.
• Uzmanlaşmış Model Güçleri: İş akışı, Gemini'nin bağlam penceresi, Claude'un kodlama yetenekleri veya GPT'nin araç kullanım hızı gibi belirli sağlayıcı güçlerinden yararlanır.
• Asimetrik Gecikme İhtiyaçları: İş akışının bazı bölümlerinin anında sonuç döndürmesi gerekirken, diğer arka plan adımları daha uzun sürebilir.

Tek amaçlı ajanlar veya basit sohbet arayüzleri için tek bir modelin bakımı genellikle daha kolaydır. Her istek aynı seviyede yetenek gerektiriyorsa, yönlendirmenin operasyonel yükü haklı olmayabilir.

---

Yaygın Hata Modları

Çok modelli mimariler, hafifletilmesi gereken belirli hata modlarını beraberinde getirir:

1. Aşırı Mühendislik Yapılmış Yönlendiriciler

Yönlendirici istemi (prompt) aşırı karmaşık hale gelirse, sınıflandırma adımının kendisi yavaş ve pahalı hale gelebilir. Yönlendirme istemlerini kısa, sınıflandırma kategorilerini ise geniş tutun.

2. Çıktı Sözleşmesi Sapması (Output Contract Drift)

Farklı modeller, JSON döndürmeleri talimatı verildiğinde bile çıktıları farklı şekilde biçimlendirebilir. Bir model ham JSON döndürürken, diğeri onu markdown blokları içine alabilir. Aşağı yönlü ayrıştırıcı hatalarını önlemek için, her adım devir tesliminde Pydantic gibi doğrulama kütüphanelerini kullanarak katı şemalar uygulayın.

3. Sessiz Kalite Bozulması

Bir yedekleme politikası, birincil sağlayıcı kesintisi sırasında isteği daha düşük seviyeli bir modele yönlendirirse, ajan bir hata vermeden daha düşük kaliteli yanıtlar döndürebilir. Net bir hız sınırlama stratejisi ve uyarı sistemi uygulamak, yedeklemelerin ne zaman aktif olduğunu takip etmeye yardımcı olur.

4. Parçalanmış Telemetri

Model kullanımı birden fazla doğrudan sağlayıcı API'sine bölündüğünde, maliyet ve performans metriklerini toplamak zorlaşır. İstekleri tek bir ağ geçidi üzerinden merkezileştirmek, günlüklemeyi ve maliyet takibini basitleştirir.

---

Minimal Bir Değerlendirme Döngüsü

Çok modelli bir ajanı sürdürmek için performansı takip etmek adına temel bir değerlendirme döngüsü oluşturun. Her çalıştırma için aşağıdaki metrikleri bir veritabanı tablosuna kaydedebilirsiniz:

• Görev Kategorisi: Yönlendirici tarafından atanan sınıflandırma.
• Seçilen Model: Her adım için seçilen model.
• Adım Gecikmesi: Her adımı tamamlamak için geçen süre.
• Token Kullanımı: Tam giriş ve çıkış token sayıları.
• Yedekleme Durumu: Bir yedekleme modelinin tetiklenip tetiklenmediği.
• Kullanıcı Geri Bildirimi: Nihai çıktının başarılı olup olmadığına dair ikili bir gösterge.

Bu verileri analiz etmek, yönlendiricinin doğru modelleri seçip seçmediğini, hangi adımların maliyetlerinizin çoğunu oluşturduğunu ve yedekleme modellerinin kabul edilebilir kaliteyi koruyup korumadığını belirlemeye yardımcı olur.

---

SSS

Farklı modellerdeki farklı istem formatlarını nasıl yönetiyorsunuz?

Farklı modeller farklı istem yapılarına en iyi yanıtı verir. Örneğin, bazı modeller sistem istemleriyle daha iyi performans gösterirken, diğerleri kullanıcı istemine gömülü talimatları tercih eder. Bunu yönetmek için, havuzunuzdaki her modele aynı ham dizeleri göndermek yerine, hedef modele göre uyarlanan şablonlara istemlerinizi soyutlayın.

Yönlendirme, kullanıcıya dönük uygulamalara çok fazla gecikme ekler mi?

Yönlendirme, sınıflandırma adımı için küçük bir miktar gecikme ekler. Bunu, yönlendirici için yüksek düzeyde optimize edilmiş, düşük gecikmeli modeller kullanarak, maksimum token sınırlarını düşük tutarak (10 token altı) veya sınıflandırma kullanıcının uygulama durumundan ya da giriş noktasından çıkarılabildiğinde adımları paralelleştirerek en aza indirebilirsiniz.

Modeller arasında geçiş yaparken JSON ayrıştırma hatalarını nasıl önlersiniz?

Ayrıştırma hatalarını önlemek için, model sağlayıcıları tarafından desteklenen yapılandırılmış çıktı özelliklerini (JSON modu veya araç çağırma gibi) kullanın. Ayrıca, tüm model çıktılarını, hattınızdaki bir sonraki adıma geçirmeden önce yükü ayrıştırmak, doğrulamak ve onarmak için Pydantic veya benzeri kütüphaneler kullanarak bir doğrulama katmanına sarın.

---

Her modele tek bir API üzerinden erişin: Tek bir API anahtarıyla 300'den fazla modele erişmek için TokenLab ile Başlayın. Birden fazla sağlayıcı hesabı yönetmeden veya farklı API'ler için yönlendirme mantığını yeniden yazmadan çok modelli ajanlar oluşturun.