配置 LMCache#

LMCache 支持两种类型的配置：

配置文件：一个包含配置项的 YAML（推荐）或 JSON 文件。
环境变量：以 LMCACHE_ 开头的环境变量。

要使用配置文件，您可以将 LMCACHE_CONFIG_FILE 环境变量设置为配置文件的路径。

备注

如果配置文件存在，则环境变量配置将被忽略。

通用配置#

控制 LMCache 核心功能的基本缓存设置。

YAML 配置名称	环境变量	描述
chunk_size	LMCACHE_CHUNK_SIZE	缓存块的大小。默认值：256
local_cpu	LMCACHE_LOCAL_CPU	是否启用 CPU 缓存。值：true/false。默认：true
max_local_cpu_size	LMCACHE_MAX_LOCAL_CPU_SIZE	最大 CPU 缓存大小（以 GB 为单位）。默认值：5.0
local_cpu_use_hugepages	LMCACHE_LOCAL_CPU_USE_HUGEPAGES	Whether to use Linux hugepages (2 MB) for CPU-pinned KV cache memory. Not compatible with P2P mode or shared memory (multiprocess). Requires pre-allocated hugepages (`sysctl vm.nr_hugepages`). Values: true/false. Default: false
local_disk	LMCACHE_LOCAL_DISK	本地磁盘缓存目录的路径（或以逗号分隔的路径）。格式：`"file:///path/to/cache"` 或 `"/path/a,/path/b"` 用于多设备 I/O。有关路径如何分配给 GPU，请参见 `local_disk_path_sharding`。
local_disk_path_sharding	LMCACHE_LOCAL_DISK_PATH_SHARDING	当提供多个路径时选择路径的策略。目前仅支持 `"by_gpu"`，该策略根据 GPU 设备 ID 选择路径（默认值："by_gpu"）。
max_local_disk_size	LMCACHE_MAX_LOCAL_DISK_SIZE	最大磁盘缓存大小（以 GB 为单位）。默认值：0.0
remote_url	LMCACHE_REMOTE_URL	远程存储 URL。格式："protocol://host:port"。
remote_serde	LMCACHE_REMOTE_SERDE	序列化格式。值："naive" 或 "cachegen"。默认值："naive"
save_decode_cache	LMCACHE_SAVE_DECODE_CACHE	是否存储解码 KV Cache。值：true/false。默认：false
use_layerwise	LMCACHE_USE_LAYERWISE	是否启用逐层流水线。值：true/false。默认值：false
pre_caching_hash_algorithm	LMCACHE_PRE_CACHING_HASH_ALGORITHM	前缀缓存的哈希算法。默认值：“builtin”
save_unfull_chunk	LMCACHE_SAVE_UNFULL_CHUNK	是否保存未满块。值：true/false。默认值：false
blocking_timeout_secs	LMCACHE_BLOCKING_TIMEOUT_SECS	阻塞操作的超时时间（以秒为单位）。默认值：10
py_enable_gc	LMCACHE_PY_ENABLE_GC	是否启用 Python 垃圾回收。值：true/false。默认：true
cache_policy	LMCACHE_CACHE_POLICY	缓存逐出策略（例如“LRU”、“LFU”、“FIFO”）。默认值：“LRU”
numa_mode	LMCACHE_NUMA_MODE	NUMA 感知内存分配模式。值："auto"（从系统检测）、"manual"（使用 extra_config 映射）、null（禁用）。启用时，在特定的 NUMA 节点上分配固定内存，以提高 GPU-CPU 内存带宽。默认值：null
external_lookup_client	LMCACHE_EXTERNAL_LOOKUP_CLIENT	外部 KV 查找服务 URI（例如，"mooncakestore://address"）。如果为 null，则默认为 LMCache 的内部查找客户端。默认值：null
priority_limit	LMCACHE_PRIORITY_LIMIT	仅在优先级值 ≤ 限制时缓存请求。（不适用于 PD 分离）类型：int。默认值：无
min_retrieve_tokens	LMCACHE_MIN_RETRIEVE_TOKENS	执行检索所需的最小命中令牌数。如果命中令牌少于此值，则跳过检索，但仍记录命中以避免重新存储现有块。有关工作示例，请参见性能调优。默认值：0（禁用）
store_location	LMCACHE_STORE_LOCATION	一个存储后端名称，用于存储 KV 缓存。当指定时，只有匹配的后端接收存储操作。有效值是存储管理器中注册的后端类名称，包括：`\"LocalCPUBackend\"`、`\"LocalDiskBackend\"`、`\"RemoteBackend\"`、`\"PDBackend\"`、`\"P2PBackend\"`、`\"GdsBackend\"` 等，以及任何存储插件后端。注意：`\"PDBackend\"` 不能用作 PD 设置中解码器实例的存储位置，因为 PDBackend 仅从预填充器到解码器是单向的。默认值：null（存储到所有活动后端）
retrieve_locations	LMCACHE_RETRIEVE_LOCATIONS	检索或查找 KV Cache 时要搜索的存储后端名称列表。当指定时，仅搜索列出的后端。有效值为在存储管理器中注册的后端类名称，包括：`\"LocalCPUBackend\"`、`\"LocalDiskBackend\"`、`\"RemoteBackend\"`、`\"PDBackend\"`、`\"P2PBackend\"`、`\"GdsBackend\"` 等，以及任何存储插件后端。默认值：null（搜索所有活动后端）
extra_config	LMCACHE_EXTRA_CONFIG={"key": value, ...}	额外的配置作为 JSON 字典。对于 NUMA 手动模式，包含 "gpu_to_numa_mapping": {gpu_id: numa_node, ...}。默认值：{}

