运行时插件#

LMCache 运行时插件系统提供了通过在 LMCache 进程旁边运行自定义脚本来扩展功能的能力。目前，插件可以用 Python 和 Bash 编写，并由 RuntimePluginLauncher 类管理。

关键使用案例#

启动度量报告器以进行集中监控
实现日志报告器以用于日志收集系统
将进程级别的指标报告给警报系统
实现健康检查和服务发现
自定义缓存管理操作

配置#

运行时插件通过环境变量和配置文件进行配置：

环境变量： - LMCACHE_RUNTIME_PLUGIN_ROLE：进程角色（例如，SCHEDULER，WORKER） - LMCACHE_RUNTIME_PLUGIN_CONFIG：包含插件配置的 JSON 字符串 - LMCACHE_RUNTIME_PLUGIN_WORKER_ID：当前工作线程 ID - LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT：集群中的总工作线程数

配置文件 (lmcache.yaml):

runtime_plugin_locations:
  - "/path/to/plugins"

extra_config:
  custom_setting: value

运行时插件命名约定#

插件文件名决定执行目标：

角色特定插件： - 格式：<ROLE>[_<WORKER_ID>][_<DESCRIPTION>].<EXTENSION> - 示例：

scheduler_foo_plugin.py：仅在 SCHEDULER 上运行

worker_0_test.sh: 仅在工作节点 ID 0 上运行

all_plugin.sh: 在所有工作节点上运行

注意：- 角色名称不区分大小写 - 指定时工作节点 ID 必须为数字 - 要针对特定的工作节点 ID，文件名必须至少包含三个由下划线分隔的部分（例如，worker_<ID>_<DESCRIPTION>.ext）。名为 worker_<DESCRIPTION>.ext 的文件将在所有工作节点上运行。

执行模型#

解释器检测： - 使用 shebang 行（例如，#!/opt/venv/bin/python） - 备用解释器：
- .py → python
- .sh → bash
输出处理：- 持续捕获标准输出/标准错误 - 以插件名称前缀记录
进程管理： - 作为子进程启动 - 当父进程退出时终止

示例运行时插件#

Python 插件 (scheduler_foo_plugin.py):

#!/opt/venv/bin/python
# SPDX-License-Identifier: Apache-2.0
"""Example plugin for LMCache system
This plugin runs continuously and exits when parent process terminates"""

# Standard
import json
import os
import signal
import time

# First Party
from lmcache.inprocess.integration.vllm.utils import lmcache_get_or_create_config
from lmcache.inprocess.v1.config import LMCacheEngineConfig


# Graceful exit handler
def handle_exit(signum, frame):
    print("Received termination signal, exiting...")
    exit(0)


signal.signal(signal.SIGTERM, handle_exit)

role = os.getenv("LMCACHE_RUNTIME_PLUGIN_ROLE")
worker_id = os.getenv("LMCACHE_RUNTIME_PLUGIN_WORKER_ID")
worker_count = os.getenv("LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT")
config_str = os.getenv("LMCACHE_RUNTIME_PLUGIN_CONFIG")
try:
    config = LMCacheEngineConfig.from_json(config_str)
except json.JSONDecodeError as e:
    print(f"Error parsing LMCACHE_RUNTIME_PLUGIN_CONFIG: {e}")
    config = lmcache_get_or_create_config()

print(
    f"Python plugin running with role: {role}, worker_id: {worker_id}, "
    f"worker_count: {worker_count}"
)
print(f"Config: {config}")

# Main loop
loop_count = 0
while True:
    print(f"Scheduler plugin is running... (loop_count: {loop_count})")
    loop_count += 1
    time.sleep(10)

Bash 插件 (all_plugin.sh):

#!/bin/bash
# Example plugin for LMCache system
# This plugin runs continuously and exits when parent process terminates

# Handle termination signal
trap "echo 'Received termination signal, exiting...'; exit 0" SIGTERM

role="$LMCACHE_RUNTIME_PLUGIN_ROLE"
worker_id="$LMCACHE_RUNTIME_PLUGIN_WORKER_ID"
worker_count="$LMCACHE_RUNTIME_PLUGIN_WORKER_COUNT"
config="$LMCACHE_RUNTIME_PLUGIN_CONFIG"

echo "All plugin started for role: $role, worker ID: $worker_id, worker count: $worker_count"
echo "All plugin accept LMCache Config: $config"

loop_count=0
while true; do
    echo "All plugin is running for ${role} ${worker_id}...(loop_count: ${loop_count})"
    loop_count=$((loop_count + 1))
    sleep 10
done

最佳实践#

保持运行时插件轻量和高效
使用描述性命名约定
实现优雅的错误处理
包含 shebang 以提高可移植性
验证配置输入
为长时间操作添加超时机制