# 决赛材料设计说明

## 1. 目标与交付物

本次工作基于分支 `feature/offload-group-num-v018-optimized` 的当前代码、初赛结项材料及已有测试结果，形成一套可用于决赛提交与 12 分钟现场答辩的正式材料。

最终交付物统一放在 `docs/finals/`：

1. `决赛项目结项书.md`：便于代码仓审阅和版本追踪。
2. `决赛项目结项书.docx`：正式排版版本，包含封面、目录、正文、表格、页眉页脚和页码。
3. `决赛答辩PPT.pptx`：继承赛事提供的 PowerPoint 模板，用于 12 分钟答辩。

项目主标题沿用：

> [功能] 适配 offload_group_size 和 offload_num_in_group 到 Ascend NPU

副标题使用：

> vLLM Ascend 权重分组预取卸载参数适配与优化

团队名称使用“乘风破浪的大学生”。

## 2. 内容事实与证据口径

材料只使用仓库中能够复核的代码、脚本和测试结果，不虚构远端性能数据或主仓对比结论。

关键环境口径：

- vLLM Ascend：v0.18.0 基线，提交 `72dc68973bd7e6ceef9a122de316a7ee9c9a84aa`
- 当前优化提交：`f0ab80524e2088763ab1e9859534f05912850194`
- 模型：`Qwen2.5-1.5B-Instruct`
- CANN：8.5.1
- PyTorch：2.9.0+cpu
- torch-npu：2.9.0
- triton-ascend：3.2.0.dev20260322

验证结果口径：

- 本地验收：35/35
- 远端 offloader 测试：69 passed，21 subtests passed
- GSM8K：baseline、group_8_num_1、group_8_num_2 均为 51/1319，精度差异为 0
- GPQA Diamond：三组均为 0/198，输出哈希一致；必须明确这是小模型零样本基线表现，不表述为高精度
- 性能中位数：
  - baseline：742.77 tok/s
  - group_8_num_1：678.85 tok/s，节省约 0.2615 GB 权重常驻空间
  - group_8_num_2：383.49 tok/s，节省约 0.5230 GB 权重常驻空间

性能结论表述为“可配置的显存容量与吞吐权衡”，不将吞吐下降包装为性能提升。

## 3. 结项书结构

结项书沿用初赛项目结项书的七章结构，并补充决赛阶段优化、主仓版本背景和完整复现方式：

1. 项目概述
2. 参数理解与技术难点
3. 技术方案
4. 实际交付
5. 测试结论
6. AI 工具使用经验
7. 限制与后续工作

正文重点说明：

- 两个参数的语义、约束和适用场景
- Ascend `PrefetchOffloader` 的静态缓冲、NPU Stream/Event 和分组预取机制
- 对 vLLM 官方 `auto/prefetch/uva` 后端选择方式的兼容
- pinned CPU storage、stride/dtype 保持、设备映射和健康检查
- 决赛相对初赛的工程化增强
- GSM8K、GPQA 和性能测试的一键复现命令、输出路径与判定标准
- v0.18.0 目标主仓未包含 Ascend 专用实现，因此“必须优于主仓已有实现”的附加条件不适用于本目标基线

Word 版本采用正式技术报告风格，以清晰层级、稳定表格和可打印性为主，不使用装饰性过强的版式。

## 4. PPT 结构与节奏

PPT 使用赛事模板的 12 页结构，不额外增加页面：

1. 封面
2. 决赛成果总览
3. 参数语义与收益边界
4. Ascend 分组预取卸载架构
5. 项目概述与版本背景
6. 设计实现
7. 功能与工程验证
8. GSM8K、GPQA 精度测试
9. 性能与显存权衡
10. AI 辅助参与与效果
11. 创新点与决赛阶段提升
12. 总结与致谢

正式讲述目标为 11 分 20 秒，预留约 40 秒缓冲。第 6、9、11 页是答辩重点，总计约 4 分 40 秒。

每页采用“一个结论 + 一组证据”的表达方式，避免将结项书段落直接搬进幻灯片。图表优先展示参数关系、数据流、测试矩阵和量化结果。

## 5. 模板继承规则

- 保留赛事模板的母版、页面比例、标题体系、页脚和品牌视觉。
- 模板中的示意页只作为布局参考，清除“请勿直接填写”等提示文字。
- 不改变封面和结束页的核心视觉识别。
- 新增内容必须落在模板既有内容区域内，不遮挡标题、页码或赛事标识。
- 性能和精度数据采用同一套数字格式，图例能够区分 baseline、group_8_num_1 和 group_8_num_2。
- 在 PowerPoint 备注中记录每页证据来源和建议讲述要点。

## 6. 验收标准

### 内容验收

- 三份交付物的标题、团队名称、版本和测试数字完全一致。
- 两个参数均有实现说明、精度验证、性能验证和复现脚本说明。
- 明确解释 GPQA 结果为 0 的背景，并保留输出一致性证据。
- 明确解释显存收益与吞吐损失，不作超出证据的结论。

### 文档验收

- Markdown 链接和代码路径有效。
- Word 文档可正常打开，目录、表格、分页、页眉页脚和中文字体显示正常。
- Word 文档经过逐页 PNG 渲染检查，无截断、重叠、孤立标题或空白异常。

### PPT 验收

- 12 页完整，适配 12 分钟答辩。
- 继承模板母版及主要视觉语言。
- 所有页面经过桌面比例渲染检查，无文本溢出、遮挡或错位。
- 通过幻灯片结构检查和模板一致性检查。

### 仓库验收

- 最终文件位于 `docs/finals/`。
- 核心代码和已有测试结果不被改写。
- 制作脚本与内部渲染中间件不作为决赛交付物放入 `docs/finals/`。
