配置参考

本页面记录了 LMCache 多进程服务器接受的每个 CLI 参数。参数按定义它们的配置模块进行分组。

MP 服务器

源: lmcache/v1/multiprocess/config.py

参数	默认	描述
--instance-id	(未设置，默认 UUID v4)	此 MP 服务器的稳定标识。用作协调器成员身份键，并投影到每条指标和每个 Span 的 OTel service.instance.id 资源属性（从而使遥测数据与协调器成员身份共享同一个 ID）。若未传递该参数，则默认为启动时生成的随机 UUID v4。
--host	localhost	绑定 ZMQ 服务器的主机地址。
--port	5555	绑定 ZMQ 服务器的端口。
--chunk-size	256	KV Cache 操作的块大小（以 token 为单位）。
--max-workers	1	工作线程的基本数量。为 GPU（亲和性）池和 CPU（正常）池设置默认值。可以通过 --max-gpu-workers 和 --max-cpu-workers 针对每个池进行覆盖。
--max-gpu-workers	(继承 --max-workers)	GPU 亲和性池（STORE/RETRIEVE）的工作线程。来自同一 vLLM 实例的请求始终分发到同一线程，从而消除 GPU 传输锁竞争。
--max-cpu-workers	(继承 --max-workers)	普通 CPU 池（LOOKUP 等）的工作线程。
--hash-algorithm	blake3	基于 token 的操作所使用的哈希算法。可选项：builtin、sha256_cbor、blake3。
--engine-type	default	缓存引擎后端类型。default 使用标准前缀缓存；blend 选择当前的 CacheBlend V3 实现（将 BlendV3Module 组合到引擎中）；blend_legacy 选择原始的 CacheBlend（将 BlendModule 组合到引擎中）。这两种 blend 变体都需要 --supported-transfer-mode 设置为 lmcache_driven 或 auto。可选项：default、blend、blend_legacy。
--supported-transfer-mode	auto	服务器加载的工作进程 → 服务器传输路径。lmcache_driven 仅启用服务器驱动的传输路径（STORE/RETRIEVE，支持 CUDA IPC 与 CPU SHM）；engine_driven 仅启用非 GPU（PREPARE/COMMIT）传输路径；auto（默认）同时加载两者，使任意设备类型的工作进程无需手动配置即可连接。可选项：lmcache_driven、engine_driven、auto。
--runtime-plugin-locations	[]	零个或多个路径，用于运行时插件脚本或目录，以便与服务器一起启动。插件由 MPRuntimePluginLauncher 生成，并通过 LMCACHE_RUNTIME_PLUGIN_CONFIG 环境变量接收完整的服务器配置。
--runtime-plugin-config	"{}"	通过 LMCACHE_RUNTIME_PLUGIN_EXTRA_CONFIG 转发到运行时插件的额外键值配置的 JSON 字符串。示例：'{\"plugin.frontend.heartbeat_url\": \"http://localhost:5000/heartbeat\"}'。
--script-allowed-imports	[]	允许在 HTTP /run_script 端点发布的脚本导入的以空格分隔的 Python 模块名称列表。示例：--script-allowed-imports numpy pandas。
--shm-name	(未设置)	非 GPU KV 传输的 SHM 段名称（仅在加载非 GPU 路径时使用，即 --supported-transfer-mode 为 auto 或 engine_driven）。未设置（默认）：自动分配一个共享内存池。 \"\"（空字符串）：禁用 SHM 并强制使用 pickle 传输路径。 任何其他值：将该确切名称用于 SHM 池段。
--worker-reap-timeout-seconds	120.0	工作线程发送至少一个心跳 PING 后进入静默状态的最长容忍时间（秒），超时后将回收其 KV Cache 注册，并释放泄漏的 GPU 上下文和 CUDA IPC 句柄。0 表示禁用回收。建议将此值保持在引擎适配器 lmcache.mp.heartbeat_interval（默认 10 秒）的至少 3 倍，以免少量心跳丢失导致活跃工作线程被误回收；若未同步调大此值而单独调大心跳间隔，适配器将在启动时发出警告。
--worker-registration-grace-seconds	3600.0	针对已注册但从未发送 PING 的工作线程（仍在预热或在首次请求前已崩溃）的静默容忍时间（秒）。必须大于或等于 --worker-reap-timeout-seconds。默认值较宽松，以避免将缓慢的模型预热误判为工作线程已宕机。
--enable-segmented-prefix	False	CacheBlend (--engine-type blend) only: on a mid-prefix L2 retrieve failure, retain the gapped prefix so the post-gap chunks stay L1-resident and only the dropped gap is recomputed, instead of truncating the prefix at the gap. No effect for other engines. See Fault Inject for a way to exercise it.

