vLLM / 推理 API#

这些 API 特定于 vLLM 推理工作者，提供缓存管理、配置、冻结控制、块统计和版本信息。

版本与信息 #

`GET /lmc_version` — LMCache 版本 #

获取 LMCache 库版本字符串。

方法: GET
路径: /lmc_version
参数: 无
响应：纯文本版本字符串。

curl http://localhost:7000/lmc_version

`GET /commit_id` — LMCache 提交 ID #

获取 LMCache git 提交 ID。

方法: GET
路径: /commit_id
参数: 无
响应: 纯文本提交 ID 字符串。

curl http://localhost:7000/commit_id

`GET /version` — 完整版本信息 #

获取完整版本信息（版本 + 提交 ID）。

方法: GET
路径: /version
参数: 无
响应: 组合版本字符串。

curl http://localhost:7000/version

`GET /inference_info` — 推理信息 #

获取推理信息，包括 vLLM 配置和 LMCache 详细信息。

方法: GET
路径: /inference_info
参数:

名称

类型

描述

format

字符串

(可选) 保留以备将来使用
响应: application/json

curl http://localhost:7000/inference_info

错误响应 (HTTP 500):

{
  "error": "Failed to get inference info",
  "message": "..."
}

`GET /inference_version` — vLLM 版本 #

获取 vLLM 版本信息。

方法: GET
路径: /inference_version
参数: 无
响应: application/json

curl http://localhost:7000/inference_version

示例响应:

{
  "vllm_version": "0.8.0"
}

配置与元数据 #

`GET /conf` — 获取配置 #

获取当前 LMCache 引擎配置值。

方法: GET
路径: /conf
参数:

名称

类型

描述

names

字符串

（可选）以逗号分隔的配置名称列表，用于过滤。
响应: application/json — 配置键值对的 JSON 对象。

# Get all config
curl http://localhost:7000/conf

# Get specific config values
curl "http://localhost:7000/conf?names=min_retrieve_tokens,save_decode_cache"

`POST /conf` — 更新配置（实验性）#

在运行时更新一个或多个配置值。

警告

此功能目前是 实验性 的。除非在 _CONFIG_DEFINITIONS 中明确标记为 "mutable": False，否则所有配置键在运行时默认是可变的。一旦该功能稳定，默认值将更改为 不可变。

更新配置仅会修改 LMCacheEngineConfig 对象中的值。如果某个组件已经在其他地方缓存了该值，则该更改对该组件将**无效**。

方法: POST
路径: /conf
Content-Type: application/json
请求体: JSON 对象，包含配置的名称-值对。
响应: application/json

curl -X POST http://localhost:7000/conf \
  -H "Content-Type: application/json" \
  -d '{"min_retrieve_tokens": 512, "save_decode_cache": true}'

示例响应 (HTTP 200):

{
  "updated": {
    "min_retrieve_tokens": 512,
    "save_decode_cache": true
  }
}

**示例响应**（部分失败，HTTP 400）：

{
  "updated": {"min_retrieve_tokens": 512},
  "errors": {"unknown_key": "Unknown config"}
}

错误案例:

未知的配置键 → "Unknown config"
不可变配置键 → "配置在运行时不可变"
无效的 JSON 主体 → HTTP 400

`GET /meta` — 引擎元数据 #

获取 LMCache 引擎的元数据（例如，worker_id、model_name、kv_shape）。

方法: GET
路径: /meta
参数:

名称

类型

描述

names

字符串

（可选）以逗号分隔的属性名称列表，用于过滤
响应: application/json — 元数据属性的 JSON 对象。

# Get all metadata
curl http://localhost:7000/meta

# Get specific attributes
curl "http://localhost:7000/meta?names=worker_id,model_name"

缓存操作 #

`DELETE /cache/clear` — 清除缓存 #

从 LMCache 引擎中清除缓存的 KV 数据。

方法: DELETE
路径: /cache/clear
参数:

名称

类型

描述

locations

列表[str]

(可选) 要清除的存储后端（例如 LocalCPUBackend、LocalDiskBackend）。如果未指定，则清除所有。
响应: application/json

