AgentKV-Adaptive

作品简介

AgentKV-Adaptive 是面向本地大模型智能体场景的上下文与 KV Cache 管理系统。项目运行在 openEuler 虚拟机中，以 llama.cpp / llama-server 作为本地推理后端，以 Qwen2.5 GGUF 模型作为实验模型，在不修改 llama.cpp 内部实现的前提下，通过外部管理层优化多轮对话、工具调用、分支推理和多会话切换中的上下文复用问题。

项目重点解决的问题是：智能体连续运行时，历史对话、工具返回结果和分支状态会不断拉长提示词，导致每轮推理需要重复处理大量上下文。AgentKV-Adaptive 通过上下文分块去重、工具结果外置、稳定前缀复用、KV Slot 生命周期管理和运行时自适应策略，减少重复计算并提升现场演示中可观测的指标表现。

主要功能

• 多轮对话模式对比：支持 baseline 与 agentkv-adaptive 等模式，单轮回复后展示 latency、prompt、cached、hit、kv_eval 指标。
• 上下文优化：将稳定系统提示、历史对话、工具输出和当前问题分层管理，降低提示词重复增长带来的推理开销。
• 工具输出外置：对大规模结构化工具结果保留摘要与引用，避免把完整工具结果反复塞回提示词。
• KV Cache 生命周期管理：管理 llama-server 的 slot 保存、恢复、复用和淘汰，适配分支推理、多会话切换等场景。
• 自适应策略选择：根据当前输入、历史长度、工具输出大小、分支状态和会话压力动态选择上下文与缓存策略，而不是固定绑定某个实验场景。
• 实验与报告生成：内置四类典型场景，支持自动运行 benchmark、记录 JSONL、生成 CSV / Markdown / 图表报告。
• 前端录屏展示：提供本地 Web Dashboard，可读取脚本命令，驱动虚拟机执行对话和实验，并实时展示终端输出与图表对比。

目录结构

AgentKV-Adaptive/
├─ agentkv/                 # 核心 Python 代码：策略、上下文、KV 生命周期、推理客户端、实验与报告
├─ configs/                 # 默认运行配置和压力测试配置
├─ scripts/                 # openEuler 部署、llama.cpp 构建、模型服务启动、现场对话和场景演示脚本
├─ tests/                   # 单元测试与 mock benchmark 测试
├─ web-dashboard/           # 用于录屏展示的动态前端页面和本地服务
├─ docs/                    # 技术文档和开发说明
├─ pyproject.toml           # Python 项目配置
├─ setup.py                 # Python 安装入口
└─ README.md                # 本说明文档

本提交目录不包含 GGUF 模型权重、llama.cpp 源码压缩包、历史实验报告和运行缓存。模型和第三方源码体积较大，应按运行说明单独放置到指定路径。

环境要求

推荐环境：

• 操作系统：openEuler 22.03 LTS-SP4 虚拟机
• Python：3.9 及以上
• 推理后端：llama.cpp / llama-server
• 模型：Qwen2.5 Instruct GGUF 量化模型，例如 qwen2.5-0.5b-instruct-q4_k_m.gguf
• Python 依赖：requests、pyyaml、tqdm、matplotlib
• 前端展示：Windows 主机安装 Node.js，并可通过 SSH 访问 openEuler 虚拟机

默认路径约定：

/opt/agentkv-manager                         # 本项目代码
/opt/agentkv                                 # AgentKV 运行数据目录
/opt/agentkv/models/qwen2.5-0.5b-instruct-q4_k_m.gguf
/opt/llama.cpp/build/bin/llama-server

openEuler 虚拟机部署

将本目录复制到虚拟机后，建议放到 /opt/agentkv-manager：

cd /opt
cp -r AgentKV-Adaptive /opt/agentkv-manager
cd /opt/agentkv-manager

安装基础依赖并创建运行目录：

bash scripts/setup_vm.sh
python3 -m pip install -e .
agentkv init --base-dir /opt/agentkv --reset-db

如果虚拟机无法联网，但依赖已经提前安装，可使用：

python3 setup.py develop --no-deps
agentkv init --base-dir /opt/agentkv --reset-db

准备 llama.cpp 和模型

由于模型权重和第三方源码不随本提交目录上传，需要提前准备：

mkdir -p /opt/src /opt/agentkv/models

将 llama.cpp 源码压缩包放到：

/opt/src/llama.cpp.zip

将 GGUF 模型放到：

/opt/agentkv/models/qwen2.5-0.5b-instruct-q4_k_m.gguf

构建 llama-server：

cd /opt/agentkv-manager
bash scripts/build_llama_cpp.sh

启动 llama-server：

cd /opt/agentkv-manager
nohup bash scripts/start_llama_server.sh > /opt/agentkv/reports/llama-server.log 2>&1 &
agentkv health --server-url http://127.0.0.1:8080

看到 ok 表示模型服务已可访问。

基础命令

初始化 AgentKV 运行目录：

agentkv init --base-dir /opt/agentkv --reset-db

检查 llama-server：

