mulkymalikuldhrs/ProxyGateLLM

ProxyGateLLM은 **22개의 AI 제공업체 (AI providers)**를 단일 통합 API로 집계하는 셀프 호스팅 방식의 오픈 소스 멀티-LLM 게이트웨이 (multi-LLM gateway)입니다. 이 서비스는 언어 모델에 대한 무료 액세스를 극대화하도록 설계되었습니다. 10개의 제공업체는 API 키 없이도 작동하며, 추가로 8개는 무료 가입만 필요합니다. 단 4개의 런타임 의존성 (runtime dependencies)만으로 구성된 ProxyGateLLM은 가볍고 설치가 빠르며 배포가 용이합니다.

이 게이트웨이는 **OpenAI 호환 API 엔드포인트 (OpenAI-compatible API endpoint)**를 제공하여, OpenAI SDK를 사용하는 모든 애플리케이션의 즉시 교체 가능한 대체재 (drop-in replacement)가 됩니다. 서킷 브레이커 (circuit breaker) 보호, 라운드 로빈 페일오버 (round-robin failover)를 통한 스마트 라우팅 (smart routing), 비용 추정, 그리고 모니터링을 위한 내장 PWA 대시보드를 포함하고 있습니다.

투명성 참고 사항: "무료" 제공업체는 Puter.js 클라이언트 측 인증 (user-pays model)을 사용합니다. 키가 필요 없는 10개의 제공업체는 사용자 API 키 없이 작동하지만, 사용량은 Puter.js의 속도 제한 (rate limits) 및 공정 사용 정책 (fair use policies)의 적용을 받습니다. BYOAPI 제공업체는 사용자의 유료 API 키를 필요로 합니다. 이것은 무제한 무료 서비스가 아니라, 무료 티어 (free-tier) 액세스를 편리하게 만들어주는 게이트웨이입니다.

#	제공업체 (Provider)	카테고리 (Category)	키 필요 여부 (Key Required)	비고 (Notes)
1	OpenAI GPT-4o-mini	🟢 키 없는 무료 (FREE no-key)	❌	Puter.js를 통해 이용
...
범례: 🟢 키 없는 무료 (FREE no-key) = Puter.js를 통해 즉시 작동 · 🟡 무료 키 (FREE-key) = 제공업체에서 무료 가입 필요 · 🔴 BYOAPI = 본인의 (유료) API 키 사용

22개의 모든 제공업체로 라우팅되는 단일 OpenAI 호환 /v1/chat/completions 엔드포인트를 제공합니다. 기존 OpenAI SDK 코드에서 baseURL만 변경하면 되며, 다른 변경 사항은 필요하지 않습니다.

설정 가능한 쿨다운 기간 (cooldown periods)을 갖춘 자동 장애 감지 기능을 제공합니다. 제공업체가 반복적으로 실패하면 서킷 브레이커 (circuit breaker)가 작동하여 트래픽을 건강한 대안으로 라우팅하며, 이를 통해 연쇄 장애 (cascading failures)와 타임아웃 대기를 방지합니다.

라운드 로빈 페일오버 (round-robin failover), 우선순위 기반 선택, 그리고 지연 시간 인식 라우팅 (latency-aware routing)을 지원합니다. 선호할 제공업체를 구성하면 게이트웨이가 오류 발생 시 폴백 (fallback)하는 동시에 자동으로 부하를 분산합니다.

토큰 카운팅 (token counting) 및 제공업체 속도 제한 테이블 (rate tables)을 통한 요청당 실시간 근사 비용 추적을 지원합니다. 여러 제공업체에 걸친 지출 현황을 파악할 수 있습니다 — 단, 추정치는 근사치이며 실제 청구 금액과는 다를 수 있습니다.

제공업체의 상태, 요청 처리량 (throughput), 오류율, 비용 지표를 모니터링할 수 있는 내장형 프로그레시브 웹 앱 (Progressive Web App, PWA)을 제공합니다 — 모든 기능은 /dashboard에서 접근 가능한 단일 인터페이스를 통해 확인할 수 있습니다.

