AgentKV-OS

面向智能体推理的内存管理系统。

在真实多轮智能体负载(单卡 H800、16 路并发、60 轮上限)上的实测结果:

优化项	实测效果	出处
任务成功率保障	两档池子均未下降(54.6k 池 p=0.804,193k 池 p=0.388,按任务配对精确检验)	RESULTS
显存占用优化	GPU KV 池压到满配的 28%(54.6k / 193k),同档 JCT 再降 116 秒(CI 不含零)	同上
上下文溢出优化	多轮会话因上下文膨胀被引擎拒收的比例:基线 23%–69% → 本系统 0(三种配置、288 会话)	同上
跨模型规模验证	换到 14B 同代码:受压档成功率 0.521 → 0.708(p=0.049)	同上
国产 OS 适配	整条推理栈在 openEuler 24.03 内端到端服务;27,648 个决策事件跨系统逐位一致	OPENEULER

其中”被引擎拒收”这条最值得先看:那些会话不是答错,是没机会答完——上下文越过模型窗口, 引擎直接返回 HTTP 400。这是调参救不了的结构性失败,也是本系统真正消除的东西。

六个推荐方向里,①③④⑤已实测、②已实现未纳入主结果、⑥(异构加速硬件)未做——逐条状态见 DESIGN 赛题对齐总表。

操作系统大赛赛题 14(高校组) · vLLM 0.10.2 + LMCache 0.3.15 · openEuler 24.03 LTS

简体中文 · English

📄 技术报告(Tech Report):doc/paper/AgentKV-OS.pdf

这个系统解决什么问题

智能体推理和单轮生成对内存的要求完全不同。一次数据分析任务要跑几十轮:模型写一行代码、看真实返回、再写下一行,上下文只增不减;会话大部分时间停在工具调用上等待,KV Cache 却一直占着显存;十几个会话并发时,推理引擎按 LRU 淘汰,分不清”正在等工具返回、马上还要用的 KV”和”已经提交答案、彻底没用的 KV”。

后果在我们的基准上是可测的:60 轮上限下,基线有 23%–69% 的会话死于上下文越过模型窗口 (引擎直接返回 HTTP 400),这些任务不是答错了,是没有机会答完。

AgentKV-OS 在两个平面上处理这件事,二者可独立开关:

KV 生命周期平面:在每次工具调用边界上,对会话 KV 做四态决策(KEEP / PIN / OFFLOAD / DROP)。四个动作折算成同一量纲(下一轮取回延迟的期望)后取最小,判据没有可调参数:OFFLOAD 优于 KEEP ⟺ save < P_evict × P_host × (rebuild − restore), 式中每个量都来自实测标定。
上下文平面:工具产生的中间数据按 full / view / handle 三级保真物化,按节点年龄降级;滞回压实让提示前缀跨轮稳定,前缀缓存持续命中。工具输出进入 KV 的 token 减少 73.3%,压缩开销是传统截断的 1/18。

AgentKV-OS 系统架构

实测结果

单卡 H800,16 路并发,同一批任务、同一批种子、优化前后硬件配置完全一致。統一在 MAX_TURNS=60 下测量,成功率用按任务配对的 McNemar 精确检验,区间为配对分层 bootstrap 95% CI。完整报告见 RESULTS.md。

指标	基线	本系统	条件
会话死于上下文溢出	23%–69%	0	8B 两档池 + 14B 受压档,共 288 会话
任务成功率(8B,54.6k 池)	0.333	0.375	9:7:32,p=0.804,不降
任务成功率(14B,57k 池)	0.521	0.708	13:4:31,p=0.049
任务完成时间 JCT(8B,54.6k)	643.1 s	527.3 s	−116 s,CI [−228.0, −2.2],显著
每会话重算 token(8B,193k)	139,897	35,642	CI [−228,002, −20,161],显著
抢占次数(8B,193k)	41.3	0	—

54.6k 池是 193k 满配的 28%,略小于三分之一;两档底线全部成立。工作点(上下文预算 16000)由四档压缩强度加无压缩对照的前沿扫描确定,是测出来的,不是选出来的。

与相关工作的差异

	vLLM / 分页 KV	LMCache / CPU 分层	上层 Agent 框架	AgentKV-OS
看得见会话语义	否	否	是,但进不了引擎	是,且进引擎
淘汰依据	LRU	LRU	无	会话状态 + 实测代价模型
上下文与 KV 联动	无	无	删文本,KV 不动	压缩即少建 KV
面向多轮增长的失败模式	溢出即 400	同左	同左	溢出为零

核心创新(三点)

