vLLM-Ascend 参数适配项目

项目简介

本项目为CCF 开源创新大赛 - vLLM Ascend参赛项目。

目标：适配昇腾 NPU 尚未支持的 vLLM 启动参数。

---

参赛要求

必须交付内容

1. ✅ 源码适配代码（Python）
2. ✅ SKILL.md（使用 AI 工具完成适配任务的说明）
3. ✅ PR 提交至 https://www.gitlink.org.cn/vllm-ascend/ccf-vllm-ascend

技术难点

• 深入理解 vLLM 推理框架核心原理
• 分析昇腾（Ascend）与 GPU 平台的技术差异
• 适配未支持的 vLLM 启动参数

---

认领参数（示例）

参数 1：--max-padding-len（示例）

• 功能：控制最大 padding 长度
• GPU 支持：✅ 已支持
• Ascend 支持：❌ 未支持
• 适配难点：昇腾算子不支持动态 padding

参数 2：--block-size（示例）

• 功能：控制 KV Cache 块大小
• GPU 支持：✅ 已支持
• Ascend 支持：❌ 未支持
• 适配难点：内存对齐要求不同

注意：实际认领的参数需从竞赛参数列表中选取（https://docs.qq.com/sheet/DZGxyV1VWcVVMZFFT?tab=BB08J2）

---

项目结构

vllm-ascend-adapter/
├── README.md                    # 本文件
├── SKILL.md                     # AI 工具使用说明（参赛必须）
├── src/
│   ├── __init__.py
│   ├── adapter.py              # 参数适配核心代码
│   ├── ascend_kernel.py       # 昇腾内核适配
│   └── param_validator.py    # 参数验证
├── test/
│   ├── __init__.py
│   ├── test_adapter.py        # 适配代码测试
│   └── test_params.py        # 参数验证测试
├── skills/
│   └── vllm-ascend-skill.md  # 参赛指南（如何认领、开发、提交）
└── docs/
    ├── PARAM_LIST.md           # 认领的参数列表
    ├── TECH_ANALYSIS.md       # GPU vs Ascend 技术差异分析
    └── ADAPTATION_GUIDE.md   # 参数适配指南

---

快速开始

1. 环境准备

# 克隆官方仓库（确保版本一致）
git clone https://github.com/vllm-project/vllm.git
cd vllm
git checkout main  # 或指定版本

# 安装昇腾 CANN（根据官方文档）
# 从 https://www.hiascend.com/ 下载安装

# 安装 vllm-ascend（基础版本）
git clone https://www.gitlink.org.cn/vllm-ascend/ccf-vllm-ascend.git
cd ccf-vllm-ascend
# 切换到 main 分支（确保版本一致）
git checkout main

2. 认领参数

1. 访问参数列表：https://docs.qq.com/sheet/DZGxyV1VWcVVMZFFT?tab=BB08J2
2. 选择 2 个未支持参数
3. 在 docs/PARAM_LIST.md 中记录
4. 在 ccf-vllm-ascend 仓库中认领（按参赛指南）

3. 开发适配代码

# 创建开发分支
cd ccf-vllm-ascend
git checkout -b feature/adapt-param-X-and-Y

# 开发适配代码（详见 src/adapter.py）
# ...

# 测试
python -m pytest test/

# 提交
git add .
git commit -m "feat: adapt params X and Y for Ascend"
git push origin feature/adapt-param-X-and-Y

4. 使用 AI 工具（必须）

本项目提倡使用 AI 工具完成适配任务。

推荐 AI 工具：

• GitHub Copilot
• Claude Code
• Cursor
• Hermes Agent（本工具）

AI 使用说明（必须写入 SKILL.md）：

1. 如何使用 AI 分析 vLLM 源码
2. 如何使用 AI 生成适配代码
3. 如何使用 AI 调试 Ascend 算子
4. AI 工具的限制和注意事项

---

开发指南

参数适配流程

1. 理解参数功能

   • 阅读 vLLM 官方文档
   • 查看 GPU 实现代码
   • 理解参数对推理的影响

2. 分析技术差异

   • GPU vs Ascend 架构差异
   • CANN 算子支持情况
   • 内存管理差异

3. 设计适配方案

   • 修改 vLLM 参数解析
   • 适配 Ascend 算子调用
   • 处理边界情况

4. 实现代码

   • 修改 vllm/engine/arg_utils.py（参数注册）
   • 修改 vllm/model_executor/layers/（算子适配）
   • 添加 Ascend 特定逻辑