惰性内存分配器配置#

用于懒惰内存分配器的设置，允许逐步分配内存以减少启动时间和初始内存占用。

备注

懒惰内存分配器旨在处理大 CPU 内存配置的场景。它从小的初始分配开始，并根据需要逐渐扩展，从而减少启动等待时间，并避免在不需要全部容量时的不必要内存消耗。

关键特性：

一次性扩展：内存扩展直到达到目标大小，然后停止
不收缩：一旦分配，内存将永远不会释放回系统
自动激活：仅在 max_local_cpu_size 超过 lazy_memory_safe_size 时激活

YAML 配置名称	环境变量	描述
enable_lazy_memory_allocator	LMCACHE_ENABLE_LAZY_MEMORY_ALLOCATOR	是否启用延迟内存分配器。值：true/false。默认值：false
lazy_memory_initial_ratio	LMCACHE_LAZY_MEMORY_INITIAL_RATIO	初始内存分配比例 (0.0-1.0)。决定在启动时分配的 max_local_cpu_size 的比例。默认值：0.2 (20%)
lazy_memory_expand_trigger_ratio	LMCACHE_LAZY_MEMORY_EXPAND_TRIGGER_RATIO	触发扩展的内存使用比例（0.0-1.0）。当使用的内存超过当前容量的此比例时，扩展开始。默认值：0.5（50%）
lazy_memory_step_ratio	LMCACHE_LAZY_MEMORY_STEP_RATIO	内存扩展步骤比例（0.0-1.0）。每次扩展增加此比例的 max_local_cpu_size。默认值：0.1（10%）
lazy_memory_safe_size	LMCACHE_LAZY_MEMORY_SAFE_SIZE	在 GB 中的阈值，超过该值后懒惰分配器激活。如果 max_local_cpu_size ≤ 此值，则无论 enable_lazy_memory_allocator 设置如何，懒惰分配器都将被禁用。默认值：0.0
reserve_local_cpu_size	LMCACHE_RESERVE_LOCAL_CPU_SIZE	保留的系统内存（以 GB 为单位），不应由 LMCache 分配。用于防止内存不足的情况。默认值：0.0

缓存混合配置#

与缓存混合功能相关的设置。

备注

我们有一个端到端的示例。我们还有更多的详细文档。

YAML 配置名称	环境变量	描述
enable_blending	LMCACHE_ENABLE_BLENDING	是否启用混合。值：true/false。默认值：false
blend_recompute_ratios	LMCACHE_BLEND_RECOMPUTE_RATIOS	混合重计算的比例。默认值：0.15
blend_check_layers	LMCACHE_BLEND_CHECK_LAYERS	确定重计算令牌的层数。默认值：1
blend_special_str	LMCACHE_BLEND_SPECIAL_STR	用于混合的分隔符字符串。默认值：" # # "

点对点共享配置#

用于启用和配置点对点 CPU KV Cache 共享及全局 KV Cache 查找的设置。

