块统计#

块统计功能提供了对 KV Cache 块重用模式的洞察，帮助您理解缓存效率并优化您的部署。

概述#

块统计跟踪和分析 KV Cache 块，以提供以下指标：

  • 处理的总块数：已处理的块的总数

  • 唯一块：遇到的不同块的数量

  • 重复块：重复块的数量

  • 重用率：重复块与总块的比例，指示缓存效率

此信息对以下内容很有价值：

  • 理解缓存命中模式

  • 优化缓存大小和逐出策略

  • 分析工作负载特征

  • 生产部署的容量规划

记录策略#

LMCache 支持多种记录策略，每种策略都针对不同的使用案例进行了优化：

内存布隆过滤器策略#

一种使用布隆过滤器进行概率重复检测的内存高效策略。

优点：

  • 低内存占用

  • 快速查找操作

  • 适合大规模部署

配置：

enable_chunk_statistics: true
chunk_statistics_strategy: "memory_bloom_filter"
extra_config:
  chunk_statistics_mem_bf_expected_chunks: 20000000  # Expected number of chunks
  chunk_statistics_mem_bf_false_positive_rate: 0.01  # Target false positive rate

环境变量：

LMCACHE_ENABLE_CHUNK_STATISTICS=true
LMCACHE_CHUNK_STATISTICS_STRATEGY=memory_bloom_filter
LMCACHE_EXTRA_CONFIG='{"chunk_statistics_mem_bf_expected_chunks": 20000000, "chunk_statistics_mem_bf_false_positive_rate": 0.01}'

文件哈希策略#

一种基于文件的策略，将块哈希写入磁盘，以便进行精确跟踪和离线分析。

优点：

  • 精确重复检测（无误报）

  • 离线分析的持久存储

  • 自动文件轮换和清理

配置：

enable_chunk_statistics: true
chunk_statistics_strategy: "file_hash"
extra_config:
  chunk_statistics_file_output_dir: "/tmp/lmcache_chunk_statistics"
  chunk_statistics_file_rotation_size: 104857600      # 100MB rotation size
  chunk_statistics_file_max_count: 100                # Maximum number of files

环境变量：

LMCACHE_ENABLE_CHUNK_STATISTICS=true
LMCACHE_CHUNK_STATISTICS_STRATEGY=file_hash
LMCACHE_EXTRA_CONFIG='{"chunk_statistics_file_output_dir": "/tmp/lmcache_chunk_statistics", "chunk_statistics_file_rotation_size": 104857600, "chunk_statistics_file_max_count": 100}'

快速入门指南#

步骤 1：启用块统计信息#

配置您的 LMCache 实例以启用块统计信息：

使用 YAML 配置：

# Enable internal API server for interacting with the chunk statistics API
internal_api_server_enabled: True
# Base port for the API server
# actual_port = internal_api_server_port_start + index
# Scheduler → 6999 + 0 = 6999
# Worker 0 → 6999 + 1 = 7000
internal_api_server_port_start: 6999
# Enable chunk statistics with memory bloom filter strategy
enable_chunk_statistics: true
chunk_statistics_strategy: "memory_bloom_filter"
chunk_statistics_auto_start_statistics: true

# Bloom filter configuration
extra_config:
  chunk_statistics_mem_bf_expected_chunks: 20000000
  chunk_statistics_mem_bf_false_positive_rate: 0.01

使用 vLLM 和 LMCache:

LMCACHE_CONFIG_FILE=lmcache.yaml \
PYTHONHASHSEED=0 \
python3 -m vllm.entrypoints.cli.main serve <model_path> \
--load-format dummy \
-tp 2 \
--trust-remote-code \
--served-model-name vllm_cpu_offload \
--gpu-memory-utilization 0.5 \
--max-num-seqs 64 \
--no-enable-prefix-caching \
--kv-transfer-config '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'

步骤 2：访问统计信息#

通过内部 API 服务器检索统计信息：

# Get current statistics (default port: 6999 for scheduler)
curl http://localhost:6999/chunk_statistics/status

示例响应：

{
  "enabled": true,
  "total_requests": 3,
  "timing": {
    "lookup_time_seconds": 0.044486284255981445,
    "record_statistics_time_seconds": 6.246566772460938e-05,
    "check_exit_conditions_time_seconds": 5.7220458984375e-06,
    "total_time_seconds": 0.04455447196960449,
    "overhead_time_seconds": 6.818771362304688e-05,
    "overhead_percentage": 0.1530434782608696
  },
  "total_chunks": 12,
  "unique_chunks": 9,
  "duplicate_chunks": 3,
  "reuse_rate": 0.25,
  "async_queue": {
    "enabled": true,
    "capacity": 100000,
    "current_size": 0,
    "max_size_reached": 0,
    "full_blocks": 0,
    "utilization": 0.0
  },
  "bloom_filter": {
    "size_mb": 11.426279067993164,
    "hash_count": 6,
    "item_count": 9,
    "bits_set": 54,
    "fill_rate": 5.633768549952377e-07,
    "expected_elements": 10000000,
    "false_positive_rate": 0.01
  },
  "timestamp": 1763026696.7670634,
  "auto_exit_enabled": false,
  "auto_exit_timeout_hours": 0.0,
  "auto_exit_target_unique_chunks": null
}

