目录
master
分支1
标签0
+ 疑修
Web IDE
QAQ
更新文档和添加启动脚本
19小时前5次提交
README.md

EdgeToolMem :面向资源受限 OpenHarmony 端侧设备的智能体工具调用数据结构化与按需内存管理系统

EdgeToolMem: Structured and On-Demand Memory Management for Agent Tool-Call Data on Resource-Constrained OpenHarmony Devices 赛题题目：面向智能体的内存管理系统设计与实现（高校赛题）

一、项目简介

EdgeToolMem 是面向 OpenHarmony 端侧 CPU 环境的智能体内存管理系统。项目基于 llama.cpp 和 Qwen 开源模型，实现支持多轮推理与自主工具调用的 Agent 工作流，并将用户问题与工具定义分离，支持本地数据读取、网页搜索等可扩展业务工具。基线组将业务工具返回的原始内容直接加入模型上下文；优化组在相同工作流上引入常驻的工具数据内存管理服务，将大规模工具输出和历史上下文转换为可独立管理的结构化数据对象，通过分块、索引、按需读取、回收和恢复机制管理数据，并根据系统内存压力在模型上下文、主存和 eMMC 之间动态迁移。系统同时记录工具调用、记录 Token、Prompt Eval Time、生成时间、生成速度、总响应时间及内存占用等指标，用于构建可复现的基线与优化对比实验。

项目最终目标：

在资源受限的端侧设备上，将智能体产生的大规模工具输出和历史上下文从连续文本转换为可分块、可索引、可回收和可恢复的数据对象，减少无关内容进入模型上下文造成的内存压力，同时尽量保证任务成功率和推理效率。

1.当前项目测试结果

与 递归摘要强基线 相比，总耗时降低约52.1%；整体执行速度约为强基线的2.09倍。模型调用次数由61次减少到31次，Prompt Token由173,368降低到86,809，降低约49.9%；上下文峰值由7,504 Token降低到6,275 Token，降低约16.4%。

指标 基线组 优化组
总耗时 10,952.0秒(约182.5分钟) 5,245.8秒(约87.4分钟)
Prompt Token 173,368 Token 86,809 Token，降低49.9%
工具执行总耗时 9,218.6秒，主要是38次大模型摘要 约223毫秒
上下文峰值(最高占用) 7,504 Token 6,275 Token，降低16.4%
负载原始文件总量 191,399字节 191,399字节
工具累计读取的原始数据 285,431字节 218,493字节，降低23.5%
发生工具原始数据 285,431字节 218,493字节
实际返回上下文的数据 21,936字节(做摘要压缩) 84,919字节
任务成功率 83.3%(5/6) 100%(6/6)

2.软硬件配置：

类型 配置
开发板 Orange Pi 5 Plus
SoC Rockchip RK3588
内存 16GB LPDDR4
存储 128GB eMMC
操作系统 OpenHarmony 5.1.0.107
推理框架 llama.cpp (commit:c15c5c77a)
模型 Qwen2.5-7B-Instruct-GGUF(Q4_K_M)
主机系统 Windows 11
开发环境 VSCode
主机目录 D:\Agent
板端目录 /data/toolmem-agent
模型资源目录 /data/agent-memory-oh

3.目标与设计概览

flowchart LR
    A[Windows / VSCode] --> B[HDC TCP 192.168.x.x:8710]
    B --> C[OpenHarmony /data/agent-memory-oh]
    C --> A1[toolmem-agent]
    A1 <--> D[llama-server]
    A1 --> T[业务工具]
    T --> S{ToolOutputSink}
    S -->|Baseline 全文| A1
    S -->|Optimized 数据流| E[toolmem-runtime]
    E --> F[artifact store]
    A1 <--> E
    A1 --> H[最终回答]

4.项目目录结构

