HF Bucket

一个 L2 适配器，通过 huggingface_hub 桶 API 将 KV Cache 对象存储在 Hugging Face Bucket 中。阻塞式 Hub 调用在一个由守护线程上的 asyncio 循环驱动的有界线程池中执行，因此 L2 控制器线程不会阻塞在网络 I/O 上。

对象名称源自 MP ObjectKey，格式为 <model>@<kv_rank_hex>@<chunk_hash_hex>[@<cache_salt>]，然后使用标准的 HFBucket 对象名称编码加上可选的桶前缀进行编码。由于 Hugging Face 的批量写入不是事务性的，因此部分失败的存储任务会协调后端元数据，以便实际落地的对象仍然计入使用量核算和后续删除。

这是一个持久化远程后端，最适合温层和冷层 KV Cache 缓存；对于最热的缓存层，建议优先使用延迟更低的本地适配器。

必填字段：

• bucket_handle：桶的位置，格式为 hf://buckets/<namespace>/<bucket>[/<prefix>]。

可选字段：

• token_env (字符串，默认 "HF_TOKEN")：用于解析 Hugging Face 访问令牌的环境变量。

• token (字符串)：token_env 未设置时直接使用的令牌备用值。

• create_bucket_if_missing (bool，默认 false)：在首次存储时惰性创建桶，而非要求桶预先存在。

• download_tmp_dir (字符串)：加载时临时下载文件的根目录。

• metadata_cache_ttl_secs (float，默认 30.0)：用于支持查找和用量统计的路径大小元数据缓存的 TTL。

• num_workers (int，默认 4)：用于执行阻塞式 Hugging Face Hub API 调用的工作线程数。

• max_capacity_gb (float，默认 0.0)：get_usage() 所使用的总容量上限。值为 0 时禁用整体逐出。

• eviction (dict)：可选的逐出策略，参见 L2AdapterConfigBase。

配置示例：

# Minimal: use an existing bucket with a token from $HF_TOKEN
--l2-adapter '{"type": "hfbucket", "bucket_handle": "hf://buckets/my-org/lmcache-kv/prod"}'

# Create the bucket on first store and bound the worker pool
--l2-adapter '{"type": "hfbucket", "bucket_handle": "hf://buckets/my-org/lmcache-kv/prod", "create_bucket_if_missing": true, "num_workers": 8}'

# Enable aggregate eviction with a capacity cap
--l2-adapter '{"type": "hfbucket", "bucket_handle": "hf://buckets/my-org/lmcache-kv/prod", "max_capacity_gb": 50, "eviction": {"eviction_policy": "LRU", "trigger_watermark": 0.9, "eviction_ratio": 0.1}}'