LiteLLM Proxy로 AI 에이전트 LLM Gateway 구축 – 백서 다운로드

이 백서는 LLM Gateway(호출 주체와 모델 사이에서 인증, 라우팅, 기록을 한 곳에서 처리하는 중계 서버)가 없을 때 막히는 일에서 출발합니다. 이어서 LiteLLM SDK와 LiteLLM Proxy의 차이, LLM Gateway 요건 여덟 가지, 오픈소스 대안 다섯 개, 도커에서 운영하는 구성, 모니터링, 한계와 다음 단계를 9개 장으로 설명합니다. 오픈마루가 에이전트 프로파일 16개를 운영하는 구성을 사례로 실어, 길목을 모아 얻은 이점과 아직 남은 공백을 함께 확인할 수 있습니다.

엔지니어는 구성과 설정을 다루는 장에서, 의사결정권자는 요건과 대안, 한계를 다루는 장에서 판단 근거를 얻을 수 있습니다. 아래 버튼을 누르면 백서 98쪽 전문을 PDF 한 파일로 받을 수 있습니다.

백서는 도입을 검토하는 팀이 순서대로 묻게 되는 질문 일곱 가지에 답합니다.

1. LLM Gateway가 없을 때 키, 비용, 모델 교체에서 무엇이 막히는가
2. LiteLLM SDK와 LiteLLM Proxy는 각각 누가 언제 쓰는가
3. LLM Gateway의 기본 요건과 상세 요건은 무엇이고 공개판은 어디까지 충족하는가
4. 오픈소스 LLM Gateway 다섯 후보는 성격이 어떻게 다른가
5. 모델 별칭, 폴백, 온프레미스 추론 서버와 클라우드 경로는 어떻게 묶는가
6. 게이트웨이에서 무엇을 관측해야 하고 지표 없이는 무엇을 볼 수 없는가
7. 키 분리, 지표 수집, 우회 경로 정리는 어떤 순서로 진행하는가

AI 에이전트는 모델이 도구 호출을 요청할 때마다 도구 결과를 가지고 모델을 다시 호출합니다. 대화 한 번이 요청 여러 건으로 늘고, 예약 작업이 더해지면 호출 주체의 수와 호출 횟수가 함께 커집니다. 오픈마루의 구성에서는 등록된 예약 작업 94건 가운데 48건이 LLM을 사용합니다.

LLM을 호출하는 주체는 에이전트 루프, 보조 스크립트, 독립 서비스 세 형태입니다. 형태마다 호출 코드를 고치는 사람과 키가 보관되는 위치가 다릅니다. 에이전트 프레임워크의 모델 설정만 점검해서는 나머지 두 형태가 조사에서 빠지므로, 도입 검토는 세 형태의 호출 경로를 모두 적는 일부터 시작해야 합니다.

LLM 자체의 원리와 기업 도입 판단 기준은 LLM이란 무엇인가 — 원리부터 기업 도입 판단까지에서 먼저 확인할 수 있습니다.

▲ 호출 주체가 프록시 한 곳으로 들어오면 프로바이더 키는 프록시에만 남습니다 (백서 4쪽)

그림의 왼쪽은 호출 주체마다 프로바이더 키를 들고 직접 연결하는 구성이고, 오른쪽은 모든 호출 주체가 프록시 한 곳으로 들어오고 프로바이더 키가 프록시에만 남는 구성입니다.

여러 소비자가 키 하나를 함께 쓰면 소비자별 지출 추적, 모델 접근 통제, 예산 설정 세 가지를 할 수 없습니다. 키가 유출되면 모든 소비자의 키를 한꺼번에 교체해야 하고, 특정 소비자만 차단하는 조치도 할 수 없습니다. 마스터 키(프록시 관리자가 쓰는 키)는 다른 키를 만드는 관리자 키이므로, 호출용으로 여러 소비자에 나누어 두기에는 권한이 지나치게 큽니다.