# Clear all cache
curl -X DELETE http://localhost:7000/cache/clear

# Clear specific backends
curl -X DELETE "http://localhost:7000/cache/clear?locations=LocalCPUBackend&locations=LocalDiskBackend"

示例响应:

{
  "status": "success",
  "num_removed": 10
}

`POST /cache/store` — 存储 KV Cache #

使用模拟令牌将 KV Cache 数据存储到 LMCache 引擎中。

方法: POST
路径: /cache/store
参数:

名称

类型

描述

tokens_mock

字符串

两个用逗号分隔的数字："start,end"``（例如，"0,100"`` 生成令牌 [0..99]）
响应: application/json

curl -X POST "http://localhost:7000/cache/store?tokens_mock=0,100"

示例响应:

{
  "status": "success",
  "num_tokens": 100
}

**错误响应**（缺少参数，HTTP 400）：

{
  "error": "Missing parameters",
  "message": "Must specify either tokens_input or tokens_mock"
}

`POST /cache/retrieve` — 检索 KV Cache #

使用模拟令牌从 LMCache 引擎检索 KV Cache 数据。

方法: POST
路径: /cache/retrieve
参数:

名称

类型

描述

tokens_mock

字符串

两个用逗号分隔的数字："start,end"``（例如 ``"0,100"）
响应: application/json

curl -X POST "http://localhost:7000/cache/retrieve?tokens_mock=0,100"

示例响应:

{
  "status": "success",
  "num_tokens": 100,
  "num_retrieved": 80
}

`GET /cache/kvcache/check` — KVCache 校验和 #

计算指定 slot_mapping 位置的 KVCache 的 MD5 校验和。用于验证存储和检索的 KVCache 是否相同。

方法: GET
路径: /cache/kvcache/check

参数:

名称	类型	描述
`slot_mapping`	字符串	槽索引，以逗号分隔。支持范围：`"0,1,2,3"` 或 `"1,2,3,[9,12],17,19"`
`chunk_size`	整数	每块计算每块校验和的块大小（必需）
`layerwise`	布尔值	如果 `true`，则每个块输出每层的校验和（默认值：`false`）

响应: application/json

# Per-chunk checksum (all layers combined)
curl "http://localhost:7000/cache/kvcache/check?slot_mapping=0,1,2,3&chunk_size=2"

# Per-layer per-chunk checksum
curl "http://localhost:7000/cache/kvcache/check?slot_mapping=0,1,2,3&chunk_size=2&layerwise=true"

示例响应 (layerwise=false):

{
  "status": "success",
  "slot_mapping_ranges": [[0, 3]],
  "chunk_size": 2,
  "num_chunks": 2,
  "chunk_checksums": ["abc123...", "def456..."],
  "layerwise": false
}

示例响应 (layerwise=true):

{
  "status": "success",
  "slot_mapping_ranges": [[0, 3]],
  "chunk_size": 2,
  "num_chunks": 2,
  "chunk_checksums": {
    "layer_0": ["abc123...", "def456..."],
    "layer_1": ["ghi789...", "jkl012..."]
  },
  "layerwise": true
}

`POST /cache/kvcache/record_slot` — 切换槽记录 #

在存储/检索操作期间启用或禁用 KVCache slot_mapping 日志记录。

方法: POST
路径: /cache/kvcache/record_slot
参数:

名称

类型

描述

enabled

字符串

"true" 表示启用，"false" 表示禁用。省略此项以查询当前状态。
响应: application/json

# Enable logging
curl -X POST "http://localhost:7000/cache/kvcache/record_slot?enabled=true"

# Disable logging
curl -X POST "http://localhost:7000/cache/kvcache/record_slot?enabled=false"

# Check current status
curl -X POST http://localhost:7000/cache/kvcache/record_slot

示例响应:

{
  "status": "success",
  "kvcache_check_log_enabled": true
}

`GET /cache/kvcache/info` — KVCache 信息 #

获取当前 KVCache 结构的信息，包括层名称、形状和设备信息。

