AgentMem：智能体推理内存管理系统

本项目为操作系统开源创新大赛参赛作品（赛题：面向智能体的内存管理系统设计与实现），针对 LLM Agent 在长生命周期、多轮工具调用、多会话并发场景中的 KV Cache 膨胀、上下文冗余、工具结果挤占上下文与抢占重算问题，构建了一套运行在 openEuler + Ascend 910B2C + vLLM-Ascend 上的内存管理优化系统。

系统不修改 vLLM 内核，通过配置驱动的引擎参数、KV connector、上下文中间件与 session 生命周期策略接入五项优化能力，并提供统一 Benchmark、运行元数据归档与 Gradio 实时演示界面。

系统架构

应用场景

多轮工具调用的 Agent 服务：客服/运维 Agent 长会话中历史消息与工具定义重复进入上下文，F2 静态精简 + 协议感知压缩降低 Prompt 规模。
大型工具结果消费场景：检索、数据库查询、日志分析等返回大型 JSON/HTML/CSV，F3 将结果外置存储、上下文只驻留摘要与引用，按需精确取回，避免 Context Overflow。
显存受限的多 Agent 并发部署：国产 NPU 单卡 HBM 有限，F1 C8 int8 量化使同预算 KV 容量翻倍，F4 将冷 KV 分级下沉 CPU/Disk。
高并发会话网关：多会话同时涌入导致 KV-pool 溢出、被动抢占与重复 prefill，F5 按 KV 水位动态准入，前置防止溢出。

主要功能

模块	解决的问题	主要实现	对应配置
F1 C8 int8 KV 量化	BF16 KV 占用高、并发容量低	post-RoPE 自校准、Qwen2/Qwen3 C8 注入、Ascend 量化启动参数	`src/configs/f1-bench-c8.yaml`
F2 上下文压缩	多轮历史与固定提示重复进入上下文	LLMLingua-2、冷热分层、增量复用、工具协议字段保护	`src/configs/f2-compress.yaml`
F3 工具数据外置	大型 JSON/HTML/CSV 工具结果挤占 KV	SQLite/内存 ArtifactStore、确定性摘要、有界按需检索	`src/configs/f3-lazyload.yaml`
F4 KV 分层存储	HBM 容量限制冷 KV 留存	`LMCacheAscendConnector`，NPU/CPU/Disk 分层	`src/configs/f4-lmcache.yaml`
F5 会话感知调度	多会话并发导致 KV 池溢出和抢占重算	KV-pool 水位滞回准入、并发 session 驱动	`src/configs/f5-evict-dynamic.yaml`

主要观测结果（不同模块 workload、运行次数与统计口径不同，不可横向比较，完整边界条件见对应报告）：

模块	主要观测	报告
F1	同 HBM 预算下 KV Token 容量 `775,936 → 1,556,992`（2.007×）	F1 Benchmark
F2	τ-bench 115 任务同轨迹配对 Prompt −19.38%，无 transport/runtime 错误	F2 115-task 结果
F3	LongBench first100 累计 Prompt −66.7%，TTFT 中位数 −87%	F3 first100 结果
F4	当前 workload 单 Agent p50 −21%、并发 4 QPS +32%	F4 集成与结果
F5	烟测抢占 2→0、KV 命中率 0.797→0.921、p50 83 s→43 s	F5 模块说明

目录结构

.
├── README.md                # 本文件
├── 作品原创承诺书.pdf
├── src/                     # 项目源代码
│   ├── agent_mem/           #   核心 Python 包
│   │   ├── server/          #     vLLM-Ascend 引擎封装
│   │   ├── agent/           #     ReAct Agent 与 τ-bench Agent
│   │   ├── middleware/      #     F2 压缩 / F3 外置中间件
│   │   ├── kv/              #     F1 C8 量化 / F4 分层 connector
│   │   ├── scheduler/       #     F5 准入控制与会话调度
│   │   ├── bench/           #     Benchmark 框架与指标
│   │   └── demo/            #     Gradio 演示界面
│   ├── configs/             #   baseline、F1–F5 与组合配置（YAML）
│   ├── benchmarks/          #   Benchmark CLI 与专项基准
│   ├── scripts/             #   校准、实验编排与分析脚本
│   └── docker/              #   容器化部署文件
├── tests/                   # 测试及验证材料：35 个单测脚本（324 项）+ results/ 实测结果 + env/ 实验环境
├── docs/                    # 决赛文档（4 份 PDF）+ reports/ 设计与技术报告
├── demo/                    # 可验证交付物（演示快速上手 + screenshots/）
└── presentation/            # 决赛现场演示 PPT + 决赛演示视频

运行时目录约定（均不入库，由 .gitignore 管理）：logs/ 实验日志、models/ 模型权重、third_party/ 第三方克隆体（版本清单见 docs/reports/third-party-versions.md）、.venv*/ 虚拟环境。

系统环境

基础开发环境（配置校验、单元测试、dry-run）：

Python >=3.11,<3.13；Linux，验证环境为 openEuler 24.03
CPU 即可运行 pytest（324 项）、ruff 与 benchmark dry-run

Ascend 真机环境（真实性能评测与演示）：

Ascend 910B2C，64 GiB HBM
CANN 9.0.0 及 Ascend 910B 算子包
PyTorch 2.10.0、torch-npu 2.10.0.post2
vLLM 0.22.1、vllm-ascend 0.22.1rc1、LMCache
Qwen2.5-7B-Instruct（主）/ Qwen3-0.6B（冒烟）模型权重

