CacheOS

作品简介

CacheOS 是一个面向智能体推理的 KV Cache 管理原型。它把一次智能体请求拆成更容易管理的几类内容：长期稳定的系统提示、工具定义和公共上下文会形成稳定前缀；当前会话、分支推理和工具返回会形成动态内容。系统围绕这两类内容记录缓存 key、命中情况、生命周期状态和迁移状态，让多轮对话、分支探索和工具调用过程中的 KV 复用变得可观测、可调度。

在智能体场景里，很多请求都会反复携带相似的系统提示、工具 schema、历史摘要和公共背景。CacheOS 会为这些稳定部分构造可复用的前缀标识，在 session 和 branch 之间共享公共前缀，同时为分支私有内容保留独立后缀。运行时会把请求、缓存、工具内容、上下文历史和 vLLM/LMCache 指标串起来，展示一次请求从进入系统、命中前缀、生成回答到落盘数据的完整过程。

目前项目包含四个主要部分：

• src/agentkv_lg/：CacheOS 核心逻辑，包括上下文构造、缓存 key、KV 策略、vLLM 插件和可视化服务。
• cacheos/adapters/：面向 BFCL、AgentBoard 等任务的评测适配。
• scripts/：启动 vLLM、运行 benchmark、填充测试表格的脚本。
• tests/：缓存 key、分支共享、vLLM 插件、前端 demo 等单元测试。

运行说明

以下命令默认在仓库根目录执行：

1. 安装环境并做快速验证

项目使用 Python 3.11。第一次运行时先创建虚拟环境并安装依赖：

python -m venv .venv
source .venv/bin/activate
pip install -e .

运行单元测试：

python -m unittest discover -s tests

2. 启动带 CacheOS 的 vLLM

默认启动脚本会使用 MODEL_PATH=/home/llminference/os2026/models/Qwen3-8B，服务名为 qwen3-8b。如果模型路径不同，可以通过 MODEL_PATH 覆盖。

mkdir -p logs results/kv_policy

VLLM_HOST=127.0.0.1 \
VLLM_PORT=8000 \
ENABLE_PREFIX_CACHING=1 \
ENABLE_KV_EVENTS=1 \
ENABLE_LMCACHE=1 \
VLLM_LOG_FILE=logs/vllm_cacheos.log \
CACHEOS_VLLM_REGISTRY_LOG=results/kv_policy/cacheos_vllm_registry.jsonl \
nohup scripts/start_vllm_qwen3_8b_kv.sh > logs/vllm_cacheos.stdout.log 2>&1 &

检查服务是否启动成功：

curl http://127.0.0.1:8000/health

返回正常后，可以继续启动前端。

3. 启动可视化前端

PYTHONPATH=src .venv/bin/python -m agentkv_lg.visual_demo \
  --host 127.0.0.1 \
  --port 8765 \
  --base-url http://127.0.0.1:8000/v1 \
  --model qwen3-8b \
  --online-default \
  --lmcache-log-file logs/vllm_cacheos.log \
  --cacheos-registry-log-file results/kv_policy/cacheos_vllm_registry.jsonl

浏览器打开：

http://127.0.0.1:8765

前端可以输入 query，选择 session 和 branch，观察 KV Topology、Timeline、Metrics、Tool Content、Conversation Context、Agent Answer 和 Final Data。连续发送相似请求时，可以看到稳定前缀命中、上下文累积、工具内容记录和最终指标变化。

4. 运行真实 benchmark 并生成表格

下面的脚本会依次运行吞吐与 KV 指标测试、BFCL 评测和表格填充：

RUN_ROOT=results/table_benchmarks/formal_$(date +%Y%m%d_%H%M%S) \
TABLE_REQUESTS=20 \
TABLE_MAX_TOKENS=64 \
TABLE_MODES=baseline,prefix_only,cacheos_no_offload,no_branch_share,full \
BFCL_CATEGORIES=simple_python \
BFCL_LIMIT_PER_CATEGORY=50 \
UPDATE_TEMPLATE=1 \
scripts/run_real_table_from_vllm.sh

运行日志会写入：

$RUN_ROOT/run.log

主要结果会出现在：

$RUN_ROOT/table_compare/summary.json
$RUN_ROOT/bfcl/
$RUN_ROOT/测试表格_真实数据.md

如果需要长时间运行，可以用 nohup：

RUN_ROOT=results/table_benchmarks/night_$(date +%Y%m%d_%H%M%S) \
TABLE_REQUESTS=50 \
TABLE_MAX_TOKENS=128 \
TABLE_MODES=baseline,prefix_only,cacheos_no_offload,no_branch_share,full \
BFCL_CATEGORIES=simple_python \
BFCL_LIMIT_PER_CATEGORY=100 \
UPDATE_TEMPLATE=1 \
nohup scripts/run_real_table_from_vllm.sh > /tmp/cacheos_tables.log 2>&1 &

查看运行状态：

tail -f /tmp/cacheos_tables.log

后续完善

后续会继续加强跨 session 的物理 KV 复用路径、GPU 到 CPU/disk 的迁移策略、更多真实任务的评测覆盖，以及前端对长时间 benchmark 的展示能力。