agentkv health --server-url http://127.0.0.1:8080

使用 mock 模式快速验证代码链路，不依赖模型服务：

agentkv bench --scenario all --mode all --mock --turn-limit 4 --out /opt/agentkv/reports/mock-run.jsonl
agentkv report --input /opt/agentkv/reports/mock-run.jsonl --out /opt/agentkv/reports/mock-report.md

运行真实 benchmark：

agentkv bench --scenario all --mode all --turn-limit 4 --out /opt/agentkv/reports/real-run.jsonl
agentkv report --input /opt/agentkv/reports/real-run.jsonl --out /opt/agentkv/reports/real-report.md

现场多轮对话展示

直接运行脚本：

cd /opt/agentkv-manager
python3 scripts/ak_chat.py

baseline 模式：

python3 scripts/ak_chat.py --baseline

adaptive 模式：

python3 scripts/ak_chat.py --ada

每次模型回复后会显示五个核心指标：

[metrics] latency=1.056s prompt=60 cached=0 hit=0.0% kv_eval=0.3735MB

指标含义：

• latency：本轮从发起请求到拿到回复的耗时。
• prompt：本轮发送给模型的提示词 token 数。
• cached：本轮命中的提示词缓存 token 数。
• hit：缓存命中率，等于 cached / prompt。
• kv_eval：本轮仍需重新评估的 KV Cache 估算量。

如果希望在虚拟机中用短命令展示，可创建命令入口：

ln -sf /opt/agentkv-manager/scripts/ak_chat.py /usr/local/bin/chat
chmod +x /opt/agentkv-manager/scripts/ak_chat.py

之后可直接输入：

chat
chat --ada

四类场景快速对比展示

安装四个场景短命令：

chmod +x /opt/agentkv-manager/scripts/ak_scenario_demo.py
ln -sf /opt/agentkv-manager/scripts/ak_scenario_demo.py /usr/local/bin/demo-longchat
ln -sf /opt/agentkv-manager/scripts/ak_scenario_demo.py /usr/local/bin/demo-tool
ln -sf /opt/agentkv-manager/scripts/ak_scenario_demo.py /usr/local/bin/demo-branch
ln -sf /opt/agentkv-manager/scripts/ak_scenario_demo.py /usr/local/bin/demo-session

四个命令分别对应：

demo-longchat     # 长对话场景，观察历史增长和缓存复用
demo-tool         # 工具调用场景，观察工具结果外置和提示词缩减
demo-branch       # 分支推理场景，观察分支状态保存和恢复
demo-session      # 多会话场景，观察多个会话之间的 slot 复用压力

每个命令默认运行 4 轮 baseline 和 4 轮 adaptive，并在最后输出汇总对比：

=== Summary: longchat ===
mode              turns  avg_latency  prompt  cached  hit     kv_eval    success
baseline              4       ...
agentkv-adaptive      4       ...

delta(adaptive vs baseline): latency=... prompt=... kv_eval=... hit_gain=...

如需调整轮数：

demo-longchat --turns 6
demo-tool --turns 6
demo-branch --turns 6
demo-session --turns 6

前端动态展示

web-dashboard 用于录屏展示。它在 Windows 主机上启动本地页面，通过 SSH 调用 openEuler 虚拟机里的 chat 和 demo-* 命令，然后将终端输出解析为图表。

准备命令脚本，默认路径为 C:\Users\微星\Desktop\chat.txt，内容示例：

chat
who are you?
what color is an apple?
q
chat --ada
who are you?
what color is an apple?
q

demo longchat
demo tool
demo branch
demo session

在 Windows 主机启动前端：

cd /d "G:\研究生文献\日常通知\研二下\比赛\提交\AgentKV-Adaptive\web-dashboard"
start-live-dashboard.cmd

浏览器访问：

http://127.0.0.1:5180/

如果虚拟机 IP 不是默认的 192.168.18.130，先设置环境变量：

set AGENTKV_VM=root@你的虚拟机IP
start-live-dashboard.cmd

如果命令脚本不在桌面，设置：

set CHAT_SCRIPT_PATH=C:\path\to\chat.txt
start-live-dashboard.cmd

测试

在不启动模型服务的情况下，可先运行单元测试和 mock benchmark：

cd /opt/agentkv-manager
python3 -m pytest -q
agentkv bench --scenario all --mode all --mock --turn-limit 2 --out /opt/agentkv/reports/test-run.jsonl
agentkv report --input /opt/agentkv/reports/test-run.jsonl --out /opt/agentkv/reports/test-report.md

前端服务语法检查：

node --check web-dashboard/server.js

说明

• baseline 表示完整历史直接拼接到提示词中，作为未使用 AgentKV 优化的对照模式。
• agentkv-adaptive 表示根据运行时状态动态选择上下文压缩、工具结果外置、缓存复用和生命周期管理策略。
• 本项目的核心目标不是修改模型本身，而是在本地推理服务之外增加一层智能体记忆管理能力，使长上下文、多工具、多分支、多会话场景更适合在资源受限的 openEuler 虚拟机中运行和展示。