Redis가 필요한 것
Redis가 필요한 것 (What Needs Redis)
Redis는 워커 프로세스를 2개 이상 실행하는 모든 LiteLLM 프록시 배포에 적극 권장돼요. 대부분의 배포가 그렇죠. --num_workers가 1보다 큰 단일 컨테이너도 해당되고, 복제본이 둘 이상인 Kubernetes 배포도 해당돼요.
프록시가 강제하는 거의 모든 것(레이트 리밋, 예산, 쿨다운, 캐시 적중, 설정 변경)은 상태(state)를 통해 조정돼요. Redis가 있으면 그 상태가 공유되어 모든 워커가 같은 카운터와 같은 무효화를 봐요. Redis가 없으면 각 워커가 자체 인메모리 사본을 유지하므로, 워커 4개에서 분당 100회 요청 제한은 실제로 400회를 통과시키고, 폐기된 키는 폐기를 처리하지 않은 워커에서 계속 사용 가능하며, 캐시 적중은 우연히 응답을 저장한 워커에만 도착해요.
Redis가 구성되지 않으면 Admin UI에 배너가 표시돼요. 의도적으로 단일 워커를 실행한다면 LITELLM_DISABLE_NO_REDIS_WARNING=true로 숨길 수 있어요.
출처: 문서
본문
Redis는 워커 프로세스를 2개 이상 실행하는 모든 LiteLLM 프록시 배포에 적극 권장돼요. 대부분의 배포가 그렇죠. --num_workers가 1보다 큰 단일 컨테이너도 해당되고, 복제본이 둘 이상인 Kubernetes 배포도 해당돼요.
프록시가 강제하는 거의 모든 것(레이트 리밋, 예산, 쿨다운, 캐시 적중, 설정 변경)은 상태를 통해 조정돼요. Redis가 있으면 그 상태가 공유되어 모든 워커가 같은 카운터와 같은 무효화를 봐요. Redis가 없으면 각 워커가 자체 인메모리 사본을 유지하므로, 워커 4개에서 분당 100회 요청 제한은 실제로 400회를 통과시키고, 폐기된 키는 폐기를 처리하지 않은 워커에서 계속 사용 가능하며, 캐시 적중은 우연히 응답을 저장한 워커에만 도착해요.
Redis가 구성되지 않으면 Admin UI에 배너가 표시돼요. 의도적으로 단일 워커를 실행한다면 LITELLM_DISABLE_NO_REDIS_WARNING=true로 숨길 수 있어요.
warning
Redis 없는 멀티 팟 배포는 베타 상태이며, 아래 목록은 완전하지 않아요. Redis 없이 팟 간에 완전히 또는 전혀 동작하지 않는 것으로 알려진 가장 잘 알려진 기능들을 다루며, 다른 기능도 그 설정에서 오작동할 수 있어요. 멀티 팟 배포의 GA 방식은 Redis와 함께 실행하는 거예요.
Redis 구성하기 (Configure Redis)
Redis를 프로비저닝하고 프록시를 그것에 끝까지 연결하려면 Set Up Redis를 보세요. 요약:
router_settings:
redis_host: os.environ/REDIS_HOST
redis_port: os.environ/REDIS_PORT
redis_password: os.environ/REDIS_PASSWORD
litellm_settings:
cache: True
cache_params:
type: redis
host: os.environ/REDIS_HOST
port: os.environ/REDIS_PORT
password: os.environ/REDIS_PASSWORD
환경에 REDIS_HOST와 REDIS_PORT를 설정하는 것만으로는 충분하지 않아요: 프록시는 config가 위처럼 Redis를 가리킬 때만 그 값을 읽어요. router_settings 블록은 라우터 상태(쿨다운, 사용량·지연 기반 라우팅)를 다루고, 캐시 블록은 응답 캐싱과 프록시 전반에서 조정되는 모든 것(레이트 리밋, 예산, 캐시 무효화, 팟 락)을 다룬다. 둘 다 구성하세요. 클러스터·센티널 배포와 general_settings.coordination_redis로 응답 캐시와 다른 Redis에 조정을 연결하려면 Redis and Valkey를 보세요.
Redis가 없으면 망가지는 것
팟 간에 저하되거나 사용할 수 없게 되는 가장 잘 알려진 기능:
| 기능 | Redis 없을 때 |
|---|---|
| 키·팀·사용자·end-user 레이트 리밋 (tpm, rpm, 최대 병렬 요청) | 워커별로 카운트되므로 유효 한도가 워커 수만큼 곱해짐 |
| 동적 레이트 리밋과 레이트 리밋 티어 | 워커별 분할 동일; 티어의 용량 몫이 각 워커에서 독립적으로 재계산됨 |
| 키·팀·사용자 예산 | 지출이 워커별로 예약·카운트되어, 다른 워커의 동시 요청이 데이터베이스가 따라잡기 전에 하드 예산을 초과할 수 있음 |
| Provider budget routing과 태그 예산 | 워커별 지출 창이라 provider나 태그가 워커 수만큼 예산을 초과할 수 있음 |
usage-based-routing-v2와 latency-based-routing |
라우팅 결정이 그 워커가 본 트래픽만 사용하므로 로드 밸런싱이 치우치고 TPM/RPM 인지 배치가 저하됨 |
| 디플로이먼트 쿨다운 | 한 워커에서 실패 후 쿨다운된 디플로이먼트가 다른 워커에서는 로테이션에 남음 |
| 응답 캐싱 | 캐시 항목이 쓴 워커에 로컬로 남아 적중률이 워커 수만큼 떨어짐. 시맨틱 캐싱은 Redis가 절대적으로 필요 |
| 가상 키·팀 캐시 무효화 | 키 삭제, 예산 편집, 팀 멤버십 변경이 로컬 캐시 항목이 만료될 때만 다른 워커에 전파됨 |
| 데이터베이스에 저장된 설정 변경 (UI에서 추가·삭제·편집한 모델, 설정 변경) | 다른 워커가 즉시가 아니라 다음 주기적 리로드에서 가져감 |
| 지출 쓰기를 위한 Redis 트랜잭션 버퍼 | 사용 불가. 모든 워커가 지출 업데이트를 데이터베이스에 직접 쓰는데, 이는 버퍼가 고트래픽에서 막으려던 실패 모드임 |
| 예약 작업 (예산 리셋, 지출 로그 정리, 키 로테이션, 만료 세션 정리, 데이터베이스 지출 플러시) | 단일 러너를 선출하는 팟 락이 없어 작업이 중복 실행되거나 전혀 실행되지 않을 수 있음 |
단일 워커 배포 (Single worker deployments)
워커 프로세스 하나와 복제본 하나를 진짜로 실행한다면 위 어느 것도 적용되지 않아요. 그 경우 로컬 메모리가 공유 상태이기 때문이에요. 이 설정은 수평 확장을 포기하고 재시작 시 모든 캐시 상태가 날아가므로, 프로덕션보다는 개발이나 저볼륨 구성으로 취급하세요.
더 알아보기 (Learn more)
- Set Up Redis: Redis 프로비저닝·연결
- Redis and Valkey: 클러스터·센티널,
coordination_redis - Production Best Practices: Redis 트랜잭션 버퍼