캐시 컨트롤

캐시 컨트롤 (Cache Controls)

캐싱을 켜면 모든 지원 호출 유형에 적용돼요. 이 페이지는 이를 좁히는 방법을 다뤄요: 요청 본문의 cache 객체로 요청별, 키 메타데이터로 가상 키별, cache_params로 프록시 전체.

출처: 문서

본문

동적 캐시 컨트롤 (Dynamic Cache Controls)

파라미터	타입	설명
ttl	선택(int)	사용자 정의 시간(초)만큼 응답을 캐시
s-maxage	선택(int)	사용자 정의 범위(초) 내에 있는 캐시 응답만 수락
no-cache	선택(bool)	응답을 캐시에 저장하지 않음
no-store	선택(bool)	응답을 캐시하지 않음
namespace	선택(str)	사용자 정의 네임스페이스 아래에 응답을 캐시

각 캐시 파라미터를 요청별로 제어할 수 있어요. 각 파라미터의 예시는 다음과 같아요.

ttl

응답을 캐시할 시간(초)을 설정해요.

OpenAI Python SDK

from openai import OpenAI
client = OpenAI(
    api_key="your-api-key",
    base_url="http://0.0.0.0:4000")
chat_completion = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    model="gpt-5.6-luna",
    extra_body={
        "cache": {
            "ttl": 300  # Cache response for 5 minutes
        }
    })

curl

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-luna",
    "cache": {"ttl": 300},
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

s-maxage

지정된 나이(초) 내에 있는 캐시 응답만 수락해요.

from openai import OpenAI
client = OpenAI(
    api_key="your-api-key",
    base_url="http://0.0.0.0:4000")
chat_completion = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    model="gpt-5.6-luna",
    extra_body={
        "cache": {
            "s-maxage": 600  # Only use cache if less than 10 minutes old
        }
    })

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-luna",
    "cache": {"s-maxage": 600},
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

no-cache

캐시를 우회하고 항상 새 응답을 강제해요.

from openai import OpenAI
client = OpenAI(
    api_key="your-api-key",
    base_url="http://0.0.0.0:4000")
chat_completion = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    model="gpt-5.6-luna",
    extra_body={
        "cache": {
            "no-cache": True  # Skip cache check, get fresh response
        }
    })

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-luna",
    "cache": {"no-cache": true},
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

no-store

응답을 캐시에 저장하지 않아요.

from openai import OpenAI
client = OpenAI(
    api_key="your-api-key",
    base_url="http://0.0.0.0:4000")
chat_completion = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    model="gpt-5.6-luna",
    extra_body={
        "cache": {
            "no-store": True  # Don't cache this response
        }
    })

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-luna",
    "cache": {"no-store": true},
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

namespace

특정 캐시 네임스페이스 아래에 응답을 저장해요.

from openai import OpenAI
client = OpenAI(
    api_key="your-api-key",
    base_url="http://0.0.0.0:4000")
chat_completion = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    model="gpt-5.6-luna",
    extra_body={
        "cache": {
            "namespace": "my-custom-namespace"  # Store in custom namespace
        }
    })

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-luna",
    "cache": {"namespace": "my-custom-namespace"},
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

키별 캐시 컨트롤 (Per-key cache controls)

가상 키의 메타데이터에 cache 필드를 설정하면, 프록시가 그 키로 만든 모든 요청에 이를 적용해요. 그래서 클라이언트는 변경이 필요 없어요. 이는 특정 클래스의 트래픽만 캐시 밖으로 빼내고 나머지는 그대로 두는 일반적인 방법이에요.

curl http://localhost:4000/key/generate \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"cache": {"no-cache": true}}
  }'

지원되는 키 수준 캐시 컨트롤: ttl, s-maxage, no-cache, no-store.

캐싱 기본값 끄기 (opt in only) (Set caching default off)

캐싱에 mode: default_off를 설정하세요.

model_list:
  - model_name: fake-openai-endpoint
    litellm_params:
      model: openai/fake
      api_key: fake-key
      api_base: https://exampleopenaiendpoint-production.up.railway.app/
