LMCache CLI 实战：用 lmcache kvcache clear 管理运行中服务的 KV Cache 状态

【免费下载链接】LMCache LMCache: Supercharge Your LLM with the Fastest KV Cache Layer 项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache

本文是一份针对 LMCache 官方 CLI 命令 lmcache kvcache 的完整技术指南。该命令用于在**运行中的 LMCache 服务（MP HTTP server）**上管理 KV cache 状态，当前提供 clear 子命令，用于清空 L1（CPU 内存）层中缓存的全部 KV 数据。读完本文，你将掌握该命令的完整参数体系、退出码语义、终端/JSON/静默三种输出模式，并能基于其底层 HTTP 调用链（POST /cache/clear）把清缓存操作可靠地编排进 shell 脚本与监控流程。文中所有结论均以本仓库文档 docs/source/cli/kvcache.rst 为骨架，并辅以 CLI 与服务端源码佐证。

命令总览：lmcache kvcache <sub-command> [options]

lmcache kvcache 命令面向正在运行的 LMCache 服务提供 KV cache 状态管理能力，与面向离线配置/启动的 lmcache server 等命令定位不同。其通用语法为：

lmcache kvcache <sub-command> [options]

执行 lmcache kvcache -h 可以看到当前支持的全部子命令与全局选项：

$ lmcache kvcache -h
usage: lmcache kvcache [-h] [--format FORMAT] [--output PATH] [-q] {clear} ...

Manage KV cache state.

subcommands:
  clear          Clear all cached KV data in L1 (CPU)

options:
  -h, --help       show this help message and exit
  --format FORMAT  Stdout output format (default: terminal). Available: terminal, json.
  --output PATH    Save metrics to a file at PATH (format chosen by --format).
  -q, --quiet      Suppress stdout output. Exit code only.

从帮助输出可以看到，该命令当前仅有一个子命令 clear。需要说明的是：--format、--output、-q/--quiet 这三个选项并不属于某个子命令专属，而是由 lmcache/cli/commands/base.py 中 BaseCommand.register() 统一为每个子命令注入的"公共输出选项"（_add_output_args），因此 lmcache kvcache 下的所有子命令都天然支持这三种输出控制方式。

命令在 CLI 体系中的位置

lmcache kvcache 是 LMCache 命令体系的一员。在 lmcache/cli/main.py 中，CLI 入口会遍历 ALL_COMMANDS 逐个注册子命令；kvcache 命令对应的实现类是 lmcache/cli/commands/kvcache.py 中的 KVCacheCommand（继承自 BaseCommand）。同一命令族中与 KV cache 运维密切相关的还有：

• lmcache ping kvcache --url ...：对 LMCache 服务做存活探测（访问 /healthcheck 端点），详见 docs/source/cli/ping.rst；
• lmcache describe kvcache --url ...：获取 KV Cache 服务的健康、L1 存储、注册适配器等信息，详见 docs/source/cli/describe.rst；
• lmcache query kvcache：查询 KV-cache 端点（文档标注当前尚未实现），详见 docs/source/cli/query.rst。

它们的服务端上下文一致：lmcache describe、lmcache ping kvcache、lmcache kvcache 均面向同一个 MP HTTP server 的 HTTP 接口（参见 docs/source/cli/server.rst）。

clear 子命令：清空 L1（CPU 内存）中的 KV 缓存

clear 是 lmcache kvcache 当前唯一实现的子命令，作用是在目标 LMCache 服务上清空 L1（CPU 内存）层缓存的全部 KV 数据。注意其语义是"整层清空"，而非按 key 定向删除——如果你需要按对象 key 定向删除（可指定 l1 / l2 / all 层级），应使用 MP HTTP server 提供的 DELETE /cache/objects 接口，而非本命令。

基本用法

lmcache kvcache clear --url <MP_HTTP_URL>

其中 <MP_HTTP_URL> 是 LMCache MP HTTP server 的地址，例如 http://localhost:8000。--url 为必填参数（源码中 required=True），必须显式指定。

一个完整示例：

$ lmcache kvcache clear --url http://localhost:8000

================ KV Cache Clear ================
Status:                                       OK
================================================

JSON 输出（便于脚本与 jq 解析）

使用 --format json 即可获得机器可读的结构化输出：