이 공백에 대응하는 기능이 가상 키(소비자별로 발급해 사용량과 권한을 나누는 키)입니다. 가상 키는 키 단위 지출 추적, 키별 모델 접근 통제, 키·사용자·팀 단위 예산을 제공하며 공개판에 포함되어 있습니다. 키 분리는 보안 조치이면서 비용 관리와 관측의 전제 조건입니다.

▲ 프로바이더 키와 사용 기록을 한 곳에 두고 호출 주체에는 가상 키만 발급합니다 (백서 19쪽)

모델 이름과 접속 주소가 호출 코드마다 적혀 있으면 교체 작업의 크기가 호출 주체 수에 비례합니다. 수정 대상이 여러 곳이면 일부만 바뀐 상태가 생기고, 그동안 호출 주체마다 다른 모델이 응답합니다. 모델 별칭은 호출 주체가 요청에 적는 모델 이름을 실제 백엔드에 연결하는 프록시 설정 항목이며, 이 수정 위치를 한 곳으로 줄입니다.

오픈마루의 에이전트 프로파일 16개는 모두 같은 기본 별칭과 같은 프록시 주소를 가리킵니다. 기본 대화 모델을 교체할 때 프로파일 16개의 설정은 그대로 두고 프록시 설정 파일의 별칭 정의만 수정합니다. 클라우드 프로바이더가 자체 일정으로 모델 제공을 끝낼 때도 같은 절차가 적용됩니다.

별칭 정의에는 각 별칭이 온프레미스 추론 서버로 가는지 클라우드 프로바이더로 가는지가 적혀 있으므로, LiteLLM Proxy의 설정 파일은 조직 밖으로 나가는 경로의 목록이기도 합니다. 오픈마루의 구성에서 프록시를 거치는 클라우드 경로는 별칭 9개 가운데 하나입니다.

▲ 모델을 교체할 때 고치는 곳은 프록시 설정 파일의 별칭 정의 한 곳입니다 (백서 8쪽)

LiteLLM은 BerriAI가 2023년에 공개한 오픈소스 프로젝트이며, 100개가 넘는 프로바이더를 OpenAI 형식 하나로 호출하게 해 줍니다. 요청, 응답, 예외 세 층이 모두 통일 대상이어서 프로바이더가 늘 때마다 호출 코드에 쌓이던 분기가 사라집니다.

호출 형식을 맞추는 일과 호출 경로를 모으는 일은 다릅니다. 형식만 맞춘 상태에서는 프로바이더 키가 여전히 호출 주체마다 남고, 누가 얼마나 호출했는지도 한 곳에서 볼 수 없습니다. 키 보관, 비용 귀속, 모델 접근 통제는 호출 주체가 여럿일 때 생기는 조직 단위의 문제이므로, 여러 호출 주체가 함께 거치는 서버가 맡아야 합니다.

LiteLLM Proxy 도입 가이드는 AI 에이전트를 위한 LLM 게이트웨이 — LiteLLM 도입 가이드에서 함께 읽을 수 있습니다.

▲ 요청, 응답, 예외 세 층의 프로바이더별 분기가 OpenAI 형식 하나로 통일됩니다 (백서 16쪽)

두 형태를 가르는 기준은 조직의 크기가 아니라 호출 주체의 수와 통제 필요입니다. LLM을 호출하는 애플리케이션이 하나뿐이면 LiteLLM SDK(애플리케이션 안에 넣는 호출 라이브러리)로 충분합니다. 에이전트와 스크립트 여러 개가 같은 키를 나누어 쓰기 시작하면 LiteLLM Proxy가 필요합니다.

▲ LiteLLM SDK는 애플리케이션 안에, LiteLLM Proxy는 조직 공용 서버 자리에 놓입니다 (백서 22쪽)

재시도, 폴백, 부하 분산은 두 형태가 함께 쓰는 Router의 기능입니다. 폴백이 필요하다는 이유만으로 서버를 두는 결정은 근거가 틀립니다. 서버를 따로 두는 이유는 키와 예산, 한 곳에 모이는 로그에서 찾아야 합니다.

