谷歌云 Bigtable 远程缓存#

警告

本页记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 LMCache MP 模式以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见二级 KV 存储。

概述：为什么选择 Bigtable？#

Cloud Bigtable 非常适合需要大规模而不牺牲性能的 LLM 服务工作负载。它提供：

大规模可扩展性：无缝扩展以处理 PB 级的 KV Cache 数据，延迟保持在稳定的个位数毫秒级。
企业可靠性：完全托管，内置复制，零停机时间扩展，以及强大的 IAM 安全性。
灵活的存储层：为您的部署选择成本和性能的最佳平衡：- SSD 层（推荐）：针对低延迟、高吞吐量缓存进行了优化。推荐用于检索速度至关重要的主要 L2 缓存设置。- HDD 层：最适合成本效益高的大规模归档存储，在容量优先于亚毫秒延迟的情况下使用。

---

快速开始：无损原始存储#

本教程将指导您如何使用原始 FP16 值（无损存储）设置具有持久性 Cloud Bigtable SSD 层的 LMCache。

步骤 1：启用 GCP Bigtable API

运行以下命令以启用所需的 Google Cloud 服务：

gcloud services enable bigtable.googleapis.com bigtableadmin.googleapis.com --project=your-gcp-project-id

步骤 2：配置 Bigtable 实例

在您选择的区域中创建一个单节点 Bigtable SSD 实例：

gcloud beta bigtable instances create lmcache-bt-instance \
    --display-name="LMCache SSD Instance" \
    --edition=ENTERPRISE \
    --cluster-storage-type=ssd \
    --cluster-config=id=lmcache-cluster,zone=us-central1-a,nodes=1 \
    --project=your-gcp-project-id

步骤 3：创建数据库表

创建一个表并配置一个名为 cf 的列族：

gcloud bigtable instances tables create lmcache-kv-table \
    --instance=lmcache-bt-instance \
    --column-families=cf \
    --project=your-gcp-project-id

步骤 4：安装 LMCache 和 Bigtable SDK

在您的服务机器上安装 LMCache 和 Google Cloud Bigtable 客户端库：

export NO_NATIVE_EXT=1
pip install --no-cache-dir lmcache google-cloud-bigtable cachetools

步骤 5：配置 LMCache

创建一个配置 YAML 文件（例如，lmcache_config.yaml），并使用以下设置：

# Setup lossless, sharded Bigtable cache
chunk_size: 256
local_cpu: true
max_local_cpu_size: 10.0
remote_url: "bigtable://your-gcp-project-id/lmcache-bt-instance"
remote_serde: "naive"

extra_config:
  bigtable_project_id: "your-gcp-project-id"
  bigtable_instance_id: "lmcache-bt-instance"
  bigtable_table_name: "lmcache-kv-table"
  bigtable_family_name: "cf"
  bigtable_layer_group_size: 10  # Splits KV chunks across columns to stay under cell size limits

第 6 步：开始使用 vLLM 服务

启动您的 vLLM 引擎，指向 LMCache 配置：

LMCACHE_CONFIG_FILE=lmcache_config.yaml vllm serve facebook/opt-6.7b

---

高级配置教程#

教程 1：服务大型模型（量化压缩）#

如果您正在服务极大的模型（例如，Llama-3.1-405B 或长上下文 70B 模型），其中原始 KV Cache 块超过 240 MB，您应该启用 LMCache 的原生 CacheGen 压缩，以在将有效负载存储到 Bigtable 之前进行量化。

创建一个 lmcache_config_compressed.yaml 文件：

chunk_size: 256
local_cpu: true
max_local_cpu_size: 10.0
remote_url: "bigtable://your-gcp-project-id/lmcache-bt-instance"

# Enable CacheGen quantization compression
remote_serde: "cachegen"

extra_config:
  bigtable_project_id: "your-gcp-project-id"
  bigtable_instance_id: "lmcache-bt-instance"
  bigtable_table_name: "lmcache-kv-table"
  bigtable_family_name: "cf"
  bigtable_layer_group_size: 0  # Disable sharding (CacheGen output fits easily in a single cell)

好处：将 KV Cache 的占用空间压缩 **10 倍到 20 倍**（将 128MB 的负载减少到 ~8MB），大幅降低 Bigtable 网络传输延迟和存储成本。

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

对于低延迟的热缓存，您可以在 Bigtable 前放置一个 Redis 实例。热请求由 Redis 提供服务，而长尾持久缓存则卸载到 Bigtable。

chunk_size: 256
local_cpu: true
max_local_cpu_size: 15.0

# Define the caching pipeline order
remote_storage_plugins:
  - "redis"
  - "bigtable"

extra_config:
  # Redis L2 Configuration
  remote_storage_plugin.redis.redis_url: "redis://your-redis-host:6379"

  # Bigtable L3 Configuration
  remote_storage_plugin.bigtable.bigtable_project_id: "your-gcp-project-id"
  remote_storage_plugin.bigtable.bigtable_instance_id: "lmcache-bt-instance"
  remote_storage_plugin.bigtable.bigtable_table_name: "lmcache-kv-table"
  remote_storage_plugin.bigtable.bigtable_family_name: "cf"
  remote_storage_plugin.bigtable.bigtable_layer_group_size: 10

---

配置参考#

在配置文件中的 extra_config 字典内配置以下选项：

Bigtable 配置参数#
参数键	类型	默认	描述
`bigtable_project_id`	字符串	无	您的 Google Cloud 项目 ID。
`bigtable_instance_id`	字符串	无	您的 Cloud Bigtable 实例 ID。
`bigtable_table_name`	字符串	无	Bigtable 表名。
`bigtable_family_name`	字符串	`cf`	Bigtable 列族名称。
`bigtable_layer_group_size`	整数	`10`	每个列组的层数。设置为 `0` 以禁用层组分片。
`bigtable_max_chunk_size_mb`	浮点数	`90.0`	禁用分片时允许的最大写入限制。超过此限制的写入将被安全地跳过。
`credentials_path`	字符串	无	GCP 服务账户 JSON 密钥文件的绝对路径。如果省略，LMCache 默认使用应用程序默认凭据 (ADC)。
`exists_cache_ttl_seconds`	浮点数	`10.0`	在 Bigtable 节点上屏蔽查找的 TTL。
`bigtable_write_timeout_ms`	浮点数	`10000.0`	数据库写入的最大超时时间。
`bigtable_read_timeout_ms`	浮点数	`5000.0`	数据库读取的最大超时。

---

故障排除#

身份验证失败：如果省略了 credentials_path，请确保您的环境通过 gcloud auth application-default login 进行身份验证或配置了 GKE 工作负载身份联合。
写入被跳过 / “Bigtable 块大小超过阈值”：* 如果使用未压缩存储（remote_serde: "naive"），请确保 bigtable_layer_group_size 设置为 10 以启用层组分片（允许写入最多 240MB）。* 或者，通过设置 remote_serde: "cachegen" 启用压缩，并将 bigtable_layer_group_size 设置为 0。
冗余 RPC 警告：如果您看到关于 use_layerwise 与分片一起运行的警告，请通过在您的 YAML 配置中设置 use_layerwise: false 来禁用它。层组分片将读取优化为单个网络往返，而 use_layerwise: true 强制进行 32 次以上的顺序网络调用。