HydraLLM: Intelligenter Orchestrator

HydraLLM: Intelligenter Orchestrator

HydraLLM ist ein kontextbewusstes Gateway, das für die effiziente Nutzung mehrerer LLM-Ressourcen entwickelt wurde. Es leitet Anfragen über Gemini / Groq / Cerebras hinweg weiter, bietet provider-spezifische Circuit Breaker, zufällige Schlüsselrotation (einschließlich quota-bewusster Cooldowns), Echtzeit-Web-Anreicherung und implementiert eine OpenAI-kompatible API auf einer strikten Clean Architecture (Domain dann Services dann Adapters dann API).

• Version: 1.3.0 (pyproject.toml)
• Python: 3.10+
• Ausführungseinstiegspunkt: python main.py
• Integrierte UI: http://localhost:8000/ui
• OpenAI-kompatibler Endpunkt: POST /v1/chat/completions

HydraLLM Technische Spezifikation (SPEC)

1. Überblick

HydraLLM ist ein hochverfügbares LLM-Gateway, das Clean Architecture einhält. Es bietet intelligentes Routing zwischen mehreren Anbietern, ausfallisolierung auf Basis von Circuit Breakern, Echtzeit-Web-Anreicherung und unterstützt die OpenAI-API-Spezifikation vollständig.

2. Spezifikation der Kernkomponenten

2.1 Gateway (src/services/gateway.py)

• Orchestrierung: Koordination des Ablaufs Session laden -> Kontext analysieren -> Web-Anreicherung -> resilient ausführen -> persistieren.
• Technische Routing-Gründe: Fügt allen Antworten die Entscheidungsgrundlage als klare Konstanten hinzu.
  • USER_HINT: explizite Vorgabe durch den Benutzer
  • TOKEN_OPTIMIZED: Optimierung auf Basis der Token-Anzahl
  • WEB_INTENT_SEARCH: Analyseergebnis der Web-Suchintention
  • MULTIMODAL_ANALYSIS: Erkennung des Bedarfs an Bildverarbeitung
  • KEY_AVAILABILITY: Schlüsselstatus und Failover-Ergebnis

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

• Routing-Algorithmus: Analysiert Token-Länge, Multimodalität und Web-Suchabsicht, um die optimale RoutingDecision zu erzeugen.
• Dynamische Verfügbarkeitsfilterung: Berücksichtigt den Echtzeitstatus des KeyManager, sodass Modelle von Anbietern ohne aktive Schlüssel aus den Optionen ausgeschlossen werden.

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

• Schlüsselrotation: Zufällige Auswahl innerhalb des aktiven Schlüssel-Pools und Nachverfolgung der Nutzung.
• Fehlermanagement: Wendet je nach Fehlertyp unterschiedliche Cooldowns an.
  • 403 Forbidden: 24 Stunden (Reaktion auf dauerhaften Ausfall auf Schlüssel-Ebene)
  • 429 Rate Limit / Quota: 1 Stunde
  • Sonstige Kommunikationsfehler: 5 Minuten

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

• Datenanreicherung: Sammelt in Echtzeit Informationen auf Basis von Playwright/Scrapling und injiziert sie in den Prompt.
• Leistungsüberwachung: Protokolliert Erfolgsquote, Anzahl gesammelter Zeichen und Latenz über die Tabelle scraping_metrics.

3. Resilienz- und Wiederherstellungsmuster (Troubleshooting Insights)

• Concurrency Guard: Wendet asyncio.Lock und threading.Lock auf Schreibvorgänge von KeyManager und SessionManager an, um die Datenintegrität unter hoher Last sicherzustellen.
• Self-Healing Scraper: Aktiviert einen automatischen Neustartmechanismus, wenn ein Absturz der Browser-Instanz erkannt wird.
• Unpacking Guard: Hält strikte Rückgabetypen (tuple[list, str | None]) und Schutzmechanismen ein, um NoneType-Fehler bei der Verarbeitung angereicherter Daten zu verhindern.