LiteLLM Proxy 안에도 기능의 경계가 하나 더 있습니다. 폴백(한 모델이 실패했을 때 요청을 다른 모델로 넘기는 동작), 재시도, 쿨다운, 타임아웃, 부하 분산은 설정 파일만으로 동작합니다. 가상 키, 예산, 사용 기록은 Postgres 데이터베이스를 연결해야 쓸 수 있습니다.

프록시를 도입했다는 사실만으로는 소비자별 통제가 가능한지 알 수 없고, 데이터베이스 연결 여부까지 확인해야 합니다. Postgres를 연결하면 상태를 갖지 않던 프록시가 데이터베이스에 의존하게 되므로, 데이터베이스의 백업과 가용성도 프록시 운영의 일부가 됩니다. 이 부담을 받아들일지가 연결 단계의 판단 기준입니다.

▲ 실패 유형에 따라 폴백 대상이 갈리고 재시도와 쿨다운이 그 앞뒤에서 동작합니다 (백서 33쪽)

백서는 LLM Gateway의 요건을 기본 네 가지와 상세 네 가지로 나누고, 판정 값을 충족, 부분 충족, 공백 세 가지로 통일했습니다. 판정 기준은 기능이 제품에 있는지보다 현재 구성에서 그 기능을 쓰고 있는지를 묻습니다. 오픈마루의 운영 구성에 적용한 결과는 충족 하나, 부분 충족 넷, 공백 셋입니다.

▲ 소비자 6종은 진입점 하나로 모였지만 같은 마스터 키를 쓰고 프록시 밖 경로 3건이 남아 있습니다 (백서 59쪽)

이 결과는 제품의 기능 범위에서 온 것이 아닙니다. 가상 키, 지출 추적, 예산, Prometheus 지표는 모두 공개판 기능이므로, 공백은 제품 교체 없이 구성 변경으로 메울 수 있습니다.

프록시 밖 경로 3건은 모두 외부 API로 향하는 호출입니다. 외부로 나가는 경로를 세어 보면 프록시 안에 한 건, 프록시 밖에 세 건이 있으므로, 프록시 설정 파일만으로는 외부 전송 경로의 일부만 설명할 수 있습니다.

백서는 공개 저장소, 오픈소스 라이선스, LLM 호출 중계 기능 세 조건으로 다섯 후보를 골랐습니다. 다섯 후보는 저장소 설명이 스스로 밝힌 범위에 따라 성격이 세 갈래로 나뉩니다. 이 구분은 기능이나 성능을 평가한 결과가 아니며, 도입 조직이 이미 갖고 있어야 하는 운영 기반이 다르다는 점을 보여 줍니다.

▲ 오픈소스 LLM Gateway 다섯 후보는 프로젝트 성격에 따라 세 갈래로 나뉩니다 (백서 44쪽)

국내에서 공급되는 솔루션은 회사명 없이 과금 통합형, GPU 플랫폼 결합형, 보안 필터링형, 글로벌 API 게이트웨이 공급형, 네트워크 어플라이언스형 다섯 유형으로 구분했습니다. 유형을 먼저 가른 다음 요건 평가표로 항목별 충족 여부를 따로 확인하는 순서를 권합니다.

사용자의 메시지 하나는 메신저, 에이전트 프로세스, LiteLLM Proxy, 추론 서버를 차례로 거칩니다. 모델이 도구 호출을 요청하면 에이전트는 도구를 실행하고 결과를 붙여 프록시에 다시 요청을 보냅니다. 모델이 도구를 두 번 호출한 뒤 답을 만든다면, 사용자에게는 대화 한 번이지만 프록시에는 요청 3건이 도착합니다.

에이전트가 늘어날 때 역할 문서, 대화 채널, 예약 작업은 에이전트 수에 비례해 늘어납니다. 반면 모델 설정은 기본 별칭 하나, OpenAI 호환 방식, 프록시 주소 세 항목으로 같습니다. 다만 요청 단위 기록만으로는 대화 단위의 비용과 지연을 알 수 없다는 점도 함께 알아 두어야 합니다.