$ lmcache kvcache clear --url http://localhost:8000 --format json
{
  "title": "KV Cache Clear",
  "metrics": {
    "status": "OK"
  }
}

该输出由 CLI 的 metrics 体系生成：KVCacheCommand._clear() 在请求成功后调用 self.create_metrics("KV Cache Clear", args) 创建 Metrics 对象，注册 status 指标后 emit()。--format json 会选用 JsonFormatter（相关格式化器定义在 lmcache/cli/metrics/ 包的 formatter.py 中）。

静默模式（仅保留退出码）

-q / --quiet 用于脚本场景：抑制 stdout 输出，只通过退出码传达结果。

$ lmcache kvcache clear -q --url http://localhost:8000
$ echo $?
0

从实现看，_clear() 在请求成功后先检查 quiet 标志：若为真则直接 return，不再构造与发射任何 metrics 输出（参见 lmcache/cli/commands/kvcache.py）。因此静默模式下唯一的可观测信号就是退出码。

选项完整说明

Flag	必填	说明
--url	是	LMCache MP HTTP server 的 URL（如 http://localhost:8000）。源码中该参数 required=True。
--format	否	输出格式：terminal（默认）或 json。
--output	否	将输出保存到 PATH 指定的文件（文件格式由 --format 决定）。
-q / --quiet	否	抑制 stdout 输出，仅保留退出码。适合脚本中只关心成败的场景。

关于 --output 的补充：当同时使用 --format json --output result.json 时，BaseCommand.create_metrics() 会同时注册一个 StreamHandler（写 stdout）与一个 FileHandler（写文件），两者使用同一个 formatter（见 lmcache/cli/commands/base.py）。也就是说，--output 不会吞掉终端输出，除非再叠加 -q。

退出码语义

Code	含义
0	成功。
1	错误（连接失败、服务端错误、参数错误）。

退出码 1 的具体触发路径可在源码中确认（lmcache/cli/commands/kvcache.py）：

• HTTP 错误（4xx/5xx）：urllib.error.HTTPError 被捕获后，尝试从响应体中解析 message 或 error 字段并写入日志，随后 sys.exit(1)；
• 连接失败：urllib.error.URLError 被捕获后记录"Cannot reach %s — is the server running?"，同样 sys.exit(1)；
• 缺少子命令：未指定 action 时提示 "No sub-command specified. Run: lmcache kvcache -h" 并退出 1。

另外，CLI 入口 lmcache/cli/main.py 对执行期间的任何未捕获异常统一记录日志并 sys.exit(1)，对 KeyboardInterrupt 则退出 130，这也是脚本判断时需要知晓的边界行为。

底层原理：clear 背后发生了什么

客户端侧：一次带 JSON 体的 POST 请求

KVCacheCommand._clear() 的实现非常直接（lmcache/cli/commands/kvcache.py）：

url = args.url.rstrip("/")
# MP HTTP server endpoint: POST /cache/clear
_http_request("POST", f"{url}/cache/clear", {"tier": "l1"})

也就是说，lmcache kvcache clear --url http://localhost:8000 实际上等价于向 MP HTTP server 发送：

POST http://localhost:8000/cache/clear
Content-Type: application/json
Body: {"tier": "l1"}

请求体 {"tier": "l1"} 明确表达"仅清空 L1 层"。_http_request() 使用 Python 标准库 urllib.request 实现，设置了 10 秒超时（urlopen(req, timeout=10)）。

服务端侧：POST /cache/clear 端点

该端点定义在 lmcache/v1/multiprocess/http_apis/cache_api.py，位于 MP server 的 cache_api 路由中，属于"Diagnostics（诊断类）"接口（同组还有 POST /cache/checksums）。其关键行为：

• 请求体可选：ClearRequest | None = None，缺省时等价于 {"tier": "l1", "force": true}；
• 层级校验：模块级常量 _CLEAR_TIER = Tier.L1，只有当请求体 tier == l1 时才继续处理；传入其他 tier 会返回 400 Bad Request，提示 only 'l1' 支持；
• 强制清空语义：直接调用 get_context(request).engine.clear()，清空该层级所有对象——包括持有活跃读写锁的对象，因此文档注释明确警告"进行中的 store/prefetch 操作可能因此损坏"；
• 响应：成功返回 {"status": "ok", "cleared": {"tier": "l1"}}；若服务未初始化则返回 503。