方法: GET
路径: /cache/kvcache/info
参数: 无
响应: application/json

curl http://localhost:7000/cache/kvcache/info

示例响应:

{
  "status": "success",
  "num_layers": 32,
  "layers": {
    "layer_0": {
      "shape": [2, 128, 16, 64, 128],
      "dtype": "torch.bfloat16",
      "device": "cuda:0"
    }
  }
}

`POST /cache/load-fs-chunks` — 加载 FS 块 #

从 FSConnector 存储加载块文件到 LocalCPUBackend 的热缓存中。

方法: POST
路径: /cache/load-fs-chunks
Content-Type: application/json

请求体：

字段	类型	描述
`config_path`	字符串	LMCache 引擎配置 YAML 文件的路径（必填）
`max_chunks`	整数	(可选) 最大加载块数
`max_failed_keys`	整数	报告的最大失败键数（默认：10）

响应: application/json
标签: cache-management

curl -X POST http://localhost:7000/cache/load-fs-chunks \
  -H "Content-Type: application/json" \
  -d '{"config_path": "/path/to/lmcache.yaml", "max_chunks": 100}'

示例响应 (HTTP 200):

{
  "status": "success",
  "loaded_chunks": 95,
  "total_files": 100,
  "failed_keys": ["key1", "key2"],
  "config_path": "/path/to/lmcache.yaml"
}

**错误响应**（无效配置，HTTP 400）：

{
  "error": "Failed to load chunks from FSConnector",
  "message": "Configuration file not found",
  "config_path": "/path/to/lmcache.yaml"
}

冻结模式 #

`PUT /freeze/enable` — 启用冻结模式 #

为 LMCache 引擎启用冻结模式。启用后：

所有存储操作将被跳过（不存储新数据）
仅使用 local_cpu 后端进行检索
不会生成 admit/evict 消息。

这可以保护本地 CPU 热缓存不受更改。

方法: PUT
路径: /freeze/enable
参数: 无
响应: application/json

curl -X PUT http://localhost:7000/freeze/enable

示例响应:

{
  "status": "success",
  "freeze": true,
  "message": "Freeze mode enabled successfully"
}

`PUT /freeze/disable` — 禁用冻结模式 #

禁用冻结模式。存储操作将正常进行。

方法: PUT
路径: /freeze/disable
参数: 无
响应: application/json

curl -X PUT http://localhost:7000/freeze/disable

示例响应:

{
  "status": "success",
  "freeze": false,
  "message": "Freeze mode disabled successfully"
}

`GET /freeze/status` — 冻结状态 #

获取当前冻结模式状态。

方法: GET
路径: /freeze/status
参数: 无
响应: application/json

curl http://localhost:7000/freeze/status

示例响应:

{
  "status": "success",
  "freeze": true,
  "message": "Freeze mode is enabled"
}

热缓存 #

这些端点控制 LocalCPUBackend 的热缓存功能。当启用热缓存时，频繁访问的 KV Cache 数据将保留在 CPU 内存中，以便更快地检索。

`PUT /hot_cache/enable` — 启用热缓存 #

为 LocalCPUBackend 启用热缓存。

方法: PUT
路径: /hot_cache/enable
参数: 无
响应: application/json

curl -X PUT http://localhost:7000/hot_cache/enable

示例响应:

{
  "status": "success",
  "hot_cache": true,
  "message": "Hot cache enabled successfully"
}

`PUT /hot_cache/disable` — 禁用热缓存 #

禁用 LocalCPUBackend 的热缓存。现有的热缓存条目将被清除，且不会写入新数据。

方法: PUT
路径: /hot_cache/disable
参数: 无
响应: application/json

curl -X PUT http://localhost:7000/hot_cache/disable

示例响应:

{
  "status": "success",
  "hot_cache": false,
  "message": "Hot cache disabled successfully"
}

`GET /hot_cache/status` — 热缓存状态 #

获取 LocalCPUBackend 的当前热缓存状态。

方法: GET
路径: /hot_cache/status
参数: 无
响应: application/json

