lmcat

lmcat（LMCache-Ascend-Test）是在 Linux + Ascend NPU 环境中管理 vLLM 服务、运行 LMCache benchmark 并保存测试结果的命令行工具。

当前版本支持：

• 从一份 YAML 配置启动、检查、查看日志、停止和重启 vLLM；
• 在单一后台受管任务中执行 LMCache multi_round_qa；
• 确保 vLLM 可用后执行不限时测试，以保持 NPU 利用率；
• 每天更新 LMCache-Ascend，并按从旧到新的顺序测试新增提交；
• 将原始 CSV、终端日志和归一化指标保存到本地；
• 在终端中查看 SQLite 数据，或导出为 Excel。

lmcat 不创建容器，也不检查 NPU 驱动、设备挂载或硬件健康。请先在目标物理机 或 vLLM-Ascend 容器内手工验证 vLLM 和 benchmark 命令，再部署 lmcat。

安装

要求 Python 3.10 或更高版本。推荐直接从 Git 仓库安装为 uv tool：

uv tool install git+https://github.com/Josh-Jing/lmcat.git

更新：

uv tool upgrade lmcat

如果内网环境不能访问 GitHub，可先复制仓库，再从本地目录安装：

uv tool install /path/to/lmcat

初始化

lmcat init

默认目录为 ~/.lmcat。可以在安装或运行前设置：

export LMCAT_HOME=/workspace/.lmcat

初始化后的目录：

~/.lmcat/
├── config.yaml
├── lmcat.db
├── artifacts/
├── logs/
│   ├── vllm.log
│   ├── bench-worker.log
│   └── serve.log
└── run/
    ├── vllm.json
    ├── bench.json
    ├── serve.json
    ├── vllm.lock
    ├── bench.lock
    ├── serve.lock
    └── daily-test.lock

lmcat.db 和部分文件只会在首次使用相关功能后出现。

配置

lmcat init 会写入以 Qwen3-32B 示例环境为基础的完整配置。编辑 ~/.lmcat/config.yaml 后再启动服务。

也可以为任意命令指定另一份配置：

lmcat -c /path/to/config.yaml vllm status

vLLM

vllm:
  command:
    - vllm
    - serve
    - /workspace/models/Qwen3-32B
    - --port
    - "8055"
  env:
    OMP_NUM_THREADS: "8"
    LD_LIBRARY_PATH: "/usr/local/lib:$LD_LIBRARY_PATH"
  health_url: http://127.0.0.1:8055/v1/models
  startup_timeout: 1800
  stop_timeout: 30

command 必须是 YAML 列表。不要加入 nohup、&、tee 或 shell 重定向：后台化、PID 身份校验以及 stdout/stderr 捕获由 lmcat 负责。

环境变量值可以引用当前进程已有的变量，例如 $LD_LIBRARY_PATH。

LMCache multi_round_qa

benchmark:
  kind: multi-round-qa
  command:
    - python3
    - /workspace/lmcaches-daily/LMCache/benchmarks/multi_round_qa/multi-round-qa.py
  num_users: 100
  num_rounds: 20
  qps: 0.5
  shared_system_prompt: 1000
  user_history_prompt: 500
  answer_len: 500
  model: Qwen3-32B
  base_url: http://127.0.0.1:8055/v1
  time: 3600
  log_interval: 30
  extra_args: []
  source_repository: /workspace/lmcaches-daily/LMCache-Ascend

这些字段会映射到官方脚本的同名参数。extra_args 可传入官方脚本的其他开关。 time 是每轮测试的秒数；官方脚本在未设置该参数时会持续运行，因此示例使用有限的 3600 秒。不要在 command 或 extra_args 中重复写由 lmcat 管理的 benchmark 参数或 --output，输出路径由 lmcat 为每次运行单独生成。

若 source_repository 指向 Git 仓库，lmcat 会在每次测试开始时读取其 HEAD 提交号并和结果一起保存。

每日服务

serve:
  schedule: "02:00"
  source_branch: main
  web_host: 0.0.0.0
  web_port: 8999
  uninstall_command:
    - pip
    - uninstall
    - -y
    - lmcache-ascend
  install_command:
    - pip
    - install
    - -v
    - --no-build-isolation
    - -e
    - .

schedule 使用机器本地时区的 HH:MM，未配置时默认为 02:00。构建前 lmcat 会安全删除 source_repository/build，然后在仓库目录中依次执行卸载和 安装命令。命令必须是 YAML 列表，不通过 shell 执行。

命令

所有层级都提供帮助：

lmcat --help
lmcat vllm --help
lmcat vllm start --help
lmcat bench --help
lmcat res --help

管理 vLLM

lmcat vllm start
lmcat vllm start --wait
lmcat vllm status
lmcat vllm logs
lmcat vllm logs -n 500
lmcat vllm logs -f
lmcat vllm stop
lmcat vllm restart
lmcat vllm restart --wait

start 成功创建并记录后台进程后立即返回。该成功结果只表示启动动作已经触发， 不表示模型服务已经 ready。回显会提示使用以下命令观察状态：

lmcat vllm status
lmcat vllm logs -f