EdgeToolMem
├── src
│   ├── main.cpp                       # 程序入口与模块装配
│   ├── agent.cpp/.hpp                 # 多阶段 Agent 循环
│   ├── context_manager.cpp/.hpp       # 上下文回收与历史恢复
│   ├── model_client.cpp/.hpp          # llama-server HTTP 客户端
│   ├── tool_registry.cpp              # 工具注册、权限与分发
│   ├── builtin_tools.cpp              # 本地数据集工具
│   ├── web_tools.cpp                  # 网页搜索与正文读取
│   ├── memory_tools.cpp               # Artifact 检索与读取工具
│   ├── output_sink.cpp/.hpp           # Baseline/Artifact 数据出口
│   ├── monitor.cpp/.hpp               # Token、时延和内存监控
│   ├── tools.hpp                      # 工具公共定义
│   └── types.hpp                      # 公共数据类型
├── src_artifact
│   ├── artifact_store.cpp/.hpp        # 完整原文、状态与异常恢复
│   ├── artifact_index.cpp/.hpp        # SQLite FTS5 分块与会话目录
│   ├── runtime_service.cpp/.hpp       # Runtime 本地流式协议
│   └── runtime_main.cpp               # toolmem-runtime 入口
├── tests                              # 核心、SQLite、Artifact 和 Runtime 测试
├── benchmark
│   ├── workloads.json                 # W1至W4负载、来源和答案检查
│   └── llama-server                   # 统一推理配置测速结果
├── data                               # LogHub、LongBench 公开负载数据
├── certs                             # HTTPS CA 证书
├── config
│   ├── llama-server.env               # 三组共用的模型服务配置
│   └── web.env.example                # 网页搜索配置示例
├── docs/optimization-design.md        # 优化方案设计记录
├── third_party                        # cpp-httplib、Mbed TLS、SQLite 等依赖
├── CMakeLists.txt
├── deploy-agent.ps1                   #部署 Agent、Runtime、数据和脚本
├── deploy-llama-kernel.ps1            # 部署统一 llama.cpp CPU 内核
├── run-agent.ps1                      # 选择模式并运行单个或全部负载
├── prepare-public-workloads.ps1       # 准备 LogHub 公开数据
├── prepare-longbench-workload.ps1     # 准备 LongBench 公开数据
├── benchmark-llama-config.ps1         # 测试线程、批处理和CPU绑定
├── start-llama-server-7b.sh
├── stop-llama-server-7b.sh
├── start-toolmem-runtime.sh
└── stop-toolmem-runtime.sh

5.板端存储目录结构

/data/toolmem-agent
├── bin
│   ├── toolmem-agent                 # Agent 主程序
│   └── toolmem-runtime               # 工具数据后台服务
├── data
│   ├── datasets.json                 # 板端可读数据集目录
│   └── *.txt                        # LogHub 和 LongBench 公开数据
├── certs/cacert.pem                  # HTTPS CA 证书
├── config
│   ├── llama-server.env             # 统一模型服务参数
│   └── web.env                      # API Key、CA和可选代理
├── artifacts                         # data.bin、manifest.json、index.sqlite
├── results                           # 监控、工具轨迹和运行结果
├── start-llama-server-7b.sh
├── stop-llama-server-7b.sh
├── start-toolmem-runtime.sh
├── stop-toolmem-runtime.sh
├── llama-server.pid
└── toolmem-runtime.pid

/data/agent-memory-oh
├── bin/llama-server                  # OpenHarmony ARM64 推理服务
├── lib                               # llama.cpp、GGML 动态库
└── models/Qwen3-8B-Q4_K_M.gguf      # 模型文件，不包含在仓库中

二、快速开始

0.环境变量说明

为了方便部署，所有VSCode终端命令依赖以下变量。

Set-Location "D:\Agent"

$SDK="D:\OpenharmonySDK.1.0.1078"
$HDC="$SDK\toolchains\hdc.exe"
$TARGET="192.168.7.7:8710"
$REMOTE="/data/toolmem-agent"

其中$TARGET是开发板的HDC TCP地址，请根据实际网络修改。

1.板端脚本

项目提供四个板端脚本，分别管理模型服务和ToolMem Runtime。

& $HDC -t $TARGET shell "$REMOTE/start-llama-server-7b.sh"
& $HDC -t $TARGET shell "$REMOTE/stop-llama-server-7b.sh"

& $HDC -t $TARGET shell "$REMOTE/start-toolmem-runtime.sh"
& $HDC -t $TARGET shell "$REMOTE/stop-toolmem-runtime.sh"

运行Baseline或Summary只需要启动llama-server；运行Optimized时还需要启动toolmem-runtime。

2. Windows 编译与测试

cmake `
    -S "D:\Agent" `
    -B "D:\Agent\build-mingw" `
    -G Ninja `
    -DCMAKE_C_COMPILER="D:/mingw64/bin/gcc.exe" `
    -DCMAKE_CXX_COMPILER="D:/mingw64/bin/g++.exe" `
    -DCMAKE_BUILD_TYPE=Release

cmake --build "D:\Agent\build-mingw" --parallel 6

ctest `
    --test-dir "D:\Agent\build-mingw" `
    --output-on-failure