curl http://localhost:7000/hot_cache/status

示例响应:

{
  "status": "success",
  "hot_cache": true,
  "message": "Hot cache is enabled"
}

块统计信息 #

这些端点通过 ChunkStatisticsLookupClient 管理块级统计信息的收集。只有在查找客户端支持统计信息时，它们才可用。

查找客户端/服务器管理 #

这些端点允许对查找客户端和服务器进行运行时管理。它们对于在不重启服务的情况下动态重新配置查找机制非常有用。

重要

首先需要更新配置

在调用 /lookup/create 或 /lookup/recreate 之前，您必须首先通过 /conf API 更新配置。新的查找客户端/服务器将使用 LookupClientFactory 创建。

对于某些配置（例如，切换 enable_scheduler_bypass_lookup），您只需更新 调度器 的配置并重新创建其查找客户端。在这种情况下，工作节点无需更改。

`GET /lookup/info` — 查找客户端/服务器信息 #

获取当前查找客户端和服务器状态的信息。如果适用，显示包装链（例如，HitLimitLookupClient(LMCacheLookupClient)）。

方法: GET
路径: /lookup/info
参数: 无
响应: application/json

curl http://localhost:6999/lookup/info

**示例响应**（调度器）：

{
  "client": "HitLimitLookupClient(LMCacheBypassLookupClient)",
  "server": "None",
  "role": "scheduler"
}

示例响应 (工作者):

{
  "client": "None",
  "server": "LMCacheLookupServer",
  "role": "worker"
}

`POST /lookup/close` — 关闭查找客户端/服务器 #

关闭当前的查找客户端（调度器）或服务器（工作节点）。

方法: POST
路径: /lookup/close
参数: 无
响应: application/json

curl -X POST http://localhost:6999/lookup/close

示例响应:

{
  "old": "HitLimitLookupClient(LMCacheBypassLookupClient)",
  "role": "scheduler"
}

`POST /lookup/create` — 创建查找客户端/服务器 #

使用当前配置创建一个新的查找客户端（调度器）或服务器（工作进程）。

方法: POST
路径: /lookup/create
参数:

名称

类型

描述

dryrun

布尔值

如果为 true，则仅显示将要创建的内容。
响应: application/json

# Dryrun - preview what would be created
curl -X POST "http://localhost:6999/lookup/create?dryrun=true"

# Actually create
curl -X POST http://localhost:6999/lookup/create

**示例响应**（干运行）：

{
  "new": "LMCacheLookupClient",
  "dryrun": true,
  "role": "scheduler"
}

示例响应 (实际创建):

{
  "new": "LMCacheLookupClient",
  "role": "scheduler"
}

`POST /lookup/recreate` — 重新创建查找客户端/服务器 #

重新创建查找客户端或服务器（相当于关闭 + 创建）。该端点会根据角色自动确定哪个组件：

scheduler 角色：重新创建查找客户端
worker 角色：重新创建查找服务器
方法: POST
路径: /lookup/recreate
参数: 无
响应: application/json

使用流程:

# Step 1: Update worker configuration (if needed)
curl -X POST "http://localhost:7000/conf" \
  -H "Content-Type: application/json" \
  -d '{"enable_async_loading": true}'

# Step 2: Recreate lookup server on worker
curl -X POST "http://localhost:7000/lookup/recreate"

# Step 3: Update scheduler configuration
curl -X POST "http://localhost:6999/conf" \
  -H "Content-Type: application/json" \
  -d '{"enable_scheduler_bypass_lookup": true}'

# Step 4: Recreate lookup client on scheduler
curl -X POST "http://localhost:6999/lookup/recreate"

**示例响应**（调度器）：

{
  "old": "HitLimitLookupClient(LMCacheBypassLookupClient)",
  "new": "LMCacheLookupClient",
  "role": "scheduler"
}

示例响应 (工作者):

{
  "old": "LMCacheLookupServer",
  "new": "LMCacheAsyncLookupServer",
  "role": "worker"
}

备注

仅客户端更改