配置选项#

基本配置#

基本配置选项#

配置键

默认值

描述

enable_chunk_statistics

false

启用块统计跟踪

chunk_statistics_strategy

memory_bloom_filter

记录策略：memory_bloom_filter 或 file_hash

chunk_statistics_auto_start_statistics

false

在初始化时自动开始统计收集

chunk_statistics_auto_exit_timeout_hours

0.0

在指定小时后自动停止（0 = 禁用）

chunk_statistics_auto_exit_target_unique_chunks

0

达到目标唯一块后自动停止（0 = 禁用）

内存布隆过滤器选项#

在 extra_config 部分配置这些选项：

布隆过滤器配置#

配置键

默认值

描述

chunk_statistics_mem_bf_expected_chunks

20000000

容量规划的预期块数

chunk_statistics_mem_bf_false_positive_rate

0.01

目标假阳性率 (1%)

文件哈希选项#

在 extra_config 部分配置这些选项：

文件哈希配置#

配置键

默认值

描述

chunk_statistics_file_output_dir

/tmp/lmcache_chunk_statistics

存储块哈希文件的目录

chunk_statistics_file_rotation_size

104857600

文件大小阈值用于轮换（字节，默认 100MB）

chunk_statistics_file_max_count

100

保留的最大文件数量

高级用法#

程序化控制#

通过内部 API 以编程方式控制统计信息收集：

# Get current statistics (default port: 6999 for scheduler)
curl http://localhost:6999/chunk_statistics/status

# Pretty print JSON output
curl http://localhost:6999/chunk_statistics/status | jq .

# Start statistics collection (if not auto-started)
curl -X POST http://localhost:6999/chunk_statistics/start

# Stop statistics collection
curl -X POST http://localhost:6999/chunk_statistics/stop

# Reset statistics
curl -X POST http://localhost:6999/chunk_statistics/reset

自动停止配置#

根据时间或块数配置自动停止：

Prometheus 指标#

当使用内部 API 服务器时，块统计信息作为 Prometheus 指标公开：

  • lmcache_chunk_statistics_total_chunks: 处理的块的总数

  • lmcache_chunk_statistics_unique_chunks: 唯一块的数量

  • lmcache_chunk_statistics_reuse_rate: 缓存重用率 (0.0 到 1.0)

  • lmcache_chunk_statistics_bloom_filter_size_mb: 布隆过滤器内存使用量 (MB)

  • lmcache_chunk_statistics_bloom_filter_fill_rate: 布隆过滤器填充率 (0.0 到 1.0)

  • lmcache_chunk_statistics_file_count: 创建的哈希文件数量

  • lmcache_chunk_statistics_current_file_size: 当前文件大小（字节）

离线分析#

对于文件哈希策略，您可以对收集到的块哈希数据进行详细的离线分析。

使用分析脚本#

LMCache 提供了一个全面的分析脚本，位于 examples/chunk_statistics/analyze_chunk_hashes.py，支持多种分析模式。

最佳实践#

  1. 选择正确的策略：

    • 使用 memory_bloom_filter 进行实时监控，且开销最小

    • 使用 file_hash 当需要精确跟踪或进行离线分析时。

  2. 调整布隆过滤器参数:

    • 根据您的工作负载大小设置 expected_chunks

    • 降低 false_positive_rate 会增加内存使用，但提高准确性。

  3. 监控内存使用情况：

    • 跟踪 bloom_filter_size_mb 指标以确保其适合可用内存

    • 如果内存使用过高，请调整 expected_chunks。

  4. 文件轮换：

    • 配置适当的 file_rotation_size 以平衡文件大小和数量

    • 设置 file_max_count 以防止无限制的磁盘使用

  5. 生产部署：

    • 启用自动停止以防止无限期的数据收集

    • 使用内部 API 服务器进行集中式指标收集

    • 与您的监控栈集成（Prometheus、Grafana 等）

故障排除#

统计未更新#

问题： 统计数据保持为零或不更新。

解决方案：

  • 验证 enable_chunk_statistics 是否设置为 true

  • 检查统计收集是否已启动（自动启动或手动启动）

  • 确保请求正在被 LMCache 实例处理

高内存使用率#

问题： Bloom 过滤器消耗了过多的内存。

解决方案：

  • 减少 chunk_statistics_mem_bf_expected_chunks

  • 增加 chunk_statistics_mem_bf_false_positive_rate （以牺牲准确性换取内存）

  • 考虑切换到 file_hash 策略

文件系统已满#

问题： 磁盘空间耗尽，使用文件哈希策略。

解决方案：

  • 减少 chunk_statistics_file_max_count

  • 减少 chunk_statistics_file_rotation_size

  • 实现外部日志轮换或归档