▲ 도구 호출이 있을 때마다 에이전트는 프록시를 다시 왕복합니다 (백서 71쪽)

LLM Gateway는 조직의 모델 호출이 모두 지나가는 한 곳이므로, 호출량과 지연, 오류, 백엔드 상태를 한 번에 볼 수 있는 유일한 위치입니다. 백서는 운영 판단에 바로 쓰이는 지표를 비용·토큰, 지연, 요청 수, 배포 상태, 폴백·쿨다운 다섯 묶음으로 나눕니다. 폴백이 일어나면 호출한 쪽은 오류 없이 다른 모델의 답을 받으므로, 지표가 없으면 지금 어느 모델이 답하고 있는지 알 수 없습니다.

첫 토큰 시간(TTFT, 요청 뒤 첫 응답 토큰이 도착하기까지의 시간)은 사용자가 에이전트의 응답을 기다리는 체감 시간과 가장 가깝습니다. 지연과 폴백 지표는 Prometheus 콜백 설정 한 줄로 데이터베이스 없이 얻습니다. 키·팀·사용자별 지표는 가상 키가 먼저 있어야 값이 나뉩니다.

▲ 게이트웨이 지표 다섯 묶음은 묶음마다 답하는 운영 질문이 다릅니다 (백서 77쪽)

호출 경로를 모으는 결정은 키를 모으는 결정이기도 합니다. 2026년 3월 24일 LiteLLM의 PyPI 패키지 두 버전이 악성 코드를 담은 채 약 40분 동안 배포됐습니다. 공식 도커 이미지로 운영한 쪽은 영향을 받지 않았는데, 이미지가 의존성 버전을 고정해 두었기 때문입니다.

공급망 통제는 게이트웨이를 실행하는 이미지의 출처를 확인하고 버전이나 다이제스트를 고정해, 어느 버전이 실행되는지를 운영자가 정하는 일입니다. 공식 사고 보고가 권고한 조치도 안전한 버전으로 고정하는 것입니다. 이 조치는 데이터베이스나 다른 구성 요소를 요구하지 않으므로 선행 조건 없이 바로 적용할 수 있습니다.

▲ 의존성 버전을 고정한 공식 도커 이미지 경로는 악성 패키지의 영향을 받지 않았습니다 (백서 88쪽)

다음 단계는 일곱 가지이고 순서는 의존 관계로 정합니다. 키와 팀별로 나뉜 지표는 가상 키가 있어야 나오고, 가상 키는 데이터베이스가 있어야 합니다. 폴백과 지연 지표는 데이터베이스 없이도 나옵니다. 그래서 선행 조건이 없는 조치로 관측을 먼저 확보하고, 데이터베이스가 필요한 조치를 그 뒤에 둡니다.

▲ 선행 조건이 없는 조치를 먼저 하고 데이터베이스가 필요한 조치를 뒤에 둡니다 (백서 90쪽)

키를 한꺼번에 나누기 어렵다면 호출이 많은 소비자와 외부로 나가는 소비자부터 나눕니다. 진행 범위는 운영 부담을 기준으로 조직이 결정해야 합니다.

• 병목은 모델이 아니라 호출 경로입니다. 조사 대상은 에이전트 루프, 보조 스크립트, 독립 서비스 세 형태입니다.
• 호출 주체가 하나이면 LiteLLM SDK로 충분하고, 둘 이상이고 키를 한 곳에서 관리해야 하면 LiteLLM Proxy가 필요합니다.
• 폴백과 재시도는 설정 파일만으로 동작하고, 가상 키와 예산은 Postgres가 있어야 합니다.
• 요건 평가표 8개 항목으로 판정한 운영 구성은 충족 1건, 부분 충족 4건, 공백 3건입니다.
• 프록시 밖 경로 3건처럼 설정 파일에 나타나지 않는 호출은 따로 조사해야 드러납니다.
• 다음 단계는 조사, 버전 고정, 지표 수집을 먼저 하고 Postgres 연결과 가상 키 발급을 그 뒤에 둡니다.

