AgentMem-Ascend：面向智能体推理的内存管理优化系统

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

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

系统架构

核心功能

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

项目还保留 LATS/MCTS 多路径决策实验，用于研究分支推理中的前缀复用与内存行为。

已归档实验结果

下表只列出已有报告中的观测值。不同模块的 workload、运行次数和统计口径不同，不能直接横向比较；完整边界条件见对应报告。

模块	主要观测	报告
F1	同 HBM 预算下 KV token 容量 `775,936 -> 1,556,992`，即 `2.007x`	F1 Benchmark
F2	tau-bench 115 任务同轨迹配对 Prompt 减少 `19.38%`，115 个结果无 transport/runtime 错误	F2 115-task 结果
F3	LongBench first100 累计 Prompt 减少约 `66.7%`，TTFT 中位数下降约 `87%`；最佳观测成功率比重测 baseline 低 3 pp	F3 first100 结果
F4	当前 workload 下单 Agent p50 下降 `21%`、并发 4 QPS 提升 `32%`；因未触发 offload，HBM 峰值基本持平	F4 集成与结果
F5	已验证烟测中抢占 `2 -> 0`、KV 命中率 `0.797 -> 0.921`、p50 `83 s -> 43 s`；完整多工况重复实验仍需按报告复跑	F5 模块说明

目录结构

.
├── agent-mem/
│   ├── src/agent_mem/       # 核心 Python 包
│   ├── benchmarks/          # 统一 Benchmark CLI 与专项基准
│   ├── configs/             # baseline、F1-F5 与组合配置
│   ├── docker/              # 容器化部署文件
│   └── tests/               # 单元测试与构造测试
├── scripts/                 # 校准、实验编排、分析与文档工具
├── docs/                    # 技术报告、实验结论与架构素材
├── dev-guide/               # 环境搭建和依赖状态
├── models/README.md         # 模型目录约定，权重不入库
└── third_party/             # 第三方版本清单，源码克隆体不入库

环境要求

基础开发环境

Python >=3.11,<3.13
Linux；项目验证环境为 openEuler 24.03
CPU 环境可运行配置校验、单元测试和 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
Qwen2.5-7B-Instruct 模型权重

完整安装过程、固定版本和已知问题见环境搭建指南、安装状态和第三方版本清单。模型权重不进入 Git，目录约定见 models/README.md。

快速开始

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

1. 创建 Python 环境

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e "agent-mem[dev,demo]" qwen-agent

运行 tau-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 压缩器使用独立环境，F4 和 Ascend 引擎还需要额外原生依赖；请按 dev-guide/environment-setup.md 配置，不要把虚拟环境、模型权重或 Hugging Face 缓存提交到仓库。

2. CPU 自检

cd agent-mem
python -m pytest tests -q
python -m ruff check src tests
python benchmarks/runner.py \
  --config configs/prefix_cache.yaml \
  --runner dry-run \
  --runs 1

dry-run 只验证配置、运行目录和指标链路，不代表真实性能结果。

3. 启动 Ascend 推理引擎

确认 NPU、CANN 和模型权重就绪后：

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

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

服务就绪后，OpenAI-compatible API 位于 http://127.0.0.1:8000/v1，Prometheus 指标位于 http://127.0.0.1:8000/metrics。

F1 C8 运行前必须完成真实 post-RoPE 校准；占位 scale 仅用于链路探针，不能用于结果评测。具体步骤见 F1 C8 注入说明。

4. 启动演示界面

在另一个终端执行：

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。界面包含普通 Agent 对话、F2/F3 上下文任务、F1/F4 通用 KV 改进、F5 高并发专项和实时监控。若服务器不直接开放端口，可使用 SSH 端口转发。

5. 运行真实 Benchmark

cd agent-mem
python benchmarks/runner.py \
  --config 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 的配置只从其声明的环境变量读取密钥，例如：

export MIMO_KEY='<your-key>'

请勿把密钥写入 YAML、README、日志或提交历史。

配置入口

使用场景	推荐配置
无优化对照	`agent-mem/configs/baseline.yaml`
vLLM 默认前缀缓存	`agent-mem/configs/prefix_cache.yaml`
F1 C8 对照	`agent-mem/configs/f1-bench-baseline.yaml` / `f1-bench-c8.yaml`
F2/F3 组合	`agent-mem/configs/f2-f3-combined.yaml`
F4 LMCache	`agent-mem/configs/f4-lmcache.yaml`
F5 原生/准入对照	`agent-mem/configs/f5-native.yaml` / `f5-evict-dynamic.yaml`
LongBench 上下文任务	`agent-mem/configs/unified-longbench.yaml`

文档

竞赛交付物

评审以 GitLink 的 master 分支为唯一最终交付入口。按大赛提交规范，下列材料均直接放在 master 分支的仓库根目录，不放入子目录：

交付物	根目录建议文件名	当前实际文件名	当前状态
作品简介、运行说明	`README.md`	`README.md`	已提交
项目说明书	`项目说明书.docx`	`项目说明书.docx`	已提交
参赛承诺书	`参赛承诺书.pdf`	`操作系统开源创新大赛作品原创承诺书.docx`	已提交（采用大赛附件模板原文件名，保留 docx 格式）
演示 PPT	`演示PPT.pptx`	`操作系统开源创新大赛PPT.pptx`	已提交（采用大赛附件模板原文件名）
演示视频	`演示视频.mp4`	`演示视频.mp4`	已提交，约 77 MB（< 100 MB 限制）

说明：本项目未单独提供「设计文档」「技术报告」，统一以「项目说明书」作为设计与技术说明材料提交，按大赛附件模板文件名命名为 项目说明书.docx。

如大赛附件模板规定了具体文件名，以模板为准；承诺书与演示 PPT 均按大赛附件模板原文件名提交。视频建议控制在 95 MB 以内，可在仓库根目录执行 stat -c '%s %n' 演示视频.mp4 复核字节数。上述三份材料（承诺书、演示 PPT、演示视频）已分类单独提交，使评委能清楚追溯代码定稿与材料定稿过程。

分支与开发历史说明

master：唯一最终交付分支；最终代码和上述全部参赛材料均以此分支为准。
main 与 agent-mem-v1：历史整合分支，用于保留开发与发布过程，不作为最终交付入口。
feat/*：各优化模块的开发、实验和调研分支，包含阶段性结果及部分未采用探索，仅用于展示持续迭代历史。

仓库保留完整的功能分支和合并提交，便于追溯各模块的开发时间、代码变更与实验过程。开发分支中的文档和数据不代表最终结论，最终可验收内容始终以 master 为准。

安全与仓库边界

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