请求体数据结构 ClearRequest 定义在 lmcache/v1/multiprocess/http_apis/schemas.py：

@dataclass(frozen=True)
class ClearRequest:
    tier: Tier = Tier.L1      # 请求数据，当前仅支持 l1
    force: bool = True        # force=true 表示实现支持时可能忽略活跃锁

源码中的 TODO(cache-control) 注释还透露了一个兼容性细节：force 字段当前被 API 接受但尚未真正生效——引擎的 CLEAR 路径始终是强制清空，真正将 force 透传需要扩展 ZMQ RequestType.CLEAR 载荷。也就是说，现阶段无论是否传 force，行为都是强清。

与 vLLM 侧清缓存接口的区别

注意不要将本命令与 LMCache 内部为 vLLM 暴露的 DELETE /cache/clear 接口混淆：后者定义在 lmcache/v1/internal_api_server/vllm/cache_api.py，可通过 curl -X DELETE "http://localhost:8000/cache/clear?locations=LocalCPUBackend&locations=LocalDiskBackend" 按后端位置定向清除。lmcache kvcache clear 面向的是 MP HTTP server 的 POST /cache/clear，语义上属于"整层强制清空"的诊断操作。在编排运维脚本时，请确认目标服务的 HTTP 面，选择对应的接口。

实战模式：把清缓存编排进脚本

原文档给出了两个非常实用的编排模式，可直接复制到生产脚本中。

模式一：处理服务器临时不可用

服务器可能因网络抖动暂时不可达，此时命令会以退出码 1 失败。如果只是瞬时故障，应实现"失败重试"而非直接报错；对于持续性的连通性问题，建议先用 lmcache ping 诊断服务状态（ping kvcache 探测 /healthcheck）：

if lmcache kvcache clear -q --url http://localhost:8000; then
    echo "Cache cleared"
else
    echo "Clear failed — server temporarily unreachable, retrying later"
fi

模式二：清缓存并捕获 JSON 结果

将 JSON 输出交给 jq 解析，实现"清缓存 + 校验状态"一体化：

RESULT=$(lmcache kvcache clear --url http://localhost:8000 --format json)
STATUS=$(echo "$RESULT" | jq -r '.metrics.status')
echo "Clear status: $STATUS"

模式三：定时/编排任务中的稳健调用

结合以上两点，可构造一个幂等且可观测的定时清理任务模板：

URL="http://localhost:8000"
if lmcache ping kvcache --url "$URL" >/dev/null 2>&1; then
    if lmcache kvcache clear --url "$URL" --format json --output /tmp/kvcache_clear.json; then
        echo "cleared: $(jq -r '.metrics.status' /tmp/kvcache_clear.json)"
    else
        echo "clear failed with exit code $?" >&2
    fi
else
    echo "server not reachable, skip" >&2
fi

需要再次强调的注意点：

1. 清空范围是 L1 全量：clear 不区分模型、不保留任何 L1 对象，属于"核弹级"操作，执行前应确认业务窗口；
2. 会破坏进行中的 store/prefetch：服务端对持锁对象同样强制清空，涉及 L2→L1 预取（prefetch）或存储写入进行中的时刻，可能产生脏状态，建议在低峰期执行；
3. --url 必须显式给出：clear 没有默认 URL，漏传会直接因参数校验失败退出；
4. 退出码是脚本的唯一可靠信号：-q 模式下没有输出，务必依赖退出码判断成败。

小结

lmcache kvcache clear 是 LMCache CLI 面向运行时 KV cache 管理的第一步落地：客户端通过 POST /cache/clear 携带 {"tier": "l1"} 触发服务端强制清空 L1 层全部缓存，配合 --format json、--output、-q 三种输出模式与稳定的退出码语义，可以无缝嵌入 cron、CI 或监控告警等自动化链路。从 KVCacheCommand 类注释可以看到，设计文档中还规划了 pin、compress、info 等后续子命令——kvcache 命令族会随 LMCache 的缓存管理能力一起持续扩展，本指南所讲的使用范式（必填 URL + 输出格式控制 + 退出码驱动）同样适用于未来的新子命令。

【免费下载链接】LMCache LMCache: Supercharge Your LLM with the Fastest KV Cache Layer 项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache