扩展 CLI

本指南解释了如何向 lmcache CLI 添加新的子命令。

架构概述

CLI 使用显式命令注册：

1. 每个命令都是一个继承自 BaseCommand 的类，位于 lmcache/cli/commands/base.py 中。

2. 命令在 lmcache/cli/commands/__init__.py 中的 ALL_COMMANDS 中被实例化和列出。

3. 在启动时，main.py 迭代 ALL_COMMANDS 并调用 cmd.register(subparsers) 来连接 argparse。

BaseCommand 是一个抽象类，具有四个必需的方法。忘记其中任何一个都会在实例化时引发 TypeError。

文件布局

lmcache/cli/
├── __init__.py
├── main.py              # Entry point
├── metrics/             # Metrics system
│   ├── __init__.py      # Re-exports
│   ├── metrics.py       # Metrics collector
│   ├── section.py       # Section data class
│   ├── handler.py       # StreamHandler, FileHandler
│   └── formatter.py     # TerminalFormatter, JsonFormatter
└── commands/
    ├── __init__.py      # ALL_COMMANDS registry
    ├── base.py          # BaseCommand ABC
    ├── describe.py      # lmcache describe
    ├── kvcache.py       # lmcache kvcache
    ├── mock.py          # Example command
    ├── ping.py          # lmcache ping
    ├── query/           # lmcache query
    │   ├── __init__.py  # QueryCommand
    │   ├── prompt.py    # Prompt placeholder expansion
    │   └── request.py   # OpenAI-compatible HTTP requests
    └── server.py        # lmcache server

逐步指南：添加新命令

第 1 步。 创建 lmcache/cli/commands/describe.py：

# SPDX-License-Identifier: Apache-2.0
import argparse

from lmcache.cli.commands.base import BaseCommand

class DescribeCommand(BaseCommand):

    def name(self) -> str:
        return "describe"

    def help(self) -> str:
        return "Describe a running KV cache server."

    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
        parser.add_argument("--url", required=True,
                            help="LMCache HTTP server URL (e.g. http://localhost:8000)")

    def execute(self, args: argparse.Namespace) -> None:
        # Connect to server, gather info...
        metrics = self.create_metrics("Describe KV Cache", args)
        metrics.add("status", "Status", "OK")
        metrics.add("chunks", "Cached chunks", 1024)
        metrics.emit()

步骤 2. 在 lmcache/cli/commands/__init__.py 中注册它：

from lmcache.cli.commands.describe import DescribeCommand

ALL_COMMANDS: list[BaseCommand] = [
    MockCommand(),
    KVCacheCommand(),
    DescribeCommand(),   # add here
    PingCommand(),
    QueryCommand(),
    ServerCommand(),
]

就是这样 --- lmcache describe --url http://localhost:8000 现在可以使用了。

使用指标系统

指标系统使用 处理器 + 格式化器 架构：

• 指标 — 收集器。包含部分和条目。

• 处理器 — 目标（标准输出、文件等）。

• 格式化器 — 渲染（ASCII 表格、JSON 等）。

BaseCommand.create_metrics() 自动设置默认处理程序，因此命令作者只需构建指标并调用 emit()：

def execute(self, args: argparse.Namespace) -> None:
    # create_metrics() auto-registers:
    #   - StreamHandler → stdout (formatter chosen by --format, default: terminal)
    #   - FileHandler   → if --output is set (same format as --format)
    metrics = self.create_metrics("Bench KV Cache Result", args)

    # Create named sections
    metrics.add_section("ops", "Operations (ops/s)")
    metrics["ops"].add("store", "Store", 41.3)
    metrics["ops"].add("retrieve", "Retrieve", 127.3)

    # Top-level metrics (no section header)
    metrics.add("status", "Status", "OK")

    # Trigger all handlers
    metrics.emit()

--format 和 --output 标志由 BaseCommand.register() 自动添加 — 子命令不需要手动添加它们。