
# vLLM Ascend 参数适配专项赛 — 最终结项材料

> 赛道: CCF 开源创新大赛 vLLM Ascend 参数适配专项赛  
> 认领参数: `offload_group_size` + `offload_num_in_group`  
> 测试日期: 2026-07-05  
> 参考提交材料结构: `Aiminer/ccf-vllm-ascend:feature/dbo-re-ascend-adapt`

---

## 一、项目概述

本次工作在 vLLM Ascend 后端适配权重 offload 参数，使用户可按 decoder layer group 控制部分层权重驻留在 host/static buffer，并在需要时换入 NPU 执行。

## 二、参数理解与技术难点

| 参数 | 含义 | 难点 |
|---|---|---|
| `offload_group_size` | 每多少层组成一个 offload group | 需要稳定映射 layer name 到 layer id |
| `offload_num_in_group` | 每个 group 中 offload 的层数 | 需要校验 `num <= group_size`，并保证默认行为不变 |

技术难点包括：

1. Ascend OOT 插件需要在模型加载前注入 vLLM offloader。
2. offload wrap 与真实模型 layer 命名存在耦合，必须可测试。
3. NPU 权重换入换出需要同时提供保守同步路径与可扩展预取路径。
4. 参数的收益不是单纯吞吐提升，而是 HBM 节省与吞吐之间的 trade-off，必须通过 benchmark 呈现。

## 三、技术方案

新增 `vllm_ascend/model_executor/offloader/` 模块：

- `selection.py`: 实现 group 参数选择规则。
- `sync.py`: 实现同步权重 offload。
- `prefetch.py`: 实现静态 buffer / 预取 offload。
- `__init__.py`: 暴露公共接口。

修改 `worker/model_runner_v1.py`：

- 新增 `create_ascend_weight_offloader(offload_config)`。
- 在 runner 初始化阶段调用 `set_offloader()`。
- 增加参数校验、实现选择和日志统计。

## 四、实际交付

| 类型 | 文件 |
|---|---|
| 源码 | `vllm_ascend/model_executor/offloader/*.py` |
| 集成 | `vllm_ascend/worker/model_runner_v1.py` |
| 单测 | `tests/model_executor/offloader/*.py`, `tests/model_executor/offloader/offload_group_size/*.py`, `tests/model_executor/offloader/offload_num_in_group/*.py` |
| 冒烟脚本 | `/data/vllm-ascend-smoke/run_smoke*.sh` |
| benchmark | `/data/vllm-ascend-smoke/run_benchmark_all.sh` |
| 稳定性 | `/data/vllm-ascend-smoke/run_stability_100.sh` |
| 文档 | `docs/offload-group-size/*.md`, `docs/offload-num-in-group/*.md`, `docs/benchmark/*.md` |

## 五、测试结论

单测：

```text
35 passed, 3 warnings
```

真实 Ascend 冒烟：

- baseline: `SMOKE_OK`
- prefetch offload: `SMOKE_OK_OFFLOAD`
- sync offload: `SMOKE_OK_OFFLOAD`
- invalid `offload_num_in_group > offload_group_size`: `SMOKE_INVALID_OK`

1.5B benchmark 表明：

- 少量 offload 可释放 HBM 且吞吐接近 baseline。
- offload 层数增加后 HBM 节省增加，但吞吐下降。
- `offload_group_size` 与 `offload_num_in_group` 的 layer 选择语义被 benchmark 和单测共同验证。

## 六、AI 工具使用经验

本次开发采用 AI 协助完成环境排查、代码实现、测试补齐和文档整理。关键经验：

1. 先用最小模型跑通冒烟，再扩大到 1.5B 模型做参数矩阵。
2. 每个参数都需要单独测试，不只依赖端到端推理。
3. 对性能参数，PR 材料必须同时说明收益和代价，避免只报告通过状态。
4. 对参考 PR/分支，优先复用其交付结构，而不是照抄具体实现。

## 七、限制与后续工作

- 当前验证聚焦单卡 eager 推理。
- TTFT 使用 `LLM.generate(max_tokens=1)` proxy，后续可补 server streaming TTFT。
- 后续可继续验证长上下文、多并发、多卡和 ACL graph 场景。