LiteLLM SDK와 LiteLLM Proxy는 무엇이 다른가요?

SDK는 애플리케이션 안에 넣는 라이브러리이고, Proxy는 조직이 함께 쓰는 게이트웨이 서버입니다. 호출 주체가 하나이면 SDK로 충분합니다. 호출 주체가 둘 이상이고 키를 한 곳에서 관리해야 하면 Proxy가 필요합니다.

가상 키를 쓰려면 무엇이 필요한가요?

가상 키를 발급하려면 프록시에 Postgres 데이터베이스를 먼저 연결해야 합니다. 폴백과 재시도는 설정 파일만으로 동작하고, 지출 추적과 예산은 가상 키가 필요합니다.

폴백만 필요해도 게이트웨이 서버를 따로 두어야 하나요?

폴백만 필요하다면 서버 없이 LiteLLM SDK의 Router 기능으로도 구성할 수 있습니다. 서버를 두는 이유는 소비자별 키와 예산, 한 곳에 모이는 로그에 있습니다.

LLM Gateway를 도입할 때 무엇부터 해야 하나요?

에이전트, 스크립트, 서비스에 흩어진 LLM 호출 경로를 조사하는 일이 먼저입니다. 주체마다 소비자, 사용 키, 대상 모델, 프록시 경유 여부를 적습니다. 가상 키 발급 단위도 이 조사에서 정합니다.

공개판만으로 어디까지 운영할 수 있나요?

가상 키, 지출 추적, 예산, 폴백, 로깅, Prometheus 지표가 모두 공개판에 포함됩니다. 관리 화면 SSO, 감사 로그, 외부 비밀 저장소 연동은 유료판에만 있으므로 보안 규정이 이를 요구하는지 따로 확인해야 합니다.

게이트웨이가 멈추면 에이전트는 어떻게 되나요?

프록시가 멈추면 그 뒤에 있는 모든 소비자의 모델 호출이 함께 멈춥니다. 폴백이 받아 주는 것은 모델 서버 쪽 장애이므로, 프록시 자체의 가용성은 복제와 헬스체크로 따로 확보해야 합니다.

지표 수집은 데이터베이스 없이도 시작할 수 있나요?

지연, 첫 토큰 시간, 폴백 발생 지표는 데이터베이스 없이 바로 수집할 수 있습니다. 키·팀·사용자별 비용과 남은 예산 지표는 가상 키가 있어야 값이 나뉩니다.

• LLM이란 무엇인가 — 원리부터 기업 도입 판단까지
• AI 에이전트를 위한 LLM 게이트웨이 — LiteLLM 도입 가이드
• AI 에이전트란 무엇인가 — 정의, 구조, 기업 도입 기준
• AI 에이전트 필수 기능 여덟 가지, 도입 전 점검 기준
• 멀티 에이전트 시스템 설계 — 협업 패턴과 도입 전 알아야 할 실패 모드
• AI LLM 가속 엔진 vLLM — GPU 병목과 도입 비용 줄이기
• 쿠버네티스 관측성, OpenTelemetry, 분산 추적
• BerriAI/litellm 저장소
• LiteLLM 문서 첫 페이지
• LiteLLM 문서, Virtual Keys
• LiteLLM 문서, Enterprise
• LiteLLM 문서, Prometheus metrics
• LiteLLM 문서, Fallbacks
• LiteLLM Security Update: Suspected Supply Chain Incident
• OpenTelemetry GenAI Semantic Conventions
• Agent Router joins AAIF

백서에는 LiteLLM SDK와 Proxy 대조표, 모델 별칭과 폴백 구성 사례, 지표 묶음별 운영 판단, 다음 단계의 선행 조건이 실려 있습니다. 요건 평가표와 호출 경로 조사표 양식을 포함한 백서 98쪽을 PDF 한 파일에 담았습니다.

도입 범위나 구성에 대한 문의는 솔루션 문의로 남겨 주세요.