Repository navigation
Configuration.zh
sikkatu edited this page Nov 2, 2026
·
7 revisions
三个文件，所有脚本都会读取。已导出到环境中的变量优先于文件（便于一次性覆盖）。
本机修改写入 configs/generic/cache.env.local（已在 .gitignore 中）——
不要修改随附的文件本身。
| 变量 | 默认值 | 含义 |
|---|---|---|
KVP_CACHE_BUDGET_GB |
1500 |
持久缓存的硬上限（GB，1.5 TB 刻意多留——容纳更多 prefill 历史）。实际边界为共享 VM 磁盘（同盘还有 Docker 与模型权重） 设备上的可用空间。 |
KVP_CACHE_ROOT |
/var/lib/kv-persistence/l2 |
缓存目录。必须位于本地 NVMe；网络挂载会破坏原子重命名（预检会警告）。 |
KVP_EVICT_TRIGGER_WATERMARK |
0.9 |
软阈值：达到预算的该比例时开始淘汰。与硬上限分开。 |
KVP_EVICT_RATIO |
0.1 |
每个淘汰周期回收的量（已用容量的比例）。 |
KVP_LMCACHE_HOST |
127.0.0.1 |
lmcache 请求主机（ZMQ）。保持回环。 |
KVP_LMCACHE_PORT |
5555 |
lmcache 请求端口。 |
KVP_LMCACHE_HTTP_PORT |
8080 |
HTTP 管理/指标前端。设计上仅限回环。 |
KVP_L1_SIZE_GB |
64 |
vLLM 与 NVMe 之间的主机内存 L1 缓冲。 |
KVP_CHUNK_SIZE |
256 |
KV 块粒度（token 数，生产环境文档化默认值）。 |
KVP_PERSIST_ENABLED |
true |
退出时保留数据文件。设为 false 会删除文件 —— 破坏核心需求。 |
KVP_CACHE_BYPASS |
0 |
1 = 禁用持久缓存（A/B 对比用）。 |
KVP_NAMESPACE_HINT |
（空） | 仅人类可读标签；不影响兼容性。 |
每个值都参与缓存命名空间计算。任何更改都会使旧条目失配（缓存未命中 —— 绝不会产生错误数据）。空值 = 错误。
| 变量 | 值形式 | 说明 |
|---|---|---|
KVP_MODEL_ID |
HF id | 如 XiaomiMiMo/MiMo-V2.6-Pro-MOPD
|
KVP_MODEL_REVISION |
完整 40 位十六进制 SHA | 固定的权重提交 |
KVP_TOKENIZER_NAME |
名称/路径 | 通常同一仓库 |
KVP_TOKENIZER_REVISION |
完整 40 位十六进制 SHA | 除非刻意分离，与权重一致 |
KVP_KV_CACHE_DTYPE |
已解析类型 |
引擎的 KV 缓存类型，写法与 vLLM CacheDType 一致：float16 / bfloat16 / fp8*；拒绝 auto。别名 fp16/bf16 不被固定版本（vllm 8e2beaa3）接受 —— 引擎拒绝以此启动（预检会警告）。这是 vLLM 计算的 KV 格式 —— 不是 L2 存储编解码（见下方 LMCACHE_L2_SERDE）。此处的 fp8 是合法的引擎类型，与有损 L2 压缩无关。 |
KVP_BLOCK_SIZE |
整数 | KV 块大小（token 数，取自引擎日志） |
KVP_NUM_KV_HEADS |
整数 | 取自模型配置 |
KVP_HEAD_DIM |
整数 | 取自模型配置 |
KVP_TP_SIZE |
整数 | 本部署为 4 |
KVP_CONNECTOR |
名称 | LMCacheMPConnector |
KVP_CONNECTOR_VERSION |
固定串 | 如 vllm-<commit>@lmcache-mp
|
KVP_MAX_MODEL_LEN |
整数 | 1048576 |
KVP_CHAT_TEMPLATE_DIGEST |
64 位十六进制 | 由预检从模型目录计算 |
KVP_LORA_ADAPTERS |
（可选） | 逗号分隔的 <adapter-id>@<revision> —— 服务时实际挂载的 LoRA。空 = 无 LoRA。设定后改变命名空间 —— 使用不同 LoRA 的部署不得共享缓存 KV。 |
KVP_MULTIMODAL_COMPONENTS |
（可选） | 逗号分隔的 <component-id>@<revision> —— 实际提供的多模态组件（视觉/音频编码器）。空 = 无。设定后改变命名空间。
|
KVP_ROPE_CONFIG_DIGEST |
（可选，64 位十六进制） | 实际生效的 RoPE 配置（scaling/theta/sections）的 sha256。空 = 未改/默认。设定后改变命名空间 —— RoPE 变更会改变 token 位置，旧 KV 不得复用。 |
KVP_SPECULATIVE_CONFIG |
（可选） | 实际启用的 speculative/MTP/draft 设置的稳定标签（例如 mtp-draft@rev, num_speculative_tokens=2）。空 = 未启用。设定后改变命名空间。
|
这四个扩展字段均由 kvpersist.identity 读取并纳入缓存命名空间与 model_name。
留空合法（“不适用”）；设定其中任意一个即拆分命名空间（安全的缓存未命中）。
| 变量 | 默认值 | 含义 |
|---|---|---|
LMCACHE_HOST / LMCACHE_PORT
|
127.0.0.1 / 5555
|
vLLM 连接的 ZMQ 请求端点 |
LMCACHE_HTTP_HOST / LMCACHE_HTTP_PORT
|
127.0.0.1 / 8080
|
管理前端 —— 保持回环 |
LMCACHE_L1_SIZE_GB |
64 |
L1 内存层 |
LMCACHE_CHUNK_SIZE |
256 |
块粒度（token 数） |
LMCACHE_EVICTION_POLICY |
LRU |
两层共用 |
LMCACHE_EVICTION_TRIGGER_WATERMARK |
0.9 |
L2 软阈值 |
LMCACHE_EVICTION_RATIO |
0.1 |
每周期回收量 |
LMCACHE_L2_SERDE |
none |
L2 编解码，仅无损：none = 逐字节精确的原始 KV；zstd / lz4 = 无损压缩（估算 1.1–1.4x）。有损编解码（fp8 / turboquant / lbq）在启动时被拒绝。编解码属于缓存身份命名空间的一部分。 |
LMCACHE_LOG_LEVEL |
DEBUG |
缓存服务日志级别。硬件验收（scripts/test-recovery.sh）需要 DEBUG：在固定的 LMCache 0.5.3 中，L2 store/load 证据日志行（L2 store completed: adapter N, N succeeded、L2 prefetch load completed: request N, N loaded、Prefetch request completed (L1+L2)）只在 DEBUG 级别输出——否则验收正则找不到匹配，运行结果只能是 INCONCLUSIVE。不跑验收时可用 INFO 减小日志。 |
KVP_L2_COMPRESS_LEVEL |
3 |
zstd 级别（1–19，lz4 忽略此值） |
USE_LOSSLESS_SERDE |
（未设置） | 操作开关：1/zstd = zstd，lz4 = lz4，0/空 = 保持 LMCACHE_L2_SERDE。仅在 LMCACHE_L2_SERDE 未导出时生效（env 优先）。 |
KVP_OTLP_ENDPOINT |
（未设置） | 缓存推送指标的 OTLP gRPC 端点（如 http://localhost:4320）。遥测默认关闭。 |
USE_OBSERVABILITY |
（未设置） |
1 = KVP_OTLP_ENDPOINT=http://localhost:4320 的简写 |
LMCACHE_OTLP_ENDPOINT |
（未设置） | 同一端点的 LMCACHE_* 名称；优先于 KVP_OTLP_ENDPOINT
|
编解码依赖（启动前 fail-fast，仅要求所选的那个）：
none — 无；zstd — 仅 zstandard；lz4 — 仅 lz4。
- 在
cache.env.local中修改KVP_CACHE_BUDGET_GB。 -
bash scripts/stop-cache.sh && bash scripts/start-cache.sh—— 数据保留。 -
bash scripts/budget-report.sh status确认新预算生效。
提高上限需先确认磁盘空间。降低到当前用量以下会立即拒绝新写入； 淘汰机制随后清理至目标水位。
bash scripts/budget-report.sh quota --set-namespace=NAME --gb 200
bash scripts/budget-report.sh quota # 列表命名空间名称来自 budget-report.sh status（namespaces 字段）；请使用
--namespace=NAME 形式，因为真实名称通常以 - 开头。
配额做什么、不做什么。 配额是一个策略与核算层：它们记录按命名空间的
限制，并让报告显示哪个命名空间超出限制。它们未接入生产写入路径 ——
BudgetLedger.admit() 的判定不会被 LMCache 适配器调用，因此命名空间可以超过
配额而没有任何东西拒绝该写入。唯一在写入时强制执行的硬容量边界是适配器的
max_capacity_gb（KVP_CACHE_BUDGET_GB）对整个 L2 的限制。在集成测试证明
强制执行之前，把配额视为规划/核算工具。
导出的变量始终优先于文件。一次性修改示例：
KVP_CACHE_BUDGET_GB=500 bash scripts/start-cache.sh终端的 export 不持久 —— 新终端中需重复执行（shell 的正常行为，不是 bug）。