Skip to main content

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.how with Speech API Token
  • 내부 speech-service -> llm.apis.how with 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}로 치환해서 이해하면 됩니다.

함께 보면 좋은 문서​