런타임 의존성 (runtime dependencies)은 express, dotenv, @heyputer/puter.js, @anthropic-ai/sdk 단 4개뿐입니다. 공격 표면 (attack surface)이 작고, 설치가 빠르며, 감사가 용이합니다.

제공업체가 오류를 반환하면, 게이트웨이는 동일한 카테고리 내의 다음 사용 가능한 제공업체로 자동으로 재시도합니다 — 클라이언트 측의 재시도 로직 없이도 원활한 회복 탄력성 (resilience)을 제공합니다.

Docker 및 Docker Compose를 사용하여 단 한 번의 명령으로 배포할 수 있습니다. 구성 가능한 환경 변수를 갖춘 프로덕션 준비 완료 (production-ready) 컨테이너화 기술을 지원합니다.

우리는 투명성을 신뢰합니다. ProxyGateLLM을 사용하기 전에 반드시 알아야 할 중요한 제한 사항 및 명확한 설명은 다음과 같습니다.

"무료" 제공업체는 Puter.js 클라이언트 측 결제를 사용합니다 — 사용자는 API 키가 아닌 Puter.js를 통해 인증하고 결제합니다. 결제 관계는 이 게이트웨이가 아닌 Puter.js가 관리합니다.
제공업체 가용성은 제3자 서비스에 따라 달라집니다 — 해당 서비스는 언제든지 변경되거나, 모델을 지원 중단(deprecate)하거나, 속도 제한 (rate limits)을 부과할 수 있습니다.
무료 티어 제공업체에는 사용량 제한이 있습니다 — 개발, 프로토타이핑 및 가벼운 워크로드에는 적합하지만, 대량의 프로덕션 환경에는 적합하지 않습니다.
서킷 브레이커 (Circuit breaker) 임계값은 구성 가능하지만 배포 환경별로 조정이 필요합니다 — 기본 설정은 귀하의 트래픽 패턴에 비해 너무 공격적이거나 너무 관대할 수 있습니다.
비용 추정치는 근사치입니다 — 실제 비용은 제공업체의 가격 변동, 토큰화 (tokenization) 차이 및 반올림에 따라 달라집니다. 정확한 청구를 위해 추정치에만 의존하지 마십시오.
이것은 게이트웨이지, LLM 제공업체가 아닙니다 — ProxyGateLLM은 기존 제공업체로 요청을 라우팅합니다. 자체적으로 모델을 호스팅하거나 서비스하지 않습니다.

┌─────────────────────────────────────────────────────────────────┐
│ 클라이언트 애플리케이션 (Client Application) │
│ (OpenAI SDK / HTTP / Dashboard) │
...

서킷 브레이커 (Circuit Breaker)는 제공업체가 다운되거나 응답하지 않을 때 발생하는 연쇄 장애 (Cascading Failures)로부터 애플리케이션을 보호합니다.

┌──────────┐ 장애 임계값 (Failure threshold) ┌──────────┐
────►│ CLOSED │─────────────────────────►│ OPEN │
│ (정상) │ │ (트립됨) │
...

상태 (State)	동작 (Behavior)
CLOSED	정상 작동. 요청이 제공업체로 전달됩니다. 장애 횟수가 카운트됩니다.
OPEN	제공업체가 트립(Tripped)되었습니다. 모든 요청이 이 제공업체를 우회합니다. 쿨다운 타이머 (Cooldown timer)가 시작됩니다.
HALF-OPEN	쿨다운이 만료되었습니다. 단일 프로브 요청 (Probe request)이 전송됩니다. 성공 시 → CLOSED. 실패 시 → 다시 OPEN.

# .env
CIRCUIT_BREAKER_FAILURE_THRESHOLD=5 # 트립되기 전까지의 장애 횟수
CIRCUIT_BREAKER_COOLDOWN_MS=30000 # 쿨다운 지속 시간 (30초)
...

