独立启动器#

LMCache 独立启动器允许您将 LMCacheEngine 作为独立服务运行，而无需 vLLM 或 GPU 依赖。这对于以下情况特别有用：

  • 测试和开发环境

  • 仅 CPU 或 P2P 后端部署

快速开始#

基本用法#

# Start with default configuration
python -m lmcache.v1.standalone

# Start with custom configuration file
python -m lmcache.v1.standalone --config examples/cache_with_configs/example.yaml

# Start with environment variables
export LMCACHE_CONFIG_FILE=examples/cache_with_configs/example.yaml
python -m lmcache.v1.standalone

CPU-Only 模式#

python -m lmcache.v1.standalone \
    --config examples/cache_with_configs/example.yaml \
    --model_name my_model \
    --worker_id 0 \
    --world_size 1

远程 P2P 模式#

待添加

配置部分#

独立启动器支持多个配置源，优先级顺序如下：

  1. **命令行参数**（最高优先级）

  2. **配置文件**（由 --config 或 LMCACHE_CONFIG_FILE 指定）

  3. **环境变量**（例如，LMCACHE_CHUNK_SIZE=512）

  4. **默认值**（最低优先级）

参数详细信息#

KV Cache 形状规范

--kvcache_shape_spec 参数支持多层组配置：

  • 格式: (shape_string):dtype:layer_count;[...]

  • shape_string: 以逗号分隔的形状（例如，'2,2,256,4,16'）

  • 示例： - 单个组：(2,2,256,4,16):float16:2 - 多个组：(2,2,256,4,16):float16:2;(3,2,256,4,4):float32:3

设备支持

  • --device=cpu: 仅 CPU 模式（默认）

  • --device=cuda: CUDA GPU 加速

  • --device=xpu: XPU GPU 加速

多级注意力 (MLA)

  • --use_mla: 启用 MLA 以提高注意力性能

  • 需要兼容的模型和配置

缓存格式

  • --fmt=vllm: vLLM 兼容格式（默认）

  • 支持其他格式以适应不同的推理引擎

命令行参数#

基本参数#

--config CONFIG_FILE             # Path to configuration file
--model_name MODEL_NAME          # Model name for cache identification
--worker_id WORKER_ID            # Worker ID (default: 0)
--world_size WORLD_SIZE          # Total workers (default: 1)
--kv_dtype {float16,float32,bfloat16,uint8}  # KV cache data type
--kv_shape KV_SHAPE              # KV cache shape (default: "2,2,256,4,16")
--kvcache_shape_spec SPEC       # Multi-group KV shape specification
--device {cpu,cuda,xpu}          # Device to run on (default: cpu)
--fmt FORMAT                     # Cache format (default: vllm)
--use_mla                        # Enable MLA (Multi-Level Attention)

使用示例#

自定义配置#

python -m lmcache.v1.standalone \
    --config examples/cache_with_configs/example.yaml \
    --chunk_size=512 \
    --max_local_cpu_size=4.0 \
    --model_name=custom_model

多层组配置#

python -m lmcache.v1.standalone \
    --config examples/cache_with_configs/example.yaml \
    --kvcache_shape_spec="(2,2,256,4,16):float16:2" \
    --kv_shape="2,2,256,4,16" \
    --model_name=multi_group_model \
    --device=cpu

GPU 设备#

python -m lmcache.v1.standalone \
    --config examples/cache_with_configs/example.yaml \
    --kvcache_shape_spec="(2,2,256,4,16):float16:2" \
    --kv_shape="2,2,256,4,16" \
    --kv_dtype=float16 \
    --device=cuda \
    --use_mla \
    --model_name=gpu_model

MLA 配置#

python -m lmcache.v1.standalone \
    --config examples/cache_with_configs/example.yaml \
    --kv_shape="16,2,512,16,64" \
    --kv_dtype=bfloat16 \
    --use_mla \
    --fmt=vllm \
    --model_name=mla_model

内部 API 服务器#

独立启动器包括一个用于监控和管理的内部 API 服务器：

python -m lmcache.v1.standalone \
    --config examples/cache_with_configs/example.yaml \
    --chunk_size=512 \
    --max_local_cpu_size=4.0 \
    --model_name=custom_model \
    --internal_api_server_enabled=True

故障排除#

常见问题#

问题: “未指定配置文件” 解决方案: 设置 LMCACHE_CONFIG_FILE 或使用 --config 参数

问题: “无法连接到控制器” 解决方案: 首先启动控制器: python -m lmcache.v1.api_server

问题: "无效的 KV 形状规范" 解决方案: 检查格式: (shape):dtype:layer_count，例如，(2,2,256,4,16):float16:2

问题: "设备不可用" 解决方案: 验证设备支持: 如果 GPU 不可用，请使用 --device=cpu

问题: "MLA 配置错误" 解决方案: 确保模型兼容并检查 --use_mla 参数

调试模式#

启用调试日志以进行故障排除：

export LMCACHE_LOG_LEVEL=DEBUG
python -m lmcache.v1.standalone

高级调试#

有关详细的层组信息：

export LMCACHE_LOG_LEVEL=DEBUG
python -m lmcache.v1.standalone \
    --kvcache_shape_spec="(2,2,256,4,16):float16:2;(3,2,256,4,4):float32:3" \
    --device=cpu

性能调优#

内存配置#

# For systems with large memory
--max_local_cpu_size=8.0

# For memory-constrained systems
--max_local_cpu_size=1.0

层组优化#

# Optimize for mixed precision models
--kvcache_shape_spec="(2,2,256,4,16):float16:2;(3,2,256,4,4):bfloat16:3"

# Optimize for different layer configurations
--kvcache_shape_spec="(2,2,512,8,32):float16:4;(4,2,256,16,16):float32:2"

GPU 加速#

# GPU-optimized configuration
--device=cuda --kv_dtype=float16 --use_mla

# Large model on GPU
--device=cuda --kv_shape="64,2,512,64,128" --max_local_cpu_size=16.0

MLA 性能#

# Enable MLA for attention optimization
--use_mla --kv_dtype=bfloat16 --device=cuda

# MLA with custom shape
--use_mla --kv_shape="32,2,1024,32,64" --fmt=vllm

最佳实践#

  1. 在生产环境中使用配置文件

  2. 根据可用内存设置适当的缓存大小

  3. 启用内部 API 以进行监控和管理

  4. **监控日志**以进行性能和错误跟踪

  5. 使用多层组配置 以支持复杂的模型架构

  6. 启用 MLA 以在支持的硬件上提高注意力性能

  7. 根据可用资源（CPU/GPU/XPU）选择合适的设备

  8. 在部署之前 验证 KV 形状规范

  9. **在配置新层组时**进行调试日志测试

  10. 为特定硬件配置优化块大小

多层组最佳实践#

  • 在层组之间使用一致的块大小以获得最佳性能

  • 将具有相似精度要求的层分组在一起

  • 首先在开发环境中验证形状规范

  • 在使用多个层组时监控内存使用情况

MLA 配置提示#

  • 仅在支持的硬件配置上启用 MLA

  • 使用 bfloat16 或 float16 精度以获得最佳 MLA 性能

  • 在生产部署之前测试 MLA 性能影响

  • 启用 MLA 后监控注意力性能指标