Skip to content

Quick Start.zh

Jump to bottom
sikkatu edited this page Nov 2, 2026 · 7 revisions

English | Русский | 中文

快速开始

一条直线路径：安装 → 配置 → 启动 → 验证。所有命令都可以直接复制执行； setup-identity.sh（步骤 3）会自动填写并核验全部身份字段，不需要手动粘贴 模型版本号。唯一强烈建议手工设置的是 KVP_CACHE_DEVICE（步骤 2），确保缓存 确实落在目标 NVMe 上：不设置它验证会以 INCONCLUSIVE 收尾而非 PASS，但首次 运行不受阻碍。

所有命令在带 GPU（以及存放缓存的 NVMe）的主机上、以运行 Docker 的用户身份执行。 不在 Docker 内，不在其他机器上。下面的 REPO 是克隆目录 —— 命令中明确写出， 无需额外补充。

0. 前提条件

  • Linux 主机（任意发行版），配备 NVIDIA GPU、Docker、固定的 vLLM 镜像和 MiMo-V2.6-Pro 本地模型目录。
  • 本地 NVMe 可用空间不少于缓存预算（默认 1.5 TB）；实际边界为固定设备上的可用空间。
  • sikkatu/recipes 的生产配方已在磁盘上（kv-persistence 脚本仅使用其 tp4.env.example（IMAGE 摘要）与 patches/ + MANIFEST.sha256（只读挂载）； 配方本身不会被修改）。

1. 克隆仓库

git clone https://github.com/sikkatu/kv-persistence ~/kv-persistence
cd ~/kv-persistence
REPO=~/kv-persistence

2. 配置缓存

cp "$REPO/configs/generic/cache.env" "$REPO/configs/generic/cache.env.local"

副本中的 KVP_CACHE_ROOT（默认 /var/lib/kv-persistence/l2）是缓存的 NVMe 路径。若 NVMe 就在该位置，保持默认；否则将这一行改为 NVMe 路径。 KVP_CACHE_BUDGET_GB（默认 1500）是硬性预算。

3. 固定模型身份

一条命令填好并核验全部必填身份字段 （KVP_MODEL_REVISION、KVP_TOKENIZER_REVISION、KVP_CHAT_TEMPLATE_DIGEST）：

bash "$REPO/scripts/setup-identity.sh" "$HOME/models/<your-model-dir>"

从磁盘上实际存在的文件（权重索引、分词器文件、按单一文档化算法处理的聊天模板） 派生确定性指纹，直接写入 configs/mimo-v2.6-pro/identity.env；脚本最后 核验写入结果（缓存命名空间必须能计算）。无需手动粘贴。如果退出码非零， 说明身份未就绪 —— 请阅读其消息。

已经在追踪上游提交 SHA？先设置它，只派生其余字段：

export KVP_MODEL_REVISION="$(curl -fsSL https://huggingface.co/api/models/XiaomiMiMo/MiMo-V2.6-Pro-MOPD | python3 -c 'import json,sys; print(json.load(sys.stdin)["sha"])')"
bash "$REPO/scripts/setup-identity.sh" "$HOME/models/<your-model-dir>"

4. 安装 LMCache CLI

python3 -m venv ~/.venvs/lmcache
~/.venvs/lmcache/bin/pip install --upgrade pip
~/.venvs/lmcache/bin/pip install -r "$REPO/requirements-lmcache.txt"
export PATH="$HOME/.venvs/lmcache/bin:$PATH"

创建 venv 需要 Python 3.12（生产镜像的运行时，也是 requirements-lmcache.txt 的目标版本）。Debian/Ubuntu (tested on Debian 12) 系统 Python 为 3.11： 请另行安装 3.12 解释器（如 bookworm-backports 或 pyenv），改用 python3.12 -m venv ~/.venvs/lmcache。Debian 上 python3-venv 需单独安装。

PATH 只在当前终端有效（若需在新终端直接调用 lmcache，请重复此 export）。 每个新终端都请重新导出 REPO、IMAGE、MODEL_DIR、PATH —— shell 变量 不会跨终端保留。若 pip wheel 与镜像 ABI 不匹配（导入错误），参见 故障排查 —— 备用方案直接从固定的镜像内运行 lmcache server。

5. 预检

bash "$REPO/scripts/preflight.sh"

出现 preflight PASSED 即可继续。每个 [!!]（双感叹号）都会给出需要修复的 具体内容。带模型目录运行一次 —— 聊天模板摘要会自动计算：