# default off model
litellm_settings:
  set_verbose: True
  cache: True
  cache_params:
    mode: default_off # 👈 Key change cache is default_off

캐시가 기본 꺼짐일 때 옵트인하기:

OpenAI Python SDK

import os
from openai import OpenAI
client = OpenAI(api_key="<litellm-api-key>", base_url="http://0.0.0.0:4000")
chat_completion = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "Say this is a test",
        }
    ],
    model="gpt-5.6-luna",
    extra_body = {
        # OpenAI python accepts extra args in extra_body
        "cache": {"use-cache": True}
    })

curl

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-luna",
    "cache": {"use-cache": True}
    "messages": [
      {"role": "user", "content": "Say this is a test"}
    ]
  }'

캐싱을 켤 호출 유형 제어하기 (/chat/completion, /embeddings 등)

기본적으로 캐싱은 모든 호출 유형에 켜져 있어요. cache_params에서 supported_call_types를 설정해 어떤 호출 유형에 캐싱을 켤지 제어할 수 있어요.

캐시는 supported_call_types에 지정된 호출 유형에만 켜져요.

litellm_settings:
  cache: True
  cache_params:
    type: redis
    supported_call_types:
      ["acompletion", "atext_completion", "aembedding", "atranscription"]
      # /chat/completions, /completions, /embeddings, /audio/transcriptions

프록시에는 캐시를 설정하되 실제 llm API 호출에는 하지 않기

요율 제한, 여러 인스턴스 간 로드밸런싱 같은 기능만 활성화하려면 이렇게 하세요.

supported_call_types: []로 설정해 실제 API 호출에 대한 캐싱을 비활성화하세요.

litellm_settings:
  cache: True
  cache_params:
    type: redis
    supported_call_types: []

캐시 키 삭제 - /cache/delete

캐시 키를 삭제하려면 삭제할 키와 함께 /cache/delete로 요청을 보내세요.

예시

curl -X POST "http://0.0.0.0:4000/cache/delete" \
  -H "Authorization: Bearer ***" \
  -d '{"keys": ["586bf3f3c1bf5aecb55bd9996494d3bbc69eb58397163add6d49537762a7548d", "key2"]}'

# {"status":"success"}

응답에서 캐시 키 보기 (Viewing Cache Keys from responses)

응답 헤더에서 cache_key를 볼 수 있어요. 캐시 히트 시 캐시 키가 x-litellm-cache-key 응답 헤더로 전송돼요.

curl -i --location 'http://0.0.0.0:4000/chat/completions' \
    --header "Authorization: Bearer ***" \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "gpt-5.6-luna",
    "user": "ishan",
    "messages": [
        {
        "role": "user",
        "content": "what is litellm"
        }
    ],
}'

litellm 프록시에서의 응답:

date: Thu, 04 Apr 2024 17:37:21 GMT
content-type: application/json
x-litellm-cache-key: 586bf3f3c1bf5aecb55bd9996494d3bbc69eb58397163add6d49537762a7548d
{
    "id": "chatcmpl-9ALJTzsBlXR9zTxPvzfFFtFbFtG6T",
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": {
                "content": "I'm sorr.."
                "role": "assistant"
            }
        }
    ],
    "created": 1712252235,
}

공급자별 선택적 파라미터 캐싱 (Provider-Specific Optional Parameters Caching)

기본적으로 LiteLLM은 표준 OpenAI 파라미터만 캐시 키에 포함해요. 하지만 일부 공급자(예: Vertex AI)는 출력에 영향을 주는 추가 파라미터를 사용하는데, 이는 표준 캐시 키 생성에 포함되지 않아요.

공급자별 파라미터 캐싱 활성화

캐시 키에 공급자별 선택적 파라미터를 포함하려면 config.yaml에 다음 설정을 추가하세요:

litellm_settings:
  cache: True
  cache_params:
    type: "redis"
  enable_caching_on_provider_specific_optional_params: True  # Include provider-specific params in cache keys