面向边缘智能体推理的 llama.cpp KV Cache 共享与复用优化

项目简介

本项目面向本地部署、多轮交互和多任务并发的边缘智能体，优化公共上下文的重复计算与 KV Cache 存储。系统以 llama-server 为推理服务，在 llama.cpp 原有 Slot 复用、Host Prompt Cache 和 Unified KV 序列归属能力上，增加 Host Radix 前缀缓存、Direct KV 区间数据通路、Resident KV 驻留共享及多来源前缀选路。

决赛阶段在初赛 Host Radix 与 Direct KV 工作的基础上，新增设备侧 Resident KV Sharing，完善公共前缀的独立持有、请求挂接、容量管理和故障回退，并适配 Ascend/CANN 多 Slot 并发执行。应用层重写为 harness-os-com，通过 LangGraph 组织本地任务、会话和工具循环，经 OpenAI 兼容接口调用优化版推理服务，提供运行追踪、请求重放和验证入口。

底层缓存服务可由 Harness、其他 Agent 框架或普通 Chat Completions 客户端使用。缓存管理在服务端完成，模型权重、注意力计算和各请求的采样状态沿用原有推理路径。

应用场景

公共系统提示、工具定义、知识文档或会话历史较长，且后续请求持续复用或派生分支时，可利用本项目的前缀共享与复用机制。随附工作台展示三个场景：

场景	功能	数据来源
投研分析（`financial_research`）	查询财报、跨期比较、比例计算及连续追问	本地虚构公司财报
现场运维（`field_maintenance`）	查询设备状态、趋势、日志和手册，分析异常证据	本地模拟设备数据
软件故障诊断（`edge_incident`）	读取事件服务的状态与日志，生成诊断和待审核建议	随附 Python 模拟事件服务

内置场景不访问真实企业数据或现场硬件，诊断流程不自动执行重启或回滚。

主要功能与技术路线

Host Radix 前缀缓存：按 Token 压缩前缀树组织公共路径与私有分支，支持最长前缀匹配、压缩边分裂、跨请求和跨 Slot 复用、增量保存及终端 LRU 回收。
Direct KV 数据通路：按逻辑 Token 区间提取、分割和组合恢复结构化 KV Payload，减少完整序列状态的重复编码、解析与拼接；恢复失败时清理不可信目标并回退完整 Prefill。
Resident KV 驻留共享：独立缓存 owner 持有 Unified KV 中已完成的公共前缀；目标请求增加 Cell 归属即可只读共享已有 K/V，各请求的私有后缀独立分配。预算按 owner 覆盖的物理 Cell 并集计费，回收检查实际释放量。
多来源前缀选路：联合评估 A（活动 Slot 自有前缀）、S（Resident 驻留前缀）和 H（Host Radix 可恢复前缀）。默认 longest 选择最长可执行前缀，等长时优先 A、S、H；每次请求提交一条选定路径。
Ascend/CANN 并发适配：修正量化矩阵乘分段输出的布局与写回，并适配 Flash Attention 掩码语义，支持多 Slot 连续批处理。
Agent 工作台与验证：提供会话与分支、工具循环、模型接口适配、运行追踪、请求清单重放及本地场景验收。

用户 / 请求清单
  -> Agent Harness：组织场景、会话与工具
  -> OpenAI Chat Completions 接口
  -> llama-server：评估 A / S / H 前缀并选择执行来源
  -> 保留活动前缀 / 挂接 Resident / Direct KV 恢复 / 完整 Prefill
  -> 计算未复用后缀并 Decode
  -> 返回回答或工具调用结果
  -> 确认计算完成后，按条件发布 Resident 与保存 Host 增量

项目结构与提交材料

比赛提交主仓库使用 master 分支，核心代码以 Git 子模块固定到具体提交。部署快照、测试材料和演示文件随主仓库提供。