참고: 이 기본값들은 시작점일 뿐입니다. 트래픽이 높은 배포 환경에서는 더 짧은 쿨다운과 더 높은 임계값이 필요할 수 있습니다. 트래픽이 낮은 배포 환경에서는 성급한 재검증 (Re-probing)을 피하기 위해 더 긴 쿨다운이 필요할 수 있습니다. 배포 환경에 맞춰 조정하십시오.

ProxyGateLLM은 모든 요청에 대해 근사적인 비용 추적 (Cost tracking)을 제공합니다. 작동 방식을 이해하면 수치를 정확하게 해석하는 데 도움이 됩니다.

예상 비용 (Estimated Cost) = (prompt_tokens × input_rate) + (completion_tokens × output_rate)

요율 (Rates)은 구성 가능한 요율 테이블 (Rate table)에 제공업체별로 저장됩니다. 예시:

제공업체 (Provider)	입력 요율 (Input Rate, 1M 토큰당)	출력 요율 (Output Rate, 1M 토큰당)
GPT-4o-mini	~$0.15	~$0.60
...

예상치는 근사치입니다 — 제공업체의 가격은 빈번하게 변경되며 요율 테이블에 즉시 업데이트되지 않을 수 있습니다.
토큰화 (Tokenization) 방식이 다릅니다 — 제공업체마다 토큰을 계산하는 방식이 다를 수 있어 비용 차이가 발생할 수 있습니다.
무료 티어 제공업체는 $0.00으로 표시됩니다 — 하지만 Puter.js 측에서 비용을 청구할 수 있습니다. 이 게이트웨이는 측정 가능한 범위 내에서만 추적합니다.
반올림 오차가 누적됩니다 — 정확한 청구를 위해서는 항상 제공업체의 대시보드를 참조하십시오.

비용 데이터는 /v1/usage를 통해 확인할 수 있습니다.

엔드포인트(endpoint)이며 PWA 대시보드에 표시됩니다.

ProxyGateLLM은 가용성을 극대화하고 지연 시간(latency)을 최소화하기 위해 제공업체(provider) 간에 요청을 지능적으로 라우팅합니다.

전략 (Strategy)	설명 (Description)	최적의 용도 (Best For)
우선순위 (Priority)	설정된 순서대로 제공업체를 시도하며, 실패 시 다음으로 넘어감	특정 제공업체를 선호하는 경우
라운드 로빈 (Round-Robin)	사용 가능한 제공업체를 균등하게 순환함	무료 제공업체 간에 부하를 분산할 때
지연 시간 인식 (Latency-Aware)	최근 지연 시간이 가장 낮은 제공업체로 라우팅함	성능이 중요한 애플리케이션
비용 최적화 (Cost-Optimized)	여러 제공업체가 모델을 지원할 수 있을 때 더 저렴한 제공업체를 선호함	예산 중심의 워크로드

# .env
ROUTING_STRATEGY=priority # priority | round-robin | latency | cost
PROVIDER_PRIORITY=gpt-4o-mini,claude-3.5-sonnet,gemini-2.0-flash
...

요청 (Request) ──► 제공업체 A (Provider A) ──► 오류 (Error) ──► 제공업체 B (Provider B) ──► 오류 (Error) ──► 제공업체 C (Provider C) ──► 성공 (Success)
(서킷 브레이커 (circuit breaker)
작동 시 건너뜀) (서킷 브레이커 (circuit breaker)
작동 시 탐색 허용)

요청이 실패하면, 라우터는 우선순위 체인 내의 다음 정상적인 제공업체를 즉시 시도합니다. 서킷 브레이커(circuit breaker)는 작동 중인(tripped) 제공업체를 건너뛰어, 이미 실패가 확인된 엔드포인트에 시간을 낭비하는 것을 방지합니다.

Node.js >= 18, npm >= 9

# 1. 저장소 복제 (Clone the repository)
git clone https://github.com/mulkymalikuldhrs/ProxyGateLLM.git
cd ProxyGateLLM
...

# 게이트웨이는 http://localhost:3333 에서 실행 중이어야 합니다
curl http://localhost:3333/v1/models

curl -X POST http://localhost:3333/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
...