5. 测试验证

   • 单元测试
   • 集成测试
   • 性能对比（GPU vs Ascend）

示例：适配 --max-padding-len

# 文件：vllm/engine/arg_utils.py

def add_cli_args(parser):
    # ... 其他参数
    parser.add_argument(
        "--max-padding-len",
        type=int,
        default=256,
        help="Maximum padding length (Ascend adapted)"
    )

# 文件：vllm/model_executor/layers/ascend_ops.py

import torch
from torch_npu import npu_ops  # 昇腾算子

def padded_attention(query, key, value, max_padding_len):
    """
    适配昇腾的 padded attention
    注意：昇腾不支持动态 padding，需固定大小
    """
    # GPU 实现（参考）
    # attn_output = F.scaled_dot_product_attention(query, key, value)
    
    # Ascend 适配实现
    if torch_npu.is_available():
        # 使用昇腾特定算子
        attn_output = npu_ops.npu_padded_attention(
            query, key, value,
            max_padding_len=max_padding_len
        )
    else:
        raise RuntimeError("Ascend NPU not available")
    
    return attn_output

---

测试

单元测试

cd /workspace/vllm-ascend-adapter
python -m pytest test/ -v

集成测试

# 启动 vLLM（带适配参数）
python -m vllm.entrypoints.openai.api_server \
    --model /path/to/model \
    --max-padding-len 256 \  # 适配的参数
    --block-size 32          # 适配的参数

---

提交 PR

1. 推送到 fork

cd ccf-vllm-ascend
git push origin feature/adapt-param-X-and-Y

2. 创建 PR

1. 访问 https://www.gitlink.org.cn/vllm-ascend/ccf-vllm-ascend
2. 点击 “Compare & pull request”
3. 填写 PR 描述：
   • 认领的参数名称
   • 适配方案说明
   • 测试结果
   • AI 工具使用说明（链接到 SKILL.md）

3. 必须包含的文件

• ✅ 源码适配代码（.py 文件）
• ✅ SKILL.md（AI 工具使用说明）
• ✅ 测试代码
• ✅ 文档更新

---

参赛指南

认领参数流程

1. 访问参数列表（腾讯文档）
2. 选择 2 个未支持参数（状态为”未认领”）
3. 在文档中填写你的信息（姓名、联系方式）
4. 在 ccf-vllm-ascend 仓库 Issues 中声明认领

开发环境要求

• CANN 版本：与 GitHub 仓库 main 分支一致
• vLLM 版本：与 GitHub 仓库 main 分支一致
• vLLM-Ascend 版本：与 GitLink 仓库 main 分支一致

重要：版本不一致可能导致适配失败！

提交要求

• ✅ 代码符合 PEP 8 规范
• ✅ 添加单元测试
• ✅ 更新相关文档
• ✅ 编写 SKILL.md（AI 工具使用说明）
• ✅ PR 描述清晰、完整

---

参考资料

官方资源

• vLLM GitHub：https://github.com/vllm-project/vllm
• vLLM-Ascend GitLink：https://www.gitlink.org.cn/vllm-ascend/ccf-vllm-ascend
• 昇腾社区：https://www.hiascend.com/
• CANN 文档：https://www.hiascend.com/document

参赛指南

• 参数列表：https://docs.qq.com/sheet/DZGxyV1VWcVVMZFFT?tab=BB08J2
• 参赛指南：（查看赛事官方文档）

技术参考

• vLLM 参数文档：https://docs.vllm.ai/
• PyTorch NPU：https://gitee.com/ascend/pytorch
• 昇腾算子参考：https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/700R001/operatorac

---

项目状态

• 当前阶段：项目初始化 ✅
• 认领参数：❌ 待认领（需访问腾讯文档）
• 适配开发：❌ 待开始
• AI 工具使用：❌ 待编写 SKILL.md
• PR 提交：❌ 待提交

---

下一步

1. 访问参数列表，认领 2 个参数
2. 创建开发分支，开始适配开发
3. 使用 AI 工具辅助开发
4. 编写 SKILL.md，记录 AI 使用过程
5. 测试验证，确保功能正确
6. 提交 PR，完成参赛任务

---

加油！祝你在 CCF 开源创新大赛中取得优异成绩！ 🏆🎊

项目地址：

• 参赛仓库：https://www.gitlink.org.cn/vllm-ascend/ccf-vllm-ascend
• 参数列表：https://docs.qq.com/sheet/DZGxyV1VWcVVMZFFT?tab=BB08J2