项目根目录/
├── README.md
├── 作品原创承诺书.pdf
├── src/
│   ├── llama.cpp-radix-tree/      # 优化后的推理框架子模块
│   └── harness-os-com/            # Agent 工作台子模块
├── docs/                         # 决赛说明材料
├── tests/                        # 测试入口、实验配置与结果
├── demo/                         # ARM64/CANN 部署与验收包
│   ├── compose.yaml
│   ├── Dockerfile.cann
│   ├── Dockerfile.harness
│   ├── harness-arm64.tar.gz
│   ├── llama-source/
│   └── harness-source/
└── presentation/
    ├── 决赛演示.pptx
    └── 决赛演示视频.mp4

材料	内容
项目说明书	系统设计、技术方案、核心模块、实验结果与实现难点
项目创新说明	创新点、相关工作对比与实现依据
成员分工及主要贡献说明	成员分工、主要贡献与协作方式
人工智能及第三方工具使用说明	人工智能工具使用情况及第三方组件声明
作品原创承诺书	作品原创性及开源使用承诺
决赛演示 PPT	项目介绍、技术亮点、实现难点、测试与场景演示
决赛演示视频	三场景运行演示，时长约 4 分 57 秒，大小约 89.27 MB

系统环境与依赖

部署包面向 Linux ARM64/aarch64、Ascend 910B 系列设备和 CANN 8.5.0。参考实验环境为 openEuler 22.03 LTS SP3、Kunpeng 920、Ascend 910B3，模型为 Qwen3-8B-Q8_0.gguf，KV 类型为 f16。

组件	要求
昇腾宿主机	可用 NPU、匹配的驱动与固件、设备节点及 `/usr/local/Ascend/driver`
容器部署	Docker、Docker Compose，具备镜像构建与设备访问权限
CANN 基础镜像	Linux ARM64，包含 CANN 8.5.0 Toolkit、运行库、算子资源、Bash、CMake 与 C++ 编译器
源码构建	CMake 3.14 及以上、GCC 或 Clang；CANN 构建需加载 Toolkit 环境
Harness 源码运行	Python 3.10 及以上；LangGraph、LangChain Core、Pydantic、FastAPI、Uvicorn，版本约束见 pyproject.toml
模型	单独准备与后端兼容的 GGUF 模型；参考文件大小与 SHA256 见部署指南

Host Radix 逻辑位于服务端，可随其他 GGML 后端构建；CPU、CUDA、Metal 等构建选项见推理框架构建文档。正式性能与容量结论以项目说明书中列明的模型、后端和负载为适用范围。

获取代码

git clone --branch master --recurse-submodules \
  https://gitlink.org.cn/IFCGM24rNS/mxzntdncglxtsjysx.git
cd mxzntdncglxtsjysx

已克隆主仓库时，初始化主仓库记录的子模块版本：

git submodule update --init --recursive
git submodule status

构建、安装与运行

昇腾容器部署

以下命令在目标 ARM64 昇腾机器上执行。先准备 CANN 基础镜像与 GGUF 模型，完整的宿主机检查、设备映射、模型摘要及故障排查见 demo/README.md。

从项目根目录进入部署包，校验并导入随附 Harness 镜像：

cd demo
sha256sum -c harness-arm64.tar.gz.sha256
docker load -i harness-arm64.tar.gz
cp .env.example .env

编辑 .env，填写实际部署环境：

配置项	设置方法
`CANN_BASE_IMAGE`	实际可用的 ARM64 CANN 8.5.0 基础镜像名称与标签，需提前导入或拉取
`CANN_ENV`	镜像内 Toolkit 环境脚本，默认 `/usr/local/Ascend/cann-8.5.0/set_env.sh`
`MODEL_DIR` / `MODEL_FILE`	宿主机模型目录的绝对路径与 GGUF 文件名
`NPU_DEVICE`	实际 NPU 设备节点，默认 `/dev/davinci0`
`INCIDENT_STATE`	模拟故障状态，默认 `degraded`

检查配置、构建模型镜像并启动三个服务：

