AgentMem

初赛作品材料

项目概述

AgentMem 是面向长生命周期智能体的分层 KV Cache、上下文和工具中间数据管理系统。它使用不可变上下文 DAG 表示多轮对话与推理分支，通过引用计数和 Copy-on-Write 共享公共前缀；缓存控制器根据复用频率、分支扇出、活跃租约、重计算成本和数据语义，在 GPU、CPU 与文件系统冷层之间管理 KV。大型工具输出保存在租户隔离的内容寻址存储中，Prompt 只保留摘要和按需读取句柄。

验证项	当前结果	证据边界
自动化测试	270/270 通过，语句覆盖率 81%	当前工程质量快照；新增 8 项 vLLM 0.23 物理适配器测试，机器可读结果已归档
3B 真实机制探针	18/18 正确；复用准入 2 次、73 blocks；hot external/resident hit 各 213 次；739 个审计事件、丢失 0	证明完整请求复用机制在真实 Qwen2.5-3B-AWQ + vLLM 0.23.0 上生效，不单独作为性能结论
3B 顺序平衡 A/B（主结果 E1）	相对 prefix-offload：P95 降低 5.58%、吞吐提高 12.60%、能耗/任务降低 17.72%	绑定 commit `d70f097`；两轮顺序相反且方向一致，正确性与工具协议均为 100%，判定 `PROMOTE_CURRENT_CANDIDATE`
20 轮 × 8 分支压力复测	45.269 秒，较历史 361.6 秒缩短 87.5%；160 个请求全部成功	CPU 模拟压力证据，不等同于 GPU 端到端延迟
控制面微基准	HTTP keep-alive 中位数加速 19.24×；500 分支前缀扇出中位数加速 238.4×	7 次重复的中位数结果，不等同于模型生成加速
7B 服务器矩阵（阶段证据 E5）	4 变体 × 4 轮、16 个子运行、1,600 个任务全部正确；AgentMem 相对 prefix-offload 的能耗/任务配对均值降低 0.90%，95% CI 为 +0.36%～+1.75%	能耗区间不跨 0；P95、吞吐区间跨 0，文件冷层配置不完全对称，GPU 峰值没有下降
本地 8GB 7B AWQ 探针	独立分支完成 10/10 正确、18 次 hot external hit、18 次 resident hit、external hit rate 17.70%，未发生 OOM	仅证明 1024 上下文、单并发、受限容量下的 7B 机制兼容性；不代表正式 7B 性能或大上下文能力

本轮主要优化

完整请求复用准入：对模型、消息、工具 Schema、采样参数等生成规范化指纹；相同请求第二次出现后才确认复用价值，一次性冷请求继续被有界准入拒绝。
vLLM 0.23 真实链路修复：补齐 primary CPU tier 的 on_new_request 转发，让请求标签、准入、完成回调和审计指标在 EngineCore 中形成闭环。
缓存淘汰热路径优化：逐层逐块扫描改为分层增量堆、版本号惰性失效和有界压缩；前缀扇出改用增量 Counter，避免重复全量扫描。
控制面稳健性：HTTP/1.1 增加空闲超时，拒绝不支持的 Transfer-Encoding 请求体并关闭连接，补充 keep-alive 与请求边界回归测试。
tokenizer 缓存双预算：LRU 同时限制条目数和估算字节数，单个超大项不进入缓存，防止长期运行时由少量大文本占满内存。
证据可复现性：Benchmark 保存任务清单、源码树哈希、原始 JSON、顺序信息和结论门禁；本地 PowerShell 脚本不再错误继承父目录 Git 身份。
vLLM 适配器失败关闭：不支持的 store_threshold >= 2 现在会在分配并缓存物理 manager 之前被拒绝，避免首次调用报错后再次调用绕过校验；新增桩运行时测试覆盖有界淘汰、保护块、语义排序、新请求转发、配置解析和 manager 复用。

功能

