Skip to content

Commit 8cb5615

Browse files
PotabkPotabk
authored
[Doc]Add chinese doc (vllm-project#10)
### What this PR does / why we need it? This PR adds Chinese documents for vllm-ascend for Chinese-speaking developers ### Does this PR introduce _any_ user-facing change? Change as follows - add README.zh.md - add environment.zh.md - add CONTRIBUTING.zh.md ### How was this patch tested? By CI --------- Signed-off-by: wangli <[email protected]>
1 parent a48b9ad commit 8cb5615

File tree

4 files changed

+295
-0
lines changed

4 files changed

+295
-0
lines changed

‎CONTRIBUTING.zh.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# 为 vLLM 昇腾插件贡献
2+
3+
## 构建与测试
4+
我们推荐您在提交PR之前在本地开发环境进行构建和测试。
5+
6+
### 环境准备与构建
7+
理论上，vllm-ascend 构建仅支持 Linux，因为`vllm-ascend` 依赖项 `torch_npu` 仅支持 Linux。
8+
9+
但是您仍然可以在 Linux/Windows/macOS 上配置开发环境进行代码检查和基本测试，如下命令所示：
10+
11+
```bash
12+
# 选择基础文件夹 (~/vllm-project/) ，创建python虚拟环境
13+
cd ~/vllm-project/
14+
python3 -m venv .venv
15+
source ./.venv/bin/activate
16+
17+
# 克隆并安装vllm
18+
git clone https://github.com/vllm-project/vllm.git
19+
cd vllm
20+
pip install -r requirements-build.txt
21+
VLLM_TARGET_DEVICE="empty" pip install .
22+
cd ..
23+
24+
# 克隆并安装vllm-ascend
25+
git clone https://github.com/vllm-project/vllm-ascend.git
26+
cd vllm-ascend
27+
pip install -r requirements-dev.txt
28+
29+
# 通过执行以下脚本以运行 lint 及 mypy 测试
30+
bash format.sh
31+
32+
# 构建:
33+
# - 目前仅支持在Linux上进行完整构建（torch_npu 限制）
34+
# pip install -e .
35+
# - 在其他操作系统上构建安装，需要跳过依赖
36+
# - build without deps for debugging in other OS
37+
# pip install -e . --no-deps
38+
39+
# 使用 `-s` 提交更改
40+
git commit -sm "your commit info"
41+
```
42+
43+
### 测试
44+
虽然 vllm-ascend CI 提供了对 [Ascend](.github/workflows/vllm_ascend_test.yaml) 的集成测试，但您也可以在本地运行它。在本地运行这些集成测试的最简单方法是通过容器：
45+
46+
```bash
47+
# 基于昇腾NPU环境
48+
git clone https://github.com/vllm-project/vllm-ascend.git
49+
cd vllm-ascend
50+
51+
IMAGE=vllm-ascend-dev-image
52+
CONTAINER_NAME=vllm-ascend-dev
53+
DEVICE=/dev/davinci1
54+
55+
# 首次构建会花费10分钟（10MB/s）下载基础镜像和包
56+
docker build -t $IMAGE -f ./Dockerfile .
57+
# 您还可以通过设置 VLLM_REPO 来指定镜像仓库以加速
58+
# docker build -t $IMAGE -f ./Dockerfile . --build-arg VLLM_REPO=https://gitee.com/mirrors/vllm
59+
60+
docker run --name $CONTAINER_NAME --network host --device $DEVICE \
61+
--device /dev/davinci_manager --device /dev/devmm_svm \
62+
--device /dev/hisi_hdc -v /usr/local/dcmi:/usr/local/dcmi \
63+
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
64+
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
65+
-ti --rm $IMAGE bash
66+
67+
cd vllm-ascend
68+
pip install -r requirements-dev.txt
69+
70+
pytest tests/
71+
```
72+
73+
## 开发者来源证书(DCO)
74+
75+
在向本项目提交贡献时，您必须同意 DCO。提交必须包含“Signed-off-by:”标头，以证明同意 DCO 的条款。
76+
77+
在`git commit`时使用`-s`将会自动添加该标头。
78+
79+
## PR 标题和分类
80+
81+
仅特定类型的 PR 会被审核。PR 标题会以适当的前缀来表明变更类型。请使用以下之一：
82+
83+
- `[Attention]` 关于`attention`的新特性或优化
84+
- `[Communicator]` 关于`communicators`的新特性或优化
85+
- `[ModelRunner]` 关于`model runner`的新特性或优化
86+
- `[Platform]` 关于`platform`的新特性或优化
87+
- `[Worker]` 关于`worker`的新特性或优化
88+
- `[Core]` 关于`vllm-ascend`核心逻辑 (如 `platform, attention, communicators, model runner`)的新特性或优化
89+
- `[Kernel]` 影响计算内核和操作的更改.
90+
- `[Bugfix]` bug修复
91+
- `[Doc]` 文档的修复与更新
92+
- `[Test]` 测试 (如：单元测试)
93+
- `[CI]` 构建或持续集成改进
94+
- `[Misc]` 适用于更改内容对于上述类别均不适用的PR，请谨慎使用该前缀
95+
96+
> [!注意]
97+
> 如果 PR 涉及多个类别，请添加所有相关前缀
98+
99+
## 其他
100+
101+
您可以在 [<u>docs.vllm.ai</u>](https://docs.vllm.ai/en/latest/contributing/overview.html) 上找到更多有关为 vLLM 昇腾插件贡献的信息。
102+
如果您在贡献过程中发现任何问题，您可以随时提交 PR 来改进文档以帮助其他开发人员。

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ vLLM Ascend Plugin
1414
| <a href="https://www.hiascend.com/en/"><b>About Ascend</b></a> | <a href="https://slack.vllm.ai"><b>Developer Slack (#sig-ascend)</b></a> |
1515
</p>
1616

17+
<p align="center">
18+
<a ><b>English</b></a> | <a href="README.zh.md"><b>中文</b></a>
19+
</p>
20+
1721
---
1822
*Latest News* 🔥
1923

‎README.zh.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
<p align="center">
2+
<picture>
3+
<!-- TODO: Replace tmp link to logo url after vllm-projects/vllm-ascend ready -->
4+
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/4a958093-58b5-4772-a942-638b51ced646">
5+
<img alt="vllm-ascend" src="https://github.com/user-attachments/assets/838afe2f-9a1d-42df-9758-d79b31556de0" width=55%>
6+
</picture>
7+
</p>
8+
9+
<h3 align="center">
10+
vLLM Ascend Plugin
11+
</h3>
12+
13+
<p align="center">
14+
| <a href="https://www.hiascend.com/en/"><b>关于昇腾</b></a> | <a href="https://slack.vllm.ai"><b>开发者 Slack (#sig-ascend)</b></a> |
15+
</p>
16+
17+
<p align="center">
18+
<a href="README.md"><b>English</b></a> | <a><b>中文</b></a>
19+
</p>
20+
21+
---
22+
*最新消息* 🔥
23+
24+
- [2024/12] 我们正在与 vLLM 社区合作，以支持 [[RFC]: Hardware pluggable](https://github.com/vllm-project/vllm/issues/11162).
25+
---
26+
## 总览
27+
28+
vLLM 昇腾插件 (`vllm-ascend`) 是一个让vLLM在Ascend NPU无缝运行的后端插件。
29+
30+
此插件是 vLLM 社区中支持昇腾后端的推荐方式。它遵循[[RFC]: Hardware pluggable](https://github.com/vllm-project/vllm/issues/11162)所述原则：通过解耦的方式提供了vLLM对Ascend NPU的支持。
31+
32+
使用 vLLM 昇腾插件，可以让类Transformer、混合专家(MOE)、嵌入、多模态等流行的大语言模型在 Ascend NPU 上无缝运行。
33+
34+
## 前提
35+
### 支持的设备
36+
- Atlas A2 训练系列 (Atlas 800T A2, Atlas 900 A2 PoD, Atlas 200T A2 Box16, Atlas 300T A2)
37+
- Atlas 800I A2 推理系列 (Atlas 800I A2)
38+
39+
### 依赖
40+
| 需求 | 支持的版本 | 推荐版本 | 注意 |
41+
|-------------|-------------------| ----------- |------------------------------------------|
42+
| vLLM | main | main | vllm-ascend 依赖 |
43+
| Python | >= 3.9 | [3.10](https://www.python.org/downloads/) | vllm 依赖 |
44+
| CANN | >= 8.0.RC2 | [8.0.RC3](https://www.hiascend.com/developer/download/community/result?module=cann&cann=8.0.0.beta1) | vllm-ascend and torch-npu 依赖 |
45+
| torch-npu | >= 2.4.0 | [2.5.1rc1](https://gitee.com/ascend/pytorch/releases/tag/v6.0.0.alpha001-pytorch2.5.1) | vllm-ascend 依赖 |
46+
| torch | >= 2.4.0 | [2.5.1](https://github.com/pytorch/pytorch/releases/tag/v2.5.1) | torch-npu and vllm 依赖 |
47+
48+
在[此处](docs/environment.zh.md)了解更多如何配置您环境的信息。
49+
50+
## 开始使用
51+
52+
> [!NOTE]
53+
> 目前，我们正在积极与 vLLM 社区合作以支持 Ascend 后端插件，一旦支持，您可以使用一行命令: `pip install vllm vllm-ascend` 来完成安装。
54+
55+
通过源码安装:
56+
```bash
57+
# 安装vllm main 分支参考文档:
58+
# https://docs.vllm.ai/en/latest/getting_started/installation/cpu/index.html#build-wheel-from-source
59+
git clone --depth 1 https://github.com/vllm-project/vllm.git
60+
cd vllm
61+
pip install -r requirements-build.txt
62+
VLLM_TARGET_DEVICE=empty pip install .
63+
64+
# 安装vllm-ascend main 分支
65+
git clone https://github.com/vllm-project/vllm-ascend.git
66+
cd vllm-ascend
67+
pip install -e .
68+
```
69+
70+
运行如下命令使用 [Qwen/Qwen2.5-0.5B-Instruct](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct) 模型启动服务:
71+
72+
```bash
73+
# 设置环境变量 VLLM_USE_MODELSCOPE=true 加速下载
74+
vllm serve Qwen/Qwen2.5-0.5B-Instruct
75+
curl http://localhost:8000/v1/models
76+
```
77+
78+
请参阅 [vLLM 快速入门](https://docs.vllm.ai/en/latest/getting_started/quickstart.html)以获取更多详细信息。
79+
80+
## 构建
81+
82+
#### 从源码构建Python包
83+
84+
```bash
85+
git clone https://github.com/vllm-project/vllm-ascend.git
86+
cd vllm-ascend
87+
pip install -e .
88+
```
89+
90+
#### 构建容器镜像
91+
```bash
92+
git clone https://github.com/vllm-project/vllm-ascend.git
93+
cd vllm-ascend
94+
docker build -t vllm-ascend-dev-image -f ./Dockerfile .
95+
```
96+
97+
查看[构建和测试](./CONTRIBUTING.zh.md)以获取更多详细信息，其中包含逐步指南，帮助您设置开发环境、构建和测试。
98+
99+
## 特性支持矩阵
100+
| Feature | Supported | Note |
101+
|---------|-----------|------|
102+
| Chunked Prefill | ✗ | Plan in 2025 Q1 |
103+
| Automatic Prefix Caching | ✅ | Imporve performance in 2025 Q1 |
104+
| LoRA | ✗ | Plan in 2025 Q1 |
105+
| Prompt adapter | ✅ ||
106+
| Speculative decoding | ✅ | Impore accuracy in 2025 Q1|
107+
| Pooling | ✗ | Plan in 2025 Q1 |
108+
| Enc-dec | ✗ | Plan in 2025 Q1 |
109+
| Multi Modality | ✅ (LLaVA/Qwen2-vl/Qwen2-audio/internVL)| Add more model support in 2025 Q1 |
110+
| LogProbs | ✅ ||
111+
| Prompt logProbs | ✅ ||
112+
| Async output | ✅ ||
113+
| Multi step scheduler | ✅ ||
114+
| Best of | ✅ ||
115+
| Beam search | ✅ ||
116+
| Guided Decoding | ✗ | Plan in 2025 Q1 |
117+
118+
## 模型支持矩阵
119+
120+
此处展示了部分受支持的模型。有关更多详细信息，请参阅 [supported_models](docs/supported_models.md)：
121+
| Model | Supported | Note |
122+
|---------|-----------|------|
123+
| Qwen 2.5 | ✅ ||
124+
| Mistral | | Need test |
125+
| DeepSeek v2.5 | |Need test |
126+
| LLama3.1/3.2 | ✅ ||
127+
| Gemma-2 | |Need test|
128+
| baichuan | |Need test|
129+
| minicpm | |Need test|
130+
| internlm | ✅ ||
131+
| ChatGLM | ✅ ||
132+
| InternVL 2.5 | ✅ ||
133+
| Qwen2-VL | ✅ ||
134+
| GLM-4v | |Need test|
135+
| Molomo | ✅ ||
136+
| LLaVA 1.5 | ✅ ||
137+
| Mllama | |Need test|
138+
| LLaVA-Next | |Need test|
139+
| LLaVA-Next-Video | |Need test|
140+
| Phi-3-Vison/Phi-3.5-Vison | |Need test|
141+
| Ultravox | |Need test|
142+
| Qwen2-Audio | ✅ ||
143+
144+
145+
## 贡献
146+
我们欢迎并重视任何形式的贡献与合作：
147+
- 请通过[提交问题](https://github.com/vllm-project/vllm-ascend/issues)来告知我们您遇到的任何错误。
148+
- 请参阅 [CONTRIBUTING.zh.md](./CONTRIBUTING.zh.md) 中的贡献指南。
149+
## 许可证
150+
151+
Apache 许可证 2.0，如 [LICENSE](./LICENSE) 文件中所示。

‎docs/environment.zh.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
### 昇腾NPU环境准备
2+
3+
### 依赖
4+
| 需求 | 支持的版本 | 推荐版本 | 注意 |
5+
|-------------|-------------------| ----------- |------------------------------------------|
6+
| vLLM | main | main | vllm-ascend 依赖 |
7+
| Python | >= 3.9 | [3.10](https://www.python.org/downloads/) | vllm 依赖 |
8+
| CANN | >= 8.0.RC2 | [8.0.RC3](https://www.hiascend.com/developer/download/community/result?module=cann&cann=8.0.0.beta1) | vllm-ascend and torch-npu 依赖 |
9+
| torch-npu | >= 2.4.0 | [2.5.1rc1](https://gitee.com/ascend/pytorch/releases/tag/v6.0.0.alpha001-pytorch2.5.1) | vllm-ascend 依赖 |
10+
| torch | >= 2.4.0 | [2.5.1](https://github.com/pytorch/pytorch/releases/tag/v2.5.1) | torch-npu and vllm 依赖 |
11+
12+
13+
以下为安装推荐版本软件的简短说明：
14+
15+
#### 容器化安装
16+
17+
您可以直接使用[容器镜像](https://hub.docker.com/r/ascendai/cann)，只需一行命令即可：
18+
19+
```bash
20+
docker run \
21+
--name vllm-ascend-env \
22+
--device /dev/davinci1 \
23+
--device /dev/davinci_manager \
24+
--device /dev/devmm_svm \
25+
--device /dev/hisi_hdc \
26+
-v /usr/local/dcmi:/usr/local/dcmi \
27+
-v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
28+
-v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
29+
-v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
30+
-v /etc/ascend_install.info:/etc/ascend_install.info \
31+
-it quay.io/ascend/cann:8.0.rc3.beta1-910b-ubuntu22.04-py3.10 bash
32+
```
33+
34+
您无需手动安装 `torch` 和 `torch_npu` ，它们将作为 `vllm-ascend` 依赖项自动安装。
35+
36+
#### 手动安装
37+
38+
您也可以选择手动安装，按照[昇腾安装指南](https://ascend.github.io/docs/sources/ascend/quick_install.html)中提供的说明配置环境。

0 commit comments

Comments
 (0)