快取控制

一旦啟用快取，就會套用到每一種支援的呼叫類型。本頁說明如何縮小範圍：可在每個請求中使用 body 內的 cache 物件、透過金鑰中繼資料依虛擬金鑰設定，或透過 cache_params 進行 proxy 全域設定。

動態快取控制

參數	類型	說明
`ttl`	Optional(int)	會將回應快取使用者定義的時間長度（以秒為單位）
`s-maxage`	Optional(int)	只會接受在使用者定義範圍內（以秒為單位）的快取回應
`no-cache`	Optional(bool)	不會將回應儲存在快取中。
`no-store`	Optional(bool)	不會快取回應
`namespace`	Optional(str)	會將回應快取在使用者定義的命名空間下

每個快取參數都可以依請求層級控制。以下是每個參數的範例：

`ttl`

設定回應快取的時間長度（以秒為單位）。

OpenAI Python SDK
curl

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 http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "cache": {"ttl": 300},
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

`s-maxage`

只接受在指定年齡內（以秒為單位）的快取回應。

OpenAI Python SDK
curl

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 $LITELLM_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "cache": {"s-maxage": 600},
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

`no-cache`

強制取得新的回應，略過快取。

OpenAI Python SDK
curl

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 $LITELLM_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "cache": {"no-cache": true},
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

`no-store`

不會將回應儲存在快取中。

OpenAI Python SDK
curl

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 $LITELLM_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "cache": {"no-store": true},
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

`namespace`

將回應儲存在特定快取命名空間下。

OpenAI Python SDK
curl

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 $LITELLM_API_KEY" \
  -d '{
    "model": "gpt-5.6-luna",
    "cache": {"namespace": "my-custom-namespace"},
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

依金鑰的快取控制

在虛擬金鑰的中繼資料中設定 cache 欄位，proxy 就會將其套用到使用該金鑰發出的每個請求，因此用戶端無需變更。這通常是讓某一類流量排除於快取之外，同時讓其他所有地方維持啟用的做法。

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

支援的金鑰層級快取控制：ttl、s-maxage、no-cache、no-store。

將快取預設關閉（僅 opt in）

將 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 mode
litellm_settings:
  set_verbose: True
  cache: True
  cache_params:
    mode: default_off # 👈 Key change cache is default_off

在快取預設關閉時 opt in 使用快取

OpenAI Python SDK
curl

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 http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -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", "aresponses"]
      # /chat/completions, /completions, /embeddings, /audio/transcriptions, /v1/responses

為 proxy 設定快取，但不套用於實際的 llm api 呼叫

如果您只想啟用像是速率限制與跨多個執行個體的負載平衡等功能，請使用此項。

將 supported_call_types: [] 設為停用實際 api 呼叫上的快取。

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

刪除快取鍵 - `/cache/delete`

若要刪除快取鍵，請將請求送到 /cache/delete，並帶上您要刪除的 keys

範例

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

# {"status":"success"}

檢視回應中的快取鍵

您可以在回應標頭中查看 cache_key；在快取命中時，快取鍵會以 x-litellm-cache-key 回應標頭送出

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

來自 litellm proxy 的回應

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,
}

提供者特定的選用參數快取

預設情況下，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

動態快取控制​

ttl​

s-maxage​

no-cache​

no-store​

namespace​

依金鑰的快取控制​

將快取預設關閉（僅 opt in）​

控制啟用快取的呼叫類型 -（/chat/completion、/embeddings 等）​

為 proxy 設定快取，但不套用於實際的 llm api 呼叫​

刪除快取鍵 - /cache/delete​

檢視回應中的快取鍵​

提供者特定的選用參數快取​

啟用提供者特定參數快取​