LMCache MP 模式 Valkey L2 适配器实战指南基于 valkey-glide 的 KV Cache 远程缓存后端【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache导读本文面向在 LMCache 多进程MP模式下将 Valkey或 Redis作为 L2 远程 KV Cache 后端的开发者完整讲解内置valkeyL2 适配器的能力边界、安装前置条件、全部配置字段与典型部署示例并深入到ValkeyWorkerPool线程模型、wire key 布局、集群槽路由、容量与驱逐策略等源码级实现原理。读完本文你将能够独立完成从单机 standalone 到 Valkey-Cluster、再到 TLS 托管服务如 ElastiCache Serverless的 L2 缓存接入与调优。适配器定位MP 模式下的原生 Valkey 后端valkeyL2 适配器valkey_l2_adapter.py是一个基于官方valkey-glide同步Python 客户端实现的 L2 适配器将 KV Cache chunk 存储到 Valkey或兼容的 Redis服务中并通过cluster_mode字段同时支持两种拓扑standalone 模式使用GlideClientValkey-Cluster 模式使用GlideClusterClient由客户端自动完成槽路由、MOVED/ASK 重定向与拓扑发现。I/O 通过内部ValkeyWorkerPool的 worker 线程池调度每个 worker 持有自己独立的 glide 客户端因此一批 key 的读写可以跨线程并行在集群模式下还能跨 primary 节点并行。从源码结构看该 worker 池是 MP 模式ValkeyL2Adapter与非 MP 模式ValkeyConnector共享的同一实现见 worker_pool.py 模块注释glide 客户端生命周期、能力探测、buffer 格式处理与可靠关闭逻辑集中在一处。与 RESP 适配器的区别在 MP 模式下LMCache 还提供了面向单个 Redis/Valkey 服务器的RESP适配器走原生 C RESP 连接器。而valkey适配器是一等公民的 Valkey 后端它直接使用valkey-glide-sync原生支持 Valkey-Cluster槽路由、MOVED/ASK 重定向、拓扑发现均在GlideClusterClient内部完成并在多 MB 级 KV chunk 上保留了 copy-reduced 的 SET/GET 能力。完整的设计动机包括为何采用同步而非异步 glide 客户端可参阅 Valkey L2 Adapter 设计文档。前置条件安装 glide sync 客户端valkey适配器要求安装valkey-glide-sync包版本 2.3.0这是同时具备 copy-reduced SET 与 buffer GET 的首个稳定版本。该依赖是惰性导入的——只有第一次启动 Valkey worker 时才会真正加载因此不启用 Valkey 的安装环境无需安装此依赖pip install valkey-glide-sync2.3.0如果 worker 启动时缺少该包适配器构造会以如下明确错误失败Valkey support requires the glide_sync module. Install: pip install valkey-glide-sync2.3.0 (note: the plain valkey-glide package is async-only)注意纯valkey-glide包只提供异步客户端不足以支撑本适配器。从 worker_pool.py 的源码可见该错误由_get_client()捕获ImportError后抛出RuntimeError产生。为什么必须用同步 glide而非异步设计文档中给出了明确的性能理由glide-async在 SET 和 GET 上都会带来不可避免的逐值拷贝——异步客户端需要将命令序列化为 Protobuf 消息跨进程内 Rust 运行时边界传递这强制对每个 value 做一次bytes拷贝glide 上游明确表述 zero-copy is sync-only。而 KV Cache chunk 通常是多 MB 级70B 模型、TP8 时约 10 MB/chunk每个请求会命中数百个 chunk若每次传输都多付一次拷贝开销将主导线上耗时。同步 glide 是唯一通过 CFFIffi.from_buffer避免该拷贝的路径。需要澄清的是zero-copy 是 glide 的术语而非字面承诺——两条路径都是copy-reduced减少拷贝而非完全零拷贝GET 时值仍在 glide-core 内部物化后再拷入调用方缓冲区SET 时负载仍会进入命令缓冲区。同步 API 会阻塞调用线程因此适配器用ThreadPoolExecutor跑 N 个独立 worker 线程来驱动并发在途请求每个 worker 通过threading.local()持有自己的 glide 客户端glide 内部多路复用使单个客户端具备高并发能力但同步 Python API 只允许单线程同时提交一条命令所以 N 线程 × N 客户端才是解锁批级并行的关键。配置字段详解valkey适配器通过 CLI 的--l2-adapterJSON 参数配置配置文件解析与校验逻辑见 valkey_l2_adapter.py 中的ValkeyL2AdapterConfig。必填字段字段说明startup_nodes种子节点列表格式为host:port[,host:port...]字符串。standalone 模式cluster_mode: false默认下仅使用第一个条目多余的会触发告警cluster 模式下任意可达的种子节点即可glide 会自动发现完整拓扑。可选字段字段默认值说明cluster_modefalse为true时使用GlideClusterClient否则使用 standaloneGlideClient。username可选认证用户名。password可选认证密码。key_prefix部署级 key 命名空间通过与标准 wire key 拼接。不得包含。留空则 wire 格式与无前缀布局完全一致。num_workers8 0内部 worker 线程池大小。每个 worker 持有独立 glide 客户端因此这是真正的 I/O 并发旋钮——大批量或集群部署时提高它可提升吞吐。tls_enablefalse启用 TLS。ElastiCache Serverless 等托管 Valkey 服务必需。database_id无可选standalone 模式的逻辑数据库 id。cluster_mode: true时忽略并告警。request_timeout5.0 0单请求超时单位秒。connection_timeout10.0 0初始连接超时单位秒。max_capacity_gb0 0声明总容量GB用于驱动LMCache 侧驱逐。0默认且推荐禁用全局 LMCache 驱逐交由 Valkey 服务端自身的maxmemory/驱逐策略coordinator 上配置的按cache_salt配额在两种情况下均生效。仅当单个 LMCache 写入方私有拥有集群时才设置 0并配合eviction块——不要与服务端驱逐或 TTL 组合二者都会使 LMCache 的字节记账漂移。ttl_seconds无可选按 key 的 TTL 秒数设置时必须是正整数。省略默认则写入无过期时间的 key。启用服务端基于时间的过期是 Valkey 服务端配置的volatile-*驱逐策略所必需的。不要与max_capacity_gb 0组合会记录告警服务端过期不会回报给 LMCache 的字节记账。源码中from_dict()与help()方法valkey_l2_adapter.py对这些字段做了逐一校验startup_nodes必须是合法的host:port且端口为正整数、num_workers必须为非布尔整数且大于 0、key_prefix不得含、max_capacity_gb不得为负、request_timeout/connection_timeout必须大于 0、ttl_seconds必须为正整数且与max_capacity_gb 0互斥并告警。standalone 模式下提供多个种子节点、或 cluster 模式下设置database_id都会触发 warning 日志。完整配置示例以下四种示例覆盖了从单机到托管集群的主要部署形态摘自 valkey.rst# 独立 Valkey / Redis 服务器服务端驱逐 --l2-adapter {type: valkey, startup_nodes: 127.0.0.1:6379} # Valkey 集群 TLS 认证托管服务 --l2-adapter { type: valkey, cluster_mode: true, startup_nodes: seed1.example.com:6379,seed2.example.com:6379, username: lmcache, password: secret, tls_enable: true, num_workers: 16 } # 私有 Valkey 集群上的 LMCache 驱动驱逐 --l2-adapter { type: valkey, cluster_mode: true, startup_nodes: 10.0.0.1:6379,10.0.0.2:6379, max_capacity_gb: 512, num_workers: 16 } # 按 key 设置 TTL服务端过期无 LMCache 侧驱逐 --l2-adapter { type: valkey, startup_nodes: 127.0.0.1:6379, ttl_seconds: 3600 }此外非 MP 模式的 Valkey 连接器valkey://scheme对应的 YAML 配置可参考 examples/kv_cache_reuse/remote_backends/valkey/valkey.yaml 与 storage_backends 文档其中使用extra_config.valkey_num_workers、extra_config.valkey_modestandalone/cluster、valkey_username/valkey_password、valkey_database、valkey_enable_ttl/valkey_ttl_sec默认 86400 秒、tls_enable等键。Wire Key 布局与集群均匀分布每个存储的值由如下 wire key 标识[key_prefix]model_namekv_rank_hexobject_group_id_hexchunk_hash_hex[cache_salt]chunk_hash_hex是统一内容哈希wire key不含Redis hashtag{...}因此 key 在集群的 16384 个槽位上均匀分布无需手动做 key 分片。这一设计的价值在集群模式下尤为明显glide 将每个 key 哈希到 16384 个槽之一CRC16(key) % 16384并路由到槽所属的 primary而 LMCache 的 wire key 嵌入了均匀内容哈希且无 hashtagkey 会自动跨槽、跨节点均匀铺开适配器无需任何显式负载均衡。实现细节可对照 valkey_l2_adapter.py 的_wire_key()方法复用了_object_key_to_string的 wire 格式仅在配置了前缀时在前面拼接prefix。线程模型与批量任务状态机并发架构┌──────────────── L2 controller ─────────────────┐ │ submit_store_task / lookup / load │ │ ▼ │ ValkeyL2Adapter │ submit one Future per key to ThreadPoolExecutor│ │ │ │ └───┼─────────────────────────────────────────────┘ │ ┌───────────┴──────── worker pool ─────────────┐ │ N threads, each with thread-local │ │ GlideClient / GlideClusterClient │ │ │ │ ┌────────── Future.add_done_callback ──────┐ │ │ │ Atomically decrement batch.remaining, │ │ │ │ record per-key ok/fail. │ │ │ │ Last finisher publishes the result and │ │ │ │ signals the matching event fd. │ │ │ └──────────────────────────────────────────┘ │ └──────────────────────────────────────────────┘每次submit_*_task都会分配一个_SubmitTaskBatchStatevalkey_l2_adapter.py由 N 个 per-key Future 共享字段用途task_id返回给调用方的公开任务 id。remaining在lock下递减归零即代表这是收尾回调。per_key_ok按下单顺序索引由每个回调写入。keys原始 key 列表用于 listener 通知与按 salt 记账。sizes每个 key 的字节数仅 store 批次填充其他路径留空。_SubmitTaskBatchState.settle_unlaunched()负责处理分发循环中途抛异常的边界情况索引launched之后从未获得 Future 的 key 永远不会触发完成回调因此需要在此把它们的remaining份额一次性扣除否则批次将永远无法收尾valkey_l2_adapter.py。从 worker_pool.py 可见ValkeyWorkerPool在构造时会对每个 worker 执行一次预热warmup强制提前构建客户端从而让任何连接/认证/缺依赖错误快速失败于构造阶段而不是等到第一次真实操作才暴露。批级并行的两层来源集群模式下适配器不做显式负载均衡分布发生在两个独立层面跨节点——glide 将 key 哈希到槽并路由到槽所属 primary均匀 wire key 无 hashtag 保证 key 均匀铺开。跨 worker 线程——批次按 key 将一个 Future 扇出到ValkeyWorkerPool的num_workers个线程上每个线程持有完整的集群客户端。大批次因此同时在线程与节点两个维度并行。已知的不均衡来源与调优手段设计文档明确指出读流量只打 primary未启用从节点读未设置 read-from-replica 偏好副本仅提供冗余不分担读负载读密集场景下所有 GET 都压在 primary 上。热 key单个极热 chunk如共享 system prompt映射到一个槽→一个节点均匀哈希无法分散从节点读可缓解。池大小 vs 节点数并发上限为num_workers默认 8。大集群上线程池而非集群可能成为瓶颈需调大num_workers以压满更多节点。无 hashtag 路由刻意不通过{cache_salt}hashtag 将某 salt 的 key 归置到单节点——那虽利于流水线但有热分片风险均匀分布更受青睐。report_status()暴露两种不同的用量视图current_size_bytes是 LMCache 的聚合逻辑字节计数集群模式下可能掩盖热分片一个节点已满而其他节点近乎空闲node_memory仅集群模式则是通过把INFO memory路由到所有节点采集的真实逐节点物理内存每节点used_memory/maxmemory用于发现分片失衡属于 best-effort——空 dict 表示INFO查询失败且不会阻塞状态上报实现见 valkey_l2_adapter.py 与 worker_pool.py。集群槽路由与重定向由 glide 处理每个 key 属于 16384 个槽之一CRC16(key) % 16384每个槽归一个 primary 所有。客户端缓存槽→节点映射并直接把请求发给所属节点。该映射可能过期reshard 或 failover 之后请求落到错误节点后服务端返回重定向——这是集群的自治愈机制而非错误MOVED——槽的所有者已永久变更reshard 完成或副本晋升。客户端在新节点上重试并更新缓存映射。ASK——槽正在迁移中这个特定 key已移动到目标节点而槽名义上仍属于源节点。客户端对这一次请求向目标节点发送ASKING 命令但不更新映射迁移尚未完成。初始发现CLUSTER SHARDS、MOVED/ASK 处理、ASKING与拓扑刷新全部由GlideClusterClient负责适配器从不解析重定向一次client.get/set调用只返回最终的、重定向后的结果。resharding增删节点对适配器透明glide 处理 MOVED/ASK 重定向与拓扑刷新种子节点无需更新。优雅 reshard 会迁移 key 并保持缓存温热不迁移槽就删节点会丢失这些 key表现为缓存 missLMCache 的字节记账可能随之漂移。容量管理与驱逐策略选定唯一权威方驱逐来自两侧必须只选一侧作为权威——双侧同时运行会使 LMCache 的字节记账与 LRU 漂移表现为 lookup/load miss绝不产出脏数据但会残留 ghost keyA. LMCache 侧LMCache 决定并执行删除自行记账内置驱逐max_capacity_gb 0eviction块进程内 pass 跟踪用量全局usage_fraction或按cache_salt配额并在超过trigger_watermark后删除。其字节计数器为每进程且重启即重置因此仅对单个写入方私有拥有集群的场景可信。注意若缺少eviction块eviction_config为None驱逐控制器不会为此适配器接线max_capacity_gb不产生任何效果。Coordinator 托管可选当LMCACHE_COORDINATOR_URL指向运行中的 MP coordinator 时实例向其注册由 coordinator 在整个集群范围内强制执行按cache_salt的配额这是单个实例看不到的聚合用量。多个 LMCache 实例共享一个集群时使用默认不设置即无 coordinator。按cache_salt配额在max_capacity_gb取何值的情况下都生效——基类通过_notify_keys_stored/_notify_keys_deleted维护每 salt 总量供任何配额策略使用。delete(keys)是同步的向池提交每个 key 一个 DEL等待每个完成至多request_timeout并以存储时捕获的 per-key 大小经_key_sizes触发_notify_keys_deletedDEL 返回0key 已不存在的静默跳过。实现上还会跳过当前被读锁钉住的 key避免读中间删值破坏加载valkey_l2_adapter.py。B. 服务端Valkey 自行回收不通知 LMCache在 Valkey 服务端设置maxmemorymaxmemory-policy配置文件 /CONFIG SET/ 托管参数组LMCache 不负责设置。按部署形态选择策略专用集群→allkeys-lfu内存压力下驱逐任意key永不卡死在maxmemory无需 TTL。共享集群→ 设置ttl_secondsvolatile-lfuvolatile-*策略只驱逐带 TTL 的 key——即只有 LMCache 自己的 key——服务端绝不会驱逐其他进程写入的数据。TTL 也允许 key 独立于内存压力按时间自行过期。ttl_seconds与max_capacity_gb 0的组合混用了两侧服务端 TTL 与 LMCache 内置驱逐会记录告警。配置校验处的具体告警逻辑见 valkey_l2_adapter.py。另注意LMCache 侧驱逐是MP 模式专属。非 MP 的ValkeyConnector自身无驱逐完全依赖服务端通过valkey_enable_ttl/valkey_ttl_sec实现同样的 TTL 机制。认证、TLS 与锁语义认证与 TLS当username/password任一非空时会构造ServerCredentials(username, password)传给 glidetls_enableTrue设置 glide 的use_tls。凭据只来自配置解析后的值不会出现在report_status()输出或日志中。tls_enable只是一个开关glide 的use_tls不带任何证书选项。它只在服务器证书可对客户端的 OS 信任库验证时有效——即公网签名证书ElastiCache Serverless、Lets Encrypt。自定义证书场景为计划中的后续工作暴露 glide 的TlsAdvancedConfiguration部署场景仅tls_enable公共 CA 证书ElastiCache Serverless✅ 可用自签名证书⏳ 待支持私有/内部 CA⏳ 待支持双向 TLSmTLS⏳ 待支持锁语义客户端侧钉住锁是客户端侧的glide/Valkey 没有 LMCache 的驱逐钉住概念。适配器在_locked_keys中维护按 key 的引用计数成功的lookup递增它submit_unlock递减它计数归零的 key 被移除。适配器从不阻止服务端驱逐——钉住只在上层的 L2 controller 层强制执行。submit_lookup_and_lock_task完成时会对每个命中 key 递增锁引用计数valkey_l2_adapter.pydelete()则跳过当前引用计数非零的 key。加载校验与错误模型Load 时的尺寸校验拒绝脏数据_do_get_into在 GET 结果与预期缓冲区大小不一致时返回False缓存 missbuffer-GET 路径——glide 返回实际写入字节数若bytes_written ! len(buf)视为存储值过期或被截断按 miss 处理。回退路径——len(data) ! len(buf)产生同样的 miss 语义。两种情况下 load 位图对该 key 报0位chunk 由引擎重新计算——适配器永远不会流出过期数据。安全方面worker_pool.py还实现了线程私有 scratch 缓冲区glide 的原生 buffer-GET 在释放 GIL 状态下写入若目标缓冲区别名化 slab 分配器内存可能被其他线程中途回收会存在悬挂槽竞态因此先落入每线程私有暂存区、再在持有 GIL 时拷入目标缓冲区同时消除逐次调用的分配开销。部分失败记账store 任务只要有任何一个key 写入失败即整体报失败——这是安全选择store controller 只在任务成功时才把任务 key 从 L1 中淘汰若部分失败仍报成功会把未存储的 key 从 L1 驱逐而永久丢失。字节记账则更细粒度_notify_keys_stored只携带实际写入的 key基类将其并入按cache_salt与聚合总量——即使任务整体标为失败get_usage()依旧准确。错误模型速查表失败场景每 key 位日志说明单个 SET 抛异常FalseWARNING批次中其他 key 不受影响。单个 GET 抛异常/超时FalseWARNING视为缓存 misschunk 重算。GET 尺寸不匹配FalseDEBUG过期/截断值被拒绝。单个 EXISTS 抛异常FalseWARNING视为 miss。单个 DEL 抛异常跳过WARNING该 key 不触发 listener 通知。集群 MOVED/ASKglide 处理—对适配器透明。连接断开glide 处理—glide 自动重连调用重试。缺少valkey-glide-sync构造失败抛出明确的、可操作的错误信息。测试与验证路径适配器配套了两层测试可用于验证上述全部行为tests/v1/distributed/test_valkey_l2_adapter.py——单元测试通过进程内glide_syncfake 模块MockValkeyServer共享 dict 模拟集中式服务器支持按操作注入故障、模拟截断值、逐节点INFO memory驱动L2AdapterInterface契约无需真实valkey-glide或 Valkey 服务器即可覆盖批量回调、部分失败、尺寸校验与锁引用计数等路径。tests/v1/distributed/test_valkey_l2_adapter_integration.py——集成测试连接本地真实 Valkey 实例验证端到端读写。使用边界与适用前提本适配器服务于LMCache MP 模式的 L2 层非 MP 场景请使用valkey://scheme 的ValkeyConnector配置参数见 storage_backends/valkey.rst两者共享同一ValkeyWorkerPool实现。max_capacity_gb 0的 LMCache 内置驱逐仅适用于单写入方私有集群且必须同时配置eviction块共享集群优先选用服务端volatile-*策略配合ttl_seconds或启用 coordinator 托管的按cache_salt配额。自定义证书、mTLS、从节点读等能力在当前版本尚未接线规划中当前 TLS 仅覆盖公共 CA 证书场景。适配器明确不实现自研 C 扩展glide 的 Rust 运行时已在 FFI 释放 GIL、不解析自定义 MOVED/ASK、不做 hashtag 路由、也不在 EXISTS 时做尺寸校验改由随后的 GET 强制校验——这些都是刻意划定的非目标以保持实现单一职责并最大化复用 glide 的能力。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
LMCache MP 模式 Valkey L2 适配器实战指南：基于 valkey-glide 的 KV Cache 远程缓存后端
LMCache MP 模式 Valkey L2 适配器实战指南基于 valkey-glide 的 KV Cache 远程缓存后端【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache导读本文面向在 LMCache 多进程MP模式下将 Valkey或 Redis作为 L2 远程 KV Cache 后端的开发者完整讲解内置valkeyL2 适配器的能力边界、安装前置条件、全部配置字段与典型部署示例并深入到ValkeyWorkerPool线程模型、wire key 布局、集群槽路由、容量与驱逐策略等源码级实现原理。读完本文你将能够独立完成从单机 standalone 到 Valkey-Cluster、再到 TLS 托管服务如 ElastiCache Serverless的 L2 缓存接入与调优。适配器定位MP 模式下的原生 Valkey 后端valkeyL2 适配器valkey_l2_adapter.py是一个基于官方valkey-glide同步Python 客户端实现的 L2 适配器将 KV Cache chunk 存储到 Valkey或兼容的 Redis服务中并通过cluster_mode字段同时支持两种拓扑standalone 模式使用GlideClientValkey-Cluster 模式使用GlideClusterClient由客户端自动完成槽路由、MOVED/ASK 重定向与拓扑发现。I/O 通过内部ValkeyWorkerPool的 worker 线程池调度每个 worker 持有自己独立的 glide 客户端因此一批 key 的读写可以跨线程并行在集群模式下还能跨 primary 节点并行。从源码结构看该 worker 池是 MP 模式ValkeyL2Adapter与非 MP 模式ValkeyConnector共享的同一实现见 worker_pool.py 模块注释glide 客户端生命周期、能力探测、buffer 格式处理与可靠关闭逻辑集中在一处。与 RESP 适配器的区别在 MP 模式下LMCache 还提供了面向单个 Redis/Valkey 服务器的RESP适配器走原生 C RESP 连接器。而valkey适配器是一等公民的 Valkey 后端它直接使用valkey-glide-sync原生支持 Valkey-Cluster槽路由、MOVED/ASK 重定向、拓扑发现均在GlideClusterClient内部完成并在多 MB 级 KV chunk 上保留了 copy-reduced 的 SET/GET 能力。完整的设计动机包括为何采用同步而非异步 glide 客户端可参阅 Valkey L2 Adapter 设计文档。前置条件安装 glide sync 客户端valkey适配器要求安装valkey-glide-sync包版本 2.3.0这是同时具备 copy-reduced SET 与 buffer GET 的首个稳定版本。该依赖是惰性导入的——只有第一次启动 Valkey worker 时才会真正加载因此不启用 Valkey 的安装环境无需安装此依赖pip install valkey-glide-sync2.3.0如果 worker 启动时缺少该包适配器构造会以如下明确错误失败Valkey support requires the glide_sync module. Install: pip install valkey-glide-sync2.3.0 (note: the plain valkey-glide package is async-only)注意纯valkey-glide包只提供异步客户端不足以支撑本适配器。从 worker_pool.py 的源码可见该错误由_get_client()捕获ImportError后抛出RuntimeError产生。为什么必须用同步 glide而非异步设计文档中给出了明确的性能理由glide-async在 SET 和 GET 上都会带来不可避免的逐值拷贝——异步客户端需要将命令序列化为 Protobuf 消息跨进程内 Rust 运行时边界传递这强制对每个 value 做一次bytes拷贝glide 上游明确表述 zero-copy is sync-only。而 KV Cache chunk 通常是多 MB 级70B 模型、TP8 时约 10 MB/chunk每个请求会命中数百个 chunk若每次传输都多付一次拷贝开销将主导线上耗时。同步 glide 是唯一通过 CFFIffi.from_buffer避免该拷贝的路径。需要澄清的是zero-copy 是 glide 的术语而非字面承诺——两条路径都是copy-reduced减少拷贝而非完全零拷贝GET 时值仍在 glide-core 内部物化后再拷入调用方缓冲区SET 时负载仍会进入命令缓冲区。同步 API 会阻塞调用线程因此适配器用ThreadPoolExecutor跑 N 个独立 worker 线程来驱动并发在途请求每个 worker 通过threading.local()持有自己的 glide 客户端glide 内部多路复用使单个客户端具备高并发能力但同步 Python API 只允许单线程同时提交一条命令所以 N 线程 × N 客户端才是解锁批级并行的关键。配置字段详解valkey适配器通过 CLI 的--l2-adapterJSON 参数配置配置文件解析与校验逻辑见 valkey_l2_adapter.py 中的ValkeyL2AdapterConfig。必填字段字段说明startup_nodes种子节点列表格式为host:port[,host:port...]字符串。standalone 模式cluster_mode: false默认下仅使用第一个条目多余的会触发告警cluster 模式下任意可达的种子节点即可glide 会自动发现完整拓扑。可选字段字段默认值说明cluster_modefalse为true时使用GlideClusterClient否则使用 standaloneGlideClient。username可选认证用户名。password可选认证密码。key_prefix部署级 key 命名空间通过与标准 wire key 拼接。不得包含。留空则 wire 格式与无前缀布局完全一致。num_workers8 0内部 worker 线程池大小。每个 worker 持有独立 glide 客户端因此这是真正的 I/O 并发旋钮——大批量或集群部署时提高它可提升吞吐。tls_enablefalse启用 TLS。ElastiCache Serverless 等托管 Valkey 服务必需。database_id无可选standalone 模式的逻辑数据库 id。cluster_mode: true时忽略并告警。request_timeout5.0 0单请求超时单位秒。connection_timeout10.0 0初始连接超时单位秒。max_capacity_gb0 0声明总容量GB用于驱动LMCache 侧驱逐。0默认且推荐禁用全局 LMCache 驱逐交由 Valkey 服务端自身的maxmemory/驱逐策略coordinator 上配置的按cache_salt配额在两种情况下均生效。仅当单个 LMCache 写入方私有拥有集群时才设置 0并配合eviction块——不要与服务端驱逐或 TTL 组合二者都会使 LMCache 的字节记账漂移。ttl_seconds无可选按 key 的 TTL 秒数设置时必须是正整数。省略默认则写入无过期时间的 key。启用服务端基于时间的过期是 Valkey 服务端配置的volatile-*驱逐策略所必需的。不要与max_capacity_gb 0组合会记录告警服务端过期不会回报给 LMCache 的字节记账。源码中from_dict()与help()方法valkey_l2_adapter.py对这些字段做了逐一校验startup_nodes必须是合法的host:port且端口为正整数、num_workers必须为非布尔整数且大于 0、key_prefix不得含、max_capacity_gb不得为负、request_timeout/connection_timeout必须大于 0、ttl_seconds必须为正整数且与max_capacity_gb 0互斥并告警。standalone 模式下提供多个种子节点、或 cluster 模式下设置database_id都会触发 warning 日志。完整配置示例以下四种示例覆盖了从单机到托管集群的主要部署形态摘自 valkey.rst# 独立 Valkey / Redis 服务器服务端驱逐 --l2-adapter {type: valkey, startup_nodes: 127.0.0.1:6379} # Valkey 集群 TLS 认证托管服务 --l2-adapter { type: valkey, cluster_mode: true, startup_nodes: seed1.example.com:6379,seed2.example.com:6379, username: lmcache, password: secret, tls_enable: true, num_workers: 16 } # 私有 Valkey 集群上的 LMCache 驱动驱逐 --l2-adapter { type: valkey, cluster_mode: true, startup_nodes: 10.0.0.1:6379,10.0.0.2:6379, max_capacity_gb: 512, num_workers: 16 } # 按 key 设置 TTL服务端过期无 LMCache 侧驱逐 --l2-adapter { type: valkey, startup_nodes: 127.0.0.1:6379, ttl_seconds: 3600 }此外非 MP 模式的 Valkey 连接器valkey://scheme对应的 YAML 配置可参考 examples/kv_cache_reuse/remote_backends/valkey/valkey.yaml 与 storage_backends 文档其中使用extra_config.valkey_num_workers、extra_config.valkey_modestandalone/cluster、valkey_username/valkey_password、valkey_database、valkey_enable_ttl/valkey_ttl_sec默认 86400 秒、tls_enable等键。Wire Key 布局与集群均匀分布每个存储的值由如下 wire key 标识[key_prefix]model_namekv_rank_hexobject_group_id_hexchunk_hash_hex[cache_salt]chunk_hash_hex是统一内容哈希wire key不含Redis hashtag{...}因此 key 在集群的 16384 个槽位上均匀分布无需手动做 key 分片。这一设计的价值在集群模式下尤为明显glide 将每个 key 哈希到 16384 个槽之一CRC16(key) % 16384并路由到槽所属的 primary而 LMCache 的 wire key 嵌入了均匀内容哈希且无 hashtagkey 会自动跨槽、跨节点均匀铺开适配器无需任何显式负载均衡。实现细节可对照 valkey_l2_adapter.py 的_wire_key()方法复用了_object_key_to_string的 wire 格式仅在配置了前缀时在前面拼接prefix。线程模型与批量任务状态机并发架构┌──────────────── L2 controller ─────────────────┐ │ submit_store_task / lookup / load │ │ ▼ │ ValkeyL2Adapter │ submit one Future per key to ThreadPoolExecutor│ │ │ │ └───┼─────────────────────────────────────────────┘ │ ┌───────────┴──────── worker pool ─────────────┐ │ N threads, each with thread-local │ │ GlideClient / GlideClusterClient │ │ │ │ ┌────────── Future.add_done_callback ──────┐ │ │ │ Atomically decrement batch.remaining, │ │ │ │ record per-key ok/fail. │ │ │ │ Last finisher publishes the result and │ │ │ │ signals the matching event fd. │ │ │ └──────────────────────────────────────────┘ │ └──────────────────────────────────────────────┘每次submit_*_task都会分配一个_SubmitTaskBatchStatevalkey_l2_adapter.py由 N 个 per-key Future 共享字段用途task_id返回给调用方的公开任务 id。remaining在lock下递减归零即代表这是收尾回调。per_key_ok按下单顺序索引由每个回调写入。keys原始 key 列表用于 listener 通知与按 salt 记账。sizes每个 key 的字节数仅 store 批次填充其他路径留空。_SubmitTaskBatchState.settle_unlaunched()负责处理分发循环中途抛异常的边界情况索引launched之后从未获得 Future 的 key 永远不会触发完成回调因此需要在此把它们的remaining份额一次性扣除否则批次将永远无法收尾valkey_l2_adapter.py。从 worker_pool.py 可见ValkeyWorkerPool在构造时会对每个 worker 执行一次预热warmup强制提前构建客户端从而让任何连接/认证/缺依赖错误快速失败于构造阶段而不是等到第一次真实操作才暴露。批级并行的两层来源集群模式下适配器不做显式负载均衡分布发生在两个独立层面跨节点——glide 将 key 哈希到槽并路由到槽所属 primary均匀 wire key 无 hashtag 保证 key 均匀铺开。跨 worker 线程——批次按 key 将一个 Future 扇出到ValkeyWorkerPool的num_workers个线程上每个线程持有完整的集群客户端。大批次因此同时在线程与节点两个维度并行。已知的不均衡来源与调优手段设计文档明确指出读流量只打 primary未启用从节点读未设置 read-from-replica 偏好副本仅提供冗余不分担读负载读密集场景下所有 GET 都压在 primary 上。热 key单个极热 chunk如共享 system prompt映射到一个槽→一个节点均匀哈希无法分散从节点读可缓解。池大小 vs 节点数并发上限为num_workers默认 8。大集群上线程池而非集群可能成为瓶颈需调大num_workers以压满更多节点。无 hashtag 路由刻意不通过{cache_salt}hashtag 将某 salt 的 key 归置到单节点——那虽利于流水线但有热分片风险均匀分布更受青睐。report_status()暴露两种不同的用量视图current_size_bytes是 LMCache 的聚合逻辑字节计数集群模式下可能掩盖热分片一个节点已满而其他节点近乎空闲node_memory仅集群模式则是通过把INFO memory路由到所有节点采集的真实逐节点物理内存每节点used_memory/maxmemory用于发现分片失衡属于 best-effort——空 dict 表示INFO查询失败且不会阻塞状态上报实现见 valkey_l2_adapter.py 与 worker_pool.py。集群槽路由与重定向由 glide 处理每个 key 属于 16384 个槽之一CRC16(key) % 16384每个槽归一个 primary 所有。客户端缓存槽→节点映射并直接把请求发给所属节点。该映射可能过期reshard 或 failover 之后请求落到错误节点后服务端返回重定向——这是集群的自治愈机制而非错误MOVED——槽的所有者已永久变更reshard 完成或副本晋升。客户端在新节点上重试并更新缓存映射。ASK——槽正在迁移中这个特定 key已移动到目标节点而槽名义上仍属于源节点。客户端对这一次请求向目标节点发送ASKING 命令但不更新映射迁移尚未完成。初始发现CLUSTER SHARDS、MOVED/ASK 处理、ASKING与拓扑刷新全部由GlideClusterClient负责适配器从不解析重定向一次client.get/set调用只返回最终的、重定向后的结果。resharding增删节点对适配器透明glide 处理 MOVED/ASK 重定向与拓扑刷新种子节点无需更新。优雅 reshard 会迁移 key 并保持缓存温热不迁移槽就删节点会丢失这些 key表现为缓存 missLMCache 的字节记账可能随之漂移。容量管理与驱逐策略选定唯一权威方驱逐来自两侧必须只选一侧作为权威——双侧同时运行会使 LMCache 的字节记账与 LRU 漂移表现为 lookup/load miss绝不产出脏数据但会残留 ghost keyA. LMCache 侧LMCache 决定并执行删除自行记账内置驱逐max_capacity_gb 0eviction块进程内 pass 跟踪用量全局usage_fraction或按cache_salt配额并在超过trigger_watermark后删除。其字节计数器为每进程且重启即重置因此仅对单个写入方私有拥有集群的场景可信。注意若缺少eviction块eviction_config为None驱逐控制器不会为此适配器接线max_capacity_gb不产生任何效果。Coordinator 托管可选当LMCACHE_COORDINATOR_URL指向运行中的 MP coordinator 时实例向其注册由 coordinator 在整个集群范围内强制执行按cache_salt的配额这是单个实例看不到的聚合用量。多个 LMCache 实例共享一个集群时使用默认不设置即无 coordinator。按cache_salt配额在max_capacity_gb取何值的情况下都生效——基类通过_notify_keys_stored/_notify_keys_deleted维护每 salt 总量供任何配额策略使用。delete(keys)是同步的向池提交每个 key 一个 DEL等待每个完成至多request_timeout并以存储时捕获的 per-key 大小经_key_sizes触发_notify_keys_deletedDEL 返回0key 已不存在的静默跳过。实现上还会跳过当前被读锁钉住的 key避免读中间删值破坏加载valkey_l2_adapter.py。B. 服务端Valkey 自行回收不通知 LMCache在 Valkey 服务端设置maxmemorymaxmemory-policy配置文件 /CONFIG SET/ 托管参数组LMCache 不负责设置。按部署形态选择策略专用集群→allkeys-lfu内存压力下驱逐任意key永不卡死在maxmemory无需 TTL。共享集群→ 设置ttl_secondsvolatile-lfuvolatile-*策略只驱逐带 TTL 的 key——即只有 LMCache 自己的 key——服务端绝不会驱逐其他进程写入的数据。TTL 也允许 key 独立于内存压力按时间自行过期。ttl_seconds与max_capacity_gb 0的组合混用了两侧服务端 TTL 与 LMCache 内置驱逐会记录告警。配置校验处的具体告警逻辑见 valkey_l2_adapter.py。另注意LMCache 侧驱逐是MP 模式专属。非 MP 的ValkeyConnector自身无驱逐完全依赖服务端通过valkey_enable_ttl/valkey_ttl_sec实现同样的 TTL 机制。认证、TLS 与锁语义认证与 TLS当username/password任一非空时会构造ServerCredentials(username, password)传给 glidetls_enableTrue设置 glide 的use_tls。凭据只来自配置解析后的值不会出现在report_status()输出或日志中。tls_enable只是一个开关glide 的use_tls不带任何证书选项。它只在服务器证书可对客户端的 OS 信任库验证时有效——即公网签名证书ElastiCache Serverless、Lets Encrypt。自定义证书场景为计划中的后续工作暴露 glide 的TlsAdvancedConfiguration部署场景仅tls_enable公共 CA 证书ElastiCache Serverless✅ 可用自签名证书⏳ 待支持私有/内部 CA⏳ 待支持双向 TLSmTLS⏳ 待支持锁语义客户端侧钉住锁是客户端侧的glide/Valkey 没有 LMCache 的驱逐钉住概念。适配器在_locked_keys中维护按 key 的引用计数成功的lookup递增它submit_unlock递减它计数归零的 key 被移除。适配器从不阻止服务端驱逐——钉住只在上层的 L2 controller 层强制执行。submit_lookup_and_lock_task完成时会对每个命中 key 递增锁引用计数valkey_l2_adapter.pydelete()则跳过当前引用计数非零的 key。加载校验与错误模型Load 时的尺寸校验拒绝脏数据_do_get_into在 GET 结果与预期缓冲区大小不一致时返回False缓存 missbuffer-GET 路径——glide 返回实际写入字节数若bytes_written ! len(buf)视为存储值过期或被截断按 miss 处理。回退路径——len(data) ! len(buf)产生同样的 miss 语义。两种情况下 load 位图对该 key 报0位chunk 由引擎重新计算——适配器永远不会流出过期数据。安全方面worker_pool.py还实现了线程私有 scratch 缓冲区glide 的原生 buffer-GET 在释放 GIL 状态下写入若目标缓冲区别名化 slab 分配器内存可能被其他线程中途回收会存在悬挂槽竞态因此先落入每线程私有暂存区、再在持有 GIL 时拷入目标缓冲区同时消除逐次调用的分配开销。部分失败记账store 任务只要有任何一个key 写入失败即整体报失败——这是安全选择store controller 只在任务成功时才把任务 key 从 L1 中淘汰若部分失败仍报成功会把未存储的 key 从 L1 驱逐而永久丢失。字节记账则更细粒度_notify_keys_stored只携带实际写入的 key基类将其并入按cache_salt与聚合总量——即使任务整体标为失败get_usage()依旧准确。错误模型速查表失败场景每 key 位日志说明单个 SET 抛异常FalseWARNING批次中其他 key 不受影响。单个 GET 抛异常/超时FalseWARNING视为缓存 misschunk 重算。GET 尺寸不匹配FalseDEBUG过期/截断值被拒绝。单个 EXISTS 抛异常FalseWARNING视为 miss。单个 DEL 抛异常跳过WARNING该 key 不触发 listener 通知。集群 MOVED/ASKglide 处理—对适配器透明。连接断开glide 处理—glide 自动重连调用重试。缺少valkey-glide-sync构造失败抛出明确的、可操作的错误信息。测试与验证路径适配器配套了两层测试可用于验证上述全部行为tests/v1/distributed/test_valkey_l2_adapter.py——单元测试通过进程内glide_syncfake 模块MockValkeyServer共享 dict 模拟集中式服务器支持按操作注入故障、模拟截断值、逐节点INFO memory驱动L2AdapterInterface契约无需真实valkey-glide或 Valkey 服务器即可覆盖批量回调、部分失败、尺寸校验与锁引用计数等路径。tests/v1/distributed/test_valkey_l2_adapter_integration.py——集成测试连接本地真实 Valkey 实例验证端到端读写。使用边界与适用前提本适配器服务于LMCache MP 模式的 L2 层非 MP 场景请使用valkey://scheme 的ValkeyConnector配置参数见 storage_backends/valkey.rst两者共享同一ValkeyWorkerPool实现。max_capacity_gb 0的 LMCache 内置驱逐仅适用于单写入方私有集群且必须同时配置eviction块共享集群优先选用服务端volatile-*策略配合ttl_seconds或启用 coordinator 托管的按cache_salt配额。自定义证书、mTLS、从节点读等能力在当前版本尚未接线规划中当前 TLS 仅覆盖公共 CA 证书场景。适配器明确不实现自研 C 扩展glide 的 Rust 运行时已在 FFI 释放 GIL、不解析自定义 MOVED/ASK、不做 hashtag 路由、也不在 EXISTS 时做尺寸校验改由随后的 GET 强制校验——这些都是刻意划定的非目标以保持实现单一职责并最大化复用 glide 的能力。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
