프록시 내부: 하나의 요청이 지나가는 길

프록시 내부: 하나의 요청이 지나가는 길

LiteLLM Proxy Server(LLM Gateway)에 요청을 보내면 내부적으로 우리가 눈치채지 못하는 몇 가지 단계를 거쳐요. "한 번만 딱, 그런데 어떤 일이 일어나는 걸까" 하는 궁금증이 들 때, 바로 이 문서가 그 길을 하나씩 보여줍니다. 이름도 그걸 잘 나타내요. Life of a Request — 요청의 생애예요.

출처: 공식문서 - Life of a Request

요청이 게이트웨이에 도착하면

클라이언트(OpenAI SDK, LangChain, curl)가 Authorization: Bearer sk-... 헤더와 함께 게이트웨이:4000으로 요청을 보냅니다. 이후 흐름은 크게 이렇게 진행돼요.

  1. 사용자 요청 수신 — 사용자가 Proxy Server(Gateway)에 요청을 보내요.
  2. 가상 키(virtual key) 인증·예산 확인 — 요청의 Bearer 토큰이 유효한지, 그리고 예산 안에 있는지 검사해요. 먼저 Redis 캐시나 인메모리 캐시에서 가상 키를 확인하고, 캐시에 없으면 DB에서 조회합니다.
  3. 레이트리밋(rate limiting) — 병렬 요청 리미터가 rpm/tpm(분당 요청 수/토큰 수)을 서버 전역, 가상 키, 사용자, 팀 단위로 각각 확인해요.
  4. proxy_server.py — /chat/completions, /embeddings 같은 엔드포인트를 담고 있으며, 이 요청들은 LiteLLM Router로 보내집니다.
  5. LiteLLM Router — LLM API 배포(deployment)에 대한 로드밸런싱·폴백·재시도를 담당해요.
  6. litellm.completion()/embedding() — Python SDK가 OpenAI API 형식으로 LLM을 호출합니다(형식 번역과 파라미터 매핑).
  7. 응답 후 처리(비동기) — 클라이언트에 응답을 보낸 뒤, 비동기 백그라운드 작업으로 로깅·레이트리밋 갱신·비용(spend) 업데이트가 수행돼요.

키포인트가 하나 있어요. DB 트랜잭션은 요청의 수명 주기에 묶이지 않습니다. 요청 경로에 DB 쓰기가 들어가지 않고, 모든 DB 쓰기는 비동기 백그라운드 작업으로 몰려 있어요. 그래서 요청 지연에 DB가 개입하지 않도록 설계되어 있죠.

PostgreSQL과 Redis가 하는 일

인증과 추적에 필요한 상태는 두 저장소가 나눠 들고 있어요.

  • PostgreSQL — 키(keys), 팀(teams), 지출(spend)을 저장하는 진실 원천(source of truth)이에요.
  • Redis — 키 캐시와 레이트리밋 카운터를 두는 고속 계층이에요. 캐시에 없을 때만 DB를 읽습니다.

Router가 실패를 처리하는 법: 재시도 vs 폴백

모든 통일 엔드포인트(.completion, .embeddings 등)는 Router를 거쳐요. Router는 실패를 두 겹으로 처리합니다.

  • function_with_fallbacks — 호출을 try-except로 감싸, 1차 배포가 실패하면 폴백(fallback) 설정의 다음 모델 그룹으로 넘어가요.
  • function_with_retries — 호출을 다시 감싸, 요청이 실패하면 같은 모델 그룹 안의 다른 사용 가능한 배포에서 재시도해요.

여기서 중요한 구분이 나옵니다. 재시도는 실패한 모델 그룹 안에 머물고, 폴백은 폴백 설정에서 다음 그룹으로 떠나요.

모델 그룹(model_group) 은 같은 model_name을 공유하고 로드밸런싱되는 LLM API 배포들의 묶음이에요. 예를 들어 gpt-5.6-luna라는 model_name 아래 Azure 배포 2개와 OpenAI 배포 1개를 두고 로드밸런싱할 수 있죠.

이미지 URL은 어떻게 처리하나요

일부 LLM API는 이미지 URL을 받지 못하고 base64 문자열만 받아요. 이런 경우 LiteLLM은 요청에서 URL을 감지하고, 대상 API가 URL을 지원하는지 확인합니다.

  • 지원하면 그대로 통과시켜요(프로바이더가 스스로 이미지를 가져옴).
  • 지원하지 않으면 이미지를 다운로드해 base64로 변환해 보내요. 변환 결과는 메모리에 최대 10개까지 캐시되고, 개별 다운로드는 50MB로 제한됩니다(MAX_IMAGE_URL_DOWNLOAD_SIZE_MB로 설정 가능).

더 알아보기