from openai import OpenAI
client = OpenAI(
base_url="http://localhost:3333/v1",
...

메서드 (Method)	엔드포인트 (Endpoint)	설명 (Description)
GET	/v1/models	사용 가능한 모든 모델과 해당 제공자 (provider) 상태 목록을 나열합니다
POST	/v1/chat/completions	OpenAI 호환 채팅 완성 (chat completion) 엔드포인트
POST	/v1/chat/completions (stream)	스트리밍 채팅 완성 ("stream": true)
GET	/v1/usage	대략적인 비용 및 사용 통계 가져오기
GET	/health	게이트웨이 상태 확인 (health check) 및 제공자 상태
GET	/dashboard	PWA 모니터링 대시보드

{
"model": "gpt-4o-mini",
"messages": [
...

표준 OpenAI 채팅 완성 응답 형식을 따르며, OpenAI SDK 및 이를 기반으로 구축된 모든 도구와 완전히 호환됩니다.

ProxyGateLLM은 /dashboard에서 접속 가능한 내장 Progressive Web App (PWA) 대시보드를 포함하고 있습니다.

제공자 상태 (Provider Health) — 22개 모든 제공자의 실시간 상태 (정상 (healthy) / 차단됨 (tripped) / 조사 중 (probing))
요청 메트릭 (Request Metrics) — 처리량 (throughput), 지연 시간 백분위수 (latency percentiles), 에러율 (error rates)
비용 추적 (Cost Tracking) — 제공자별, 모델별, 시간 범위별 대략적인 지출액
서킷 브레이커 제어 (Circuit Breaker Controls) — 차단된 회로를 확인하고 수동으로 재설정
다크 모드 (Dark Mode) — 어떤 환경에서도 편안한 모니터링

대시보드는 PWA입니다. 브라우저 탭을 열지 않고도 기기에 설치하여 빠르게 접속할 수 있습니다.

# 클론 및 설정 (Clone and configure)
git clone https://github.com/mulkymalikuldhrs/ProxyGateLLM.git
cd ProxyGateLLM
...

# 이미지 빌드 (Build the image)
docker build -t proxygate-llm .
# 컨테이너 실행 (Run the container)
...

version: '3.8'
services:
proxygate-llm:
...

ProxyGateLLM은 오픈 소스 AI 게이트웨이 프로젝트인 OmniRoute에서 영감을 받았습니다. ProxyGateLLM은 자체적인 아키텍처와 기능 세트를 갖추고 처음부터 구축되었지만, 통합된 멀티 제공자 API 게이트웨이라는 개념은 이 분야를 개척한 OmniRoute와 같은 프로젝트들에 공을 돌립니다.

교육 및 연구 목적으로만 사용하십시오 (For Education and Research Purpose Only)

이 프로젝트는 엄격히 교육 및 연구 목적으로만 제공됩니다. 저자 및 기여자는 이 소프트웨어의 사용으로 인해 발생하는 어떠한 손해, 손실 또는 위험에 대해서도 어떠한 책임도 지지 않습니다 (no responsibility or liability).

저희는 제공업체의 가용성을 보장하지 않습니다 — 제3자 서비스는 언제든지 변경되거나, 속도 제한 (rate-limit)이 걸리거나, 무료 티어 (free tiers)를 중단할 수 있습니다. 저희는 Puter.js 또는 BYOAPI 제공업체를 통해 발생하는 비용에 대해 어떠한 책임도 지지 않습니다 — 사용량을 주의 깊게 모니터링하십시오. 저희는 어떠한 제공업체의 응답 품질, 안전성 또는 정확성도 보증하거나 지지하지 않습니다. - 사용자의 책임 하에 사용하십시오. 통합하기 전에 항상 제공업체의 서비스 약관을 검토하십시오.

이 프로젝트는 MIT 라이선스 (MIT License) 하에 라이선스가 부여됩니다 — 자세한 내용은 LICENSE 파일을 참조하십시오.

MIT License
Copyright © 2024-2026 Mulky Malikul Dhaher. All rights reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy
...

Mulky Malikul Dhaher