面向多并发长上下文的 llama.cpp 分页式 KV Cache 与计算加速优化

作品简介

本项目面向开源大模型推理框架 llama.cpp 在多并发长上下文场景中的计算效率问题。原版统一 KV Cache 在多序列并发时，注意力算子面对的是由多条序列、空闲 cell 和 padding 共同组成的统一物理跨度，无关位置虽被掩码排除，却仍进入数据访问和计算范围，导致 prefill 阶段首 Token 延迟升高、decode 阶段输出吞吐下降。

我们直接改造了 llama.cpp 的 KV Cache、序列管理和 GGML 计算图，在 PagedAttention 思想基础上设计并实现了 ubatch 对齐式分页注意力（UA-PagedAttention）：KV Cache 按序列维护页面映射与真实长度，构图阶段依据 ubatch 中各 token 的序列归属将页表和真实 KV 长度按 token 顺序展开传入 GGML 算子，后端据此只访问各 Query 所属序列的有效页面。同一计算接口分别在 CUDA 和 CANN 后端落地，llama-server 服务接口保持兼容。

同时从零构建了完整的 Story-agent 智能体系统，包含图式智能体编排、十类本地故事工具、长 Prompt 合成、llama-server 流式推理和独立多会话前端，作为分页推理引擎面向复杂长上下文工作负载的直接验证。

关键性能数据（16K Prompt、8 路并发）：

指标	CUDA 原版	CUDA 分页	提升	CANN 原版	CANN 分页	提升
平均 TTFT	19.11 s	8.28 s	-56.67%	26.55 s	14.65 s	-44.81%
聚合输出吞吐	71.19 tok/s	154.17 tok/s	+116.57%	50.48 tok/s	75.85 tok/s	+50.27%

仓库结构

本仓库为作品提交主仓库，代码以 Git 子模块形式组织：

目录/文件	说明
`paged-llama.cpp/`	分页式 KV Cache 优化的 llama.cpp 推理框架（子模块）
`Story-agent/`	基于 LangGraph 的离线故事生成 Agent 验证应用（子模块）
`scripts/`	项目测试脚本（正确性、性能、集成测试）
`操作系统开源创新大赛项目说明书.pdf`	设计文档与技术报告
`面向多并发长上下文的llama.cpp分页式KV-Cache与计算加速优化.pptx`	演示 PPT
`演示视频.mp4`	演示视频
`作品原创承诺书.pdf`	参赛承诺书
`使用说明-CANN.md`	CANN（Ascend NPU）后端构建与运行说明
`使用说明-CUDA.md`	CUDA（NVIDIA GPU）后端构建与运行说明
`README-original.md`	赛题原始说明

代码仓库

推理框架（paged-llama.cpp）：https://gitlink.org.cn/IFwnjPgFSU/paged-llama.cpp
验证应用（Story-agent）：https://gitlink.org.cn/IFwnjPgFSU/Story-agent

运行说明

详细的构建、部署与测试说明请参阅对应后端的使用文档：

CANN 后端（Ascend NPU）：参见 使用说明-CANN.md
CUDA 后端（NVIDIA GPU）：参见 使用说明-CUDA.md

快速开始（概述）

克隆代码：

git clone --recurse-submodules https://gitlink.org.cn/IFwnjPgFSU/mxzntdncglxtsjysx.git
cd mxzntdncglxtsjysx

构建 llama.cpp（以 CANN 为例）：

source /usr/local/Ascend/cann/set_env.sh
cmake -S paged-llama.cpp -B paged-llama.cpp/build-cann \
  -DGGML_CANN=ON -DSOC_TYPE=Ascend910B3 \
  -DCMAKE_BUILD_TYPE=Release -DLLAMA_BUILD_SERVER=ON
cmake --build paged-llama.cpp/build-cann --target llama-server -j 8

启动 llama-server：

paged-llama.cpp/build-cann/bin/llama-server \
  -m models/Qwen3-8B-Q8_0.gguf \
  -ngl 99 -dev CANN0 -np 4 -c 131072 \
  --host 127.0.0.1 --port 8080 --alias qwen \
  --paged-attn --page-size 128

启动 Story Agent 后端：

cd Story-agent
PYTHONPATH=backend \
STORY_DATA_DIR=./data/story_index \
STORY_USE_LLM=true \
LLAMA_SERVER_URL=http://127.0.0.1:8080/v1 \
LLAMA_MODEL=qwen \
.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

运行测试：

# 正确性测试
python3 -u scripts/run_project_tests.py --suite correctness \
  --binary paged-llama.cpp/build-cann/bin/llama-server \
  --model models/Qwen3-8B-Q8_0.gguf \
  --device CANN0 --memory-source npu --gpu-index 0 \
  --output-dir test_runs/correctness --port 18090

# 集成测试
python3 -u scripts/test_integration_20.py \
  --url http://127.0.0.1:8000/api/chat/stream \
  --prompts Story-agent/scripts/benchmark_prompts_20.txt \
  --max-tokens 128 --timeout 3600 \
  --output test_runs/integration.json

环境要求

操作系统：openEuler 22.03 LTS-SP3 或兼容 Linux 发行版
CANN 后端：Ascend NPU + CANN Toolkit 8.5.0+
CUDA 后端：NVIDIA GPU + CUDA 13.0+（RTX 5090 验证）
Python 3.10/3.11、Node.js 20+、CMake、GCC/G++
模型：Qwen3-8B（GGUF 格式，Q8_0 量化）

文档索引

文档	说明
`操作系统开源创新大赛项目说明书.pdf`	完整技术方案、系统设计与实现细节
`使用说明-CANN.md`	CANN 后端详细构建、部署与测试指南
`使用说明-CUDA.md`	CUDA 后端详细构建、部署与测试指南
`README-original.md`	赛题原始说明
`Story-agent/README.md`	Story Agent 应用说明
`Story-agent/CODE_READING_GUIDE.txt`	Story Agent 代码阅读指南