LMCache Basic Check Tool 使用指南：安装验证、存储后端连通性与 KV 键生成测试

LMCache Basic Check Tool 使用指南安装验证、存储后端连通性与 KV 键生成测试【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache导读LMCache Basic Check Tool 是 LMCache 自带的测试与验证工具用于在正式接入推理引擎前快速校验安装、配置和后端连通性。本文将以docs/source/developer_guide/usage/basic_check.rst文档为骨架结合lmcache/v1/basic_check.py、lmcache/v1/check/模式注册器源码与examples/basic_check/示例配置完整讲解各检查模式、命令行参数、配置方式与底层实现原理。读完本文你可以独立完成 LMCache 远程后端fs 等连通性测试、存储管理器读写校验并为压测批量生成可复用的测试键。注意本文档对应的是 LMCache 的in-process进程内模式该模式目前已被标记为 deprecated弃用。在正式生产环境中建议优先使用功能更全面、性能更好的 LMCache MP 模式多进程模式。本文内容仅用于对旧有 in-process 部署进行自检与排障。工具定位一条命令验证 LMCache 全链路Basic Check Tool 的入口是 lmcache/v1/basic_check.py它被设计用来完成以下几类任务测试远程后端remote backend的连接建立与数据读写验证存储管理器storage manager的配置与批量化操作为性能测试生成测试键key校验配置项是否合法提供诊断信息辅助故障排查。它的核心执行模型是模式mode驱动用户通过--mode指定要运行的检查项工具通过注册器动态加载对应实现。从源码结构看所有模式实现都位于 lmcache/v1/check/ 目录下以check_mode_*.py前缀命名由init.py 中的CheckModeRegistry在运行时动态发现并注册。快速开始查看可用模式在运行任何检查之前先确认工具本身能正常导入、并查看当前环境支持哪些模式python -m lmcache.v1.basic_check --mode list输出会列出所有已注册的检查模式例如Available check modes: - gen - test_remote - test_storage_manager - test_l2_adapter从源码看模式列表由 CheckModeRegistry.load_modes() 动态生成它会扫描lmcache/v1/check/目录下所有check_mode_前缀的 Python 模块通过importlib.import_module导入再利用inspect.getmembers找出所有带有is_check_mode标记的函数由check_mode(name)装饰器设置完成注册。这意味着新增一个check_mode_xxx.py模块并加上装饰器即可自动扩展新的检查模式无需修改注册逻辑本身。如果--mode list报错或模式列表为空说明 LMCache 安装不完整或依赖缺失应首先排查安装环节详见下文配置与安装验证。检查模式详解工具支持多种检查模式每个模式针对特定功能组件下文逐一说明其作用、原理与用法。test_remote远程后端连通性测试该模式用于测试远程后端的完整功能核心覆盖与远程后端如 fs 文件系统后端建立连接put/get 操作及数据完整性校验put/get/exists 操作及性能报告输出。用法python -m lmcache.v1.basic_check --mode test_remote从实现 check_mode_test_remote.py 可以看到它的完整测试链路通过lmcache_get_or_create_config()获取配置构造默认的LMCacheMetadata默认 KV 数据类型为bfloat16默认对象大小 1024 个元素见 utils.py 中的DEFAULT_KV_DTYPE_STR与DEFAULT_OBJ_SIZE启动EventLoopManager创建LocalCPUBackendCPU 本地缓存层与RemoteBackend远程后端构造两类测试数据non_exist_*确保不存在的键和exist_*先 put 再 get 的键通过run_common_test_framework依次执行 contains → put → get 流程put 调用backend.submit_put_task并设置 10 秒超时get 调用backend.get_blocking最后用validate_get_results做数据完整性比对输出性能报告并在 finally 块中关闭后端、停止事件循环。该模式直接验证的是 lmcache/v1/storage_backend 中RemoteBackend及其底层 connector连接器的可用性——连接建立失败、读写超时、数据损坏等问题都会在这里暴露出来。test_storage_manager存储管理器验证该模式验证存储管理器StorageManager的整体操作核心覆盖配置合法性校验batched_put/batched_get 批量操作及数据完整性校验batched_put/batched_get/contains 批量操作及性能报告。用法python -m lmcache.v1.basic_check --mode test_storage_manager从实现 check_mode_test_storage_manager.py 看该模式通过create_storage_manager_with_config定义于 utils.py基于当前配置创建StorageManager成功创建即打印Test: Passed - Created storage manager with valid config这本身就是一次配置合法性验证。随后的批量读写测试走的是更高层的语义contains 通过asyncio.to_thread(storage_manager.contains, key)包装为真正异步调用避免阻塞事件循环put 调用storage_manager.batched_put([key], [memory_obj])写入后调用wait_put_tasks_complete等待远程后端落盘任务全部完成防止 get 时数据尚未持久化get 调用storage_manager.get(key)取回数据并做完整性校验。值得留意的是测试数据构造函数会为每个MemoryObj填充基于索引的独特数值模式memory_obj.tensor.fill_(float(i 1))并以ref_count_up()增加引用计数从而保证每个测试对象唯一、可区分、可正确回收。genKV 测试键生成该模式用于为性能测试和基准测试批量生成测试键特性包括可配置键的数量--num-keys与并发度--concurrency内存高效的批处理复用内存对象避免一次性分配海量内存进度条展示与性能指标输出偏移量--offset支持便于分布式环境下多节点生成互不冲突的键。用法python -m lmcache.v1.basic_check --mode gen --num-keys 1000 --concurrency 16从实现 check_mode_gen.py 看其关键设计包括内存复用batch_size min(concurrency, 100)仅创建最多 100 个MemoryObj并在批处理间以 round-robin 方式循环复用每个对象ref_count_up把内存占用压到最低流控调用flow_control_check(remote_backend, concurrency, sleep_count)当远程后端待处理任务过多时动态休眠避免一次性打爆后端队列批量写入按concurrency大小切批逐批调用storage_manager.batched_put进度可视化基于tqdm输出Generating keys进度条收尾保障全部键写入后调用wait_put_tasks_complete确保远程后端所有 put 任务真正落盘。测试键本身通过 utils.py 的create_test_key生成它基于模型名、固定 world_size8、worker_id0并用hashlib.sha256(key_id.encode())的哈希值作为chunk_hash从而保证同一key_id在不同运行中生成的键完全一致、可复现。分布式场景的 offset 用法# 节点 A生成键 gen_0 ~ gen_99 python -m lmcache.v1.basic_check --mode gen --num-keys 100 --concurrency 8 --offset 0 # 节点 B生成键 gen_100 ~ gen_199不与节点 A 冲突 python -m lmcache.v1.basic_check --mode gen --num-keys 100 --concurrency 8 --offset 100test_l2_adapterMP 模式 L2 适配器测试进阶除文档明确列出的三个模式外从 basic_check.py 的命令行参数定义和 check_mode_test_l2_adapter.py 的实现看工具还内置了test_l2_adapter模式用于验证 L2二级存储适配器。它通过--l2-adapter参数以 JSON 形式传入适配器规格例如python -m lmcache.v1.basic_check --mode test_l2_adapter \ --l2-adapter {type:mock,max_size_gb:1}该模式基于 lmcache/v1/distributed/l2_adapters 的适配器工厂创建 L2 适配器构造ObjectKey与TensorMemoryObj进行写入与读取验证。这属于 in-process 模式之外的扩展检查项可在升级到 MP 模式时用来快速验证 L2 适配器配置是否正确。命令行参数完整参考工具统一通过python -m lmcache.v1.basic_check调用入口脚本 lmcache/v1/basic_check.py 使用argparse解析参数。完整参数如下参数是否必填说明默认值--mode MODE必填要运行的操作模式传list可查看所有可用模式无--model MODEL否测试用模型名作为持久化 KV 缓存键的一部分/lmcache_test_model/--num-keys NUM否gen 模式下生成的键数量对test_*模式则作为测试迭代次数5源码实际默认值--concurrency NUM否操作并发度仅 gen 模式生效16--offset NUM否键生成的偏移量仅 gen 模式生效用于分布式测试0--l2-adapter JSON否L2 适配器规格JSON 字符串可重复传入test_l2_adapter 模式[]--obj-size NUM否测试对象大小元素个数1024DEFAULT_OBJ_SIZE--kv-dtype STR否KV 数据类型如float32、bfloat16、float16依模式而定默认bfloat16--settle-time SEC否写入完成后、读取前等待的秒数对远程后端等异步落盘场景很有用0.0说明关于--num-keys的默认值文档中描述为gen 模式默认 100但以当前仓库源码为准basic_check.py 中该参数的实际默认值为5其 help 文本也明确说明它同时用于 gen 模式的键数量与test_*模式的迭代次数。因此建议在使用时显式指定该参数避免依赖默认值产生歧义。关于 KV 数据类型的补充--kv-dtype的取值映射定义在 utils.py 中通过DTYPE_MAP来自lmcache.v1.kv_layer_groups将字符串解析为torch.dtype传入无法识别的字符串时工具会打印Error: unsupported --kv-dtype xxx并直接返回。--obj-size用于控制 KV 张量大小工具会依据_compute_kv_shape将对象大小换算为 vllm 格式的(num_layers, 2, num_tokens, num_heads, head_size)形状固定num_layers1, num_heads1并要求obj_size为偶数。配置方式与示例配置Basic Check Tool 复用的是 LMCache 现有的配置文件因此配置方式与 LMCache 本身完全一致可通过环境变量指定配置路径export LMCACHE_CONFIG_PATH/path/to/config.yaml python -m lmcache.v1.basic_check --mode test_remote官方示例配置详解examples/basic_check/目录提供了专为 basic check 优化的示例配置 example_config.yaml# LMCache Basic Check Example Configuration # This configuration file provides settings optimized for basic check operations # Basic cache settings chunk_size: 256 local_cpu: False max_local_cpu_size: 1 save_unfull_chunk: False remote_url: fs://host:0/tmp/lmcache_fs_test extra_config: save_chunk_meta: False各配置项含义如下配置项含义建议chunk_size: 256KV 缓存分块大小token 数决定缓存粒度256 是文档推荐的测试值实际生产按模型与显存调整local_cpu: False是否启用 CPU 本地缓存层纯远程后端测试可关闭以聚焦远端链路文档示例中为true视测试目标而定max_local_cpu_size: 1CPU 本地缓存最大容量单位 GB测试环境 1GB 足够按文档中 1.0 表示 1GB的语义理解save_unfull_chunk: False是否保存未填满的 chunk测试时关闭可减少无效落盘remote_url: fs://host:0/tmp/lmcache_fs_test远程后端地址此处为 fs 文件系统后端可替换为其他支持的远程后端 URLextra_config.save_chunk_meta: False扩展配置是否保存 chunk 元数据测试时关闭可减少元数据开销remote_url是测试远程后端的关键配置fs://前缀表示使用文件系统后端对应 csrc/storage_backends/fs 的实现host:0与路径共同决定存储位置。需要说明的是该示例配置与文档正文中给出的精简版local_cpu: true、remote_url: file:///tmp/lmcache_basic_check略有差异——仓库内示例以fs://协议为准两者均可按实际后端选择。使用示例配置的两种方式参考 examples/basic_check/README.md# 方式一复制到默认配置位置 cp example_config.yaml ~/.lmcache/config.yaml # 方式二通过环境变量指定推荐便于多配置切换 export LMCACHE_CONFIG_PATH$(pwd)/example_config.yaml实战示例合集以下命令组合覆盖了最常见的自检场景均可直接复制运行需要已安装 LMCache 及其依赖# 1. 查看可用模式 python -m lmcache.v1.basic_check --mode list # 2. 远程后端连通性测试使用默认配置 python -m lmcache.v1.basic_check --mode test_remote # 3. 存储管理器验证自定义模型名键名将包含该模型前缀 python -m lmcache.v1.basic_check --mode test_storage_manager --model /my_model/ # 4. 生成 100 个键、8 并发 python -m lmcache.v1.basic_check --mode gen --num-keys 100 --concurrency 8 # 5. 分布式测试带偏移量生成键多节点互不冲突 python -m lmcache.v1.basic_check --mode gen --num-keys 100 --concurrency 8 --offset 1000 # 6. 自定义 KV 数据类型与对象大小 python -m lmcache.v1.basic_check --mode test_remote --kv-dtype float16 --obj-size 2048 # 7. 针对远程后端异步落盘的 settle 时间写入后等待再读取 python -m lmcache.v1.basic_check --mode test_remote --settle-time 2.0每种测试模式的输出都包含通过/失败的明确结论test_remote与test_storage_manager会附带 put/get/exists 的性能报告gen模式会输出 tqdm 进度条和最终生成数量便于直接判断系统健康度。源码结构模式注册与测试框架解析为了让读者对工具有更深入的理解这里整理其代码组织方式均位于lmcache/v1/下lmcache/v1/ ├── basic_check.py # CLI 入口参数解析与模式分发 └── check/ ├── __init__.py # CheckModeRegistry check_mode 装饰器 ├── utils.py # 共享工具键生成、元数据、公共测试框架、性能输出 ├── check_mode_gen.py # gen 模式 ├── check_mode_test_remote.py # test_remote 模式 ├── check_mode_test_storage_manager.py # test_storage_manager 模式 └── check_mode_test_l2_adapter.py # test_l2_adapter 模式几个值得注意的实现细节注册机制CheckModeRegistry 采用懒加载loaded标志get_mode首次调用时才触发load_modes()扫描目录模式函数通过check_mode(名字)装饰器打上is_check_mode与mode_name属性完成标记。公共测试框架run_common_test_frameworkutils.py以测试上下文test_context驱动统一的 contains/put/get 流程各模式只需注入自己的异步包装函数与校验函数即可复用整套测试与性能统计逻辑这是三个测试模式代码高度一致的根本原因。键的可复现性create_test_key用sha256(key_id)生成chunk_hash配合固定world_size8与worker_id0保证同一key_id跨进程、跨运行可复现——这正是gen模式生成的键能被压测脚本直接引用的前提。自动化测试保障该工具自身带有完整的单元测试 tests/v1/test_basic_check.py覆盖了注册器的核心行为可作为理解工具内部机制的补充参考test_register_and_get验证注册与按名获取test_register_duplicate_raises验证重复注册同名模式会抛出ValueErrortest_get_mode_returns_none_for_unknown验证未知模式返回None入口脚本会打印Error: Unknown mode xxxtest_load_modes_discovers_decorated_functions通过 mockos.listdir与importlib.import_module验证动态发现机制test_load_modes_skips_import_errors验证单个模块导入失败不会导致整体加载崩溃。常见问题与排障建议--mode list为空或报 ImportError通常是安装不完整或可选依赖缺失。可先运行python -c import lmcache.v1.basic_check确认导入无误再检查是否安装了 requirements/common.txt 中的基础依赖。test_remote连接失败检查配置中的remote_url协议与路径是否正确如fs://host:0/...以及目标存储目录是否有读写权限可先用--settle-time参数增大写入到读取的等待时间排除异步落盘时序问题。test_storage_manager分配失败输出Could only allocate N/M memory objects时说明可用的 CPU 内存或缓存容量不足可调大max_local_cpu_size或减小--num-keys。gen模式生成失败确认远程后端可写、put 任务能完成flow_control_check的流控机制会自动放缓提交节奏若长期卡在进度条上优先排查远端吞吐与磁盘 IO。in-process 模式已弃用若你正在规划新的生产部署请直接参考 LMCache MP 模式文档 的安装与配置指南MP 模式提供更完整的特性支持与更优性能basic check 工具更多用于存量 in-process 环境的自检。总结Basic Check Tool 是 LMCache 安装后第一道自检的便捷入口test_remote验证远程后端链路test_storage_manager验证配置与批量读写gen为压测批量生成可复现的测试键test_l2_adapter则覆盖 MP 模式下的 L2 适配器。结合其模式注册器设计与公共测试框架你还可以通过新增check_mode_*.py模块快速扩展自定义检查项。建议在实际使用中以--mode list确认当前版本支持的模式为准并优先迁移到功能更完善的 MP 模式。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考