DB에 저장되는 것
DB에 저장되는 것 (What is stored in the DB)
LiteLLM 프록시는 PostgreSQL 데이터베이스를 사용해 다양한 정보를 저장해요. DB가 사용되는 주요 기능은 다음과 같아요.
출처: 문서
본문
- 가상 키, 조직, 팀, 사용자, 예산 등.
- 요청별 사용량 추적.
DB 스키마 링크: 전체 DB 스키마를 여기에서 볼 수 있어요.
DB 테이블 (DB Tables)
조직, 팀, 사용자, 최종 사용자 (Organizations, Teams, Users, End Users)
| 테이블 이름 | 설명 | 행 삽입 빈도 |
|---|---|---|
| LiteLLM_OrganizationTable | 조직 수준 구성을 관리. 조직 지출, 모델 액세스, 메타데이터 추적. 예산 구성과 팀에 연결. | 낮음 |
| LiteLLM_TeamTable | 조직 내 팀 수준 설정 처리. 팀 구성원, 관리자, 역할 관리. 팀별 예산, 요율 제한, 모델 액세스 제어. | 낮음 |
| LiteLLM_UserTable | 사용자 정보와 설정 저장. 개별 사용자 지출, 모델 액세스, 요율 제한 추적. 사용자 역할과 팀 멤버십 관리. | 낮음 |
| LiteLLM_EndUserTable | 최종 사용자 구성 관리. 모델 액세스와 리전 요구사항 제어. 최종 사용자 지출 추적. | 낮음 |
| LiteLLM_TeamMembership | 팀 참여 추적. 팀별 사용자 예산과 지출 관리. | 낮음 |
| LiteLLM_OrganizationMembership | 조직 내 사용자 역할 관리. 조직별 사용자 권한과 지출 추적. | 낮음 |
| LiteLLM_InvitationLink | 사용자 초대 처리. 초대 상태와 만료 관리. 초대를 만든/수락한 사람 추적. | 낮음 |
| LiteLLM_UserNotifications | 모델 액세스 요청 처리. 사용자의 모델 액세스 요청 추적. 승인 상태 관리. | 낮음 |
인증 (Authentication)
| 테이블 이름 | 설명 | 행 삽입 빈도 |
|---|---|---|
| LiteLLM_VerificationToken | 가상 키와 그 권한 관리. 토큰별 예산, 요율 제한, 모델 액세스 제어. 키별 지출과 메타데이터 추적. | 중간 - 모든 가상 키 저장 |
모델 (LLM) 관리 (Model (LLM) Management)
| 테이블 이름 | 설명 | 행 삽입 빈도 |
|---|---|---|
| LiteLLM_ProxyModelTable | 모델 구성을 저장. 사용 가능한 모델과 그 파라미터 정의. 모델별 정보와 설정 포함. | 낮음 - 구성 전용 |
예산 관리 (Budget Management)
| 테이블 이름 | 설명 | 행 삽입 빈도 |
|---|---|---|
| LiteLLM_BudgetTable | 조직, 키, 최종 사용자용 예산·요율 제한 구성 저장. 최대 예산, 소프트 예산, TPM/RPM 한도, 모델별 예산 추적. 예산 기간과 리셋 시점 처리. | 낮음 - 구성 전용 |
추적 & 로깅 (Tracking & Logging)
| 테이블 이름 | 설명 | 행 삽입 빈도 |
|---|---|---|
| LiteLLM_SpendLogs | 모든 API 요청의 상세 로그. 토큰 사용량, 지출, 타이밍 정보 기록. 사용된 모델과 키 추적. | 중간 - 간격으로 실행되는 배치 프로세스 |
| LiteLLM_DailyUserSpend 및 형제 테이블 (DailyTeamSpend, DailyOrgSpend, DailyTagSpend, DailyEndUserSpend, DailyAgentSpend) | 사용자, 팀, 조직, 태그, 최종 사용자, 에이전트별 사전 집계된 일일 지출 롤업. Admin UI Usage 보기는 SpendLogs를 스캔하지 않고 이 집계를 읽음. | 낮음 - 엔티티·일별 한 행, 배치로 업데이트 |
| LiteLLM_DailyGatewayRequests | 요청 메트릭 미들웨어가 ASGI 엣지에서 기록하는 성공/실패 요청 수. 날짜, 카테고리, 라우트로 키 지정. Usage 페이지의 Successful Requests·Failed Requests 타일과 Gateway Requests by Endpoint 차트 백엔드. gateway request counts 참고. | 낮음 - 라우트·일별 한 행, 배치로 업데이트 |
| LiteLLM_AuditLog | 시스템 구성 변경 추적. 누가 무엇을 변경했는지 기록. 팀, 사용자, 모델 업데이트 이력 유지. | 기본 꺼짐, 높음 - 엔티티 변경마다 실행 |
LiteLLM_SpendLogs 비활성화 (Disable LiteLLM_SpendLogs)
general_settings 아래에 disable_spend_logs: True 또는 disable_error_logs: True를 설정해 그 테이블 쓰기를 중단하세요. 지출 로그를 비활성화하면 UI에서 요청별 로그 상세를 잃지만 로깅 통합(s3, Prometheus, Langfuse)에서는 비용 지표를 유지해요. 오류 로그를 비활성화하면 UI의 Errors 보기를 잃지만 애플리케이션 로그와 다른 로깅 통합에서는 오류를 유지해요. 프로덕션 체크리스트의 keeping error logs out of the database 참고.
데이터베이스 마이그레이션 (Migrating Databases)
데이터베이스를 마이그레이션해야 한다면, 서비스 연속성과 무중단을 보장하려면 다음 테이블을 복사해야 해요:
| 테이블 이름 | 설명 |
|---|---|
| LiteLLM_VerificationToken | 기존 가상 키가 계속 동작하도록 필수 |
| LiteLLM_UserTable | 기존 가상 키가 계속 동작하도록 필수 |
| LiteLLM_TeamTable | 팀 마이그레이션에 필수 |
| LiteLLM_TeamMembership | 팀 멤버 예산 마이그레이션에 필수 |
| LiteLLM_BudgetTable | 기존 예산 설정 마이그레이션에 필수 |
| LiteLLM_OrganizationTable | 선택 - DB에서 조직을 사용하는 경우에만 마이그레이션 |
| LiteLLM_OrganizationMembership | 선택 - DB에서 조직을 사용하는 경우에만 마이그레이션 |
| LiteLLM_ProxyModelTable | 선택 - LLM을 DB에 저장하는 경우에만 (즉 STORE_MODEL_IN_DB=True) |
| LiteLLM_SpendLogs | 선택 - LiteLLM UI의 과거 데이터를 원하는 경우에만 |
| LiteLLM_ErrorLogs | 선택 - LiteLLM UI의 과거 데이터를 원하는 경우에만 |
논리 복제로 데이터베이스 복제 (Replicating the database with logical replication)
Postgres 논리 복제는 행이 업데이트되거나 삭제될 때 복제본 ID의 열만 운반해요. Prisma는 모든 LiteLLM 테이블을 Postgres 기본값(기본 키)으로 만들므로, 다운스트림 소비자는 새 행은 보지만 이전 행은 보지 못해요. Neon의 lakehouse sync 같은 싱크는 REPLICA IDENTITY FULL을 요구하고 그것이 없는 테이블을 거부해요.
LITELLM_SET_REPLICA_IDENTITY_FULL=True를 설정하면 LiteLLM이 각 마이그레이션 실행 끝에 모든 LiteLLM 테이블에 대해 다음을 실행해요:
ALTER TABLE "LiteLLM_..." REPLICA IDENTITY FULL;
이는 미래 업그레이드가 추가하는 테이블까지 포함하므로, 설정이 업그레이드를 견디고 손으로 다시 적용할 필요가 없어요. 이미 FULL인 테이블은 건너뛰고, LiteLLM이 소유하지 않은 같은 스키마의 테이블은 그대로 둬요.
export LITELLM_SET_REPLICA_IDENTITY_FULL=True
litellm --config /path/to/config.yaml
마이그레이션을 실행하는 데이터베이스 사용자는 테이블을 소유해야 해요. 그렇지 않으면 ALTER가 거부되고, LiteLLM은 복제 메타데이터가 요청 서빙에 필요하지 않으므로 Postgres 오류를 기록하고 그냥 시작해요.
REPLICA IDENTITY FULL은 모든 UPDATE와 DELETE에서 Postgres가 전체 이전 행을 WAL에 쓰게 하므로, 복제 소비자가 필요로 하지 않으면 꺼두세요.