멀티테넌트 아키텍처: 조직·팀·사용자·키, 네 겹으로 나누는 격리

한대의 LiteLLM 프록시로 회사 안의 여러 팀(조직, 팀, 부서)을 동시에 서비스하면서, 각 팀의 접근 권한·지출·사용량을 서로 섞이지 않게 유지하는 구조를 멀티테넌시(Multi-tenancy)라고 해요. 게이트웨이 하나가 모든 LLM 프로바이더로 가는 공용 입구가 되고, 요청마다 '어느 테넌트 소속인지'라는 컨텍스트가 따라다니면서 그 요청이 어떤 모델에 닿을지, 어느 예산을 쓰는지, 비용이 어디에 쌓이는지가 결정됩니다.

이 설계가 풀려고 하는 문제는, 여러 그룹이 LLM 게이트웨이를 함께 쓸 때 자연스럽게 나타나는 것들이에요. 비용이 한 바구니에 섞이지 않고 정확한 사업부에 귀속되어야 하고, 팀마다 필요한 모델·예산·비율이 다르니 접근 권한도 달라야 하죠. 관리 책임도 위임되어야 해서, 팀장이 플랫폼 전체 관리자 권한 없이 자기 팀만 관리할 수 있어야 하고요. 그리고 몇 명 쓰는 상황부터 수만 명까지, 설계를 바꾸지 않고 같은 구조가 유지되어야 합니다.

출처: 공식문서 — Multi-Tenant Architecture with LiteLLM

테넌트는 네 겹의 경계로 모델링된다

LiteLLM은 테넌시를 조직 → 팀 → 사용자 → 키라는 네 겹의 중첩 구조로 봅니다. 각 겹이 격리와 지출 귀속의 경계가 돼요.

조직(Organization) — 최상위 테넌트로 여러 팀을 감쌀 수 있어요. 보통 사업부나 리전 단위로 만듭니다. 조직끼리는 서로의 데이터와 키를 볼 수 없고, 각자 자체 예산과 허용 모델 목록을 가지며, 자기 조직 안의 팀만 관리하는 전담 조직 관리자(org admin)가 배정됩니다. 조직은 엔터프라이즈 기능이에요.
팀(Team) — 함께 일하는 사용자들의 논리적 묶음으로, 오픈소스에서 최상위 테넌트 경계 역할을 해요. 팀은 자체 예산·비율 제한·관리자·모델 접근 제어·공용 워크로드용 서비스 계정 키를 가집니다. 조직 안에 들어가면 그 조직의 제약을 상속받아서, 조직 예산을 넘거나 허용되지 않은 모델에 닿을 수 없어요.
사용자(User) — 하나 이상의 팀에 속하고 키를 만들거나 쓰는 개인입니다. 사용자별로 지출이 추적되고, 역할(일반 내부 사용자부터 팀/조직 관리자, 플랫폼 전체 프록시 관리자까지)에 따라 할 수 있는 일이 달라집니다. 사용자를 삭제하면 그가 개인 소유한 키도 함께 지워져요.
가상 키(Virtual Key) — 요청을 인증하고 지출 추적으로 테넌트에 묶는 실질적인 매개체입니다. 사용자에, 팀에(멤버가 바뀌어도 살아남는 서비스 계정 키), 또는 둘 다에 묶을 수 있어요.

오픈소스 vs 엔터프라이즈에서의 경계

팀과 가상 키는 오픈소스에서 쓸 수 있고, 팀만으로도 최상위 테넌트 경계를 만들 수 있어요. 조직과 조직 관리자는 그 위에 한 겹 더 쌓는 계층으로 엔터프라이즈 기능이라 따로 라이선스가 필요합니다. 오픈소스에서는 팀(예: Engineering Backend 팀, Marketing Content 팀)으로 같은 분리를 표현하고, 부서 단위 합산 대신 더 평평한 구조를 쓰면 돼요.

지출은 위로 흘러가고 예산은 아래로 굳어진다

모든 요청의 비용은 키·사용자·팀·조직에 동시에 귀속되어요. 예산은 각 겹에 걸 수 있고 아래쪽이 위쪽을 넘지 못하도록 안쪽으로 강제됩니다. 팀 예산은 조직 예산을, 사용자 예산은 팀 예산을 넘을 수 없고, 경로상 어느 겹이라도 예산을 넘으면 그 요청은 차단됩니다. 이 덕분에 공용 인스턴스 하나로 **테넌트별 chargeback(비용 정산)과 showback(비용 표시)**이 가능해져요.

관리 위임: 같은 계층을 따라 내려간다

격리가 제대로 작동하려면 관리 권한도 같은 계층을 따라 위임되어야 해요. LiteLLM은 두 종류의 역할을 두는데, 플랫폼 전역 역할(proxy_admin, proxy_admin_viewer, internal_user)은 어디서든 적용되고, 범위 역할(org_admin, team_admin)은 특정 조직이나 팀 하나만 통제합니다. 프록시 관리자가 조직을 만들고 조직 관리자를 정하면, 조직 관리자는 자기 조직 안의 팀을 만들고 팀 관리자를 배정하고, 팀 관리자는 자기 팀의 멤버·비율 제한·키만 관리해요. 팀 예산은 유지하거나 낮출 수 있지만 올리려면 프록시 관리자가 필요하죠. 이 체인 덕분에 수천 명을 온보딩할 때마다 매번 중앙 관리자를 거치지 않아도 됩니다.

실무에서 나타나는 모습

같은 네 겹이 여러 현실 세계를 표현해요. 대기업은 부서마다 조직을 주고(개발·마케팅·영업이 각자 여러 팀을 가짐), 회사 하나는 프로덕션·스테이징·개발을 각각 별도 팀으로 나눠 실험이 운영 예산을 쓰거나 운영을 불안정하게 만들지 못하게 막죠. 테넌시 격리가 어디서 어떻게 작동하는지 더 깊이 보려면 아래 링크를 따라가면 됩니다.