sxueck/llm-gateway

프로덕션급 LLM 게이트웨이 관리 시스템, 배포 6개월 만에 500억 토큰 이상의 안정적인 부하 처리 달성 (지속적으로 누적 중). 여러 LLM 제공업체, 가상 키(Virtual Key), 라우팅 설정 및 모델 관리를 위한 직관적인 Web UI 인터페이스를 제공합니다.

기능	설명
제공업체 관리	20개 이상의 주요 LLM 제공업체 지원: OpenAI, Anthropic, Google, DeepSeek 등
가상 키	가상 API 키 생성 및 관리, 속도 제한(Rate Limiting) 및 액세스 제어 지원
라우팅 설정	부하 분산(Load Balancing) 및 장애 조치(Failover) 전략을 통한 서비스 가용성 향상
모델 관리	모든 제공업체의 모델을 통합 관리, 일괄 가져오기 및 사용자 정의 설정 지원
멀티 엔드포인트 지원	/v1/chat/completions, /v1/responses, /v1/messages 등의 엔드포인트와 호환
상태 모니터링	로그인 없이 접근 가능한 상태 체크 페이지, 모델 가용률, 지연 시간 분위수(P50/P95) 및 에러 분포를 실시간 전시
사용자 인증	JWT 기반의 보안 인증 메커니즘
실시간 모니터링	대시보드를 통해 시스템 상태 및 설정 정보 전시
중계 스테이션 지원	Codex 등 상위(Upstream)에서 강제로 주입하는 프롬프트(Prompt)를 격리하여, 하위(Downstream) 애플리케이션이 프롬프트를 더 규격화된 방식으로 따를 수 있도록 함
내장 PII 보호	요청 내 개인 식별 정보(PII)를 자동 감지 및 비식별화, 스트리밍 응답 복구 지원

의존성	버전 요구사항	설명
Node.js	>= v22	런타임 환경
...

# 저장소 클론
git clone https://github.com/sxueck/llm-gateway.git
cd llm-gateway
...

.env 파일을 생성하고 환경 변수를 설정합니다:

cp .env.example .env

.env 파일을 편집합니다 (최소한 MySQL과 JWT_SECRET 설정이 필요합니다):

PORT=3000
NODE_ENV=development
LOG_LEVEL=info
...

중요: 프로덕션 환경에서는 반드시 JWT_SECRET을 강력한 랜덤 문자열(최소 32자 이상)로 수정하십시오.

# 백엔드(3000)와 프론트엔드(5173)를 동시에 시작
bun run dev:all

서비스	주소
Web UI	http://localhost:5173
Backend API	http://localhost:3000

개별 시작:

# 백엔드만 시작
bun run dev:backend
# 프론트엔드만 시작
...

프로덕션 빌드 및 시작 (프론트엔드/백엔드 분리 배포):

# 프론트엔드 및 백엔드 빌드
bun run build
# 백엔드 시작 (프로덕션 모드)
...

팁: 프론트엔드 결과물은 packages/web/dist에 위치하며, Nginx 또는 정적 파일 서버를 사용하여 별도로 배포하십시오.

Docker 배포 가이드를 참조하십시오.

공급업체 추가 - DeepSeek와 같은 AI 서비스 제공업체를 추가하고 공급업체 키를 입력합니다.
모델 추가 - 공급업체가 제공하는 AI 모델(예: DeepSeek의 deepseek-chat)을 추가합니다.
가상 키 생성 - LLM Gateway의 API에 액세스하는 데 사용됩니다.
(선택 사항) 프롬프트 관리 규칙 구성 - 프롬프트의 동적 수정 및 강화를 구현합니다.
가상 키를 사용하여 API 액세스 - 애플리케이션에서 LLM Gateway를 호출합니다.

LLM Gateway는 공개 상태 모니터링 페이지를 제공하며, 로그인 없이도 접근하여 각 모델의 가용성과 성능 지표를 실시간으로 확인할 수 있습니다.

• "시스템 설정 -> 모니터링 설정"에서 "지속적 모니터링 활성화"를 켭니다.
• 처음 활성화할 때 시스템은 자동으로 "모니터링 전용 가상 키"를 생성합니다:
  • 모든 모델에 대한 액세스 권한을 가집니다.
  • 상태 체크 전용으로만 사용됩니다.
  • 기본적으로 요청 본문/응답 본문 로그는 비활성화됩니다.

"지속적 모니터링"이 활성화된 상태에서만 다음 기능이 작동합니다:

• 백엔드 상태 체크 스케줄러 실행 (대상에 대해 주기적으로 상태 체크 수행)
• 공개 모니터링 페이지 및 관련 인증 없는 API 접근 가능

팁: 언제든지 "지속적 모니터링"을 끌 수 있으며, 끌 경우 스케줄러가 중단되고 공개 접근이 차단됩니다 (공개 엔드포인트는 404 반환).

http://your-gateway-url/status에 접속하면 상태 모니터링 페이지를 볼 수 있습니다.

실시간 상태 모니터링 - 구성된 모든 모델 대상의 현재 상태(정상/성능 저하/다운)를 표시
가용률 통계 - 1시간 및 24시간 가용률 표시
지연 시간 지표 - P50 및 P95 지연 시간 통계
에러 추적 - 에러 유형 및 에러 메시지를 기록하고 표시
자동 새로고침 - 기본 60초마다 데이터 자동 새로고침
상세 이력 - 대상을 클릭하여 상세한 체크 이력을 확인 가능

상태 모니터링은 다음과 같은 공개 API 엔드포인트를 제공합니다 (인증 불필요):

엔드포인트 (Endpoint)	설명
GET /public/health/summary	모든 대상의 요약 정보 가져오기
GET /public/health/targets	대상 목록 가져오기
GET /public/health/detail?target_id=xxx	단일 대상의 상세 정보 가져오기
GET /public/health/runs?target_id=xxx&window=24h&page=1&page_size=50	체크 이력 가져오기

상태 체크 (Health Check) 대상은 데이터베이스를 통해 설정하며, 모든 모델 또는 가상 모델에 대해 상태 체크를 설정할 수 있습니다:

-- 예시: 모델에 상태 체크 추가
INSERT INTO health_targets (id, name, type, target_id, enabled, check_interval_seconds, check_prompt)
VALUES ('target-1', 'DeepSeek Chat', 'model', 'model-id-here', 1, 300, 'Say "OK"');

주요 설정 파라미터 (Parameters):

파라미터	설명	기본값
check_interval_seconds	체크 주기 (초)	300초 (5분)
check_prompt	상태 체크에 사용되는 프롬프트 (Prompt)	"Say 'OK'"
check_config	타임아웃(Timeout), 재시도(Retry) 등의 파라미터를 설정할 수 있는 JSON 설정	-

상태 모니터링 API는 기본적으로 속도 제한 (Rate Limiting) 보호가 활성화되어 있습니다:

• 각 IP당 분당 최대 60개의 요청
• 제한 초과 시 429 에러 반환

Issue 및 Pull Request 제출을 환영합니다!

MIT License - LLM Gateway