docker compose config --quiet
docker compose build llama-server
docker compose up -d --no-build
docker compose ps
docker compose logs --tail 100 llama-server

模型镜像从 demo/llama-source/ 构建；此部署快照的版本与编译修复已在部署指南中说明。Harness 和软件故障服务共用导入的 ARM64 镜像。需要从源码重新构建 Harness 时，在 demo/ 执行 docker compose build harness，构建过程需要访问 Python 包源。

默认配置启用 Host Radix、Resident KV Sharing 与 longest 选路，使用 16K 总上下文、4 个并行 Slot、Unified KV 和 4096 MiB Host 缓存。该配置用于功能部署；性能实验采用各自记录的配置。

服务	地址	用途
llama-server	`http://127.0.0.1:8080`	推理接口与缓存管理
Agent Harness	`http://127.0.0.1:8090`	三场景工作台、会话、工具与运行追踪
模拟事件服务	容器网络 `http://edge-event-api:8765`	软件故障状态与日志

等待模型加载后，在 demo/ 执行验收：

sh verify.sh

浏览器访问 Agent 工作台。远程使用时，可建立 ssh -L 8090:127.0.0.1:8090 用户名@服务器地址 隧道后访问同一地址。验收脚本检查健康状态，并对三个助手发起真实模型与工具调用。停止服务使用 docker compose down，会话与日志卷保留。

Harness 源码安装与运行

已有可用 llama-server 时，也可单独运行 Harness。以下安装命令从项目根目录执行：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ./src/harness-os-com

在一个终端启动模拟事件服务：

python src/harness-os-com/examples/edge_event_api.py \
  --host 127.0.0.1 --port 8765 --state degraded

在另一个终端激活同一虚拟环境，进入 Harness 项目并启动工作台：

source .venv/bin/activate
cd src/harness-os-com
export LLM_BASE_URL=http://127.0.0.1:8080/v1
export LLM_MODEL=local
export EDGE_HARNESS_INCIDENT_URL=http://127.0.0.1:8765
python -m uvicorn edge_harness.app:app --host 127.0.0.1 --port 8090

LLM_MODEL 需与模型服务公布的模型名或 --alias 一致。推理框架独立构建、缓存组合及 API 说明见推理框架 README，Harness 的场景与调用说明见 Harness README。

测试与验证

功能验收

服务启动后，检查模型与工作台健康状态；已安装 Harness 的环境可运行真实调用验收：

curl --fail http://127.0.0.1:8080/health
curl --fail http://127.0.0.1:8090/health
python -m edge_harness.verify --base-url http://127.0.0.1:8090 --chat

容器部署使用前述 demo/verify.sh。验收覆盖助手、数据、会话、请求预览、工具执行和非空最终回答。

Agent 单元与组件测试

激活已安装 Harness 依赖的虚拟环境，在项目根目录执行：

python tests/experiments/agent-tests/scripts/run.py \
  --harness-dir ./src/harness-os-com

测试使用假后端或 mock，无需运行大模型；软件服务集成用例启动临时本地 HTTP 服务。前端 Markdown 渲染用例需要 Node.js，未安装时该用例跳过。覆盖范围见 Agent 测试说明。

C++ 缓存管理测试

Host Radix 与 Resident 管理器分别包含 22 和 16 个场景。两个测试源码均显式取消 NDEBUG，Release 构建也保留断言；下面使用 Debug 便于定位失败。示例从项目根目录执行，使用部署包中的源码快照，在已加载 CANN 环境的宿主机上构建并运行：

source /usr/local/Ascend/cann-8.5.0/set_env.sh
cmake -S demo/llama-source -B demo/llama-source/build-tests \
  -DCMAKE_BUILD_TYPE=Debug -DGGML_CANN=ON -DGGML_NATIVE=OFF \
  -DLLAMA_CURL=OFF
cmake --build demo/llama-source/build-tests --parallel 8 \
  --target test-server-prompt-cache-radix test-server-kv-resident-cache
