跳至主要内容

缓存

注意

关于 OpenAI/Anthropic 提示词缓存（Prompt Caching），请查看此处

缓存 LLM 响应。LiteLLM 的缓存系统存储并重用 LLM 响应，以节省成本并降低延迟。当你两次发出相同的请求时，系统将返回缓存的响应，而不是再次调用 LLM API。

支持的缓存​

  • 内存缓存
  • 磁盘缓存
  • Redis 缓存
  • Qdrant 语义缓存
  • Redis 语义缓存
  • S3 存储桶缓存
  • GCS 存储桶缓存

虚拟密钥验证缓存 (Redis)​

当代理验证虚拟密钥（客户 API 密钥）时，结果会被缓存，这样就不必在每次请求时都查询数据库。默认情况下，该缓存仅存在于每个工作进程中——因此在部署后，新的 Pod 或额外的 Uvicorn 工作进程会各自预热自己的缓存，在预热完成前可能会触发更多的数据库读取操作。

设置 litellm_settings.enable_redis_auth_cache: true，将虚拟密钥的验证数据镜像到配置在 litellm_settings.cache / cache_params 下的同一个 Redis 实例中。这样，工作进程和副本就可以在整个集群中共享缓存的验证条目。

要求

  • litellm_settings.cache 必须为 true（代理的 Redis 在缓存设置期间初始化）。请参阅所有设置。
  • cache_params.type 必须为 redis（或根据你的缓存配置设置为 Redis 集群）；验证缓存会附加到该 Redis 客户端。请参阅支持的 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
提示

启动日志会区分这两种模式：设置 enable_redis_auth_cache: true 后，你应该会看到一条关于虚拟密钥查找在工作进程间共享的消息。

快速入门​

可以通过在 config.yaml 中添加 cache 键来启用缓存

第一步：将 cache 添加到 config.yaml​

model_list:
  - model_name: gpt-3.5-turbo
    litellm_params:
      model: gpt-3.5-turbo
  - 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

[可选] 第一步之二：添加 Redis 命名空间，默认 TTL​

命名空间​

如果你想为密钥创建文件夹，可以设置命名空间，如下所示

litellm_settings:
  cache: true
  cache_params: # set cache params for redis
    type: redis
    namespace: "litellm.caching.caching"

这样密钥的存储方式将是

litellm.caching.caching:<hash>

Redis 集群​

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" }]

Redis 哨兵（Sentinel）​

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]

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 等参数在性能上存在差异。

GCP IAM 身份验证​

对于带有 IAM 身份验证的 GCP Memorystore Redis，请安装所需的依赖项

目前仅支持通过 GCP 并仅在 Redis 集群上使用 Redis 的 IAM 身份验证。
uv add google-cloud-iam

对于带有 GCP IAM 的 Redis 集群

litellm_settings:
  cache: True
  cache_params:
    type: redis
    redis_startup_nodes:
      [{ "host": "10.128.0.2", "port": 6379 }, { "host": "10.128.0.2", "port": 11008 }]
    gcp_service_account: "projects/-/serviceAccounts/your-sa@project.iam.gserviceaccount.com"
    ssl: true
    ssl_cert_reqs: null
    ssl_check_hostname: false

第二步：将 Redis 凭据添加到 .env​

在操作系统环境中设置 REDIS_URL 或 REDIS_HOST 以启用缓存。

REDIS_URL = ""        # REDIS_URL='redis://username:password@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

附加参数（kwargs）

信息

使用 REDIS_* 环境变量来配置所有的 Redis 客户端库参数。这是切换 Redis 设置的建议方案，因为它会自动将环境变量映射到 Redis 客户端的参数中。

你可以通过在操作系统环境中存储变量名 + 值来传递任何额外的 redis.Redis 参数，如下所示

REDIS_<redis-kwarg-name> = ""

例如

REDIS_SSL = "True"
REDIS_SSL_CERT_REQS = "None" 
REDIS_CONNECTION_POOL_KWARGS = '{"max_connections": 20}'
警告

