LiteLLM 기반 사내 LLM API 통합 게이트웨이 구축 예시
LiteLLM 기반 사내 LLM API 통합 게이트웨이 구축 예시
개요
여러 서비스가 Gemini, OpenAI, Claude 같은 LLM 공급자 API를 각각 직접 호출하면 키 관리, 사용량 추적, 호출 제한, 예산 통제가 프로젝트마다 달라집니다. 공급자 키가 여러 애플리케이션에 퍼지면서 교체와 회수도 어려워질 수 있습니다.
LLM API 통합 게이트웨이는 사내 서비스와 외부 LLM 공급자 사이에 단일 통제 계층을 둡니다. 각 서비스에는 공급자 키 대신 게이트웨이 가상 키를 발급하고, 게이트웨이가 모델 라우팅, 인증, 호출 제한, 비용 집계와 차단을 담당합니다.
이 문서는 LiteLLM을 사용해 이런 구조를 구축할 때 필요한 구성요소, 구축 순서, 사전에 확정할 정책과 검수 기준을 정리한 예시입니다. 특정 회사 환경에 그대로 적용하는 완성형 설계가 아니며, 실제 트래픽과 보안 정책에 맞춘 조정이 필요합니다.
적용하기 좋은 경우
- 여러 프로젝트가 동일하거나 서로 다른 LLM 공급자를 사용한다.
- 공급자 API 키를 각 애플리케이션에 직접 배포하고 있다.
- 프로젝트별 사용량과 비용을 구분하기 어렵다.
- 한 프로젝트의 과도한 호출이 전체 예산이나 공급자 할당량에 영향을 줄 수 있다.
- 모델 교체 때 모든 애플리케이션을 수정하지 않고 중앙 설정으로 전환하고 싶다.
- 호출 기록과 오류를 공통 형식으로 관찰할 필요가 있다.
목표 구조
사내 서비스 A ─┐
사내 서비스 B ─┼─ 가상 API 키 ─ 내부 DNS/TLS ─ LiteLLM Gateway ─ Gemini
사내 서비스 C ─┘ │ ├─ OpenAI(확장)
│ └─ Claude(확장)
├─ Redis: 호출량·예산 카운터
├─ PostgreSQL: 키·사용량·설정
├─ Secret Manager: 공급자 키·관리 키
└─ Langfuse: 추적·관측(선택)
애플리케이션은 LiteLLM의 OpenAI 호환 엔드포인트와 내부 모델 이름만 사용합니다. 실제 공급자, 모델 버전, 공급자 키는 게이트웨이 설정에서 관리합니다.
예를 들어 애플리케이션에는 gemini-fast, gemini-quality 같은 안정적인 내부 이름을 제공하고, 실제 공급자 모델은 중앙 설정에서 연결할 수 있습니다. 모델 변경이 필요할 때 애플리케이션 코드를 일괄 수정하지 않고 라우팅 설정을 변경할 수 있습니다.
필수 구성요소
| 구성요소 | 역할 | 운영 시 확인할 사항 |
|---|---|---|
| LiteLLM Proxy | 단일 API, 인증, 모델 라우팅, 비용·호출 제한 | 버전 고정, 상태 확인, 타임아웃, 재시도 정책 |
| PostgreSQL | 가상 키, 사용자·팀, 지출과 설정 저장 | 백업, 복원, 암호화, 마이그레이션 |
| Redis | 분산 호출 제한과 예산 카운터 | 영속화, 장애 정책, TLS, 접근 통제 |
| 내부 로드밸런서 또는 리버스 프록시 | TLS 종료, 접근 경로, 추가 호출 제한 | 내부 DNS, 인증서, 소스 네트워크 제한 |
| Secret Manager | Gemini 키, LiteLLM 관리 키와 Salt Key 보관 | 평문 환경 파일 배포 방지, 접근 감사, 교체 절차 |
| 관측 도구 | 오류, 지연 시간, 사용량과 추적 확인 | 프롬프트·응답 저장 여부, 마스킹, 보존 기간 |
배포 형태 예시
검증 또는 소규모 단일 서버 구성
한 대의 전문 호스팅 환경 또는 관리형 클라우드 VM에서 Docker Compose로 LiteLLM, PostgreSQL, Redis를 실행합니다. 구축과 인수인계가 단순하지만 서버 한 대의 장애가 전체 게이트웨이 중단으로 이어집니다. 자동 장애조치, 수평 확장과 무중단 업그레이드는 별도로 설계해야 합니다.
운영 안정성을 높인 구성
내부 로드밸런서 뒤에 LiteLLM 인스턴스를 둘 이상 배치하고 PostgreSQL과 Redis는 관리형 서비스 또는 별도 고가용성 구성으로 운영합니다. 애플리케이션 컨테이너의 스키마 변경을 막고 전용 마이그레이션 작업을 두면 업그레이드와 롤백을 통제하기 쉽습니다.
구성 선택은 예상 호출량보다 허용 가능한 중단 시간, 복구 목표, 운영 인력과 데이터 보호 기준을 먼저 고려해야 합니다.
정책 설계 예시
가상 키 단위
공급자 키를 프로젝트에 배포하지 않고 프로젝트와 환경별 LiteLLM 가상 키를 발급합니다.
- 서비스와 환경마다 별도 키 사용: 예) 주문 서비스 운영, 주문 서비스 검증
- 키별 허용 모델 제한
- 키 소유자와 담당 팀을 메타데이터로 기록
- 만료일과 회수 절차 정의
- LiteLLM Master Key는 운영 자동화에서만 사용하고 애플리케이션에 배포하지 않음
예산과 호출 제한
현재 LiteLLM은 키, 사용자, 팀에 RPM(분당 요청 수), TPM(분당 토큰 수), 최대 동시 요청 수를 설정할 수 있습니다. 키 하나에 일일·월간 예산 창을 함께 적용하는 구성도 가능합니다.
{
"models": ["gemini-fast"],
"rpm_limit": "<requests-per-minute>",
"tpm_limit": "<tokens-per-minute>",
"max_parallel_requests": "<parallel-request-limit>",
"budget_limits": [
{ "budget_duration": "24h", "max_budget": "<daily-budget-usd>" },
{ "budget_duration": "30d", "max_budget": "<monthly-budget-usd>" }
],
"metadata": {
"service": "<service-name>",
"environment": "<environment>"
}
}
위 값은 형식을 설명하기 위한 자리표시자입니다. 실제 한도는 예상 트래픽, 요청당 최대 토큰, 공급자 할당량과 장애 시 영향을 기준으로 정해야 합니다.
LiteLLM 공식 제한 단위는 RPM, TPM, 최대 동시 요청 수입니다. 정확한 초당 요청 수 제한이 필요하면 API Gateway, 리버스 프록시 또는 Redis 기반 사용자 정의 미들웨어를 추가해야 합니다.
예산 차단 정책
LiteLLM은 빠른 예산 확인을 위해 Redis 카운터를 사용하고 PostgreSQL 기록과 정합성을 맞춥니다. Redis와 DB 상태를 확인할 수 없을 때 요청을 허용할지 차단할지 결정해야 합니다.
비용 차단이 가용성보다 중요하다면 fail_closed_budget_enforcement 사용을 검토합니다. 이 설정은 예산을 검증할 수 없는 요청을 거절하는 대신 Redis 또는 DB 장애 시 정상 요청도 중단될 수 있습니다.
요청의 최종 비용은 응답이 생성된 뒤 확정되므로 예산 한도만으로 모든 초과 지출을 완전히 없애기는 어렵습니다. 큰 단일 요청과 동시에 진행 중인 요청의 영향을 줄이려면 예산, TPM, 최대 출력 토큰과 동시 요청 제한을 함께 사용해야 합니다.
구축 전에 확정할 사항
| 항목 | 선택 또는 질문 | 결정이 필요한 이유 |
|---|---|---|
| Gemini 인증 방식 | Google AI Studio API 키 또는 Vertex AI | 인증, 네트워크, 권한과 비용 집계 방식이 달라짐 |
| 대상 기능 | 채팅, 스트리밍, 도구 호출, 구조화 출력, 임베딩, 이미지 등 | 필요한 호환성 테스트 범위를 정함 |
| 내부 모델 이름 | 공급자 이름 노출 또는 안정적인 별칭 | 향후 모델 교체와 애플리케이션 수정 범위에 영향 |
| 키 발급 단위 | 프로젝트, 서비스, 팀, 운영·검증 환경 | 비용 귀속과 사고 시 차단 범위를 정함 |
| 호출 제한 | 키·팀·모델별 RPM, TPM, 동시 요청 수 | 과도한 호출과 공급자 429 오류를 줄임 |
| 초당 제한 | 필요한지, 전역인지 키별인지 | LiteLLM 외부 제한 계층 필요 여부를 결정 |
| 예산 기간 | 일·월 한도와 초기화 시간대 | LiteLLM 기본 예산 창은 UTC 기준으로 동작 |
| 장애 정책 | 예산 확인 불가 시 허용 또는 차단 | 비용 보호와 서비스 가용성 사이의 기준 |
| 재시도·대체 모델 | 재시도 횟수, 대체 모델, 재시도 대상 오류 | 중복 비용과 응답 품질 변화를 통제 |
| 네트워크 | 내부 전용 주소, 허용 대역, 외부 송신 정책 | 공격 표면과 사내 연동 방식을 정함 |
| TLS | 내부 CA, 관리형 인증서 또는 공인 인증서 | 인증서 발급과 갱신 책임을 정함 |
| 비밀정보 | 사용할 Secret Manager와 접근 주체 | 공급자 키와 관리 키 유출을 방지 |
| 로그 데이터 | 프롬프트·응답 저장, 마스킹, 보존 기간 | 개인정보와 기밀정보 노출 위험을 통제 |
| 가용성 | 단일 서버 또는 다중 인스턴스 | 배포 방식, 비용, 복구 절차에 영향 |
| 백업·복구 | RPO, RTO, 백업 주기와 복구 시험 | DB 손상과 운영 실수에 대비 |
| Langfuse | 제외, 외부 서비스 연동, 자체 호스팅 | 인프라와 데이터 저장 범위가 크게 달라짐 |
| 인프라 코드 | Docker Compose만 제공 또는 Terraform 포함 | 환경 재현성과 변경 이력을 결정 |
단계별 구축 절차
1. 사용 현황 조사
연동 대상 서비스, 현재 사용하는 Gemini 기능, 모델, 평균·최대 호출량, 요청당 토큰과 오류 처리 방식을 조사합니다. 기존 공급자 키가 저장된 위치와 교체 가능한 배포 절차도 확인합니다.
2. 정책과 이름 설계
가상 키 발급 단위, 내부 모델 별칭, 허용 모델, 예산, 호출 제한, 로그 저장 범위를 문서로 확정합니다. 운영 환경과 검증 환경의 키와 예산은 분리합니다.
3. 네트워크와 데이터 저장소 구성
내부 DNS, TLS, 보안 그룹, 외부 LLM API로 나가는 HTTPS 경로를 구성합니다. PostgreSQL과 Redis에는 애플리케이션 네트워크에서만 접근하도록 제한하고 백업과 영속화 정책을 적용합니다.
4. LiteLLM 배포
이동하는 이미지 태그 대신 검증한 버전을 고정합니다. LiteLLM Master Key, Salt Key, 공급자 키는 Secret Manager에서 주입하고 로그와 설정 파일에 평문으로 남기지 않습니다. 상태 확인과 재시작 정책도 함께 구성합니다.
5. Gemini와 모델 라우팅 설정
Gemini 모델을 내부 모델 이름에 연결하고 타임아웃, 재시도와 오류 변환을 확인합니다. 향후 OpenAI나 Claude를 추가할 때 같은 내부 API 형식을 유지할 수 있도록 모델 목록과 공급자 설정을 분리합니다.
6. 키 관리 자동화
LiteLLM 관리 API를 감싼 Shell 또는 Python CLI를 작성합니다. 최소 기능은 키 발급, 조회, 수정, 차단, 해제와 삭제입니다. Master Key가 터미널 기록이나 출력에 노출되지 않도록 입력과 로그를 제한합니다.
7. 예산과 호출 제한 검증
작은 시험 한도로 일일·월간 예산, RPM, TPM과 동시 요청 제한을 각각 초과시켜 거절 동작을 확인합니다. Redis 재시작, DB 연결 실패와 공급자 429 응답에서도 정의한 정책대로 동작하는지 확인합니다.
8. 관측과 알림 구성
키·서비스·모델별 호출 수, 토큰, 비용, 지연 시간과 오류율을 확인할 수 있게 합니다. 프롬프트와 응답은 기본 저장 대상으로 가정하지 말고 데이터 분류 정책에 따라 명시적으로 허용하거나 마스킹합니다.
9. 단계적 전환
검증 환경에서 기존 Gemini 직접 호출과 게이트웨이 결과를 비교한 뒤 서비스별로 순차 전환합니다. 전환이 끝나면 애플리케이션에 남은 공급자 키를 회수합니다. 장애 시 공급자 직접 호출을 허용할지 여부는 사전에 정한 정책을 따릅니다.
10. 운영 인수인계
키 발급과 회수, 예산 변경, 모델 추가, 로그 확인, 장애 대응, 백업 복원, 버전 업그레이드와 롤백 절차를 관리자 매뉴얼과 실행 예제로 제공합니다.
Langfuse 선택 범위
LiteLLM에서 기존 Langfuse로 호출 추적을 보내는 연동은 콜백과 인증 정보 설정이 중심입니다. 프롬프트와 응답을 보내지 않으려면 전체 메시지 로깅을 끄거나 요청별 입력·출력 마스킹을 적용해야 합니다.
Langfuse 자체 호스팅은 단순 화면 추가가 아닙니다. 현재 구성에는 Langfuse Web, Worker, PostgreSQL, Redis, ClickHouse와 객체 저장소가 포함됩니다. Docker Compose 구성은 검증 또는 소규모 환경에 적합하지만 고가용성, 수평 확장과 자동 백업은 별도 설계가 필요합니다. 따라서 기본 게이트웨이 구축과 별도 선택 범위로 구분하는 편이 안전합니다.
검수 기준 예시
- 유효한 가상 키로 허용된 모델을 호출할 수 있다.
- 잘못되거나 차단·삭제된 키의 요청은 거절된다.
- 키가 허용하지 않은 모델을 호출할 수 없다.
- RPM, TPM과 동시 요청 제한을 넘기면 정의한 오류로 거절된다.
- 일일·월간 예산 창이 독립적으로 집계되고 한도 초과 요청이 차단된다.
- Redis와 PostgreSQL 장애 상황에서 합의한 허용·차단 정책이 적용된다.
- 스트리밍, 도구 호출, 구조화 출력 등 실제 서비스가 사용하는 기능이 프록시를 거쳐 동작한다.
- 서비스·키·모델별 사용량과 비용을 조회할 수 있다.
- 로그와 오류 응답에 공급자 키, Master Key와 비밀정보가 노출되지 않는다.
- PostgreSQL 백업을 별도 환경에 복원할 수 있다.
- 설정과 매뉴얼만으로 운영자가 새 모델을 추가하고 시험할 수 있다.
- 애플리케이션 배포 환경에서 기존 공급자 키가 제거된다.
산출물 예시
- 인프라 아키텍처 구성도와 네트워크 흐름
- 버전이 고정된 Docker Compose 또는 배포 설정
- LiteLLM 모델·라우팅·보안 설정 파일
- 환경 변수 예시와 Secret Manager 연결 안내
- 가상 키 발급·수정·차단·삭제 CLI
- 예산·호출 제한 관리 API 예제 또는 Postman 컬렉션
- 상태 확인, 로그, 백업·복구와 장애 대응 런북
- Gemini 연동과 서비스별 전환 시험 결과
- OpenAI·Claude 등 공급자와 모델 추가 매뉴얼
- 보안 검토와 최종 검수 결과
예시 일정
| 기간 | 주요 작업 |
|---|---|
| 1주차 | 현황 조사, 정책 확정, 네트워크·PostgreSQL·Redis 구성 |
| 2주차 | LiteLLM 배포, Gemini 연동, 가상 키와 예산·호출 제한 적용 |
| 3주차 | 운영 CLI, 관측·알림, 백업과 장애 대응 절차 작성 |
| 4주차 | 서비스 연동, 부하·장애 시험, 문서화와 인수인계 |
단일 서버와 한 개 공급자 모델로 시작하는 구축 예시입니다. 다중 리전, 고가용성, Langfuse 자체 호스팅, 사내 SSO, 감사 로그, 무중단 배포와 인프라 코드까지 포함하면 별도 일정과 검수가 필요합니다.