查找哈希日志记录

源: lmcache/v1/mp_observability/subscribers/logging/lookup_hash.py

启用时，服务器将在 EventBus 上以 MP_LOOKUP 事件的形式发布 lookup() 期间计算的块哈希。LookupHashLoggingSubscriber 会将这些事件写入滚动 JSONL 文件以供离线分析。默认禁用。这些参数属于可观察性配置组。

参数	默认	描述
--lookup-hash-log-dir	"" (禁用)	写入查找哈希 JSONL 文件的目录。空字符串将禁用日志记录。
--lookup-hash-log-rotation-interval	21600 (6 小时)	滚动到新日志文件前的时间间隔（秒）。
--lookup-hash-log-rotation-max-size	104857600 (100 MB)	即使时间间隔未到，触发滚动的最大文件大小（字节）。
--lookup-hash-log-max-files	100	保留的最大日志文件数量。当超过此限制时，最旧的文件将被删除。

HTTP 前端

源: lmcache/v1/multiprocess/config.py

HTTP 前端在运行 lmcache server 时包含在内。

参数	默认	描述
--http-host	0.0.0.0	绑定 HTTP (FastAPI/uvicorn) 服务器的主机。
--http-port	8080	绑定 HTTP 服务器的端口。

L1 内存管理器

来源: lmcache/v1/distributed/config.py

参数	默认	描述
--l1-size-gb	必需	L1 层的大小（以 GB 为单位）。默认情况下，设置固定 DRAM 的 L1 大小，或者在设置了 --gds-l1-path 时，设置 GDS 块文件（请参见下面的 GDS L1 层）。
--l1-use-lazy / --no-l1-use-lazy	True	启用或禁用 L1 内存的延迟分配。传递 --l1-use-lazy 以启用（默认），或传递 --no-l1-use-lazy 以显式禁用。延迟分配依赖于 cudart 主机固定内存，因此在非 CUDA 后端（lmcache.torch_dev 未暴露 cudart 属性）下，无论标志取值如何，都会自动降级为立即分配并记录警告。
--l1-init-size-gb	20	使用延迟分配时的初始分配大小（GB）。
--l1-align-bytes	4096	对齐大小（以字节为单位，默认 4 KB）。
--l1-devdax-path	(未设置)	Optional /dev/dax* device or mmap-able file to use as the L1 backing arena. When set, disable lazy allocation with --no-l1-use-lazy and disable SHM transfer advertising with --shm-name "" because the L1 bytes live in the DAX mapping. If a DAX L2 adapter with the same device_path is registered, that adapter's max_dax_size_gb is used as the L1 Device-DAX overflow size.

GDS L1 层

来源: lmcache/v1/distributed/config.py

可选功能。设置 --gds-l1-path 可将 L1 存储介质从固定 DRAM 切换为通过 GPUDirect Storage（cuFile DMA）访问的 NVMe slab 文件。此时 CPU 固定 DRAM 层将被禁用，--l1-size-gb 用于设置 slab 大小。启用此选项后，请禁用字节数组 L2 适配器（GDS 层不为其提供可注册的 L1 内存缓冲区）。

参数	默认	描述
--gds-l1-path	未设置	GDS L1 slab 的 NVMe 目录。设置此项将启用 GDS L1 层；每个进程共享一个位于 <path>/lmcache_gds_slab.bin 的 slab。
--gds-l1-use-direct-io / --no-gds-l1-use-direct-io	True	使用 O_DIRECT 打开 slab（在 ext4 上的 GDS DMA 快速路径所需）。

L1 管理器 TTLs

来源: lmcache/v1/distributed/config.py

参数	默认	描述
--l1-write-ttl-seconds	600	每个对象的写锁的生存时间（秒）。
--l1-read-ttl-seconds	300	每个对象的读取锁的生存时间（秒）。

逐出策略

来源: lmcache/v1/distributed/config.py

