通用 API#

所有组件（调度器、工作者、控制器）都提供公共 API。

GET /env — 环境变量#

获取运行进程的所有环境变量。

  • 方法: GET

  • 路径: /env

  • 参数: 无

  • 响应: application/json — 所有环境变量的 JSON 对象（按键排序）。

curl http://localhost:7000/env

示例响应：

{
  "HOME": "/root",
  "PATH": "/usr/local/bin:/usr/bin",
  "PYTHONPATH": "/app"
}

GET /loglevel — 日志级别管理#

获取或设置 Python 日志记录器的日志级别。行为取决于查询参数：

  • 无参数：列出所有记录器及其级别。

  • ``logger_name`` 仅: 获取指定记录器的级别。

  • ``logger_name`` 和 ``level``: 设置指定记录器（包括其所有处理程序）的级别。

  • 方法: GET

  • 路径: /loglevel

  • 参数:

    名称

    类型

    描述

    logger_name

    字符串

    (可选) 查询或设置的日志记录器名称

    level

    字符串

    (可选) 设置的日志级别 (例如 DEBUG, INFO, WARNING, ERROR)

  • 响应: text/plain

# List all loggers
curl http://localhost:7000/loglevel

# Get a specific logger level
curl "http://localhost:7000/loglevel?logger_name=lmcache.v1.cache_engine"

# Set a specific logger level
curl "http://localhost:7000/loglevel?logger_name=lmcache.v1.cache_engine&level=DEBUG"

**示例响应**（列出所有）：

=== Loggers and Levels ===
lmcache.v1.cache_engine: WARNING
lmcache.v1.storage_backend: INFO

**示例响应**（获取）：

lmcache.v1.cache_engine: WARNING

示例响应 (设置):

Set lmcache.v1.cache_engine level to DEBUG (including all handlers)

**错误响应**（无效级别，HTTP 400）：

Invalid log level: INVALID_LEVEL

GET /metrics — Prometheus 指标#

以标准展示格式获取 Prometheus 指标数据。

  • 方法: GET

  • 路径: /metrics

  • 参数: 无

  • 响应: text/plain — Prometheus 文本格式的展示。

curl http://localhost:7000/metrics

POST /metrics/reset — 重置 Prometheus 指标#

重置所有 Prometheus 指标为其初始状态。

  • 方法: POST

  • 路径: /metrics/reset

  • 参数: 无

  • 响应: text/plain — "ok" 表示成功。

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

GET /threads — 线程信息#

获取有关活动线程的信息，并可选择性地进行过滤。

  • 方法: GET

  • 路径: /threads

  • 参数:

    名称

    类型

    描述

    name

    字符串

    (可选) 按线程名称过滤（模糊匹配，大小写不敏感）

    thread_id

    整数

    （可选）按线程 ID 过滤

  • 响应: text/plain — 包含堆栈跟踪和摘要的线程信息。

# Get all threads
curl http://localhost:7000/threads

# Filter by name
curl "http://localhost:7000/threads?name=api-server"

# Filter by thread ID
curl "http://localhost:7000/threads?thread_id=12345"

GET /periodic-threads — 周期性线程状态#

获取有关注册的周期性线程的信息。

  • 方法: GET

  • 路径: /periodic-threads

  • 参数:

    名称

    类型

    描述

    level

    字符串

    (可选) 按线程级别过滤：critical、high、medium、low

    running_only

    布尔值

    (可选) 仅显示正在运行的线程（默认值：false）

    active_only

    布尔值

    (可选) 仅显示活动线程（默认值：false）

  • 响应: application/json

# Get all periodic threads
curl http://localhost:7000/periodic-threads

# Filter by level
curl "http://localhost:7000/periodic-threads?level=critical"

# Only running threads
curl "http://localhost:7000/periodic-threads?running_only=true"

示例响应：

{
  "summary": {
    "total_count": 5,
    "running_count": 3,
    "active_count": 3,
    "by_level": {
      "critical": {"total": 1, "running": 1, "active": 1},
      "high": {"total": 2, "running": 1, "active": 1}
    }
  },
  "threads": [
    {
      "name": "heartbeat",
      "level": "critical",
      "is_running": true,
      "is_active": true,
      "last_run_time": "2025-01-01T00:00:00",
      "interval": 10.0
    }
  ]
}

**错误响应**（无效级别，HTTP 400）：

{
  "error": "Invalid level: unknown. Valid values: critical, high, medium, low"
}

GET /periodic-threads/{thread_name} — 单个周期线程#

通过名称获取特定周期线程的详细信息。

  • 方法: GET

  • 路径: /periodic-threads/{thread_name}

  • 路径参数：

    名称

    类型

    描述

    thread_name

    字符串

    周期性线程的名称

  • 响应: application/json

curl http://localhost:7000/periodic-threads/heartbeat

**错误响应**（未找到，HTTP 404）：

{
  "error": "Thread not found: heartbeat"
}

GET /periodic-threads-health — 周期性线程健康检查#

对周期性线程的快速健康检查。如果所有 critical 和 high 级别的线程都处于活动状态，则返回健康状态。

  • 方法: GET

  • 路径: /periodic-threads-health

  • 参数: 无

  • 响应: application/json

curl http://localhost:7000/periodic-threads-health

**示例响应**（健康）：

{
  "healthy": true,
  "unhealthy_count": 0,
  "unhealthy_threads": []
}

**示例响应**（不健康）：

{
  "healthy": false,
  "unhealthy_count": 1,
  "unhealthy_threads": [
    {
      "name": "heartbeat",
      "level": "critical",
      "last_run_ago": 120.5,
      "interval": 10.0
    }
  ]
}

POST /run_script — 运行脚本#

在受限的沙箱环境中上传并执行 Python 脚本。该脚本可以访问 app``（FastAPI 应用实例）和有限的内置函数。导入仅限于在 ``script_allowed_imports 中配置的模块。

  • 方法: POST

  • 路径: /run_script

  • 内容类型: multipart/form-data

  • 参数:

    名称

    类型

    描述

    script

    文件

    要执行的 Python 脚本文件

  • 响应: text/plain — 脚本中的 result 变量，或者如果没有设置 result 则为 "脚本执行成功"。

curl -X POST http://localhost:7000/run_script \
  -F "script=@/path/to/scratch.py"

示例脚本 (scratch.py):

lmcache_engine = app.state.lmcache_adapter.lmcache_engine

result = {
    "is_first_rank": lmcache_engine.metadata.is_first_rank(),
    "model_version": lmcache_engine.metadata.kv_shape,
}

示例响应：

{'is_first_rank': True, 'model_version': (27, 1, 64, 1, 576)}

**错误响应**（无脚本，HTTP 400）：

No script file provided

**错误响应**（执行错误，HTTP 500）：

Error executing script: Import of 'os' is not allowed