Redis 및 Valkey 캐시
Redis 및 Valkey 캐시 (Redis and Valkey Cache)
Redis는 LiteLLM의 기본 캐시이며 워커와 복제본 간에 공유되는 유일한 캐시예요. Valkey, AWS ElastiCache, GCP Memorystore 모두 Redis 프로토콜을 사용하므로 이 페이지의 모든 내용이 그들에게도 적용돼요.
출처: 문서
본문
프록시를 Redis에 연결하기 (Connect the proxy to Redis)
model_list:
- model_name: gpt-5.6-luna
litellm_params:
model: gpt-5.6-luna
- model_name: text-embedding-ada-002
litellm_params:
model: text-embedding-ada-002
litellm_settings:
set_verbose: True
cache: True # set cache responses to True, litellm defaults to using a redis cache
캐싱을 활성화하려면 OS 환경에 REDIS_URL 또는 REDIS_HOST 중 하나를 설정하세요.
REDIS_URL = "" # REDIS_URL='redis://username:***@hostname:port/database'
## OR ##
REDIS_HOST = "" # REDIS_HOST='redis-18841.c274.us-east-1-3.ec2.cloud.redislabs.com'
REDIS_PORT = "" # REDIS_PORT='18841'
REDIS_PASSWORD = "" # REDIS_PASSWORD='liteLlmIsAmazing'
REDIS_USERNAME = "" # REDIS_USERNAME='my-redis-username' [OPTIONAL] if your redis server requires a username
REDIS_SSL = "True" # REDIS_SSL='True' to enable SSL by default is False
추가 Redis kwargs (Additional Redis kwargs)
info
모든 Redis 클라이언트 라이브러리 파라미터를 구성하려면
REDIS_*환경 변수를 사용하세요. 이는 환경 변수를 Redis 클라이언트 kwargs로 자동 매핑하므로 Redis 설정을 토글하는 데 권장되는 메커니즘이에요.
변수와 값을 OS 환경에 저장해 redis.Redis의 추가 인자를 전달할 수 있어요:
REDIS_<redis-kwarg-name> = ""
예를 들어:
REDIS_SSL = "True"
REDIS_SSL_CERT_REQS = "None"
REDIS_MAX_CONNECTIONS = "20"
변수 이름은 REDIS_ + 대문자 kwargs 이름이므로, 풀 크기는 REDIS_MAX_CONNECTIONS이에요. REDIS_CONNECTION_POOL_KWARGS 변수는 없어요. 설정해도 아무 효과가 없어요.
warning
참고: 정수, 부울, 복잡한 객체 같은 비문자열 Redis 파라미터의 경우 Redis 클라이언트 초기화 중 실패할 수 있으므로
REDIS_*환경 변수 사용을 피하세요. 그런 파라미터에는 라우터 구성의cache_kwargs를 사용하세요.
환경에서 어떻게 읽히는지 보기
그런 다음 프록시 실행:
$ litellm --config /path/to/config.yaml
네임스페이스 (Namespace)
키를 위한 폴더를 만들고 싶다면 네임스페이스를 설정할 수 있어요:
litellm_settings:
cache: true
cache_params: # set cache params for redis
type: redis
namespace: "litellm.caching.caching"
그러면 키는 다음과 같이 저장돼요:
litellm.caching.caching:<hash>
제한된 ACL 사용자 (Restricted ACL users, Redis 7+ / Valkey)
보안 정책상 프록시가 기본값 대신 최소 권한 사용자로 연결해야 한다면, 위처럼 네임스페이스를 설정하고 그 사용자에게 네임스페이스의 키 패턴과 채널 패턴, 그리고 필요한 명령어를 부여하세요:
ACL SETUSER litellm-proxy on '>your-password' '~litellm:*' '&litellm:*' +@all
litellm을 네임스페이스로 바꾸세요. 네임스페이스를 설정하면 프록시가 쓰는 모든 키가 <namespace>: 아래에 있어서 ~<namespace>:*가 그것을 모두 덮어요. 네임스페이스가 없으면 프록시의 키들이 서로 다른 이름을 가지므로 ACL을 범위 지정할 실용적인 키 패턴이 없어요.
채널 부여도 중요해요: Redis 7+와 Valkey는 resetchannels로 ACL 사용자를 만들어 모든 pub/sub 채널을 거부해요. 프록시는 콘피그 동기화와 인증 캐시 무효화를 위해 채널을 구독해요. &:*(또는 네임스페이스가 없을 때 &litellm_proxy.*)가 없으면 로그에 몇 초마다 No permissions to access a channel; reconnecting in 5s가 반복되고, 콘피그 변경은 주기적 재로드에서만 전파돼요.
ACL을 범위 지정할 때 알아야 할 두 가지 더:
general_settings.coordination_redis블록(응답 캐시와 다른 Redis를 조정에 가리키는 용도)도namespace를 받아들이므로, 그 사용자도 같은 방식으로 범위를 지정할 수 있어요.- 조정 Redis를
REDIS_HOST/REDIS_PORT환경 변수만으로 구성하면(cache_params redis 블록 없이) 네임스페이스를 담을 수 없어서 키에 접두사가 없고, 연결 사용자는 범위가 지정되지 않은 키 부여가 필요해요.
프록시 로그에 No permissions to access a key가 보이고 지출 추적이 Restoring N transaction sets to in-memory queues를 반복해서 기록하면, 연결 사용자의 ACL에 위의 부여 중 하나가 빠진 거예요. 네임스페이스 구분자 수정이 없는 프록시 버전에서는, 리터럴 이름이 네임스페이스 문자열로 시작하는 내부 키(예: 네임스페이스 litellm 아래의 litellm_spend_update_buffer)가 네임스페이스 밖에 쓰여져 부여가 있어도 거부됐어요. Redis ACL LOG에서 거부된 키가 접두사 없이 나타나면 업그레이드하세요.
Redis 클러스터 (Redis Cluster)
config.yaml의 cache_params 아래 redis_startup_nodes로, 또는 REDIS_CLUSTER_NODES 환경 변수({"host": ..., "port": ...} 객체의 JSON 목록)로 프록시를 Redis 클러스터에 지정하세요. 둘 중 하나만 있으면 돼요.
config.yaml에 설정하기
model_list:
- model_name: "*"
litellm_params:
model: "*"
litellm_settings:
cache: True
cache_params:
type: redis
redis_startup_nodes: [{ "host": "127.0.0.1", "port": "7001" }]
.env에 설정하기
.env에서 REDIS_CLUSTER_NODES를 설정해 redis 클러스터를 구성할 수 있어요.
REDIS_CLUSTER_NODES 값 예시:
REDIS_CLUSTER_NODES = "[{"host": "127.0.0.1", "port": "7001"}, {"host": "127.0.0.1", "port": "7003"}, {"host": "127.0.0.1", "port": "7004"}, {"host": "127.0.0.1", "port": "7005"}, {"host": "127.0.0.1", "port": "7006"}, {"host": "127.0.0.1", "port": "7007"}]"
note
.env에서 redis 클러스터 노드를 설정하는 파이썬 스크립트 예시:# List of startup nodes startup_nodes = [ {"host": "127.0.0.1", "port": "7001"}, {"host": "127.0.0.1", "port": "7003"}, {"host": "127.0.0.1", "port": "7004"}, {"host": "127.0.0.1", "port": "7005"}, {"host": "127.0.0.1", "port": "7006"}, {"host": "127.0.0.1", "port": "7007"}, ] # set startup nodes in environment variables os.environ["REDIS_CLUSTER_NODES"] = json.dumps(startup_nodes) print("REDIS_CLUSTER_NODES", os.environ["REDIS_CLUSTER_NODES"])
Redis 센티널 (Redis Sentinel)
config.yaml의 cache_params 아래 service_name과 sentinel_nodes로, 또는 REDIS_SENTINEL_NODES, REDIS_SERVICE_NAME, REDIS_SENTINEL_PASSWORD 환경 변수로 프록시를 Redis Sentinel 배포에 지정하세요.
config.yaml에 설정하기
model_list:
- model_name: "*"
litellm_params:
model: "*"
litellm_settings:
cache: true
cache_params:
type: "redis"
service_name: "mymaster"
sentinel_nodes: [["localhost", 26379]]
sentinel_password: "password" # [OPTIONAL]
.env에 설정하기
.env에서 REDIS_SENTINEL_NODES를 설정해 redis 센티널을 구성할 수 있어요.
REDIS_SENTINEL_NODES 값 예시:
REDIS_SENTINEL_NODES='[["localhost", 26379]]'
REDIS_SERVICE_NAME = "mymaster"
REDIS_SENTINEL_PASSWORD = "password"
note
.env에서 redis 클러스터 노드를 설정하는 파이썬 스크립트 예시:# List of startup nodes sentinel_nodes = [["localhost", 26379]] # set startup nodes in environment variables os.environ["REDIS_SENTINEL_NODES"] = json.dumps(sentinel_nodes) print("REDIS_SENTINEL_NODES", os.environ["REDIS_SENTINEL_NODES"])
TTL
litellm_settings:
cache: true
cache_params: # set cache params for redis
type: redis
ttl: 600 # will be cached on redis for 600s
# default_in_memory_ttl: Optional[float], default is None. time in seconds.
# default_in_redis_ttl: Optional[float], default is None. time in seconds.
SSL
.env에 REDIS_SSL="True"를 설정하면 LiteLLM이 이를 감지해요.
REDIS_SSL="True"
빠른 테스트용으로 REDIS_URL도 사용할 수 있어요. 예:
REDIS_URL="rediss://.."
하지만 프로덕션에서 REDIS_URL을 쓰는 건 권장하지 않아요. 이를 redis_host, port 등과 비교했을 때 성능 차이를 발견했어요.
IAM 인증 (IAM authentication)
두 주요 관리형 Redis 서비스 모두 비밀번호 대신 수명이 짧은 서명 토큰으로 프록시를 인증하게 해줘요. 그래서 콘피그나 시크릿 스토어에 Redis 비밀번호가 존재하지 않아요. ElastiCache와 Valkey는 AWS ElastiCache IAM Authentication을, Memorystore는 GCP Memorystore IAM Authentication을 보세요.
Redis max_connections
Redis용 cache_params에서 max_connections 파라미터를 설정할 수 있어요. 이는 Redis 클라이언트에 직접 전달되어 풀의 최대 동시 연결 수를 제어해요. No connection available 같은 오류가 보이면 이 값을 늘려보세요:
litellm_settings:
cache: true
cache_params:
type: redis
max_connections: 100
cache_params는 응답 캐시 클라이언트만 크기 조정해요. 프록시는 각자 고유한 풀을 가진 Redis 클라이언트를 두 개 더 보유할 수 있어요: general_settings.coordination_redis의 조정 Redis(지출 추적, 크로스 포드 요율 제한, 포드 잠금)와 router_settings.redis_host / redis_port / redis_password의 라우터 Redis. 그 블록 안에서 max_connections를 설정해 크기를 조정하세요. coordination_redis는 여분의 키를 Redis 클라이언트로 전달하고, router_settings.cache_kwargs는 라우터 클라이언트에 대해 동일하게 해요:
general_settings:
coordination_redis:
host: os.environ/REDIS_HOST
port: 6379
max_connections: 100
router_settings:
redis_host: os.environ/REDIS_HOST
redis_port: 6379
cache_kwargs:
max_connections: 100
응답 캐싱이 비활성화되고 coordination_redis 블록이 없으면 조정 클라이언트는 REDIS_* 환경 변수만으로 구성되므로, 풀 크기를 정하려면 REDIS_MAX_CONNECTIONS가 방법이에요.
Redis socket_timeout
프록시 캐시 클라이언트는 각 Redis 명령에 대해 최대 socket_timeout초를 기다린 후 타임아웃을 발생시켜요. 기본값은 litellm/caching/redis_cache.py의 RedisCache.__init__가 설정하는 5.0초예요. cache_params.socket_timeout으로 설정하세요. 값은 Redis 클라이언트에 그대로 전달되고 모든 토폴로지(독립형, REDIS_URL, 클러스터, 센티널)에 적용돼요:
litellm_settings:
cache: true
cache_params:
type: redis
socket_timeout: 1.0 # seconds per Redis command, default 5.0
조정 및 라우터 클라이언트는 자체 5.0초 기본값을 가지며, 자체 블록에서 같은 키를 읽어요. 부하 중 지출 추적이나 요율 제한이 기록하는 Timeout reading from <host>:6379는 조정 클라이언트에서 온 것이므로, cache_params가 아니라 거기서 socket_timeout을 올리세요:
general_settings:
coordination_redis:
host: os.environ/REDIS_HOST
port: 6379
socket_timeout: 10.0
router_settings:
redis_host: os.environ/REDIS_HOST
redis_port: 6379
cache_kwargs:
socket_timeout: 10.0
REDIS_SOCKET_TIMEOUT 환경 변수(기본 0.1)는 캐시 클라이언트의 타임아웃을 바꾸지 않아요. LiteLLM은 이를 명시적 socket_timeout 없이 구축된 Redis 클라이언트에만 적용하는데, 오늘날 그것은 litellm/_redis.py의 센티널 연결 경로예요. 프록시 캐시 클라이언트는 항상 자체 socket_timeout(5.0초 기본값 또는 cache_params 값)을 전달하고, 호출자 kwarg가 REDIS_* 환경 매핑보다 우선하므로 REDIS_SOCKET_TIMEOUT이 설정돼도 캐시 클라이언트는 여전히 5.0초로 동작해요. 같은 방식으로 구축되는 조정·라우터 클라이언트도 동일해요. 캐시 클라이언트가 센티널을 통해 연결할 때도, 센티널 기본값이 적용되려는 시점에 kwarg가 이미 존재하므로 동일해요. 유일한 예외는 cache_params의 socket_timeout: null인데, 이는 kwarg를 빼서 REDIS_SOCKET_TIMEOUT이 통과되게 해요.
가상 키 인증 캐시 (Redis) (Virtual Key Authentication Cache)
프록시가 가상 키(고객 API 키)를 검증하면 결과가 캐시되어 매 요청마다 데이터베이스를 조회하지 않아요. 기본적으로 이 캐시는 각 워커 프로세스 안에만 존재하므로, 배포 후 새 pod나 추가 Uvicorn 워커는 각자 캐시를 데우고, 데워질 때까지 더 많은 DB 읽기를 유발할 수 있어요.
litellm_settings.enable_redis_auth_cache: true를 설정해 가상 키 인증 데이터를 litellm_settings.cache / cache_params 아래에 구성된 동일한 Redis 인스턴스로 미러링하세요. 그러면 워커와 복제본이 클러스터 전체에서 캐시된 인증 항목을 공유해요.
요구사항
litellm_settings.cache가 true여야 해요 (캐시 설정 중에 프록시용 Redis가 초기화됨). All settings 참고.cache_params.type가 redis여야 해요 (또는 캐시 콘피그에 따른 Redis Cluster). 인증 캐시는 그 Redis 클라이언트에 붙어요. supported cache_params 참고.- 선택적으로
general_settings.user_api_key_cache_ttl(초) 설정: Redis 인증 캐싱이 활성화되면 TTL이 인메모리와 Redis 계층 모두에 적용되므로, 오래된 키가 일관되게 만료돼요.
예시:
litellm_settings:
cache: true
enable_redis_auth_cache: true
cache_params:
type: redis
host: os.environ/REDIS_HOST
port: 6379
general_settings:
user_api_key_cache_ttl: 300 # optional; seconds
tip
시작 로그가 두 모드를 구분해요:
enable_redis_auth_cache: true면 워커 간에 가상 키 조회가 공유된다는 메시지가 보여요.
키 객체의 캐시 TTL (Cache TTL for the key object)
인메모리 캐시가 키 객체를 저장하는 시간을 구성해요 (db 요청 방지).
general_settings:
user_api_key_cache_ttl: <your-number> #time in seconds
기본값은 60초예요.
키 객체의 캐시 용량 (Cache capacity for the key object)
인메모리 계층은 워커당 기본 200개 항목을 보유하며, 가상 키, 팀, 사용자, 최종 사용자, 멤버십이 공유해요. 활성 키가 그보다 많으면 항목이 요청 사이에 축출되고 모든 인증 조회가 DB로 폴백돼요. 키 수에 맞게 캡을 올리세요:
general_settings:
user_api_key_cache_max_size: 5000 # entries per worker, must be a positive integer
같은 손잡이를 Admin UI의 Settings > Router Settings > General에서, 또는 POST /config/field/update로 런타임에 편집할 수 있어요. 다음 콘피그 재로드 시 재시작 없이 실행 중인 캐시가 리사이즈돼요. config.yaml에 설정된 값이 DB 값보다 우선해요.