参数	默认	描述
--eviction-policy	必需	逐出策略。可选项：LRU、IsolatedLRU、noop。noop 用于纯缓冲区模式，此时 L1 仅作为写缓冲区（数据写入 L2 后即从 L1 删除）。IsolatedLRU 为每个 cache_salt 维护独立的 LRU 列表，并要求在运行时通过 /quota HTTP 端点为每个 cache_salt 配置配额（参见 Quota Management）；未注册配额的 cache_salt 的有效上限为 0 字节，其数据将在下一个逐出周期被清除（白名单语义）。
--eviction-trigger-watermark	0.8	触发逐出的内存使用比例 (0.0--1.0)。
--eviction-ratio	0.2	触发时逐出的已分配内存比例 (0.0--1.0)。

L2 策略

来源: lmcache/v1/distributed/config.py

参数	默认	描述
--l2-store-policy	default	L2 存储策略。决定每个键被写入哪些适配器，以及 L2 存储完成后是否从 L1 删除该键。default 策略将所有键写入全部适配器并保留 L1 中的数据。skip_l1 策略将所有键写入全部适配器后从 L1 删除（纯缓冲区模式）。可选项：default、skip_l1。
--l2-prefetch-policy	default	L2 预取策略。当多个适配器均持有某个键时，决定由哪个适配器加载该键。default 策略选择第一个适配器（索引最小）。预取的键是临时的（读取完成后删除）。retain 策略采用相同的加载计划，但将预取的键永久保留在 L1 中。可选项：default、retain。
--l2-prefetch-max-in-flight	8	最大并发预取（L2 加载）请求数量。限制 PrefetchController 同时发起的在途加载数，防止 L1 内存压力过大。
--periodic-notifier-interval-ms	5	定期事件通知器心跳的间隔（毫秒）。一个原生 C++ 后台线程按此间隔向所有已注册的文件描述符写入数据，以唤醒缺少原生异步完成回调的 L2 适配器的控制器轮询循环。

L2 适配器

源: lmcache/v1/distributed/l2_adapters/config.py

L2 适配器通过可重复的 --l2-adapter <JSON> 参数进行配置。每个 JSON 对象必须包含一个 "type" 字段，用于选择适配器类型。--l2-adapter 参数的顺序决定了适配器的顺序（级联）。

注册的适配器类型：nixl_store, nixl_store_dynamic, fs, fs_native, mock, mooncake_store, aerospike, s3, resp, plugin, native_plugin, raw_block, dax。

每种适配器类型的必填和可选字段及各后端示例，均记录在 Secondary KV Storage 下各自的页面中，包括此处未详细说明的适配器（fs_native、raw_block、dax、mooncake_store、hfbucket、resp）。

aerospike -- Aerospike 原生连接器

原生 C++ Aerospike L2 适配器（可选，需使用 BUILD_AEROSPIKE=1 构建）。构建前提条件和完整字段列表请参见 二级 KV 存储。

字段：

• hosts (必需): 种子主机 host:port[,host:port...]。

• namespace (可选，默认 ``"lmcache"``): Aerospike 命名空间。

• set_name / set (可选，默认 ``"kv_chunks"``): Aerospike 集。

• num_workers (可选，默认 ``8``): C++ I/O 工作线程。

• read_timeout_ms / write_timeout_ms (可选): 客户端超时。

• default_ttl_seconds (可选，默认 ``86400``): 记录的 TTL (0 = 命名空间默认)。

• target_segment_bytes / max_record_bytes (可选，默认 ``0``): 分片目标和记录容量覆盖 (0 = 自动发现)。

• username / password (可选): 企业版认证。

• max_capacity_gb (可选，默认 ``0``): 用于逐出跟踪的 L2 容量上限（0 表示禁用跟踪）。

示例：

--l2-adapter '{"type": "aerospike", "hosts": "127.0.0.1:3000", "namespace": "lmcache", "set_name": "kv_chunks", "num_workers": 8}'

多个适配器（级联）

多次传递 --l2-adapter。适配器按给定顺序使用：

--l2-adapter '{"type": "nixl_store", "backend": "POSIX", "backend_params": {"file_path": "/data/ssd/l2", "use_direct_io": "false"}, "pool_size": 64}' \
--l2-adapter '{"type": "nixl_store", "backend": "GDS", "backend_params": {"file_path": "/data/nvme/l2", "use_direct_io": "true"}, "pool_size": 128}'