完整安装过程、固定版本与已知问题见环境搭建指南、安装状态与第三方版本清单。模型权重不入库，按 models/<模型名>/ 约定存放。

依赖要求

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev,demo]" qwen-agent   # dev=pytest/ruff，demo=gradio/plotly

运行 τ-bench 真任务前按版本清单安装第三方依赖：

git clone https://github.com/sierra-research/tau-bench third_party/tau-bench
python -m pip install -e third_party/tau-bench

F2 的 LLMLingua-2 压缩器使用独立 venv（.venv-compress/，由 src/configs/f2-compress.yaml 的 worker_venv 指定）；F4 与 Ascend 引擎需额外原生依赖（CANN、torch-npu 等），见环境搭建指南。不要把虚拟环境、模型权重或 Hugging Face 缓存提交到仓库。

构建方法

# 从仓库根目录
python -m pip install -e .            # 核心依赖 pyyaml/httpx/openai
python -m pip install -e ".[dev,demo]" # + 开发与演示依赖

容器方式（可选）：docker compose -f src/docker/compose.yml up（需先完成 NPU 设备挂载与 Ascend 环境变量，见 src/docker/compose.yml 注释）。

运行方法

以下命令均从仓库根目录执行。

1. 启动 Ascend 推理引擎（NPU、CANN、模型权重就绪后）：

source /usr/local/Ascend/ascend-toolkit/set_env.sh
source .venv/bin/activate

python -m agent_mem.server.vllm_server \
  --config src/configs/prefix_cache.yaml \
  --model-path models/Qwen2.5-7B-Instruct \
  --tool-call-parser hermes \
  --port 8000 \
  --log-file logs/engine.log

OpenAI 兼容 API：http://127.0.0.1:8000/v1；Prometheus 指标：http://127.0.0.1:8000/metrics。 F1 C8 运行前必须完成真实 post-RoPE 校准（占位 scale 仅用于链路探针，不能用于评测），步骤见 F1 C8 注入说明。

2. 启动演示界面（另一终端）：

source .venv/bin/activate
python -m agent_mem.demo \
  --engine-url http://127.0.0.1:8000/v1 \
  --model Qwen2.5-7B-Instruct \
  --model-path models/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 --port 7860

浏览器访问 http://<服务器地址>:7860（远程可 SSH 端口转发）。界面含 Agent 对话、F2/F3 上下文任务、F1/F4 KV 优化、F5 高并发专项与实时监控，详见 demo/README.md。

3. 运行真实 Benchmark：

python src/benchmarks/runner.py \
  --config src/configs/prefix_cache.yaml \
  --runner qwen-agent \
  --engine-url http://127.0.0.1:8000/v1 \
  --device npu --max-tasks 10 --max-steps 20 --max-concurrency 1

结果写入 logs/，每个 run 归档配置副本、Git commit、环境快照、指标与运行日志。需要外部 user simulator 的配置只从声明的环境变量读取密钥（如 MIMO_KEY），勿将密钥写入 YAML、日志或提交历史。

测试方法

python -m pytest tests -q                  # 324 项单测（CPU 即可；tau_bench 等重依赖自动跳过）
python -m ruff check src/agent_mem tests   # 代码规范（与 CI 同口径）
python src/benchmarks/runner.py \
  --config src/configs/prefix_cache.yaml \
  --runner dry-run --runs 1                # 配置/运行目录/指标链路自检
python -m pytest --cov=src/agent_mem --cov-fail-under=60   # CI 同口径覆盖率门

F1–F5 各模块的实测验证材料（workload、运行次数、统计口径、原始结论）见 tests/results/；全部测试材料的清单与使用方法见 tests/README.md。

已知限制

统计口径：各模块实验的 workload、运行次数与口径不同，结果不能横向比较；结论以对应报告标注的边界条件为准。
F1 必须真实校准：C8 占位 scale 仅用于链路探针，未做 post-RoPE 真校准时不能用于结果评测。
F3 成功率代价：最佳观测成功率比重测 baseline 低约 3 pp（检索型压缩的固有权衡），详见 F3 报告。
F5 复现范围：已验证烟测与公平实验；完整多工况重复实验需按 docs/reports/F5-technical-report.md 的设计复跑。
dry-run 不代表性能：dry-run 只验证配置与指标链路。
F4 未触发 offload 的 workload 中 HBM 峰值持平：分层收益体现在时延与并发吞吐。

文档

文档	位置
项目说明书（决赛版）	`docs/项目说明书.pdf`
项目创新说明	`docs/项目创新说明.pdf`
成员分工及主要贡献说明	`docs/成员分工及主要贡献说明.pdf`
人工智能及第三方工具使用说明	`docs/人工智能及第三方工具使用说明.pdf`
技术设计方案 / F1–F5 技术报告	`docs/reports/`
指标目录与口径	`docs/reports/metrics-catalog.md`
演示 PPT / 演示视频	`presentation/`

分支说明

master：唯一最终交付分支；决赛全部代码与材料以此为准。
历史开发分支（feat/*、agent-mem-v1、main）仅用于展示迭代过程，不作为交付入口；其中的文档和数据不代表最终结论。

安全与仓库边界

不提交模型权重、虚拟环境、Hugging Face 缓存、原始运行日志与本机缓存。
不提交 API key、访问令牌、账号信息或含密钥的环境快照。
第三方源码克隆体不入库，仓库只保留来源、版本与 commit 清单（docs/reports/third-party-versions.md）。
所有性能结论必须注明硬件、配置、运行次数与统计口径；不得把 dry-run 或静态演示数据当作真机结果。