Hugging Face Buckets 后端#

Hugging Face Buckets 后端使用 LMCache 内置的远程存储插件框架，将 LMCache 块存储在 Hugging Face Bucket 中。这是一个持久的远程后端，适合于温暖和冷却的 KV Cache 持久化，而不是最热的本地层。

何时使用它#

当您想要时，请使用 HFBucket 后端：

一个 Hub 原生的持久存储，用于 KV Cache 数据。
一个可以通过 remote_storage_plugins 配置的远程后端。
在一个 LMCache 部署中有多个命名的桶实例。

避免将其用作最低延迟缓存查找的主要热路径。本地 CPU、本地磁盘和其他低延迟后端更适合最热门的缓存层。

要求和限制#

LMCache 使用 huggingface_hub 存储桶 API 进行上传、下载、列出和删除操作。
首次内置版本故意采取保守态度：
- 仅支持完整块。
- 部分块上传被拒绝。
- 当存储的对象大小与预期的完整 LMCache 块大小不匹配时，下载将被拒绝。
- 块元数据未存储在桶对象中。

最小配置#

chunk_size: 256
local_cpu: false
save_unfull_chunk: false
remote_serde: "naive"
blocking_timeout_secs: 10
remote_storage_plugins: ["hfbucket"]
extra_config:
  remote_storage_plugin.hfbucket.bucket_handle: "hf://buckets/my-org/lmcache-kv/prod"
  remote_storage_plugin.hfbucket.token_env: "HF_TOKEN"
  remote_storage_plugin.hfbucket.create_bucket_if_missing: false
  remote_storage_plugin.hfbucket.download_tmp_dir: "/tmp/lmcache-hfbucket"
  remote_storage_plugin.hfbucket.metadata_cache_ttl_secs: 30

多个实例#

使用实例限定的插件名称来配置同一 LMCache 配置中的多个基于桶的远程存储。

remote_storage_plugins: ["hfbucket.us", "hfbucket.eu"]
extra_config:
  remote_storage_plugin.hfbucket.us.bucket_handle: "hf://buckets/my-org/lmcache-kv/us"
  remote_storage_plugin.hfbucket.us.token_env: "HF_US_TOKEN"
  remote_storage_plugin.hfbucket.eu.bucket_handle: "hf://buckets/my-org/lmcache-kv/eu"
  remote_storage_plugin.hfbucket.eu.token_env: "HF_EU_TOKEN"

配置参考#

所有配置键都位于 extra_config.remote_storage_plugin.<plugin_name>.* 下，其中 plugin_name 可以是 hfbucket 或者实例限定名称，例如 hfbucket.prod。

bucket_handle（必需）：Hugging Face Bucket 句柄，格式为 hf://buckets/<namespace>/<bucket>[/<prefix>]。
token_env（可选，默认 HF_TOKEN）：用于解析 Hugging Face 访问令牌的环境变量。
token（可选）：直接的令牌覆盖。当两者都设置时，token_env 优先。
create_bucket_if_missing (可选，默认 false)：在第一次写入路径时延迟创建存储桶。
download_tmp_dir (可选): 连接器本地下载临时空间的根目录。在 Linux 上，将其指向 tmpfs 挂载，例如 /dev/shm/lmcache-hfbucket，可以避免下载路径上的磁盘写入。
metadata_cache_ttl_secs（可选，默认值为 30）：缓存确切存在性和大小元数据的生存时间（TTL）。

MP 模式配置#

在多进程（MP）模式下，Hugging Face Buckets 通过传递给 LMCache 服务器的 JSON 规范配置为 L2 适配器。这与上面的非 MP remote_storage_plugins 配置是分开的。每个 --l2-adapter 参数接受一个 JSON 对象，其 \"type\": \"hfbucket\" 字段选择 HFBucket 适配器。

{
  "type": "hfbucket",
  "bucket_handle": "hf://buckets/my-org/lmcache-kv/prod",
  "token_env": "HF_TOKEN",
  "create_bucket_if_missing": false,
  "download_tmp_dir": "/tmp/lmcache-hfbucket-mp",
  "metadata_cache_ttl_secs": 30,
  "num_workers": 4,
  "max_capacity_gb": 500,
  "eviction": {
    "eviction_policy": "LRU",
    "trigger_watermark": 0.85,
    "eviction_ratio": 0.2
  }
}

HFBucket L2 适配器字段#

类型（必需）：必须是 "hfbucket"。
bucket_handle（必需）：Hugging Face Bucket 句柄，格式为 hf://buckets/<namespace>/<bucket>[/<prefix>]。
token_env：用于解析 Hugging Face 访问令牌的环境变量（默认 "HF_TOKEN"）。
token（可选，直接的令牌回退。当环境变量设置时，token_env 优先。对于生产部署，建议使用 token_env 以避免在适配器 JSON 中存储秘密。）
create_bucket_if_missing: 在第一次存储操作时懒惰地创建存储桶（默认值为 false）。这仅在存储桶缺失且令牌有权限创建时有效；它无法修复无效的凭据、无效的句柄或网络故障。
download_tmp_dir: 临时加载下载的根目录（默认 /tmp/lmcache-hfbucket-mp）。MP 适配器将桶文件下载到每个任务的临时文件中，然后将其字节复制到 MP 控制器提供的目标 MemoryObj 缓冲区中。
metadata_cache_ttl_secs: 缓存的确切路径大小元数据的 TTL（默认 30）。当其他进程可能在 LMCache 之外修改同一存储桶前缀时，将此值设置得更低，以便更新的元数据比减少 Hugging Face 元数据调用更为重要。
num_workers: 用于阻塞 Hugging Face Hub 存储桶 API 调用的工作线程数量（默认 4）。HFBucket Python API 是同步的，因此 MP 模式在适配器的基于 eventfd 的完成接口后面运行上传、查找、加载和删除工作，使用有限的线程池。
max_capacity_gb: get_usage() 用于基于水印的 L2 逐出的容量。设置为 0（默认）以禁用聚合容量跟踪；此时 get_usage() 报告适配器未提供逐出信号。
逐出: 可选的子字典，用于为此适配器启用 L2 逐出控制器。当存在时，当前正在加载的键会通过查找和锁定路径受到保护，并在解锁之前被 delete() 跳过。

与非多租户 HFBucket 的区别#

Hugging Face 桶操作是同步的，但适配器通过在工作线程上运行阻塞调用使提交变为非阻塞。
MP 加载不会分配和返回新的内存。MP 控制器提供目标 MemoryObj 缓冲区，适配器将下载的字节复制到这些缓冲区中。
键通过 ObjectKey (model_name + kv_rank + chunk_hash + 可选的 cache_salt) 来识别，而不是 CacheEngineKey。序列化的 MP 对象名称为 <model>@<kv_rank_hex>@<chunk_hash_hex>[@<cache_salt>]，然后对其进行编码以形成桶路径。此命名与非 MP HFBucket 连接器的 CacheEngineKey 对象名称不兼容，因此由非 MP LMCache 填充的桶前缀不能被 MP LMCache 直接读取，反之亦然。
完整对象写入是基于批处理的。Hugging Face 的批量写入不是事务性的，因此失败的存储任务可能仍会在桶中留下某些对象。MP 适配器在此类失败后会协调后端元数据，因此实际写入的对象会被计入使用量并在后续删除（提交的存储任务仍会被报告为失败）。

注意事项#

后端在配置的桶前缀下存储对象，使用 LMCache 键的可逆编码，因此 list() 返回 LMCache 键字符串，而不是原始桶对象路径。