S3 后端#

示例配置#

基本 S3 配置#

chunk_size: 256
local_cpu: False
save_unfull_chunk: False
remote_url: "s3://your-bucket-name"
remote_serde: "naive"
blocking_timeout_secs: 10
extra_config:
  s3_region: "us-east-1"
  s3_num_io_threads: 64
  save_chunk_meta: False

S3 Express One Zone#

chunk_size: 256
local_cpu: False
save_unfull_chunk: False
remote_url: "s3://{BUCKET_NAME}.s3express-{AZ_ID}.{REGION}.amazonaws.com"
remote_serde: "naive"
blocking_timeout_secs: 10
extra_config:
  save_chunk_meta: False
  s3_num_io_threads: 64
  s3_prefer_http2: True
  s3_region: "{REGION}"
  s3_enable_s3express: True

CoreWeave (S3 兼容)#

chunk_size: 256
local_cpu: False
max_local_cpu_size: 50
save_unfull_chunk: False
enable_async_loading: True
remote_url: "s3://test-127.cwlota.com"
remote_serde: "naive"
blocking_timeout_secs: 10
extra_config:
  s3_num_io_threads: 320
  s3_prefer_http2: False
  s3_region: "US-WEST-04A"
  s3_enable_s3express: False
  save_chunk_meta: False
  disable_tls: True
  aws_access_key_id: "your-access-key-id"
  aws_secret_access_key: "your-secret-access-key"

注意：cwlota.com 是 CoreWeave 的 S3 兼容云存储，旨在为 GPU 本地性提供缓存。您可以将 disable_tls: True 设置为非 AWS 服务。

查看 LMCache、Cohere 和 CoreWeave 之间的博客文章：https://blog.lmcache.ai/en/2025/10/29/breaking-the-memory-barrier-how-lmcache-and-coreweave-power-efficient-llm-inference-for-cohere/

配置参数#

remote_url: S3 存储桶 URL (s3://bucket-name)
save_unfull_chunk: 保存部分块（默认值：False，对于 S3 必须为 False）
enable_async_loading: 异步加载（默认值：False）
blocking_timeout_secs: 超时秒数（默认值：10）

S3 特定（在 extra_config 中）#

s3_region: S3 客户端的 AWS 区域（必需）
s3_num_io_threads: AWS CRT 客户端生成的 IO 线程数量。超过 CPU 核心数量后，收益会逐渐减少。这也是限制外发请求数量的一种方式，以防您的 S3 兼容对象存储具有速率限制网关。
s3_prefer_http2: 启用带有 ALPN 协商的 HTTP/2 (["h2", "http/1.1"])
s3_enable_s3express: 在 AWS CRT 客户端中启用 S3 Express 单区支持
save_chunk_meta: 是否在对象存储中与您的数据一起保存块元数据（对于 S3，需设置为 False）
aws_access_key_id: AWS 访问密钥 ID（或在您的环境中使用 aws configure 登录）
aws_secret_access_key: AWS 秘密访问密钥（或在您的环境中使用 aws configure 登录）

提示::

- Use same region for compute and S3

考虑使用 S3 Express One Zone，以获得更少的冗余但更好的性能。

MP 模式配置#

在多进程（MP）模式下，S3 通过传递给 LMCache 服务器的 JSON 规范配置为 L2 适配器，而不是通过 remote_url + extra_config。每个 --l2-adapter 参数接受一个 JSON 对象，其 \"type\": \"s3\" 字段选择 S3 适配器。

{
  "type": "s3",
  "s3_endpoint": "s3://my-bucket",
  "s3_region": "us-east-1",
  "s3_num_io_threads": 64,
  "s3_prefer_http2": true,
  "s3_enable_s3express": false,
  "disable_tls": false,
  "max_capacity_gb": 500,
  "eviction": {
    "eviction_policy": "LRU",
    "trigger_watermark": 0.85,
    "eviction_ratio": 0.2
  }
}

S3 L2 适配器字段#

**类型**（必需）：必须是 "s3"。
s3_endpoint (必需): 存储桶 URL。接受 s3://bucket 或裸主机形式（例如 bucket.s3.us-east-1.amazonaws.com）。
s3_region (必需): S3 客户端的 AWS 区域。
s3_num_io_threads: CRT IO 线程的数量（默认 64）。
s3_prefer_http2: 通过 ALPN 协商尝试 HTTP/2（默认 true）。
s3_enable_s3express: 启用 S3 Express 单区域签名（默认 false）。
disable_tls: 跳过 TLS，用于非 AWS HTTP 端点（默认 false）。
aws_access_key_id, aws_secret_access_key: 可选的静态凭证。当省略时，适配器使用 AWS 默认凭证链（aws configure、环境变量、IRSA 等）。
max_capacity_gb: get_usage() 用于基于水印的 L2 逐出所使用的容量。设置为 0``（默认）以禁用使用跟踪 — ``get_usage() 将返回 (-1.0, -1.0)，并且不会触发自动逐出。
逐出：可选的子字典，启用此适配器的 L2 逐出控制器。有关完整的架构，请参见 L2AdapterConfigBase _parse_eviction_config。当存在时，当前正在加载的键（通过查找和锁定路径进行引用计数）将被 delete() 跳过。

与非多租户 S3 的区别#

MP 适配器支持一流的逐出：它实现了 delete()``（真实的 S3 ``DeleteObject）、引用计数的 submit_unlock 和由 max_capacity_gb 驱动的 get_usage()。
键通过 ObjectKey (model_name + kv_rank + chunk_hash) 而不是 CacheEngineKey 来识别。线格式对象名称为 <model>@<kv_rank_hex>@<chunk_hash_hex>，这与非 MP 命名不兼容。由非 MP LMCache 填充的桶不能被 MP LMCache 直接读取，反之亦然。
未填充的块会被拒绝（与非 MP 的约束相同）。