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）。

注意事项#

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