3. OpenHarmony 交叉编译

$SDK = "D:\OpenharmonySDK.1.0.1078"

cmake `
    -S "D:\Agent" `
    -B "D:\Agent\build-ohos" `
    -G Ninja `
    -DCMAKE_TOOLCHAIN_FILE="$SDK\native\build\cmake\ohos.toolchain.cmake" `
    -DOHOS_ARCH=arm64-v8a `
    -DOHOS_STL=c++_static `
    -DCMAKE_BUILD_TYPE=Release

cmake --build "D:\Agent\build-ohos" --parallel 6

4. 连接开发板并部署

& $HDC tconn $TARGET
& $HDC list targets

.\deploy-agent.ps1 -Target $TARGET

模型和llama.cpp板端内核不包含在仓库中。如果已准备llama-build-manifest.json及对应的bin、lib文件，可执行：

.\deploy-llama-kernel.ps1 `
    -Target $TARGET `
    -PackageRoot "D:\agent-memory-oh\deploy"

将Qwen3-8B模型放到启动配置指定的位置：

/data/agent-memory-oh/bin/llama-server
/data/agent-memory-oh/models/Qwen3-8B-Q4_K_M.gguf

该路径需要与config/llama-server.env中的TOOLMEM_LLAMA_MODEL保持一致。

5. 配置网页工具

W2网页负载需要配置Tavily API Key。复制示例文件，填入实际Key后单独发送到开发板：

Copy-Item .\config\web.env.example .\config\web.env
notepad .\config\web.env

& $HDC -t $TARGET shell "mkdir -p $REMOTE/config"
& $HDC -t $TARGET file send `
    ".\config\web.env" `
    "$REMOTE/config/web.env"
& $HDC -t $TARGET shell "chmod 600 $REMOTE/config/web.env"

真实web.env已被.gitignore排除，deploy-agent.ps1不会自动上传该文件。不运行W2时可跳过此步。

6. 启动模型并运行负载

& $HDC -t $TARGET shell "$REMOTE/start-llama-server-7b.sh"

# 普通Agent基线：业务工具结果直接返回模型
.\run-agent.ps1 `
    -Mode baseline `
    -WorkloadId W1 `
    -ResultGroup w1-baseline

# 递归摘要强基线
.\run-agent.ps1 `
    -Mode summary `
    -WorkloadId W4 `
    -ResultGroup w4-summary `
    -ModelTimeoutSeconds 1800

# EdgeToolMem优化组
& $HDC -t $TARGET shell "$REMOTE/start-toolmem-runtime.sh"

.\run-agent.ps1 `
    -Mode optimized `
    -WorkloadId W4 `
    -ResultGroup w4-optimized `
    -ModelTimeoutSeconds 1800

通过-WorkloadId All可以连续运行全部负载。通过-Question可以在单个负载权限下替换默认问题。例如执行自定义网页搜索：

.\run-agent.ps1 `
    -Mode optimized `
    -WorkloadId W2 `
    -Question "搜索cpp-httplib官方GitHub许可证页面。只回答许可证名称和链接。" `
    -ResultGroup custom-web `
    -ModelTimeoutSeconds 600

实验完成后停止后台服务：

& $HDC -t $TARGET shell "$REMOTE/stop-toolmem-runtime.sh"
& $HDC -t $TARGET shell "$REMOTE/stop-llama-server-7b.sh"

三、实验输出

每次运行都会生成独立结果目录：

results/<ResultGroup>/<WorkloadId>-<Mode>-<时间戳>/
├── metrics.json
├── samples.jsonl
├── tool_trace.jsonl
├── evaluation.json
├── console.log
└── session-input.json
文件 内容
metrics.json 最终答案、Token、时延、工具数据量及 PSS/RSS/HWM 等汇总指标
samples.jsonl Agent、llama-server、Runtime 和系统内存的周期采样数据
tool_trace.jsonl 每次工具调用的参数、耗时、源数据量、返回数据量和执行状态
evaluation.json 各阶段答案检查结果与任务完成情况
console.log Agent 阶段、工具调用和最终答案的控制台记录
session-input.json 本次实验实际使用的问题与阶段配置

结果目录还会保存 llama-server 配置和构建信息，便于复现实验环境。

四、视频演示(主要演示如何进行负载测试)

链接: https://pan.baidu.com/s/1k8ysR5qkbF4D7eua6_k7OQ 提取码: u229

关于
README.md
60.7 MB
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号