把工具调用边界变成 KV 的调度点 —— 会话大部分时间停在工具调用里,KV 却一直占着显存。系统在每个工具边界对会话 KV 做四态决策(KEEP / PIN / OFFLOAD / DROP)。实测:抢占 41.3 → 0,每会话重算 token 139,897 → 35,642。
上下文压缩做成”可回取”而非”丢弃” —— 降级内容保留结构化摘要与句柄,压缩确定到 token 级(两次独立运行差 19 个 token),开销 2.0 s/会话。
判据无自由参数 —— 冷重算曲线 R²=0.99,主存层吞吐由 12,549 次真实恢复标定为 30.66 GiB/s,重算/取回平衡点 13.6 token(不足一个 vLLM 块),全部可从入库数据重算。

安装部署

部署顺序:先部署 Viper Agent Runtime(智能体与基准的载体),再安装 AgentKV-OS 本体。以下每条命令都在参考环境实跑过;踩过的坑直接写在对应步骤里。

参考环境:Linux(实测 Ubuntu 22.04 与 openEuler 24.03)、NVIDIA GPU(实测 H800 80 GiB;驱动 CUDA 12.x)、Python ≥ 3.10、磁盘约 40 GiB(模型 16 GiB + 数据与依赖)。

第 0 步 · 目录约定

mkdir -p ~/agentkv && cd ~/agentkv
export AGENTKV_PROJECT_ROOT="$PWD"      # 之后所有脚本都以它定位 viper/ 与 AgentKV-OS/
git clone git@code.gitlink.org.cn:yuzZIypPeU/mxzntdncglxtsjysx.git AgentKV-OS
# 或 HTTPS:git clone https://gitlink.org.cn/yuzZIypPeU/mxzntdncglxtsjysx.git AgentKV-OS

第 1 步 · 部署 Viper Agent Runtime

viper 是我们面向数据分析场景自研的智能体:模型写一行 pandas,真实沙箱执行,再依据返回结果写下一行,如此往复直到提交答案——赛题参考项目(LangChain、AutoGPT)描述的正是这类形态,而 viper 要解决的是模型对真实数据的自动化处理能力。它同时是本项目的基准载体,随主分支分发于仓库内 viper/ 目录(单次导入,来源与修改范围见说明书 “代码原创说明”)。

整个工具链按 $AGENTKV_PROJECT_ROOT/{AgentKV-OS, viper, models} 的同级布局定位路径, 用一根软链对齐即可:

cd "$AGENTKV_PROJECT_ROOT"
ln -sfn "$PWD/AgentKV-OS/viper" viper
cd viper

安装依赖,两条路任选:

# 路 A(标准):机器上有 poetry
poetry install

# 路 B(无 poetry;参考主机连 ensurepip 都没有,python -m venv 会造出无 pip 的空壳):
# 用任何一个带 pip 的 Python ≥3.10,把后端依赖装进旁路目录
python3 -m pip install --target /tmp/viperui-libs \
    fastapi "uvicorn[standard]" sqlalchemy aiosqlite loguru requests pyyaml tabulate
export PYTHONPATH="$PWD:/tmp/viperui-libs"

数据就位检查(基准的 8 张表、106 万行交易,随分支自带):

ls -la database/_financial/_financial.sqlite    # 应为 ~71 MB

启动并验证(此步不需要 GPU——回放模式):

AGENTKV_DASHBOARD_REPLAY="$PWD/backend/recordings/sample_agentkv.jsonl" \
  python3 -m uvicorn backend.api:app --host 0.0.0.0 --port 6456
# 另一终端:
curl -s http://localhost:6456/health            # {"status":"UP"}
# 浏览器: http://localhost:6456/mmde/app            主应用(历史会话可直接回看解题过程)
#         http://localhost:6456/mmde/app/dashboard  运行时仪表盘(指标口径页在第二个标签)