上下文 DAG、多会话、多分支、检查点和 Copy-on-Write。
模型、Tokenizer 配置和租户共同参与缓存键计算，避免不安全复用。
Agent-aware 与 LRU 两种缓存策略，以及与 vLLM block budget 对齐的容量准入控制。
GPU、CPU、文件系统冷层三层逻辑缓存与迁移决策。
JSON、文本和二进制工具结果的压缩、去重、分页及 JSON Pointer 读取。
工具对象原子落盘、完整性校验、安全 GC，以及零租约 KV、已关闭分支和会话元数据的显式回收。
仅使用 Python 标准库实现的 HTTP 控制面、Prometheus 文本指标和 CLI；安装包中的 typing-extensions 只为 Python 3.9+ 上的 vLLM 适配器提供兼容类型标记。
确定性模拟、真实 AgentSuite、分支生命周期和四组 vLLM 消融 Benchmark。
openEuler 24.03 控制面容器、实测证据脚本与 OpenAI-compatible vLLM 客户端。

flowchart LR
    A[Agent Runtime] --> B[Context DAG]
    B --> C[Agent-aware Cache Controller]
    C --> D[vLLM Adapter]
    D --> E[GPU Hot Tier]
    D --> F[CPU Warm Tier]
    D --> G[Filesystem Cold Tier]
    A --> H[Tool Artifact Store]
    H --> B

快速开始

要求 Python 3.9 或更高版本。下面的 Windows 命令均在 PowerShell 中执行。

1. 创建基础控制面与开发测试环境

cd "<AgentMem 项目目录>"
python -m venv .venv
Set-ExecutionPolicy -Scope Process Bypass
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -c "import agentmem, typing_extensions; print('AgentMem install OK')"
agentmem --help

.[dev] 会安装 AgentMem、明确声明的 typing-extensions 运行依赖，以及 pytest、 pytest-cov。如果还要启用工具对象的可选 Zstandard 压缩，可将安装命令改为：

python -m pip install -e ".[dev,compression]"

本节只安装可直接在 Windows 上运行的控制面、无 GPU 演示和开发测试环境，不会安装 vLLM、CUDA、模型权重或完整 GPU 数据面。真实模型推理由后文的 vLLM Docker 容器提供，不要在 Windows 虚拟环境中额外执行 pip install vllm。

如果命令行同时显示 (.venv) (base)，表示 Conda 基础环境与项目虚拟环境同时激活；只要 Get-Command python 指向项目的 .venv\Scripts\python.exe 就可以继续运行。

2. 运行无 GPU 演示

agentmem --data-dir .\runtime-data demo --branches 3

该命令不会下载模型，也不需要 GPU。它会演示会话、上下文 DAG、分支共享、缓存、工具对象存储和生命周期回收。

3. 运行测试与模拟 Benchmark

python -m pytest -q
agentmem benchmark --rounds 8 --branches 4 --output .\my-test-results

结果写入 my-test-results\results.json 和 my-test-results\report.md。复现 20 轮、8 分支压力测试时，为避免覆盖仓库证据，请使用单独目录：

agentmem benchmark --rounds 20 --branches 8 --output .\my-stress-results

4. 启动离线控制面

第一个 PowerShell 窗口运行：

agentmem --data-dir .\runtime-data serve `
  --host 127.0.0.1 `
  --port 8080 `
  --simulation-tokenizer

--simulation-tokenizer 表示只验证 AgentMem 控制面，不连接真实模型。第二个 PowerShell 窗口检查服务：

Invoke-RestMethod http://127.0.0.1:8080/healthz
(Invoke-WebRequest http://127.0.0.1:8080/metrics).Content

创建测试会话：

$body = @{
  model_id = "Qwen/Qwen2.5-3B-Instruct"
  tenant_id = "demo"
  system_prompt = "你是一名运维智能体"
} | ConvertTo-Json

$result = Invoke-RestMethod `
  -Method Post `
  -Uri "http://127.0.0.1:8080/sessions" `
  -ContentType "application/json; charset=utf-8" `
  -Body $body

$result | ConvertTo-Json -Depth 10

返回 session_id 和 branch_id 即表示创建成功。PowerShell 默认把复杂的 cache 字段显示成 @{...}，这不是错误；使用 ConvertTo-Json -Depth 10 可以展开查看。

第一阶段：Qwen 3B AWQ

环境与模型

真实模型运行需要 NVIDIA 驱动、支持 GPU 的 Docker Desktop/WSL2 和本地模型文件。当前 Windows 配置默认使用：

D:\AgentMem\models\Qwen2.5-3B-Instruct-AWQ

运行前检查：

Test-Path "D:\AgentMem\models\Qwen2.5-3B-Instruct-AWQ"
docker version
nvidia-smi

Test-Path 必须返回 True。文档中的其他盘符只是示例，不能直接复制不存在的路径。

1. 启动 vLLM 数据面

如果离线控制面仍在运行，可以先保留；vLLM 使用端口 8000，不会与控制面的 8080 冲突。执行：

powershell -ExecutionPolicy Bypass `
  -File .\scripts\start-vllm.ps1 `
  -Variant agentmem `
  -ModelProfile qwen2.5-3b-awq `
  -ModelPath "D:\AgentMem\models\Qwen2.5-3B-Instruct-AWQ" `
  -Replace