YAML 配置名称	环境变量	描述
enable_p2p	LMCACHE_ENABLE_P2P	是否启用点对点共享。值：true/false。默认：false
p2p_host	LMCACHE_P2P_HOST	IP 地址。如果 enable_p2p 为 true，则必需。
peer_init_ports	LMCACHE_PEER_INIT_PORTS	p2p 对等初始化的端口。如果 enable_p2p 为 true，则需要此项。
peer_lookup_ports	LMCACHE_PEER_lookup_PORTS	用于点对点（p2p）对等查找的端口。如果 enable_p2p 为 true，则必需。
transfer_channel	LMCACHE_TRANSFER_CHANNEL	例如 nixl。如果 enable_p2p 为 true，则必需。

控制器配置#

KV 缓存控制器功能的设置。

YAML 配置名称	环境变量	描述
enable_controller	LMCACHE_ENABLE_CONTROLLER	是否启用控制器。值：true/false。默认：false
lmcache_instance_id	LMCACHE_LMCACHE_INSTANCE_ID	LMCache 实例的 ID。默认值："lmcache_default_instance"
controller_url	LMCACHE_CONTROLLER_URL	控制器服务器的 URL
lmcache_worker_port	LMCACHE_LMCACHE_WORKER_PORT	LMCache 工作进程的端口号

分离式 Prefill 配置#

分离式 Prefill 功能的设置。最新/默认的 PD 实现在 lmcache/v1/storage_backend/pd_backend.py 中。

备注

启用 PD 时，以下限制适用（欢迎贡献以消除这些限制）：

remote_url 必须为 null
save_decode_cache 必须为 false
enable_p2p 必须为 false

YAML 配置名称	环境变量	描述
enable_pd	LMCACHE_ENABLE_PD	是否启用 PD。值：true/false。默认值：false
transfer_channel	LMCACHE_TRANSFER_CHANNEL	用于 PD 的传输通道。值：“nixl”。默认：无
pd_role	LMCACHE_PD_ROLE	PD 角色。值："sender"（预填充器）或 "receiver"（解码器）。
pd_buffer_size	LMCACHE_PD_BUFFER_SIZE	PD 传输缓冲区大小的上限（以字节为单位），与块大小对齐。当 enable_pd=true 时，发送方和接收方均需要此设置。
pd_buffer_device	LMCACHE_PD_BUFFER_DEVICE	PD 缓冲区的设备。值："cpu"，"cuda"。当 enable_pd=true 时，发送者和接收者都需要此项。
nixl_backends	LMCACHE_NIXL_BACKENDS	Nixl 传输后端列表。适用于非分离式用例（见下文）。UCX 默认设置足以满足分离式用例。默认值：["UCX"]
pd_peer_host	LMCACHE_PD_PEER_HOST	对等连接的主机。接收方绑定所需。
pd_peer_init_port	LMCACHE_PD_PEER_INIT_PORT	用于对等连接的初始化端口。接收方需要绑定到此端口。
pd_peer_alloc_port	LMCACHE_PD_PEER_ALLOC_PORT	用于对等连接的分配端口。接收方需要绑定到此端口。
pd_proxy_host	LMCACHE_PD_PROXY_HOST	代理服务器的主机。发送方连接以通知代理解码器传输完成时必需。
pd_proxy_port	LMCACHE_PD_PROXY_PORT	代理服务器的端口。发送方需要连接以通知代理传输到解码器已完成。
pd_allocation_timeout_sec	LMCACHE_PD_ALLOCATION_TIMEOUT_SEC	在放弃之前重试内存分配的最大秒数。默认值：5.0
pd_shutdown_timeout_sec	LMCACHE_PD_SHUTDOWN_TIMEOUT_SEC	事件循环关闭和线程加入的最大等待秒数。默认值：5.0
pd_condition_poll_interval_sec	LMCACHE_PD_CONDITION_POLL_INTERVAL_SEC	在等待线程/asyncio Condition 时的轮询间隔（以秒为单位）。足够小以保持响应，足够大以避免浪费 CPU。默认值：0.05
pd_max_prefill_len	LMCACHE_PD_MAX_PREFILL_LEN	PD 缓冲区必须能够容纳的最大 Prefill 令牌长度。如果大于 0，当缓冲区容量（以令牌为单位）小于此值时，初始化将引发 ValueError。设置为 0（默认值）以跳过检查。
pd_backend_mode	LMCACHE_PD_BACKEND_MODE	选择 PD 后端实现：'async'（默认）使用基于 asyncio 的实现；'sync' 使用原始的基于线程的同步实现。默认值："async"
pd_skip_proxy_notification	LMCACHE_PD_SKIP_PROXY_NOTIFICATION	当为真时，发送方在 KV 传输后跳过 ZMQ 代理通知，并且不需要 pd_proxy_host/pd_proxy_port。此选项仅适用于管理通过 HTTP 的分离式解码请求流的外部调度器（例如，vLLM 生产堆栈路由器），并且不依赖于 ZMQ 通知。它不得与 LMCache 的内置分离代理（`disagg_proxy_server.py`）一起使用，因为该代理依赖于 ZMQ 通知来知道 KV 传输何时完成，然后再转发解码请求。值：true/false。默认值：false
pd_bidirectional	LMCACHE_PD_BIDIRECTIONAL	当为真时，启用双向 NIXL 缓存探测。Prefiller 在传输之前查询解码器以获取缓存的 KV 块，并通过 NIXL RDMA 读取缓存的块，而不是重计算。值：true/false。默认值：false
pd_peer_query_port	LMCACHE_PD_PEER_QUERY_PORT	用于双向缓存查询通道的 ZMQ 端口（每个 TP 排名一个）。当 pd_bidirectional=true 时，预填充器和解码器都需要此配置。示例：[7500, 7501, 7502, 7503]