需要显式等待 health_url ready 时使用 lmcat vllm start --wait，最多等待 startup_timeout 秒。restart 使用相同约定：默认在触发新进程后返回， restart --wait 才等待新服务 ready。

状态含义：

• stopped：没有 lmcat 管理的进程，HTTP 接口也不可用；
• starting：进程存在，仍在启动期限内等待接口；
• ready：lmcat 管理的进程和 HTTP 接口均正常；
• unhealthy：进程存在，但超过启动期限后接口仍不可用；
• stale：状态文件存在，但对应进程已经不存在或 PID 已被复用；
• external：接口可用，但服务不是当前 lmcat 实例启动的。

stop 只会停止状态文件中记录且身份匹配的进程组。它先发送 SIGTERM；只有显式 使用 --force 且优雅停止超时后才发送 SIGKILL。

logs 显示 ~/.lmcat/logs/vllm.log 的最后 100 行，-f 持续跟随。第一版 尚不执行日志轮转。

运行 benchmark

启动一次有限时长的后台正式测试，命令成功触发后立即返回：

lmcat bench
lmcat bench run
lmcat bench run multi-round-qa

bench run 是兼容别名。任意时刻最多只有一个受管 benchmark。停止当前任务：

lmcat bench stop

stop 是幂等的，并会停止整个受管进程组。

触发 vLLM 启动，并在后台等待服务 ready 后运行不限时 benchmark：

lmcat vllm busy

该命令立即返回。无限测试只用于保持 NPU 忙碌，不写入正式结果数据库；通过 lmcat bench stop 停止它。

每次正式测试生成独立的 CSV 和终端日志。lmcat 从官方 CSV 的逐请求数据计算 请求数、实际 QPS、输入/输出 token 吞吐、单请求平均生成吞吐、平均 TTFT，以及 平均 TPOT。TTFT 使用秒，TPOT 使用毫秒/token：

mean(generation_time / max(generation_tokens - 1, 1)) × 1000

结果还保存 LMCache-Ascend commit、LMCache 版本、压测触发时间、实际 vLLM 参数、 vLLM 环境变量、benchmark 类型和实际参数列表。lmcat 不解析彩色终端摘要。

运行每日服务

后台启动长期调度器，成功创建并记录进程后立即返回：

lmcat serve start

该命令同时启动结果 Web 仪表盘。默认监听 0.0.0.0:8999；从局域网的浏览器访问 http://<服务器 IP>:8999/。web_host 和 web_port 可在 serve 配置中覆盖。仪表盘 不提供登录认证，页面会展示测试模型、提交、命令相关的结果信息，因此只应暴露在受信任 的内网，并通过防火墙限制不受信任的来源。

后台触发一个周期，适合首次验证，同样立即返回：

lmcat serve once

立即在后台触发一个周期，并在本轮结束后继续按每日计划调度：

lmcat serve now

serve now 与长期调度器一样会启动 Web 仪表盘。即使立即执行的首轮周期失败， 调度器仍会继续运行，并等待下一次 serve.schedule。

查看状态、日志或触发停止：

lmcat status
lmcat serve status
lmcat serve logs
lmcat serve logs -f
lmcat serve stop

每日周期开始时，服务停止当前 benchmark 和 vLLM；更新 benchmark.source_repository 后，根据数据库中的最后一次提交，只测试新增提交。 第一次运行没有历史记录时只测试当前 HEAD。多个提交按旧到新依次测试，每个提交 预算两小时，benchmark 使用构建和 vLLM 启动后的剩余时间，并预留五分钟收集数据。

同一时间只允许一个每日周期。前一天的周期尚未结束时，下一次调度不会打断它。周期 结束时，仓库恢复到 serve.source_branch 的最新提交，重新构建、触发 vLLM，并 启动不限时 busy benchmark。每日周期持锁期间拒绝用户启动新的 bench 或 busy。

serve stop 只表示成功发出优雅停止请求，也会立即返回。调度器空闲时会与 Web 仪表盘一起退出；若每日周期正在运行，二者会持续运行到本轮测试完成、恢复最新提交并 启动 busy 后退出。lmcat status 与 lmcat serve status 都会显示调度器状态、每日 周期状态、Web 绑定地址和 HTTP 健康状态。

裸 lmcat serve 只显示子命令帮助。调度器由 lmcat 自己后台管理，不修改系统 crontab。

查看和导出结果

lmcat res
lmcat res --full
lmcat res --limit 10
lmcat res xlsx
lmcat res xlsx -o /workspace/logs/results.xlsx
lmcat res csv
lmcat res csv -o /workspace/logs/results.csv

SQLite 数据库位于当前配置文件同目录下的 lmcat.db。Excel 和 CSV 默认导出到当前目录。 Web 仪表盘提供按 benchmark、模型、状态、提交前缀和时间范围筛选的结果表格，以及按 测试时间排列的 QPS（req/s）和 TTFT（s）跨提交概览图；页面每 15 秒自动刷新。

暂不包含

• NPU 驱动、设备挂载和硬件健康检查；
• vLLM 日志轮转；
• vllm bench runner；
• 多 profile 管理和多机结果汇总。

这些能力将在目标 Ascend 环境验证当前版本后继续设计。