HydraLLM: Akıllı Orkestratör

HydraLLM: Akıllı Orkestratör

HydraLLM, birden fazla LLM kaynağını verimli biçimde kullanmak için tasarlanmış, bağlam farkındalığına sahip bir ağ geçididir. İstekleri Gemini / Groq / Cerebras genelinde yönlendirir; sağlayıcı bazlı devre kesiciler, rastgele anahtar rotasyonu (kota farkındalıklı cooldown dahil), gerçek zamanlı web zenginleştirme sunar ve OpenAI uyumlu API'yi katı bir Clean Architecture (Domain ardından Services ardından Adapters ardından API) üzerine kurar.

• Sürüm: 1.3.0 (pyproject.toml)
• Python: 3.10+
• Çalıştırma giriş noktası: python main.py
• Entegre UI: http://localhost:8000/ui
• OpenAI uyumlu uç nokta: POST /v1/chat/completions

HydraLLM Teknik Spesifikasyonu (SPEC)

1. Genel Bakış

HydraLLM, Clean Architecture ilkelerine uyan yüksek erişilebilirlikli bir LLM ağ geçididir. Birden fazla sağlayıcı arasında akıllı yönlendirme, devre kesici tabanlı hata yalıtımı, gerçek zamanlı web zenginleştirme sağlar ve OpenAI API spesifikasyonunu eksiksiz destekler.

2. Temel Bileşen Spesifikasyonları

2.1 Gateway (src/services/gateway.py)

• Orkestrasyon: Oturum yükleme -> bağlam analizi -> web zenginleştirme -> dayanıklı yürütme -> kalıcılaştırma akışını koordine eder.
• Teknik yönlendirme gerekçeleri: Tüm yanıtlara karar verme temelini açık sabitler olarak dahil eder.
  • USER_HINT: kullanıcının açık belirtimi
  • TOKEN_OPTIMIZED: token sayısına dayalı optimizasyon
  • WEB_INTENT_SEARCH: web arama niyeti analiz sonucu
  • MULTIMODAL_ANALYSIS: görsel işleme gereksiniminin tespiti
  • KEY_AVAILABILITY: anahtar durumu ve failover sonucu

2.2 Context Analyzer (src/services/analyzer.py)

• Yönlendirme algoritması: Token uzunluğunu, multimodal olup olmadığını ve web arama niyetini analiz ederek en uygun RoutingDecision üretir.
• Dinamik kullanılabilirlik filtreleme: KeyManagerın gerçek zamanlı durumunu yansıtarak etkin anahtarı olmayan sağlayıcıların modellerini seçenekler arasından çıkarır.

2.3 Key Manager (src/services/key_manager.py)

• Anahtar rotasyonu: Etkin anahtar havuzu içinde rastgele seçim ve kullanım takibi.
• Hata yönetimi: Hata türüne göre farklı cooldown uygulanır.
  • 403 Forbidden: 24 saat (anahtar bazında kalıcı arıza durumuna karşılık)
  • 429 Rate Limit / Quota: 1 saat
  • Diğer iletişim hataları: 5 dakika

2.4 Web Context Service (src/services/web_context_service.py)

• Veri zenginleştirme: Playwright/Scrapling tabanlı gerçek zamanlı bilgi toplama ve prompt içine enjeksiyon.
• Performans takibi: scraping_metrics tablosu üzerinden başarı oranı, toplanan karakter sayısı ve gecikme süresi kaydı.

3. Dayanıklılık ve Kurtarma Kalıpları (Troubleshooting Insights)

• Concurrency Guard: KeyManager ve SessionManager yazma işlemlerine asyncio.Lock ve threading.Lock uygulayarak yüksek yük altında veri bütünlüğünü garanti eder.
• Self-Healing Scraper: Tarayıcı örneği çökmesi algılandığında otomatik yeniden başlatma mekanizmasını devreye alır.
• Unpacking Guard: Zenginleştirme verisi işlenirken oluşabilecek NoneType hatalarını önlemek için katı dönüş tipi (tuple[list, str | None]) ve korumaları uygular.