ctest --test-dir demo/llama-source/build-tests \
  -R '^(test-server-prompt-cache-radix|test-server-kv-resident-cache)
 \
  --no-tests=error --output-on-failure

场景清单见 C++ 测试说明。Direct KV 往返、HTTP 生命周期、输出一致性和故障回退等集成验证入口见推理框架验证说明。

资源与性能实验

实验	方法与结果入口
Resident 物理占用与容量	运行说明、结果摘要
Host 缓存存储与预算	运行说明、结果摘要
三配置性能消融	运行说明、结果摘要

各实验目录保留输入生成规则、脚本、配置及汇总结果。真实实验需要空闲 Ascend NPU、Release/CANN 构建和相同 GGUF 模型，模型文件、服务端二进制与源码路径需按目标机器和本仓库布局配置。测试材料总索引见 tests/README.md。

现有记录的主要结果如下，完整条件与数据口径见项目说明书及对应结果文件：

实验条件	记录结果
八个 16K 输入共享 8K 前缀，两侧 Resident 关闭，保留相同八条缓存	Host 快照/Payload 从 18,433.507 降至 10,368.644 MiB，减少 43.75%
约 16K 输入、50% 公共前缀、四请求，两侧 Host 缓存关闭	技术说明与对话历史场景的最小已测成功 KV 池容量从 66,560 降至 41,984 Cell，减少 36.92%，两侧均有五次重复支持
六档公共前缀、三种配置、每组合三轮，共 54 轮、6,912 请求	Host Radix 与 Resident 联合配置相对 Legacy 的单请求平均 E2E 加速为 1.23～1.41 倍

Host 指标为服务端统计的快照/Payload 占用，未完整计入树节点与容器额外开销；Resident 指标区分已用物理 Cell、启动池容量与 KV Buffer 分配量。容量实验的检索场景未形成有效边界结论。性能消融的 8K、12K 档保留了模式间请求访问顺序差异，且联合配置在部分档位的 TTFT 增大，结论限定于所记录负载与配置。

已知限制

Host Radix 与 Resident 默认均关闭，可分别启用或联合启用。Host Radix 需要非零 --cache-ram；Resident 需要 --kv-unified、--no-context-shift 和 --cache-reuse 0。
Resident 当前支持普通全注意力、单维连续位置的因果文本模型；SWA、循环或混合内存、编码器上下文、Draft/MTP、多模态及 aLoRA 等不受支持。启用期间不接受请求级 LoRA 与适配器更新，固定普通 LoRA 可用。具体检查见推理框架 README。
Host Direct KV 当前面向纯文本 Prompt。选路不支持将 Resident 前缀与 Host 后缀拼接恢复；完整前缀命中仍需重算最后一个输入 Token 取得 logits。
缓存位于单个 llama-server 进程内，退出后不保留，也不跨服务实例共享。共享收益取决于公共前缀长度、请求顺序、分支规模、预算和并发调度。
设备池内物理 Cell 的减少不等于整卡 HBM 同比例下降，Host Payload 的减少也不等于整个进程 RAM 同比例下降。
随附 Harness 镜像为 Linux ARM64；GGUF 模型、CANN 基础镜像及宿主机驱动需另行准备。模拟场景的诊断与计算结果需要人工核对。

开源基础与参考

本项目基于 llama.cpp、GGML/CANN、LangGraph、LangChain Core、FastAPI、Uvicorn、Pydantic 和 Qwen 等开源项目或模型。Radix 前缀组织参考 SGLang RadixAttention；本项目围绕 llama.cpp 的 KV 数据结构、状态接口和服务生命周期实现 Host 索引、Direct KV 数据通路、Resident owner 管理与协同选路。

推理框架保留上游项目说明和 MIT 许可证。其他第三方代码、依赖、模型及数据的来源、版本和许可证以各组件声明为准；技术参考文献见项目说明书。