注意：对于非字符串的 Redis 参数（如整数、布尔值或复杂对象），请避免使用 REDIS_* 环境变量，因为它们在 Redis 客户端初始化时可能会失败。建议改用路由器配置中的 cache_kwargs。

查看它是如何从环境中读取的

第三步：使用配置运行代理​

$ litellm --config /path/to/config.yaml

用法​

基础​

发送两次相同的请求

curl http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
     "model": "gpt-3.5-turbo",
     "messages": [{"role": "user", "content": "write a poem about litellm!"}],
     "temperature": 0.7
   }'

curl http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
     "model": "gpt-3.5-turbo",
     "messages": [{"role": "user", "content": "write a poem about litellm!"}],
     "temperature": 0.7
   }'

动态缓存控制​

参数类型描述
ttl可选 (int)将响应缓存用户定义的时间长度（单位：秒）
s-maxage可选 (int)仅接受处于用户定义时长范围内的缓存响应（单位：秒）
no-cache可选 (bool)将不会把响应存入缓存。
no-store可选 (bool)将不会缓存该响应
namespace可选 (str)将响应缓存在用户定义的命名空间下

每个缓存参数都可以在请求级别进行控制。以下是每个参数的示例

ttl​

设置缓存响应的时间（秒）。

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-3.5-turbo",
    extra_body={
        "cache": {
            "ttl": 300  # Cache response for 5 minutes
        }
    }
)

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-3.5-turbo",
    extra_body={
        "cache": {
            "s-maxage": 600  # Only use cache if less than 10 minutes old
        }
    }
)

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-3.5-turbo",
    extra_body={
        "cache": {
            "no-cache": True  # Skip cache check, get fresh response
        }
    }
)

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-3.5-turbo",
    extra_body={
        "cache": {
            "no-store": True  # Don't cache this response
        }
    }
)

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-3.5-turbo",
    extra_body={
        "cache": {
            "namespace": "my-custom-namespace"  # Store in custom namespace
        }
    }
)

仅为代理设置缓存，不作用于实际的 LLM API 调用​

如果你只想启用速率限制和多实例负载均衡等功能，可以使用此功能。

设置 supported_call_types: [] 以禁用实际 API 调用上的缓存。

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

调试缓存 - /cache/ping​

LiteLLM 代理公开了一个 /cache/ping 端点来测试缓存是否按预期工作

用法

curl --location 'http://0.0.0.0:4000/cache/ping'  -H "Authorization: Bearer sk-1234"

预期响应 - 当缓存健康时

{
    "status": "healthy",
    "cache_type": "redis",
    "ping_response": true,
    "set_cache_response": "success",
    "litellm_cache_params": {
        "supported_call_types": "['completion', 'acompletion', 'embedding', 'aembedding', 'atranscription', 'transcription']",
        "type": "redis",
        "namespace": "None"
    },
    "redis_cache_params": {
        "redis_client": "Redis<ConnectionPool<Connection<host=redis-16337.c322.us-east-1-2.ec2.cloud.redislabs.com,port=16337,db=0>>>",
        "redis_kwargs": "{'url': 'redis://:******@redis-16337.c322.us-east-1-2.ec2.cloud.redislabs.com:16337'}",
        "async_redis_conn_pool": "BlockingConnectionPool<Connection<host=redis-16337.c322.us-east-1-2.ec2.cloud.redislabs.com,port=16337,db=0>>",
        "redis_version": "7.2.0"
    }
}

高级功能​