P2P 后端配置#

P2P（点对点）后端超时行为的设置。这些配置通过 extra_config 指定。

extra_config:
  p2p_socket_recv_timeout_ms: 30000
  p2p_socket_send_timeout_ms: 10000

配置键	默认	描述
p2p_socket_recv_timeout_ms	30000	套接字接收操作的超时时间（以毫秒为单位）
p2p_socket_send_timeout_ms	10000	套接字发送操作的超时时间（以毫秒为单位）

Nixl（作为存储后端）配置#

将 Nixl 用作存储后端而不是分离式 Prefill 的设置。此模式需要在 extra_config 中进行额外配置。

备注

这是一种不同于分离式 Prefill 的模式。当使用 Nixl 作为存储后端时，您需要通过 extra_config 进行配置。

extra_config:
  # enable_nixl_storage will disable disaggregated prefill mode.
  enable_nixl_storage: true
  nixl_backend: "POSIX"  # Options: "GDS", "GDS_MT", "POSIX", "HF3FS", "OBJ"
  nixl_path: "/path/to/storage/"
  nixl_pool_size: 64

配置键	描述
enable_nixl_storage	是否启用 Nixl 存储后端。值：true/false
nixl_backend	存储后端类型。选项：“GDS”、“GDS_MT”、“POSIX”、“HF3FS”、“OBJ”
nixl_path	Nixl 存储的文件系统路径
nixl_pool_size	存储池中的文件或对象数量
nixl_endpoint_list	每个工作节点的对象存储端点 URL 列表。每个 TP 工作节点通过 `local_worker_id` 轮询选择一个条目，覆盖 `nixl_backend_params.endpoint_override`。仅在 `nixl_backend` 为 `"OBJ"` 时应用（否则静默忽略）。每个条目必须以 `http://` 或 `https://` 开头；空列表在引擎初始化时会引发 `ValueError`。
nixl_use_hugepages	Whether to use Linux hugepages (2 MiB) for the NIXL CPU buffer. Requires pre-allocated hugepages (`sysctl vm.nr_hugepages`). Values: true/false. Default: false

附加存储配置#

不同存储后端和路径的设置。

YAML 配置名称	环境变量	描述
gds_path	LMCACHE_GDS_PATH	GDS 后端的路径。支持以逗号分隔的多设备 I/O 路径（例如 `/mnt/nvme0/cache,/mnt/nvme1/cache`）。有关路径如何分配给 GPU，请参见 `gds_path_sharding`。
gds_path_sharding	LMCACHE_GDS_PATH_SHARDING	当提供多个路径时选择路径的策略。目前仅支持 `"by_gpu"`，该策略根据 GPU 设备 ID 选择路径（默认值："by_gpu"）。
gds_buffer_size	LMCACHE_GDS_BUFFER_SIZE	GDS 操作的缓冲区大小
use_gds	LMCACHE_USE_GDS	启用或禁用 GPU 直接存储 API 的使用（默认：true）
gds_backend	LMCACHE_GDS_BACKEND	使用的 GDS 库后端（默认："cufile"）

自定义 Prometheus 直方图桶#

您可以通过向 extra_config 添加一个键 histogram_bucket_<name> 来覆盖任何 Prometheus 直方图度量的默认桶边界，其中 <name> 是度量名称不带 lmcache: 前缀。

