[Doc] Add sphinx build for vllm-ascend (#55)
### What this PR does / why we need it?
This patch enables the doc build for vllm-ascend
- Add sphinx build for vllm-ascend
- Enable readthedocs for vllm-ascend
- Fix CI:
- exclude vllm-empty/tests/mistral_tool_use to skip `You need to agree
to share your contact information to access this model` which introduce
in
314cfade02
- Install test req to fix
https://github.com/vllm-project/vllm-ascend/actions/runs/13304112758/job/37151690770:
```
vllm-empty/tests/mistral_tool_use/conftest.py:4: in <module>
import pytest_asyncio
E ModuleNotFoundError: No module named 'pytest_asyncio'
```
- exclude docs PR
### Does this PR introduce _any_ user-facing change?
No
### How was this patch tested?
1. test locally:
```bash
# Install dependencies.
pip install -r requirements-docs.txt
# Build the docs and preview
make clean; make html; python -m http.server -d build/html/
```
Launch browser and open http://localhost:8000/.
2. CI passed with preview:
https://vllm-ascend--55.org.readthedocs.build/en/55/
Signed-off-by: Yikun Jiang <yikunkero@gmail.com>
This commit is contained in:
Yikun Jiang
107
docs/source/developer_guide/contributing.md
Normal file
107
docs/source/developer_guide/contributing.md
Normal file
@@ -0,0 +1,107 @@
|
||||
# Contributing
|
||||
|
||||
## Building and testing
|
||||
It's recommended to set up a local development environment to build and test
|
||||
before you submit a PR.
|
||||
|
||||
### Prepare environment and build
|
||||
|
||||
Theoretically, the vllm-ascend build is only supported on Linux because
|
||||
`vllm-ascend` dependency `torch_npu` only supports Linux.
|
||||
|
||||
But you can still set up dev env on Linux/Windows/macOS for linting and basic
|
||||
test as following commands:
|
||||
|
||||
```bash
|
||||
# Choose a base dir (~/vllm-project/) and set up venv
|
||||
cd ~/vllm-project/
|
||||
python3 -m venv .venv
|
||||
source ./.venv/bin/activate
|
||||
|
||||
# Clone vllm code and install
|
||||
git clone https://github.com/vllm-project/vllm.git
|
||||
cd vllm
|
||||
pip install -r requirements-build.txt
|
||||
VLLM_TARGET_DEVICE="empty" pip install .
|
||||
cd ..
|
||||
|
||||
# Clone vllm-ascend and install
|
||||
git clone https://github.com/vllm-project/vllm-ascend.git
|
||||
cd vllm-ascend
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
# Then you can run lint and mypy test
|
||||
bash format.sh
|
||||
|
||||
# Build:
|
||||
# - only supported on Linux (torch_npu available)
|
||||
# pip install -e .
|
||||
# - build without deps for debugging in other OS
|
||||
# pip install -e . --no-deps
|
||||
|
||||
# Commit changed files using `-s`
|
||||
git commit -sm "your commit info"
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
Although vllm-ascend CI provide integration test on [Ascend](https://github.com/vllm-project/vllm-ascend/blob/main/.github/workflows/vllm_ascend_test.yaml), you can run it
|
||||
locally. The simplest way to run these integration tests locally is through a container:
|
||||
|
||||
```bash
|
||||
# Under Ascend NPU environment
|
||||
git clone https://github.com/vllm-project/vllm-ascend.git
|
||||
cd vllm-ascend
|
||||
|
||||
IMAGE=vllm-ascend-dev-image
|
||||
CONTAINER_NAME=vllm-ascend-dev
|
||||
DEVICE=/dev/davinci1
|
||||
|
||||
# The first build will take about 10 mins (10MB/s) to download the base image and packages
|
||||
docker build -t $IMAGE -f ./Dockerfile .
|
||||
# You can also specify the mirror repo via setting VLLM_REPO to speedup
|
||||
# docker build -t $IMAGE -f ./Dockerfile . --build-arg VLLM_REPO=https://gitee.com/mirrors/vllm
|
||||
|
||||
docker run --name $CONTAINER_NAME --network host --device $DEVICE \
|
||||
--device /dev/davinci_manager --device /dev/devmm_svm \
|
||||
--device /dev/hisi_hdc -v /usr/local/dcmi:/usr/local/dcmi \
|
||||
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
|
||||
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
|
||||
-ti --rm $IMAGE bash
|
||||
|
||||
cd vllm-ascend
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
pytest tests/
|
||||
```
|
||||
|
||||
## DCO and Signed-off-by
|
||||
|
||||
When contributing changes to this project, you must agree to the DCO. Commits must include a `Signed-off-by:` header which certifies agreement with the terms of the DCO.
|
||||
|
||||
Using `-s` with `git commit` will automatically add this header.
|
||||
|
||||
## PR Title and Classification
|
||||
|
||||
Only specific types of PRs will be reviewed. The PR title is prefixed appropriately to indicate the type of change. Please use one of the following:
|
||||
|
||||
- `[Attention]` for new features or optimization in attention.
|
||||
- `[Communicator]` for new features or optimization in communicators.
|
||||
- `[ModelRunner]` for new features or optimization in model runner.
|
||||
- `[Platform]` for new features or optimization in platform.
|
||||
- `[Worker]` for new features or optimization in worker.
|
||||
- `[Core]` for new features or optimization in the core vllm-ascend logic (such as platform, attention, communicators, model runner)
|
||||
- `[Kernel]` changes affecting compute kernels and ops.
|
||||
- `[Bugfix]` for bug fixes.
|
||||
- `[Doc]` for documentation fixes and improvements.
|
||||
- `[Test]` for tests (such as unit tests).
|
||||
- `[CI]` for build or continuous integration improvements.
|
||||
- `[Misc]` for PRs that do not fit the above categories. Please use this sparingly.
|
||||
|
||||
> [!NOTE]
|
||||
> If the PR spans more than one category, please include all relevant prefixes.
|
||||
|
||||
## Others
|
||||
|
||||
You may find more information about contributing to vLLM Ascend backend plugin on [<u>docs.vllm.ai</u>](https://docs.vllm.ai/en/latest/contributing/overview.html).
|
||||
If you find any problem when contributing, you can feel free to submit a PR to improve the doc to help other developers.
|
||||
102
docs/source/developer_guide/contributing.zh.md
Normal file
102
docs/source/developer_guide/contributing.zh.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# 贡献指南
|
||||
|
||||
## 构建与测试
|
||||
我们推荐您在提交PR之前在本地开发环境进行构建和测试。
|
||||
|
||||
### 环境准备与构建
|
||||
理论上，vllm-ascend 构建仅支持 Linux，因为`vllm-ascend` 依赖项 `torch_npu` 仅支持 Linux。
|
||||
|
||||
但是您仍然可以在 Linux/Windows/macOS 上配置开发环境进行代码检查和基本测试，如下命令所示：
|
||||
|
||||
```bash
|
||||
# 选择基础文件夹 (~/vllm-project/) ，创建python虚拟环境
|
||||
cd ~/vllm-project/
|
||||
python3 -m venv .venv
|
||||
source ./.venv/bin/activate
|
||||
|
||||
# 克隆并安装vllm
|
||||
git clone https://github.com/vllm-project/vllm.git
|
||||
cd vllm
|
||||
pip install -r requirements-build.txt
|
||||
VLLM_TARGET_DEVICE="empty" pip install .
|
||||
cd ..
|
||||
|
||||
# 克隆并安装vllm-ascend
|
||||
git clone https://github.com/vllm-project/vllm-ascend.git
|
||||
cd vllm-ascend
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
# 通过执行以下脚本以运行 lint 及 mypy 测试
|
||||
bash format.sh
|
||||
|
||||
# 构建:
|
||||
# - 目前仅支持在Linux上进行完整构建（torch_npu 限制）
|
||||
# pip install -e .
|
||||
# - 在其他操作系统上构建安装，需要跳过依赖
|
||||
# - build without deps for debugging in other OS
|
||||
# pip install -e . --no-deps
|
||||
|
||||
# 使用 `-s` 提交更改
|
||||
git commit -sm "your commit info"
|
||||
```
|
||||
|
||||
### 测试
|
||||
虽然 vllm-ascend CI 提供了对 [Ascend](https://github.com/vllm-project/vllm-ascend/blob/main/.github/workflows/vllm_ascend_test.yaml) 的集成测试，但您也可以在本地运行它。在本地运行这些集成测试的最简单方法是通过容器：
|
||||
|
||||
```bash
|
||||
# 基于昇腾NPU环境
|
||||
git clone https://github.com/vllm-project/vllm-ascend.git
|
||||
cd vllm-ascend
|
||||
|
||||
IMAGE=vllm-ascend-dev-image
|
||||
CONTAINER_NAME=vllm-ascend-dev
|
||||
DEVICE=/dev/davinci1
|
||||
|
||||
# 首次构建会花费10分钟（10MB/s）下载基础镜像和包
|
||||
docker build -t $IMAGE -f ./Dockerfile .
|
||||
# 您还可以通过设置 VLLM_REPO 来指定镜像仓库以加速
|
||||
# docker build -t $IMAGE -f ./Dockerfile . --build-arg VLLM_REPO=https://gitee.com/mirrors/vllm
|
||||
|
||||
docker run --name $CONTAINER_NAME --network host --device $DEVICE \
|
||||
--device /dev/davinci_manager --device /dev/devmm_svm \
|
||||
--device /dev/hisi_hdc -v /usr/local/dcmi:/usr/local/dcmi \
|
||||
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
|
||||
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
|
||||
-ti --rm $IMAGE bash
|
||||
|
||||
cd vllm-ascend
|
||||
pip install -r requirements-dev.txt
|
||||
|
||||
pytest tests/
|
||||
```
|
||||
|
||||
## 开发者来源证书(DCO)
|
||||
|
||||
在向本项目提交贡献时，您必须同意 DCO。提交必须包含“Signed-off-by:”标头，以证明同意 DCO 的条款。
|
||||
|
||||
在`git commit`时使用`-s`将会自动添加该标头。
|
||||
|
||||
## PR 标题和分类
|
||||
|
||||
仅特定类型的 PR 会被审核。PR 标题会以适当的前缀来表明变更类型。请使用以下之一：
|
||||
|
||||
- `[Attention]` 关于`attention`的新特性或优化
|
||||
- `[Communicator]` 关于`communicators`的新特性或优化
|
||||
- `[ModelRunner]` 关于`model runner`的新特性或优化
|
||||
- `[Platform]` 关于`platform`的新特性或优化
|
||||
- `[Worker]` 关于`worker`的新特性或优化
|
||||
- `[Core]` 关于`vllm-ascend`核心逻辑 (如 `platform, attention, communicators, model runner`)的新特性或优化
|
||||
- `[Kernel]` 影响计算内核和操作的更改.
|
||||
- `[Bugfix]` bug修复
|
||||
- `[Doc]` 文档的修复与更新
|
||||
- `[Test]` 测试 (如：单元测试)
|
||||
- `[CI]` 构建或持续集成改进
|
||||
- `[Misc]` 适用于更改内容对于上述类别均不适用的PR，请谨慎使用该前缀
|
||||
|
||||
> [!注意]
|
||||
> 如果 PR 涉及多个类别，请添加所有相关前缀
|
||||
|
||||
## 其他
|
||||
|
||||
您可以在 [<u>docs.vllm.ai</u>](https://docs.vllm.ai/en/latest/contributing/overview.html) 上找到更多有关为 vLLM 昇腾插件贡献的信息。
|
||||
如果您在贡献过程中发现任何问题，您可以随时提交 PR 来改进文档以帮助其他开发人员。
|
||||
Reference in New Issue
Block a user