控制启用缓存的调用类型 - (/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

在 config.yaml 中设置缓存参数​

model_list:
  - model_name: gpt-3.5-turbo
    litellm_params:
      model: gpt-3.5-turbo
  - 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
  cache_params: # cache_params are optional
    type: "redis" # The type of cache to initialize. Can be "local", "redis", "s3", or "gcs". Defaults to "local".
    host: "localhost" # The host address for the Redis cache. Required if type is "redis".
    port: 6379 # The port number for the Redis cache. Required if type is "redis".
    password: "your_password" # The password for the Redis cache. Required if type is "redis".

    # Optional configurations
    supported_call_types:
      ["acompletion", "atext_completion", "aembedding", "atranscription"]
      # /chat/completions, /completions, /embeddings, /audio/transcriptions

删除缓存键 - /cache/delete​

要删除缓存键，请向 /cache/delete 发送请求，包含你想要删除的 keys

示例

curl -X POST "http://0.0.0.0:4000/cache/delete" \
  -H "Authorization: Bearer sk-1234" \
  -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 sk-1234' \
    --header 'Content-Type: application/json' \
    --data '{
    "model": "gpt-3.5-turbo",
    "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,
}

**设置默认不开启缓存 - 仅通过显式选择开启**​

  1. 为缓存设置 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
  1. 在默认不开启缓存的情况下选择启用缓存
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-3.5-turbo",
    extra_body = {        # OpenAI python accepts extra args in extra_body
        "cache": {"use-cache": True}
    }
)

Redis max_connections​

你可以在 Redis 的 cache_params 中设置 max_connections 参数。此参数会直接传递给 Redis 客户端，用于控制连接池中同时存在的最大连接数。如果你看到类似 No connection available 的错误，请尝试增大此值。

litellm_settings:
  cache: true
  cache_params:
    type: redis
    max_connections: 100

proxy config.yaml 中支持的 cache_params​

cache_params:
  # ttl
  ttl: Optional[float]
  default_in_memory_ttl: Optional[float]
  default_in_redis_ttl: Optional[float]
  max_connections: Optional[Int]

  # Type of cache (options: "local", "redis", "s3", "gcs")
  type: s3

  # List of litellm call types to cache for
  # Options: "completion", "acompletion", "embedding", "aembedding"
  supported_call_types:
    ["acompletion", "atext_completion", "aembedding", "atranscription"]
    # /chat/completions, /completions, /embeddings, /audio/transcriptions

  # Redis cache parameters
  host: localhost # Redis server hostname or IP address
  port: "6379" # Redis server port (as a string)
  password: secret_password # Redis server password
  namespace: Optional[str] = None,

  # GCP IAM Authentication for Redis
  gcp_service_account: "projects/-/serviceAccounts/your-sa@project.iam.gserviceaccount.com" # GCP service account for IAM authentication
  gcp_ssl_ca_certs: "./server-ca.pem" # Path to SSL CA certificate file for GCP Memorystore Redis
  ssl: true # Enable SSL for secure connections
  ssl_cert_reqs: null # Set to null for self-signed certificates
  ssl_check_hostname: false # Set to false for self-signed certificates

  # S3 cache parameters
  s3_bucket_name: your_s3_bucket_name # Name of the S3 bucket
  s3_region_name: us-west-2 # AWS region of the S3 bucket
  s3_api_version: 2006-03-01 # AWS S3 API version
  s3_use_ssl: true # Use SSL for S3 connections (options: true, false)
  s3_verify: true # SSL certificate verification for S3 connections (options: true, false)
  s3_endpoint_url: https://s3.amazonaws.com # S3 endpoint URL
  s3_aws_access_key_id: your_access_key # AWS Access Key ID for S3
  s3_aws_secret_access_key: your_secret_key # AWS Secret Access Key for S3
  s3_aws_session_token: your_session_token # AWS Session Token for temporary credentials

  # GCS cache parameters
  gcs_bucket_name: your_gcs_bucket_name # Name of the GCS bucket
  gcs_path_service_account: /path/to/service-account.json # Path to GCS service account JSON file
  gcs_path: cache/ # [OPTIONAL] GCS path prefix for cache objects

提供商特定可选参数的缓存​

默认情况下，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

进阶 - 用户 API 密钥缓存 TTL​

配置内存缓存存储密钥对象的时间长度（防止频繁数据库请求）

general_settings:
  user_api_key_cache_ttl: <your-number> #time in seconds

默认该值为 60 秒。

🚅
LiteLLM 企业版
SSO/SAML、审计日志、支出跟踪、多团队管理和护栏 —— 专为生产环境构建。
了解更多 →