值必须是一个数字边界的列表（浮点数或整数）。

extra_config:
  histogram_bucket_time_to_retrieve: [0.01, 0.05, 0.1, 0.5, 1.0, 5.0]
  histogram_bucket_retrieve_speed: [100, 500, 1000, 5000, 10000]

可用直方图名称	描述
`time_to_retrieve`	从缓存中检索所需时间（秒）
`time_to_store`	缓存存储时间（秒）
`time_to_lookup`	缓存查找时间（秒）
`retrieve_process_tokens_time`	在检索中处理令牌的时间（秒）
`retrieve_broadcast_time`	在检索中广播内存对象的时间（秒）
`retrieve_to_gpu_time`	在检索中将数据移动到 GPU 的时间（秒）
`remote_backend_batched_get_blocking_time`	从远程后端获取数据的时间（秒）
`instrumented_connector_batched_get_time`	连接器使用的时间（秒）
`store_process_tokens_time`	存储中处理令牌的时间（秒）
`store_from_gpu_time`	从 GPU 移动数据到存储的时间（秒）
`store_put_time`	将数据存储到存储中的时间（秒）
`retrieve_speed`	检索速度（每秒令牌数）
`store_speed`	存储速度（每秒令牌数）
`p2p_time_to_transfer`	通过 P2P 传输的时间（秒）
`p2p_transfer_speed`	P2P 传输速度（每秒令牌数）
`remote_time_to_get`	从远程后端获取的时间（毫秒）
`remote_time_to_put`	远程后端的放置时间（毫秒）
`remote_time_to_get_sync`	从远程后端同步获取的时间（毫秒）
`request_cache_hit_rate`	请求缓存命中率 (0.0 到 1.0)
`request_cache_lifespan`	请求缓存生命周期（分钟）

内部 API 服务器配置#

用于内部 API 服务器的设置，该服务器为 LMCache 引擎提供管理和调试 API。API 服务器在每个工作节点和调度器上运行，允许您在运行时检查和控制 LMCache 的行为。

备注

内部 API 服务器提供以下端点：

指标：性能和缓存统计信息
配置: 运行时配置检查
元数据：引擎和模型元数据
线程：线程调试信息
日志级别：动态日志级别调整
脚本执行：运行自定义 Python 脚本，访问 LMCache 引擎

配置选项#

YAML 配置名称	环境变量	描述
internal_api_server_enabled	LMCACHE_INTERNAL_API_SERVER_ENABLED	是否启用内部 API 服务器。默认值：false
internal_api_server_host	LMCACHE_INTERNAL_API_SERVER_HOST	用于绑定内部 API 服务器的主机。默认值：“0.0.0.0”
internal_api_server_port_start	LMCACHE_INTERNAL_API_SERVER_PORT_START	内部 API 服务器的起始端口。端口分配：调度器 = port_start + 0，工作者 i = port_start + i + 1。示例：如果 port_start=6999，则调度器=6999，工作者 0=7000，工作者 1=7001，等等。默认值：6999
internal_api_server_include_index_list	LMCACHE_INTERNAL_API_SERVER_INCLUDE_INDEX_LIST	启用 API 服务器的工作者/调度器索引列表。使用 0 表示调度器，1 表示工作者 0，2 表示工作者 1，依此类推。如果为 null，则在所有工作者/调度器上启用。示例：[0, 1] 仅在调度器和工作者 0 上启用。默认值：null
internal_api_server_socket_path_prefix	LMCACHE_INTERNAL_API_SERVER_SOCKET_PATH_PREFIX	如果指定，则使用 Unix 域套接字而不是 TCP 端口。套接字路径将为 "{prefix}_{port}"。示例："/tmp/lmcache_api_socket" 创建 "/tmp/lmcache_api_socket_6999"、"/tmp/lmcache_api_socket_7000" 等。默认值：null

插件配置#

插件系统的设置。

YAML 配置名称	环境变量	描述
plugin_locations	LMCACHE_PLUGIN_LOCATIONS	插件位置列表。默认值：[]

已弃用的配置#

这些配置已被弃用，可能会在未来的版本中被移除。

YAML 配置名称	环境变量	描述
audit_actual_remote_url	LMCACHE_AUDIT_ACTUAL_REMOTE_URL	(已弃用) 用于审计的实际远程 LMCache 实例的 URL。请改用 extra_config['audit_actual_remote_url']。