KVP_MODEL_DIR="$HOME/models/<your-model-dir>" bash "$REPO/scripts/preflight.sh"

此处不需要手动复制：setup-identity.sh（步骤 3）已写入 digest； 上面的命令只是确认它与模型目录一致。

6. 启动持久缓存服务

bash "$REPO/scripts/start-cache.sh"

服务以分离方式运行（setsid nohup），因此断开 SSH 或关闭此终端也不会 中断它；日志和 pid 位于 KVP_CACHE_ROOT 下。此前缓存的数据会被 保留 —— 启动绝不会清空缓存。

可选：无损压缩

默认情况下块以逐字节精确方式存储（LMCACHE_L2_SERDE=none）—— 不做任何 变换，也无额外依赖。若要以无损 zstd 或 lz4 压缩存储（真实 KV 负载上约 1.1–1.4x 更小）：

USE_LOSSLESS_SERDE=1 bash "$REPO/scripts/start-cache.sh"     # zstd
USE_LOSSLESS_SERDE=lz4 bash "$REPO/scripts/start-cache.sh"   # lz4

第 7 步必须使用同一个开关（它属于缓存身份命名空间）。zstd 只需要 zstandard 包，lz4 只需要 lz4：启动前的检查只要求所选的那一个编解码， 而 none 模式的缓存完全不需要压缩包。每个帧携带 CRC32：损坏会被检测并 报告为缓存未命中，绝不会作为错误的 KV 返回。

可选：Prometheus + Grafana 监控

bash "$REPO/scripts/start-observability.sh"
# Grafana -> http://localhost:3000（匿名 Admin，无需登录）

然后用 USE_OBSERVABILITY=1 启动缓存，指标才会流向收集器。栈端口仅绑定 127.0.0.1。缓存不依赖该栈也能完整工作。

7. 启动带缓存的 vLLM

此步骤的前置条件（三项均必需）：

  1. 生产配方必须在磁盘上，位于启动器默认期望的路径（或用 RECIPE_DIR 指向它）： 
    git clone https://github.com/sikkatu/recipes ~/recipes
    启动器仅读 tp4.env.example 以复用配方固定的 IMAGE 摘要及经校验和验证的 patches/（以只读挂载）；配方本身绝不被修改。
  2. 需要 API_KEY。 启动器从当前目录的 live/api_key 读取（或已导出的 API_KEY）。若还没有密钥： 
    mkdir -p live && openssl rand -hex 24 > live/api_key && chmod 600 live/api_key
  3. MODEL_DIR 必须指向与步骤 3 相同的本地模型目录 —— 这里构建的身份与那里的 权重必须一致。
cd "$REPO"
export IMAGE="$(bash "$REPO/scripts/print-recipe-image.sh" "$HOME/recipes/recipes/rtx-pro-6000/mimo-v2.6-pro-hotsplit")"
export MODEL_DIR="$HOME/models/<your-model-dir>"
bash "$REPO/scripts/run-vllm-with-persist.sh"

启动脚本以生产配方的参数为基线，另加 KV 连接器、缓存身份命名空间挂载、 --enable-prompt-tokens-details 和固定的 --block-size —— 这不是逐项复制 （配方的 KV_PERSIST=1 分支现已在这四点上与之一致；见 配方集成）。配方补丁会校验校验和，以只读方式挂载。

8. 验证

bash "$REPO/scripts/verify-engine-identity.sh"   # 必需门禁：引擎配置 == identity 固定值
bash "$REPO/scripts/test-recovery.sh"            # 验收：PASS / INCONCLUSIVE / FAIL (exit 0/5/1)

test-recovery.sh 在接触缓存之前先调用 verify-engine-identity.sh：如果任一 identity 固定值与运行中引擎不符，拒绝复用缓存（exit 4）。如果无法验证某个值（例如 KVP_MODEL_DIR 未设置），结果为 INCONCLUSIVE（exit 5）——绝不悄悄 PASS。物理 NVMe 检查通过 KVP_CACHE_DEVICE 进行；在 cache.env.local 中设置它后 PASS 才可达。

预热 → 重启 vLLM → 重新发送；预热 → 重启两个服务 → 重新发送。脚本按阶段输出 cached_tokens 和恢复证据到 benchmarks/results/。磁盘恢复的证明是每次重启后 cached_tokens > 0 加上缓存日志中的 L2/磁盘读取事件，并有物理 NVMe 读取计数器佐证 —— 单凭速度绝不作为证据。

下一步

Clone this wiki locally