Bigtable#

一个由 Google Cloud Bigtable 支持的 L2 适配器，能够实现进程外的远程 KV 缓存。它支持层组分片，将大型张量负载划分到多个列限定符中，以确保安全地低于 Bigtable 单元格大小限制。

Dependency compatibility#

If google-cloud-bigtable and protobuf are incompatible, importing Bigtable can raise TypeError: Descriptors cannot be created directly. lmcache server --help logs the error and continues listing available adapters. Selecting Bigtable still raises the import error; install a compatible client version before using it, for example:

pip install --upgrade google-cloud-bigtable

为什么选择 Bigtable？#

Cloud Bigtable 是企业级 LLM 服务工作负载的 L2 存储后端的优秀选择：

亚毫秒/单数延迟：基于 SSD 的 Bigtable 集群提供实时提示缓存所需的低延迟，防止远程缓存检索成为 LLM 生成的瓶颈。
高并发和吞吐量：水平扩展以处理来自多个 vLLM 实例的数千个并发查询，保护 L1 内存免受缓存未命中的影响。
企业级托管服务：由 Google Cloud 完全管理，提供内置的多区域复制、IAM 访问控制和零停机时间的扩展。
与层级无关的存储灵活性：将 LMCache 配置与数据库部署解耦。选择 SSD 层 作为主要低延迟缓存，或选择 HDD 层 作为经济高效的大规模归档存储。

必填字段：

bigtable_project_id (str): 您的 Google Cloud 项目 ID。
bigtable_instance_id (str): 您的 Cloud Bigtable 实例 ID。
bigtable_table_name (str): Bigtable 表名。

可选字段：

bigtable_family_name (str, default "cf"): 列族名称。必须在 Bigtable 表中预先创建。
bigtable_column_name (str, default \"data\"): 当禁用分片时使用的列限定符名称。
layer_group_size (int, default 10): 每个列组的层数。设置为 0 以禁用层组分片。
bigtable_max_chunk_size_mb (float, default 90.0): The maximum allowed write limit when sharding is disabled (or when using CacheGen). Writes exceeding this are skipped and the store task reports failure.
credentials_path (str, default None): GCP 服务账户 JSON 密钥文件的绝对路径。如果省略，则默认为应用程序默认凭据 (ADC)。
exists_cache_ttl_seconds (float, default 10.0): 用于内部缓存的 TTL（生存时间），单位为秒，该缓存可以保护 Bigtable 免受冗余查找请求。
bigtable_write_timeout_ms (float, default 10000.0): 数据库写入的最大超时时间。
bigtable_read_timeout_ms (float, default 5000.0): 数据库读取的最大超时。

环境变量回退。 当相应的配置值为空时，将使用这些环境变量：BT_PROJECT_ID、BT_INSTANCE_ID、BT_TABLE_NAME。

If any payload exceeds the configured unsharded limit or the adapter's 240 MiB sharded row limit, the entire store task reports failure. Other valid payloads in that task are still written and counted in cache usage. This prevents the buffer-only store policy from deleting L1 data on the assumption that every payload reached Bigtable. For example, with layer_group_size=0 and bigtable_max_chunk_size_mb=1, a 2 MiB payload is rejected and the task fails.

教程与配置示例#

教程 1：服务大规模模型（FP8 压缩）#

如果您正在服务极大的模型，其中单个 KV Cache 块非常庞大，您可以启用 FP8 量化压缩。这将 KV Cache 的占用空间压缩 2x 并减少传输到 Bigtable 的网络开销。

在 Bigtable L2 适配器 JSON 规范中添加 "serde" 子字典：

lmcache server \
    --port 65432 \
    --http-port 8080 \
    --l2-adapter '{
        "type": "bigtable",
        "bigtable_project_id": "your-gcp-project-id",
        "bigtable_instance_id": "lmcache-bt-instance",
        "bigtable_table_name": "lmcache-kv-table",
        "layer_group_size": 10,
        "serde": {
            "type": "fp8",
            "fp8_dtype": "float8_e4m3fn"
        }
    }' \
    --l1-size-gb 10.0 \
    --eviction-policy LRU

教程 2：三层混合存储（本地 CPU -> Redis L2 -> Bigtable SSD L3）#

您可以在 Bigtable 前面放置一个 Redis/Valkey 实例，作为快速热缓存，在未命中时将请求级联到 Bigtable。

使用多个 --l2-adapter 参数按顺序配置多个 L2 适配器：

lmcache server \
    --port 65432 \
    --http-port 8080 \
    --l2-adapter '{"type": "resp", "host": "your-redis-host", "port": 6379}' \
    --l2-adapter '{
        "type": "bigtable",
        "bigtable_project_id": "your-gcp-project-id",
        "bigtable_instance_id": "lmcache-bt-instance",
        "bigtable_table_name": "lmcache-kv-table",
        "layer_group_size": 10
    }' \
    --l1-size-gb 10.0 \
    --eviction-policy LRU

教程 3：多层存储级联（SSD 热层 -> HDD 存档）#

为了平衡热缓存命中的低延迟性能和长期归档存储的成本效益，您可以通过两种方式配置分层存储（从 SSD 到 HDD）：

方法 A：原生 Bigtable 分层存储（推荐 - 零配置）#

Google Cloud Bigtable 支持原生 分层存储。通过 Google Cloud 控制台、gcloud CLI 或 Terraform 在您的表上启用基于年龄的分层策略，Bigtable 会在后台自动将较旧/较冷的单元格移动到成本效益高的不频繁访问存储层。

无需更改 LMCache 配置：您只需在 LMCache 中配置一个 Bigtable L2 适配器。
无需代码更改：Bigtable 透明地处理将读取和写入路由到正确层级。
自然老化：由于单元格是使用默认的服务器时间戳写入的，因此它们将根据配置的策略窗口自然老化。

有关更多信息，请参阅官方的 Bigtable 分层存储概述。

方法 B：手动 LMCache 存储级联（替代方案）#

如果您更喜欢管理单独的物理 Bigtable 实例或表（例如，一个 SSD 和一个 HDD），您可以通过在启动命令中顺序配置多个 L2 适配器，直接在 LMCache 中级联它们：

lmcache server \
    --port 65432 \
    --http-port 8080 \
    --l2-adapter '{
        "type": "bigtable",
        "bigtable_project_id": "your-gcp-project-id",
        "bigtable_instance_id": "lmcache-bt-ssd-instance",
        "bigtable_table_name": "lmcache-kv-hot-table",
        "layer_group_size": 10
    }' \
    --l2-adapter '{
        "type": "bigtable",
        "bigtable_project_id": "your-gcp-project-id",
        "bigtable_instance_id": "lmcache-bt-hdd-instance",
        "bigtable_table_name": "lmcache-kv-archive-table",
        "layer_group_size": 10
    }' \
    --l1-size-gb 10.0 \
    --eviction-policy LRU

配置示例：自定义超时和显式服务账户#

您可以配置自定义数据库超时设置，并在 JSON 有效负载中传递显式服务帐户密钥文件路径：

lmcache server \
    --port 65432 \
    --http-port 8080 \
    --l2-adapter '{
        "type": "bigtable",
        "bigtable_project_id": "your-gcp-project-id",
        "bigtable_instance_id": "lmcache-bt-instance",
        "bigtable_table_name": "lmcache-kv-table",
        "credentials_path": "/secrets/gcp/sa_key.json",
        "bigtable_write_timeout_ms": 5000.0,
        "bigtable_read_timeout_ms": 2000.0
    }' \
    --l1-size-gb 10.0 \
    --eviction-policy LRU