HydraLLM

여러 제공자(Gemini·Groq·Cerebras)와 로컬 모델(Ollama/OpenCode/OpenClaw)을 하나의 OpenAI 호환 엔드포인트로 묶는 컨텍스트 인지 LLM 게이트웨이입니다. /v1/chat/completions 그대로라 기존 도구·SDK를 코드 변경 없이 붙입니다.

왜 만들었나
무료 티어 LLM은 분당·일일 쿼터가 빡빡하고, 키 하나로는 금방 막힙니다. 키·제공자를 여러 개 두고 한도에 걸리면 자동으로 다음으로 넘기고, 클라우드가 다 막히면 로컬 모델로 우아하게 저하시켜 끊기지 않게 쓰고 싶었습니다.

라우팅·복원력

• 토큰 수·멀티모달(이미지)·웹 의도·명시적 힌트로 제공자/모델 자동 선택
• 제공자별 서킷브레이커(5회 실패 → 60초 차단)
• 키 풀 랜덤 선택 + 카테고리별 쿨다운(429 쿼터 / 403 권한 / 기타)
• 클라우드 소진 시 로컬 Ollama로 최종 폴백

무료 쿼터에 진심

• 사용 가능 모델 자동 탐색·교체: 기동 시 후보를 경량 probe 해 403/404 모델을 피하고 동작하는 모델을 기본값으로(예: gemini-flash-latest 403 → gemini-2.5-flash 자동 전환)
• 키별 쿼터 모니터링: 분/일(PT 기준) 사용량·한도·리셋 시각·쿨다운 추적
• 실측 probe: 다른 도구가 같은 키를 써서 생긴 외부 소진까지 실제 호출로 확인
• 웹·CLI 대시보드 동시 제공 — 터미널에서 quota_cli.py로 통계·키 쿼터·세션·로그·설정 조회(--watch 주기 갱신)

그 외

• 세션 영속화(SQLite WAL) + 컨텍스트 compaction(LLMLingua-2 압축, 폴백 체인)
• Playwright 웹 보강으로 학습 컷오프 보완(trafilatura markdown 추출)
• 보안: SSRF 차단(사설 IP·리다이렉트 재검증), admin fail-closed, 프론트 XSS 이스케이프
• 통합 SPA(/ui)에서 playground + 대시보드 + 키 상태

설치

pip install '.[dev,compression]'        # 런타임 + 압축(LLMLingua)
python -m playwright install chromium    # 웹 스크래퍼용 1회
cp .env.example .env                      # 키(GEMINI/GROQ/CEREBRAS) 입력
python main.py                            # 기본 :8000

참고: 다중 키 로테이션은 일부 제공자 ToS와 충돌할 수 있어, 본인 소유 키·허용 범위 내 사용을 전제로 합니다(저장소 DISCLAIMER.md 참조). Python 3.10+, pydantic v2.