HydraLLM: インテリジェント・オーケストレーター

HydraLLM: インテリジェント・オーケストレーター

HydraLLMは、複数のLLMリソースを効率的に活用するよう設計されたコンテキスト認識型ゲートウェイです。Gemini / Groq / Cerebras 全体にわたってリクエストをルーティングし、プロバイダー別サーキットブレーカー、ランダムキー・ローテーション（クォータ認識クールダウンを含む）、リアルタイムWeb拡張機能を提供し、OpenAI互換APIを厳格なClean Architecture（Domain の次に Services、その次に Adapters、最後に API）の上に構築しています。

• バージョン: 1.3.0 (pyproject.toml)
• Python: 3.10+
• 実行エントリーポイント: python main.py
• 統合UI: http://localhost:8000/ui
• OpenAI互換エンドポイント: POST /v1/chat/completions

HydraLLM 技術仕様書 (SPEC)

1. 概要

HydraLLMは、Clean Architectureに準拠した高可用性LLMゲートウェイです。複数プロバイダー間のインテリジェント・ルーティング、サーキットブレーカーベースの障害分離、リアルタイムWeb拡張機能を提供し、OpenAI API仕様を完全にサポートします。

2. 主要コンポーネント仕様

2.1 Gateway (src/services/gateway.py)

• オーケストレーション: セッション読み込み -> コンテキスト分析 -> Web拡張 -> 回復性のある実行 -> 永続化の流れを調整。
• 技術的ルーティング理由: すべての応答に、意思決定の根拠を明確な定数として含めます。
  • USER_HINT: ユーザーによる明示的な指定
  • TOKEN_OPTIMIZED: トークン数ベースの最適化
  • WEB_INTENT_SEARCH: Web検索インテント分析結果
  • MULTIMODAL_ANALYSIS: 画像処理の必要性を検知
  • KEY_AVAILABILITY: キー状態およびフェイルオーバー結果

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

• ルーティングアルゴリズム: トークン長、マルチモーダルかどうか、Web検索意図を分析して最適な RoutingDecision を生成。
• 動的可用性フィルタリング: KeyManager のリアルタイム状態を反映し、有効なキーがないプロバイダーのモデルは選択肢から除外します。

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

• キー・ローテーション: アクティブキープール内でのランダム選択および使用量追跡。
• 障害管理: エラー種別ごとに異なるクールダウンを適用。
  • 403 Forbidden: 24時間（キー単位の恒久障害に対応）
  • 429 Rate Limit / Quota: 1時間
  • その他の通信エラー: 5分

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

• データ拡張: Playwright/Scrapling ベースのリアルタイム情報収集とプロンプト注入。
• パフォーマンス追跡: scraping_metrics テーブルを通じて成功率、収集文字数、遅延時間を記録。

3. 回復性と復旧パターン (Troubleshooting Insights)

• Concurrency Guard: KeyManager および SessionManager の書き込み処理に asyncio.Lock と threading.Lock を適用し、高負荷状況でのデータ整合性を保証します。
• Self-Healing Scraper: ブラウザインスタンスのクラッシュを検知した際に、自動再起動メカニズムを作動させます。
• Unpacking Guard: 拡張データ処理時に発生しうる NoneType エラーを防ぐため、厳格な戻り値型（tuple[list, str | None]）とガードを遵守します。