内部 API 服务器

internal_api_server 提供用于在运行时管理和检查 LMCache 引擎的 HTTP API。API 被组织为三个类别：

• 通用 API — 在所有组件（调度器、工作线程、控制器）中可用。

• vLLM / 推理 API — 特定于 vLLM 推理工作节点。

• 控制器 API — 特定于 LMCache 控制器。

• 通用 API
  • GET /env — 环境变量
  • GET /loglevel — 日志级别管理
  • GET /metrics — Prometheus 指标
  • POST /metrics/reset — 重置 Prometheus 指标
  • GET /threads — 线程信息
  • GET /periodic-threads — 周期性线程状态
  • GET /periodic-threads/{thread_name} — 单个周期线程
  • GET /periodic-threads-health — 周期性线程健康检查
  • POST /run_script — 运行脚本
• vLLM / 推理 API
  • 版本与信息
  • 配置与元数据
  • 缓存操作
  • 冻结模式
  • 热缓存
  • 块统计信息
  • 查找客户端/服务器管理
  • 旁路模式
• 控制器 API
  • GET /controller/key-stats — 关键统计信息
  • GET /controller/workers — 工作信息

配置

以下参数可以在 YAML 文件中配置：

# Enable/disable the internal API server
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
# List of scheduler/worker indices: 0 for scheduler, 1 for worker 0, 2 for worker 1, etc.
internal_api_server_include_index_list: [0, 1]
# Socket path prefix for the API server. If configured, the server will use a Unix socket instead of listening on a port.
internal_api_server_socket_path_prefix: "/tmp/lmcache_internal_api_server/socket"

# Actual socket files will be:
#   /tmp/lmcache_internal_api_server/socket_6999 (scheduler)
#   /tmp/lmcache_internal_api_server/socket_7000 (worker 0)

端口分配

每个组件的端口计算公式为：

actual_port = internal_api_server_port_start + port_offset

port_offset 是：

• 0 用于调度器

• 1 + worker_id 用于工作进程（例如，工作进程 0 → 偏移 1，工作进程 1 → 偏移 2）

API 类别与路由发现

服务器使用 APIRegistry 自动发现和注册 API 端点模块。任何位于 lmcache/v1/internal_api_server/{common,vllm,controller}/ 下并导出 router = APIRouter() 的文件，名称以 *_api.py 结尾，将会被自动包含。

扩展服务器

要添加一个新的 API 端点：

1. 在适当的类别目录中创建一个新文件（common/、vllm/ 或 controller/）。

2. 将文件命名为 _api.py 后缀（例如，my_feature_api.py）。

3. 定义 router = APIRouter() 并添加你的端点。

该端点将在下次服务器启动时自动发现并注册。