Aaa_111667 vLLM-Ascend 参数适配交付

参赛信息

队伍名：Aaa_111667
认领参数：--offload-prefetch-step、--offload-params
目标平台：Ascend NPU
验证设备：Ascend 910B3，64 GiB HBM
CANN：9.0.0

本仓库分支仅包含本次参数适配的比赛交付内容：源码修复、测试、文档、可复现基准脚本，以及使用 AI 工具完成适配任务所沉淀的 SKILL.md。它不是完整上游 vLLM-Ascend 仓库的镜像。

适配内容

修复有效卸载模块数不能被预取步长整除时的静态缓冲区槽位归属问题。
按 offload_params 过滤后的有效模块数限制静态缓冲池大小。
对只有一个归属模块的槽位跳过冗余回填。
使用参数名点分段的整段匹配，避免误选 scale、offset 等相邻参数。
修正 E2E 基线，确保输出比较前移除所有卸载相关选项。

交付文件

类型	路径
适配源码	`vllm_ascend/model_executor/offloader/prefetch.py`
单元测试	`tests/ut/model_executor/`
NPU E2E	`tests/e2e/pull_request/one_card/test_cpu_weight_offload.py`
E2E 基线工具	`tests/e2e/pull_request/utils.py`
用户文档	`docs/source/user_guide/feature_guide/weight_cpu_offload.md`
文档导航	`docs/hooks/nav_titles.py`、`mkdocs.yml`
基准脚本	`benchmarks/scripts/run-weight-cpu-offload-benchmarks.sh`
结果汇总	`benchmarks/scripts/summarize-weight-cpu-offload.py`
AI 工作流	`SKILL.md`
版本绑定	`.github/vllm-main-verified.commit`

版本组合

vLLM-Ascend 基线：6cd692a8038cc0e8e8c2cd285244b46893f0c715
已验证开发提交：43d8f6e55dd933873d7f57375b056ce43cadc921
已验证 vLLM：1f486d96a17303ce8db8e02be39545b2be338446

验证结果

Ruff、格式、空白、Bash、ShellCheck、Markdownlint：通过
offloader 单元测试：9 passed
NPU 针对性 E2E：4 passed, 6 deselected
完整 CPU 权重卸载 E2E：10 passed
Qwen3-8B 冒烟矩阵：6/6 通过
Qwen3-8B 正式性能矩阵：18/18 通过
所有性能配置固定使用 32 GiB KV cache

复现方法

python -m pytest -sv tests/ut/model_executor/test_prefetch_offloader.py
python -m pytest -sv \
  tests/e2e/pull_request/one_card/test_cpu_weight_offload.py \
  -k "multi_step_non_divisible or step_exceeds_module_count"
python -m pytest -sv tests/e2e/pull_request/one_card/test_cpu_weight_offload.py

NUM_PROMPTS=32 REPEATS=1 \
  bash benchmarks/scripts/run-weight-cpu-offload-benchmarks.sh
NUM_PROMPTS=200 REPEATS=3 \
  bash benchmarks/scripts/run-weight-cpu-offload-benchmarks.sh

社区方案重叠说明

GitLink PR #16033 独立修复了 1 <= step < M 范围内相同的非整除环边界问题，本提交不将该行为声明为独有贡献。本提交独立覆盖 step >= M 时按有效模块数限制缓冲区，以及跳过单归属槽位冗余回填的路径。