可观察性

源: lmcache/v1/mp_observability/config.py

三种模式（指标、日志记录、链路追踪）的完整说明，请参见 可观察性。

参数	默认	描述
--disable-observability	关闭	总开关：完全禁用 EventBus。
--disable-metrics	关闭	跳过指标订阅者（不暴露 Prometheus 端点）。
--disable-logging	关闭	跳过日志订阅者。
--enable-tracing	关闭	注册链路追踪订阅者。需要 --otlp-endpoint。
--event-bus-queue-size	10000	事件总线队列中最大事件数，超过后将进行尾部丢弃。
--otlp-endpoint	(无)	用于导出指标和链路追踪数据的 OTLP gRPC 端点。
--prometheus-port	9090	Prometheus /metrics 端点的端口。

vLLM 客户端配置

在 vLLM 端，通过 kv_connector_extra_config 参数指定 LMCache 服务器的主机和端口：

vllm serve Qwen/Qwen3-14B \
    --kv-transfer-config \
    '{"kv_connector":"LMCacheMPConnector", "kv_role":"kv_both", "kv_connector_extra_config": {"lmcache.mp.host": "127.0.0.1", "lmcache.mp.port": 6000}}'

LMCacheMPConnector 从 kv_connector_extra_config 中读取以下键：

连接器 extra_config 键

所有连接器级别的选项都通过 kv_connector_extra_config 传递，并使用 lmcache.mp. 前缀。

键	默认	描述
lmcache.mp.host	tcp://localhost	LMCache MP 服务器的主机（带有 ZMQ 传输前缀）。
lmcache.mp.port	5555	LMCache MP 服务器的端口。必须与服务器的 --port 匹配。
lmcache.mp.mq_timeout	300.0	阻塞消息队列请求的超时时间（秒），包括初始块大小查询和 KV Cache 注册/注销。如果服务器在此时间窗口内未响应，连接器将在启动时引发 ConnectionError。
lmcache.mp.heartbeat_interval	10.0	连接器向服务器发送周期性心跳 PING 的时间间隔（秒）。
lmcache.mp.mp_transfer_mode	auto	工作进程 → 服务器传输上下文的路由模式。可选值：auto（CUDA 设备使用 engine_driven，其他设备使用 lmcache_driven）、engine_driven（强制使用 IPC / SHM 零拷贝）或 lmcache_driven（强制使用工作进程端 gather/scatter 拷贝）。若设置了此选项，将覆盖 LMCACHE_MP_TRANSFER_MODE 环境变量。

环境变量

变量	描述
LMCACHE_LOG_LEVEL	LMCache 的日志级别（DEBUG、INFO、WARNING、ERROR）。设置为 DEBUG 以查看 L2 存储活动、预取结果等。
PYTHONHASHSEED	设置为固定值以实现跨进程的可重复哈希（在使用 --hash-algorithm builtin 时相关）。

完整示例

lmcache server \
    --host 0.0.0.0 \
    --port 6555 \
    --chunk-size 512 \
    --max-workers 4 \
    --max-gpu-workers 2 \
    --hash-algorithm blake3 \
    --engine-type default \
    --lookup-hash-log-dir /data/lmcache/lookup_hashes \
    --lookup-hash-log-rotation-interval 21600 \
    --lookup-hash-log-rotation-max-size 104857600 \
    --lookup-hash-log-max-files 100 \
    --l1-size-gb 100 \
    --l1-use-lazy \
    --l1-init-size-gb 20 \
    --l1-align-bytes 4096 \
    --l1-write-ttl-seconds 600 \
    --l1-read-ttl-seconds 300 \
    --eviction-policy noop \
    --l2-store-policy skip_l1 \
    --eviction-trigger-watermark 0.9 \
    --eviction-ratio 0.1 \
    --l2-prefetch-policy default \
    --l2-prefetch-max-in-flight 8 \
    --periodic-notifier-interval-ms 5 \
    --l2-adapter '{"type": "nixl_store", "backend": "POSIX", "backend_params": {"file_path": "/data/lmcache/l2", "use_direct_io": "false"}, "pool_size": 64}' \
    --prometheus-port 9090 \
    --metrics-sample-rate 0.01 \
    --enable-tracing \
    --otlp-endpoint http://localhost:4317