LiteLLM Gateway
multi-saas-kit은 AI/LLM 기능을 빠르게 도입할 수 있도록 LiteLLM 기반 LLM Gateway 를 기본 제공 방향으로 채택합니다.
이 문서의 핵심은 간단합니다.
- 신규 도입 개발사가 공급사별 API를 직접 제어하지 않아도 됩니다.
- 플랫폼은 기본적으로
llm.apis.how+ LiteLLM 구조를 권장합니다. - 앱은 OpenAI-compatible API와 내부 model alias만 알면 됩니다.
제공 방식
LiteLLM Gateway는 두 모드로 이해하면 좋습니다.
1. Managed Mode
귀사 운영 서비스 사용:
llm.apis.how
이 모드는 빠른 시작에 유리합니다.
2. Self-Hosted Mode
구입사가 직접 운영:
- 기본 권장 도메인:
llm.${ROOT_DOMAIN} - 예:
llm.codebase.how,llm.infra.acme.com
이 모드는 kit의 독립성과 확장성을 높입니다.
권장 원칙
- 기본 설계는 self-hosted 가능성 을 전제로 합니다.
- managed endpoint는 빠른 시작 옵션 으로 설명합니다.
왜 기본 제공으로 두는가
실무에서는 다음 기능이 거의 항상 필요합니다.
- 여러 LLM 공급사 연결
- 키 관리
- budget / rate-limit
- fallback / retry
- 비용 추적
- 운영 대시보드
이 기능을 프로젝트마다 다시 만들면 도입 속도가 크게 떨어집니다.
그래서 multi-saas-kit은 LiteLLM을 기본 LLM control plane 으로 두고, 플랫폼은 그 위에 운영 정책과 제품 UX를 얹는 방향을 권장합니다.
기본 제공 범위
LiteLLM 기반 기본 제공 범위는 다음과 같습니다.
- virtual key 발급
- model alias
- provider routing
- fallback / retry
- spend tracking
- budget / rate-limit
- observability 연동
API Access Key Core와의 관계
LiteLLM 자체는 virtual key와 gateway 정책을 담당하지만, multi-saas-kit는 상위 API 서비스의 외부 인증을 공용 API Access Key Core 로 통합하는 방향을 사용합니다.
예:
- 외부 browser/app ->
speech.apis.howwithSpeech API Token - 내부
speech-service->llm.apis.howwith LiteLLM internal key
즉 LiteLLM virtual key와 API access key는 경쟁 관계가 아니라 계층이 다릅니다.
권장 구조
App / Worker / Client
│
│ OpenAI-compatible API + Virtual Key
▼
llm.<root-domain> or llm.apis.how
│
├─ 운영 정책 / 문서 / 관리 UI
└─ LiteLLM Gateway
│
├─ OpenAI
├─ Anthropic
├─ Vertex AI
├─ DeepSeek
├─ xAI
└─ OpenRouter
개발사가 좋아할 만한 이유
1. 바로 시작 가능
공급사별 API 차이를 학습하기 전에, 우선 하나의 OpenAI-compatible endpoint로 붙일 수 있습니다.
2. 모델 교체 비용 감소
앱이 공급사 원본 모델명 대신 alias를 사용하면, 운영자는 gateway 설정만 바꿔도 됩니다.
3. 키 보안이 단순해짐
앱에 공급사 원본 키를 넣는 대신 virtual key만 배포하면 됩니다.
4. 운영 기능이 기본 포함
예산, 속도 제한, fallback, 비용 추적을 starter 단계부터 사용할 수 있습니다.
운영 권장사항
- 앱 트래픽에는
master_key대신 virtual key를 사용하세요. - model alias를 먼저 정의하고 앱 코드에는 alias만 노출하세요.
- Redis + DB를 함께 두고 spend / rate-limit / 캐시 운영을 분리하세요.
- fallback 대상 모델을 최소 1개 이상 두세요.
- observability 도구를 최소 1개 이상 연결하세요.
- 상위 API 서비스 usage와 LiteLLM spend log를 연결해 actual cost를 backfill 하세요.
플랫폼에서의 위치
LiteLLM은 다음 관점에서 이해하면 좋습니다.
- LiteLLM: 범용 gateway 엔진
- llm.apis.how: multi-saas-kit용 운영/정책/제품 레이어
- API Access Key Core: 상위 API 서비스의 공통 외부 인증/정책 레이어
- docs.codebase.how: 도입 개발사를 위한 공식 사용 가이드
Self-hosted 배포에서는 이 레이어를 llm.${ROOT_DOMAIN}로 치환해서 이해하면 됩니다.