start_backend.sh 已内置 poetry 缺失时的回退;有 GPU 的现场去掉 AGENTKV_DASHBOARD_REPLAY 即为实时采集模式。对话框的实时求解走本地引擎(http://localhost:8000/v1,第 2 步部署后自然满足); 引擎未启动时,历史会话回放与仪表盘回放不受影响。

第 2 步 · 安装 AgentKV-OS

cd "$AGENTKV_PROJECT_ROOT"
python3 -m venv .venv-vllm && . .venv-vllm/bin/activate
pip install -e "AgentKV-OS[dev]"

推理栈(版本组合实测过;transformers 必须钉住——5.x 删除了 vLLM 0.10.2 读取的 all_special_tokens_extended,不钉住引擎会在 tokenizer 初始化处直接死):

pip install vllm==0.10.2 lmcache==0.3.15 transformers==4.56.2 huggingface_hub==0.36.2 \
            pandas diskcache requests

模型(任一来源,放到 $AGENTKV_PROJECT_ROOT/models/Qwen3-8B):

pip install modelscope && modelscope download --model Qwen/Qwen3-8B \
    --local_dir "$AGENTKV_PROJECT_ROOT/models/Qwen3-8B"

引擎侧四态执行(主结果的 stage-2 两臂都在打补丁引擎上运行):把 scripts/repro/patches/agentkv_engine.patch(8 文件 545 行, 附 SHA256)打到 vLLM Continuum fork 上,装进实验脚本约定的 .venv-continuum:

cd "$AGENTKV_PROJECT_ROOT"
git clone https://github.com/Hanchenli/vllm-continuum baselines/vllm-continuum
git -C baselines/vllm-continuum checkout 316a587
git -C baselines/vllm-continuum apply "$AGENTKV_PROJECT_ROOT/AgentKV-OS/scripts/repro/patches/agentkv_engine.patch"
python3 -m venv .venv-continuum
VLLM_USE_PRECOMPILED=1 .venv-continuum/bin/pip install -e baselines/vllm-continuum
.venv-continuum/bin/pip install lmcache==0.3.15 transformers==4.56.2 huggingface_hub==0.36.2

不打补丁时系统以 stage-1 运行(上下文平面 + 主存层),足以跑测试套件与上下文平面类实验;demo 与主实验复现需要上面的打补丁引擎。实验脚本按名字定位这两个虚拟环境 ($AGENTKV_PROJECT_ROOT/.venv-vllm 与 .venv-continuum),补丁明细见该目录 README。

起推理引擎(实时求解与实时仪表盘需要它)

上面的第 1 步用回放模式验证了前后端,不需要 GPU。要让对话框真的解题、仪表盘显示真实指标,起一个本地引擎即可(所有组件默认都连它):

cd "$AGENTKV_PROJECT_ROOT"
.venv-vllm/bin/python -m vllm.entrypoints.openai.api_server \
  --model "$AGENTKV_PROJECT_ROOT/models/Qwen3-8B" --port 8000 \
  --served-model-name qwen3-8b --max-model-len 32768 \
  --gpu-memory-utilization 0.40 --enable-prefix-caching \
  --guided-decoding-backend guidance

首次加载权重约 3–4 分钟;curl -s localhost:8000/v1/models 有返回即就绪。 模型放在本地盘:权重从网络文件系统读会慢一个数量级(实测同一份权重,本地盘 2 分钟、网络盘 25 分钟仍未就绪),把 models/ 放本地磁盘或先复制过去再起。引擎起来后,把第 1 步的后端改用实时模式重启(去掉 AGENTKV_DASHBOARD_REPLAY), 对话框与仪表盘即为实时。

第 3 步 · 验证

python -m pytest tests/ -q          # 参考环境:500 passed, 12 skipped
python scripts/repro/decision_parity.py | tail -3   # 打印 27,648 事件的决策哈希

在 openEuler 上验证(无 root、无 docker,rootless proot):

bash scripts/repro/openeuler_proot_bringup.sh verify   # GPU 路径
bash scripts/repro/openeuler_proot_bringup.sh test     # 测试套件(客户机自带 Python)
bash scripts/repro/openeuler_proot_bringup.sh parity   # 决策逐位一致性

五节证据(含端到端服务)见 OPENEULER.md。

第 4 步 · 跑第一个对照

# 主实验的一档(基线臂 + 系统臂 × 1 重复,约 25 分钟);
# DESCENT_TAG 给本次运行独立标签,避免与入库结果目录冲突:
MAX_TURNS=60 UTILS="0.36" DESCENT_TAG=_local bash scripts/repro/exp_memory_descent.sh 1
python -m bench.analyze_experiment \
  --root results/concurrent_qwen3-8b_real_mixed_batch_s16 \
  --baseline m_base_local --candidate m_full_local --paired-success

每次运行落盘运行契约(引擎构建标识、补丁哈希、GPU、全部受控变量)与逐会话轨迹; 报告中的汇总指标可直接对账入库的 summary.json,配对检验用的逐会话轨迹因体积不入库, 按上述命令重跑即可再生,方法见 BENCHMARK.md。

文档索引

文件	内容
DESIGN.md	技术方案、系统设计与实现细节、部署细节、消融开关表
RESULTS.md	测试报告:全部对照实验、统计结论、负面结果与撤回记录
BENCHMARK.md	负载定义、复现命令、成功率约束的适用域、该负载不适合回答什么
OPENEULER.md	openEuler 运行证据与跨发行版决策一致性
results/README.md	每次运行保存什么、哪些入库
scripts/repro/patches/	引擎补丁与说明

仓库结构

agentkv/                策略层:生命周期决策、代价模型、上下文物化、连接器
bench/                  智能体层:回放器、批量任务集(多题型家族)、严格判分、并发驱动、分析器
tests/                  63 个测试文件(参考环境 500 通过、12 跳过)
scripts/repro/          十个实验脚本 + 引擎补丁 + openEuler 引导与证据采集
results/                入库的逐次运行记录(summary/provenance/contention)
viper/                  Viper Agent Runtime(基准载体,随主分支分发)

演示视频

第三届 OS 大赛演示视频 · Deepsleep

链接:https://pan.baidu.com/s/1Fx4DFkpUMQPuHDKL8VQVnQ 提取码:jeud