对于某些配置更改（例如，切换 enable_scheduler_bypass_lookup），您只需更新调度器的配置并重新创建其查找客户端。在这种情况下，工作节点的查找服务器无需重新创建。

`POST /chunk_statistics/start` — 开始统计 #

开始收集块统计信息。

方法: POST
路径: /chunk_statistics/start
参数: 无
响应: application/json

curl -X POST http://localhost:7000/chunk_statistics/start

示例响应:

{
  "status": "success",
  "message": "Started"
}

**错误响应**（不支持，HTTP 400）：

{
  "error": "Not available",
  "message": "Client does not support statistics."
}

`POST /chunk_statistics/stop` — 停止统计 #

停止收集块统计信息。

方法: POST
路径: /chunk_statistics/stop
参数: 无
响应: application/json

curl -X POST http://localhost:7000/chunk_statistics/stop

示例响应:

{
  "status": "success",
  "message": "Stopped"
}

`POST /chunk_statistics/reset` — 重置统计信息 #

重置所有收集的块统计信息。

方法: POST
路径: /chunk_statistics/reset
参数: 无
响应: application/json

curl -X POST http://localhost:7000/chunk_statistics/reset

示例响应:

{
  "status": "success",
  "message": "Reset"
}

`GET /chunk_statistics/status` — 统计状态 #

获取当前块统计信息和自动退出配置。

方法: GET
路径: /chunk_statistics/status
参数: 无
响应: application/json

curl http://localhost:7000/chunk_statistics/status

示例响应:

{
  "is_collecting": true,
  "total_chunks": 1000,
  "unique_chunks": 500,
  "timestamp": 1706745600.0,
  "auto_exit_enabled": true,
  "auto_exit_timeout_hours": 24.0,
  "auto_exit_target_unique_chunks": 1000
}

旁路模式 #

绕过模式允许在运行时动态跳过特定的存储后端。被绕过的后端将被排除在 contains/put/get 操作之外。这对于故障注入测试、隔离有问题的后端或在不重启引擎的情况下进行调试非常有用。

`GET /bypass/list` — 列出被绕过的后端 #

列出所有当前被绕过的后端和所有可用的后端名称。

方法: GET
路径: /bypass/list
参数: 无
响应: application/json

curl http://localhost:7000/bypass/list

示例响应:

{
  "status": "success",
  "bypassed_backends": ["RemoteBackend"],
  "all_backends": ["LocalCPUBackend", "RemoteBackend"]
}

`PUT /bypass/add` — 将后端添加到绕过列表 #

将后端添加到绕过列表中。被绕过的后端将被排除在 contains/put/get 操作之外。

方法: PUT
路径: /bypass/add
参数:

名称

类型

描述

backend_name

字符串

要绕过的后端名称（必填）
响应: application/json

curl -X PUT "http://localhost:7000/bypass/add?backend_name=RemoteBackend"

示例响应:

{
  "status": "success",
  "backend_name": "RemoteBackend",
  "bypassed": true,
  "was_already_bypassed": false,
  "bypassed_backends": ["RemoteBackend"]
}

**错误响应**（未知后端，HTTP 400）：

{
  "error": "Unknown backend",
  "message": "Backend 'FooBackend' not found. Available: ['LocalCPUBackend', 'RemoteBackend']"
}

`PUT /bypass/remove` — 从旁路列表中移除后端 #

从旁路列表中移除后端，恢复其正常操作。

方法: PUT
路径: /bypass/remove
参数:

名称

类型

描述

backend_name

字符串

恢复的后端名称（必填）
响应: application/json

curl -X PUT "http://localhost:7000/bypass/remove?backend_name=RemoteBackend"

示例响应:

{
  "status": "success",
  "backend_name": "RemoteBackend",
  "bypassed": false,
  "was_bypassed": true,
  "bypassed_backends": []
}

**错误响应**（未知后端，HTTP 400）：

{
  "error": "Unknown backend",
  "message": "Backend 'FooBackend' not found. Available: ['LocalCPUBackend', 'RemoteBackend']"
}