Repository navigation
Troubleshooting.zh
先检查三样东西：
bash scripts/budget-report.sh status # 占用、命名空间、磁盘空闲
tail -n 100 "$KVP_CACHE_ROOT/lmcache-server.log" # 缓存服务
docker logs --tail 100 mimo-pro-tp4-kvp # 引擎（kv-persistence 启动器）（KVP_CACHE_ROOT 定义在 configs/generic/cache.env.local。）
-
KVP_MODEL_REVISION must be a full 40-hex SHA—— 粘贴提交 SHA，而不是分支名 （见快速开始步骤 3）。 -
KVP_CHAT_TEMPLATE_DIGEST must be 64 hex—— 带KVP_MODEL_DIR="$HOME/models/MiMo-V2.6-Pro-MOPD"再运行 一次预检；复制打印出的值。
ERROR: lmcache CLI missing —— 按快速开始步骤 4 安装。如果环境内
import lmcache 因未定义符号报错，说明 pip wheel 与当前 PyTorch/CUDA 栈不匹配。
备用方案：直接从生产镜像运行服务：
docker run --rm --entrypoint lmcache "$IMAGE" server --help若此命令可行，把 scripts/start-cache.sh 中的 lmcache server 一行改为在
docker run 内执行，参数完全相同（端口/路径不变）。
- 启动顺序：
start-cache.sh必须在 vLLM 启动器之前 （run-vllm-with-persist.sh否则会拒绝启动）。 - 查看服务日志的错误行；两个进程使用同一主机网络 —— 不要在不改两边的情况下更换请求端口。
- 用配方集成（
KV_PERSIST=1）时：启动器应打印KV_PERSIST=1: attaching LMCache connector …—— 若缺失，旋钮没传到启动器 （检查tp4.env以及变量是否已导出）。
按顺序检查：
- 响应中
cached_tokens> 0。 -
grep -c Retrieved "$KVP_CACHE_ROOT/lmcache-server.log"在请求期间增长； 重启后的条目就是磁盘恢复的证据。 -
used_bytes没有因重建同样数据而增长（前后对比budget-report.sh status）。 - 身份未变 —— 重新运行
scripts/preflight.sh；版本/dtype/模板变化会悄悄进入 新命名空间（按设计如此）。 -
KVP_PERSIST_ENABLED为true（否则start-cache.sh会警告）。
报告中 free_bytes: 0，或适配器在硬上限处记录拒绝 —— 提高
KVP_CACHE_BUDGET_GB 或显式清理旧命名空间（purge --namespace=NAME --yes，
名称来自 status）。硬上限是 L2 适配器中的 max_capacity_gb：一旦用量达到
它，新写入被拒绝（服务继续运行，只是不再写入缓存）。软阈值（90%）的淘汰
通常会先回收空间，但这不是防止把磁盘本身写满的保证 —— 真正的边界是
存放 KVP_CACHE_ROOT 的卷上的可用空间（在参考主机上该卷还存放 Docker、
模型和系统）。请保留可用空间余量，磁盘紧张时调低预算。服务运行期间切勿
手动删除缓存根目录里的个别文件。
提高 KVP_EVICT_TRIGGER_WATERMARK（更晚开始）或调整 KVP_EVICT_RATIO
（每周期回收更多）。先用很小的隔离预算验证，再指望 1.5 TB 规模的效果。
实际模式见状态报告中的 evictions/reclaimed_bytes 计数。
测量提示词中真正稳定的那部分：
python3 "$REPO/implementation/prompt_probe.py" --tokenizer "$MODEL_DIR" \
--request-file a.json --request-file b.json用从客户端导出的两个真实请求体。若 stable_prefix_tokens 很小，说明动态值
（时间戳、工具调用 id）破坏了前缀 —— 从源头修复序列化，或接受这一限制。
为了缓存而截断历史是被禁止的。
损坏是可容忍的：未命中即重新计算。要手动清理：停止缓存服务，
执行 bash scripts/budget-report.sh purge --all --yes，再启动。
绝不会自动发生。无损编解码的帧还携带 CRC32：损坏或被截断的帧会在读取时
被检测并报告为缓存未命中 —— 绝不会作为错误的 KV 返回。
-
CodecError: zstandard/lz4 python bindings not installed—— 所选编解码 需要其 Python 包（zstd→zstandard，lz4→lz4）。在 lmcache 的 venv 中安装它，或回退到LMCACHE_L2_SERDE=none（逐字节精确的原始模式，完全不 需要依赖）。检查在服务器启动前运行，绝不会要求未使用的编解码：none模式 不需要任何压缩包。 -
LMCACHE_L2_SERDE=... is LOSSY and is not supported—— 预期行为：本项目仅 支持无损。请使用none、zstd或lz4。 - 切换编解码后缓存命中消失 —— 预期且安全：编解码属于缓存身份命名空间，旧块 变为缓存 miss。重新存储它们（或切回原编解码）—— 绝不会错误命中。
- 压缩后磁盘未变小 —— 编解码只压缩真正可压缩的内容；不可压缩的块按原样存储 并填充到 4 KiB 页边界。在很小的块上，28 字节的头部可能占主导。
被强杀（SIGKILL、OOM、断电）后，适配器可能留下 <final>.bin.tmp.<uuid> ——
未能原子重命名的文件。上游仅在干净关闭时清扫它们。用
bash scripts/budget-report.sh status（字段 tmp_files / tmp_files_bytes）
检查，用 purge --tmp --yes（仅清残余）或 purge --all --yes 删除。
两条命令都用活跃写入注册表（kvpersist.tmp_guard）保护进行中的写入：每次写入
在创建 tmp 文件前登记标记、原子重命名后清除。存活判定在两种启动模式下都有效
（第 18 轮）：
-
host 模式 —— 标记记录
(pid, 进程启动时间)，只要该进程仍在即为存活 （/proc/<pid>+ 启动时间防 PID 复用）； -
docker 模式（
KVP_LAUNCH_MODE=docker，无--pid=host）—— 标记记录写入进程的 PID 命名空间 id；当标记属于外来命名空间时，主机 CLI 无法检查其 PID，因此存活判定 回退到标记自身的 HEARTBEAT（写入期间每 30 秒刷新一次）：2 分钟内被触碰过的标记 = 存活，更旧 = 崩溃残留。 若完全无法判定存活（无 /proc、标记不可读）则保留标记：宁可多留一个 tmp 文件，也不 删除活跃写入的文件。写入者确已退出的标记在一小时后清扫。第二重兜底适用于未使用 注册表的写入者（例如裸的lmcache server）：最近 15 分钟内修改过的*.tmp.*一律跳过 —— 该窗口是启发式，不是绝对锁。
在缓存服务推送遥测之前该栈是被动的。用 USE_OBSERVABILITY=1（或
KVP_OTLP_ENDPOINT=http://localhost:4320）启动缓存并检查日志中的 [kvp]
横幅。Docker 模式下 start-cache.sh 会自动把 localhost 改写为
host.docker.internal。栈的所有端口仅绑定 127.0.0.1（回环契约）。
改变任何身份字段都会更换命名空间：旧的缓存条目不会被删除，但无法再被寻址—— 这看起来像"缓存坏了"，其实是隔离机制按设计工作。下表中每一行都会使本次部署 之前缓存的所有 KV 失效：
| 你改变了... | 对命名空间的影响 | 可复用旧缓存？ |
|---|---|---|
| 模型权重（内容替换，即使文件名相同） | shard 字节 SHA-256 改变 | 否 |
| 模型版本（HF SHA） | 改变 | 否 |
| 分词器（tokenizer.json / tokenizer_config.json） | 改变 | 否 |
| chat_template / chat_template.jinja 内容 | digest 改变 | 否 |
--kv-cache-dtype（如 bfloat16 -> float16） |
改变 | 否 |
--max-model-len |
改变 | 否 |
--tensor-parallel-size |
改变 | 否 |
| config.json 中 KV 几何配置 | 改变 | 否 |
| vLLM 构建 / LMCache 连接器版本（KVP_CONNECTOR_VERSION） | 改变 | 否 |
--enforce-eager / 其他改变 KV 计算顺序的引擎标志 |
可能改变块布局 → 改变 | 否 |
| Docker 镜像摘要（不同 vLLM 构建） | 改变 | 否 |
实践建议：用 setup-identity.sh 的输出固定 KVP_MODEL_REVISION，随每次部署保存
identity.env.local；只要改了引擎参数就预期命名空间改变——把"改完设置后缓存变冷"
当作正确预期行为来处理，而不是 bug。