模型位于默认目录时也可以省略 -ModelPath。查看容器和模型加载日志：

docker ps
docker logs -f agentmem-vllm

日志查看窗口按 Ctrl+C 不会停止容器。模型加载完成后检查：

Invoke-WebRequest http://127.0.0.1:8000/health

返回 HTTP 200 表示 vLLM 已就绪。

2. 启动真实 AgentMem 控制面

如果之前启动了带 --simulation-tokenizer 的控制面，先在对应窗口按 Ctrl+C，避免端口 8080 被占用。然后运行：

agentmem --data-dir D:\AgentMem\control-plane serve `
  --host 127.0.0.1 `
  --port 8080 `
  --vllm-url http://127.0.0.1:8000 `
  --tokenizer-model Qwen/Qwen2.5-3B-Instruct-AWQ

真实模型模式不要添加 --simulation-tokenizer。

3. 执行完整验收

在另一个已激活 .venv 的 PowerShell 窗口运行：

python .\scripts\verify_phase1.py

脚本验证 Qwen 非流式与 SSE 流式 Chat API、AgentMem 控制面、真实生成和回答回写。固定环境、权重哈希和实测指标见第一阶段实测报告。

4. 停止服务

AgentMem 窗口按 Ctrl+C，然后停止 vLLM：

docker stop agentmem-vllm

常见问题：

Model directory does not exist：-ModelPath 指向了不存在的示例目录；先用 Test-Path 检查，并改为真实模型目录。
Address already in use：已有进程占用 8080；先停止之前的模拟控制面。
vLLM 长时间未就绪：使用 docker logs -f agentmem-vllm 查看模型加载或显存错误。
正式 7B 服务器配置至少需要 16GB 显存。8GB GPU 默认使用本节的 3B AWQ；仓库独立分支中的 7B 本地探针只适用于 1024 上下文、单并发机制验证。

真实配置与正交消融

仓库保留 native、prefix、prefix-offload、agentmem 四个核心固定配置，并新增 lru-artifact、agent-inline 两个正交附加配置。模型、缓存、KV 冷层和结果默认都放在 D:\AgentMem：

.\scripts\start-vllm.ps1 -Variant prefix-offload -Replace
.\scripts\run_variant_benchmarks.ps1 -ResultsRoot D:\AgentMem\results\variants

单独运行“LRU/Agent-aware × 工具内联/外置”四格消融：

