扩展 CLI#

本指南介绍如何为 lmcache CLI 添加新子命令。

架构概述#

CLI 使用显式命令注册：

  1. 每个命令都是一个继承自 BaseCommand 的类。

  2. 所有命令均在中央 ALL_COMMANDS 注册表中实例化并列出。

  3. 启动时，入口点遍历 ALL_COMMANDS 并调用 cmd.register(subparsers)，将各子命令注册到 argparse。

BaseCommand 是一个抽象类，包含少量必需方法（名称、帮助、参数注册及执行）。若遗漏其中任一方法，实例化时将引发 TypeError。

逐步指南：添加新命令#

步骤 1. 创建一个继承自 BaseCommand 的新命令类：

# 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. 将其实例添加到 ALL_COMMANDS 注册表中：

from lmcache.cli.commands.describe import DescribeCommand

ALL_COMMANDS: list[BaseCommand] = [
    # ... existing commands ...
    DescribeCommand(),   # add here
]

至此，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() 自动添加 — 子命令无需手动添加。