配置参考

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

MP 服务器

源: lmcache/v1/multiprocess/config.py

参数	默认	描述
--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 亲和力池（存储/检索）的工作线程。来自同一 vLLM 实例的请求始终分配到同一线程，从而消除 GPU 传输锁争用。
--max-cpu-workers	(继承 --max-workers)	正常 CPU 池（查找等）的工作线程。
--hash-algorithm	blake3	基于令牌的操作的哈希算法。可选项：builtin、sha256_cbor、blake3。
--engine-type	default	缓存引擎后端类型。default 使用 MPCacheEngine；blend 使用 BlendEngineV2 进行跨请求的 KV 重用。可选项：default，blend。
--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\"}'。

查找哈希日志记录

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

启用时，服务器将在 EventBus 上发布在 lookup() 期间计算的块哈希作为 MP_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 为单位）。
--l1-use-lazy / --no-l1-use-lazy	True	Enable or disable lazy allocation for L1 memory. Pass --l1-use-lazy to enable (default) or --no-l1-use-lazy to explicitly disable. Lazy allocation relies on cudart host-pinned memory, so on non-CUDA backends (where lmcache.torch_dev exposes no cudart attribute) it is automatically downgraded to eager allocation with a logged warning, regardless of the flag value.
--l1-init-size-gb	20	使用延迟分配时的初始分配大小（GB）。
--l1-align-bytes	4096	对齐大小（以字节为单位，默认 4 KB）。

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 — 每个``cache_salt``的配额管理）；没有注册配额的 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 内存压力。

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、s3、resp、plugin、native_plugin、raw_block、dax。

nixl_store -- 基于 NIXL 的持久存储

字段：

• backend (必需): 选项包括 POSIX, GDS, GDS_MT, HF3FS, OBJ, AZURE_BLOB。

• backend_params (文件基础后端必需)：字符串键值对的字典。文件基础后端（GDS, GDS_MT, POSIX, HF3FS）需要 file_path 和 use_direct_io。

• pool_size (必需): 预分配的存储描述符数量 (> 0)。

示例：

# POSIX backend (local file system)
--l2-adapter '{"type": "nixl_store", "backend": "POSIX", "backend_params": {"file_path": "/data/lmcache/l2", "use_direct_io": "false"}, "pool_size": 64}'

# GDS backend (GPU Direct Storage)
--l2-adapter '{"type": "nixl_store", "backend": "GDS", "backend_params": {"file_path": "/data/nvme/lmcache", "use_direct_io": "true"}, "pool_size": 128}'

# GDS_MT backend (multi-threaded GDS)
--l2-adapter '{"type": "nixl_store", "backend": "GDS_MT", "backend_params": {"file_path": "/data/nvme/lmcache", "use_direct_io": "true"}, "pool_size": 128}'

# HF3FS backend (shared file system)
--l2-adapter '{"type": "nixl_store", "backend": "HF3FS", "backend_params": {"file_path": "/mnt/hf3fs/lmcache", "use_direct_io": "false"}, "pool_size": 64}'

# OBJ backend (object store -- no file_path needed)
--l2-adapter '{"type": "nixl_store", "backend": "OBJ", "backend_params": {}, "pool_size": 32}'

# AZURE_BLOB backend
--l2-adapter '{"type": "nixl_store", "backend": "AZURE_BLOB", "backend_params": {"account_url": "https://<account_name>.blob.core.windows.net", "container_name": "<container_name>"}, "pool_size": 32}'

fs -- 文件系统支持的存储

一个使用异步 I/O 的纯文件系统 L2 适配器。

字段：

• base_path (必需): 存储 KV Cache 文件的目录。

• relative_tmp_dir (可选): 临时文件的相对子目录。

• read_ahead_size (可选): 通过首先读取这么多字节来触发预读。

• use_odirect (可选)：通过 O_DIRECT 跳过页面缓存（默认 false）。

示例：

# Basic FS adapter
--l2-adapter '{"type": "fs", "base_path": "/data/lmcache/l2"}'

# With temp directory
--l2-adapter '{"type": "fs", "base_path": "/data/lmcache/l2", "relative_tmp_dir": ".tmp"}'

mock -- 测试用的模拟适配器

字段：

• max_size_gb (必需)：适配器的最大大小（以 GB 为单位，> 0）。

• mock_bandwidth_gb (必需): 模拟带宽，单位为 GB/秒 (> 0)。

示例：

--l2-adapter '{"type": "mock", "max_size_gb": 256, "mock_bandwidth_gb": 10}'

s3 -- 兼容 S3 的对象存储

使用 AWS CRT（通用运行时）的 S3 后端 L2 适配器，以实现高吞吐量传输到 AWS S3 或任何 S3 兼容的端点。有关详细信息，请参见 L2 存储（持久缓存）。

字段：

• s3_endpoint (必需): 存储桶 URL，可以是 "s3://<bucket>" 或裸主机形式。

• s3_region (必需): AWS 区域字符串。

• s3_num_io_threads (可选，默认 ``64``): CRT I/O 线程。

• s3_prefer_http2 (可选，默认 ``true``): 通过 ALPN 协商 HTTP/2。

• s3_enable_s3express (可选，默认 ``false``): 启用 S3 Express 签名。

• disable_tls (可选，默认 ``false``): 跳过 TLS（用于非 AWS HTTP 端点）。

• aws_access_key_id / aws_secret_access_key (可选): 静态凭证；省略以使用默认凭证提供程序链。

• max_capacity_gb (可选，默认 ``0.0``): get_usage() 使用的总容量。值为 0 将禁用总的逐出。

示例：

--l2-adapter '{"type": "s3", "s3_endpoint": "s3://my-bucket", "s3_region": "us-west-2"}'

多个适配器（级联）

多次传递 --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 端点的端口。
--service-instance-id	(未设置，默认 UUID v4)	此 MP 服务器实例的标识符，作为 OTel 资源属性 service.instance.id 附加在每个指标和跨度上。当未传递该标志时，默认为随机 UUID v4。传递 --service-instance-id=\"\" 以强制设置为空值。

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 reads the following keys from kv_connector_extra_config:

Key	默认	描述
lmcache.mp.host	tcp://localhost	Host (with ZMQ transport prefix) of the LMCache MP server.
lmcache.mp.port	5555	Port of the LMCache MP server. Must match the server's --port.
lmcache.mp.mq_timeout	300.0	Timeout (seconds) for blocking message-queue requests, including the initial chunk-size query and KV cache registration/unregistration. If the server does not respond within this window, the connector raises ConnectionError on startup.
lmcache.mp.heartbeat_interval	10.0	Interval (seconds) between periodic heartbeat pings sent from the connector to the server.

环境变量

变量	描述
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 \
    --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