.\scripts\run_factorial_ablations.ps1 `
  -ResultsRoot D:\AgentMem\results\factorial-ablations -IndependentRuns 4

prefix-offload 使用受限的 1GB CPU KV 层；完整 agentmem 额外将 D:\AgentMem\kv-cache 作为文件系统冷层，并启用工具结果外置和 Agent-aware 策略。配置、真实日志证据和四组结果见第二至第四阶段报告。

第五至第七阶段默认使用更适合本机的 Qwen2.5 1.5B AWQ，并执行每组预热 5 次、正式重复 3 次的公平实验。下载校验、7B 服务器限制、完整指标和原始结果见第五至第七阶段实测报告。

第八至第十阶段增加真实 tool_calls/read_artifact 闭环、120 请求并发矩阵、置信区间、冷层回读压力、完整请求复用准入和 7B 服务器矩阵。3B 已完成本地真实机制探针与两轮顺序平衡性能 A/B；7B 已形成服务器四轮矩阵和独立的本地受限机制探针，但只有能耗/任务约 0.90% 的配对改善可以作为稳定正向加分项。详见第八至第十阶段实施与实测报告、 3B V4 机制结果和 7B 矩阵分析。

vLLM 集成

AgentMem 不重复实现 vLLM 已有的 CUDA KV 搬运内核。控制面负责智能体生命周期、稳定上下文和工具外置；AgentMemTieringOffloadingSpec 实现 vLLM 0.23 的物理 CachePolicy 接口，根据跨请求复用、活跃请求、分支扇出、语义提示和前缀位置选择 CPU KV 淘汰块。冷层淘汰使用有界衰减 ghost history，回读时恢复长期价值而不恢复过期租约。prefix-offload 继续使用 LRU，作为严格物理消融基线。

当前物理语义提示是请求级标量，并非逐物理块标签；自定义策略作用于 CPU offload 主层，不替换 GPU block allocator。块级语义映射只有在 vLLM 块顺序、工具模板和 KV Group 均可验证时才适合启用，因此当前结果不得据此宣称 GPU 侧语义淘汰收益。

可通过以下代码生成完整 AgentMem 启动参数；运行进程必须能通过 PYTHONPATH 导入本项目的 src 目录：

from agentmem.backends import VLLMBackend

print(VLLMBackend.serve_command("Qwen/Qwen2.5-3B-Instruct"))

真实 Benchmark 示例：

agentmem --data-dir .real-bench real-benchmark \
  --base-url http://127.0.0.1:8000 \
  --model-id Qwen/Qwen2.5-1.5B-Instruct-AWQ \
  --layers 28 --kv-heads 2 --head-dim 128 \
  --warmups 5 --repetitions 3 --branches 2 \
  --variant agentmem \
  --output benchmark-results/agentmem-real.json

文档

当前边界

本仓库实现的是可运行的 AgentMem 控制面、工具对象存储和 vLLM 0.23 物理策略适配器。当前 3B GPU 主结果 E1 已由相反顺序的两轮 A/B、正确性门禁和原始结果支撑，并绑定 commit d70f097。它只适用于报告所列 RTX 5060 Laptop GPU 8GB、 Qwen2.5-3B-Instruct-AWQ、固定容量和任务集，不能外推到其他模型、硬件或生产负载。后续控制面与淘汰热路径优化属于 E3/E4 工程证据，尚未用最新源码重跑端到端 GPU A/B。

物理 Agent-aware 策略作用于 vLLM CPU offload 主层，不替换 GPU block allocator。固定 GPU blocks 条件下两组 GPU 峰值相同，因此项目不宣称已经直接降低 GPU 显存。本轮控制面微基准和 CPU 模拟压力结果也不能替代真实模型端到端 A/B。

7B 服务器矩阵可以陈述 16/16 子运行正确和能耗/任务配对均值降低约 0.90%，能耗 95% CI 为 +0.36%～+1.75%；但 P95 与吞吐区间跨 0，且两臂文件冷层配置不完全对称， GPU 峰值没有下降。本地 8GB 7B 独立分支只证明受限配置下的真实复用机制。

3B A/B 中，AgentMem 控制面、任务驱动和证据采集位于 openEuler 容器，GPU 推理由独立 vLLM 容器提供，宿主为 Windows 11 + Docker Desktop/WSL2。因此可以陈述 openEuler 控制面集成验证完成，但不能表述为“原生 openEuler GPU 正式 A/B 已完成”。

演示视频

若项目中的演示视频不能查看，请到百度网盘下载观看。通过网盘分享的文件：演示视频.mp4 链接: https://pan.baidu.com/s/1fv5rfBpuYEFGRWXyKZ2NfQ?pwd=1wbc 提取码: 1wbc

License

MIT