diff --git a/.github/workflows/vllm_ascend_test.yaml b/.github/workflows/vllm_ascend_test.yaml index e2f8ca55..1e211221 100644 --- a/.github/workflows/vllm_ascend_test.yaml +++ b/.github/workflows/vllm_ascend_test.yaml @@ -25,6 +25,7 @@ on: - '*.txt' - '**/*.py' - '.github/workflows/vllm_ascend_test.yaml' + - '!docs/**' pull_request: branches: - "main" @@ -32,6 +33,7 @@ on: - '*.txt' - '**/*.py' - '.github/workflows/vllm_ascend_test.yaml' + - '!docs/**' # Bash shells do not use ~/.profile or ~/.bashrc so these shells need to be explicitly # declared as "shell: bash -el {0}" on steps that need to be properly activated. diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..00ed22e5 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,20 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-22.04 + tools: + python: "3.12" + +sphinx: + configuration: docs/source/conf.py + fail_on_warning: true +# If using Sphinx, optionally build your docs in additional formats such as PDF +formats: [] + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements-docs.txt diff --git a/README.md b/README.md index deef7028..5aa7a46e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@

- - vllm-ascend + + vllm-ascend

@@ -71,7 +71,7 @@ curl http://localhost:8000/v1/models **Please refer to [official docs](./docs/index.md) for more details.** ## Contributing -See [CONTRIBUTING](./CONTRIBUTING.md) for more details, which is a step-by-step guide to help you set up development environment, build and test. +See [CONTRIBUTING](docs/source/developer_guide/contributing.md) for more details, which is a step-by-step guide to help you set up development environment, build and test. We welcome and value any contributions and collaborations: - Please feel free comments [here](https://github.com/vllm-project/vllm-ascend/issues/19) about your usage of vLLM Ascend Plugin. diff --git a/README.zh.md b/README.zh.md index b162cbf5..4a15648d 100644 --- a/README.zh.md +++ b/README.zh.md @@ -1,7 +1,7 @@

- - vllm-ascend + + vllm-ascend

@@ -72,7 +72,7 @@ curl http://localhost:8000/v1/models **请参阅 [官方文档](./docs/index.md)以获取更多详细信息** ## 贡献 -有关更多详细信息，请参阅 [CONTRIBUTING](./CONTRIBUTING.md)，可以更详细的帮助您部署开发环境、构建和测试。 +有关更多详细信息，请参阅 [CONTRIBUTING](docs/source/developer_guide/contributing.zh.md)，可以更详细的帮助您部署开发环境、构建和测试。 我们欢迎并重视任何形式的贡献与合作： - 您可以在[这里](https://github.com/vllm-project/vllm-ascend/issues/19)反馈您的使用体验。 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..37b2bda7 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,21 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..9e7c4a6c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,21 @@ +# vLLM Ascend Plugin documents + +## Build the docs + +```bash +# Install dependencies. +pip install -r requirements-docs.txt + +# Build the docs. +make clean +make html +``` + +## Open the docs with your browser + +```bash +python -m http.server -d build/html/ +``` + +Launch your browser and open http://localhost:8000/. + diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 860501b3..00000000 --- a/docs/index.md +++ /dev/null @@ -1,15 +0,0 @@ -# Ascend plugin for vLLM -vLLM Ascend plugin (vllm-ascend) is a community maintained hardware plugin for running vLLM on the Ascend NPU. - -This plugin is the recommended approach for supporting the Ascend backend within the vLLM community. It adheres to the principles outlined in the [[RFC]: Hardware pluggable](https://github.com/vllm-project/vllm/issues/11162), providing a hardware-pluggable interface that decouples the integration of the Ascend NPU with vLLM. - -By using vLLM Ascend plugin, popular open-source models, including Transformer-like, Mixture-of-Expert, Embedding, Multi-modal LLMs can run seamlessly on the Ascend NPU. - -## Contents - -- [Quick Start](./quick_start.md) -- [Installation](./installation.md) -- Usage - - [Running vLLM with Ascend](./usage/running_vllm_with_ascend.md) - - [Feature Support](./usage/feature_support.md) - - [Supported Models](./usage/supported_models.md) diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 00000000..e837e992 --- /dev/null +++ b/docs/requirements-docs.txt @@ -0,0 +1,8 @@ +sphinx==6.2.1 +sphinx-argparse==0.4.0 +sphinx-book-theme==1.0.1 +sphinx-copybutton==0.5.2 +sphinx-design==0.6.1 +sphinx-togglebutton==0.3.2 +myst-parser==3.0.1 +msgspec diff --git a/docs/requirements-test.txt b/docs/requirements-test.txt new file mode 100644 index 00000000..b8c6fe99 --- /dev/null +++ b/docs/requirements-test.txt @@ -0,0 +1,2 @@ +pytest-asyncio + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..c90946f5 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,105 @@ +# +# Copyright (c) 2025 Huawei Technologies Co., Ltd. All Rights Reserved. +# This file is a part of the vllm-ascend project. +# Adapted from vllm-project/vllm/docs/source/conf.py +# Copyright 2023 The vLLM team. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +# -- Project information ----------------------------------------------------- + +project = 'vllm-ascend' +copyright = '2025, vllm-ascend team' +author = 'the vllm-ascend team' + +# The full version, including alpha/beta/rc tags +release = '' + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. + +# Copy from https://github.com/vllm-project/vllm/blob/main/docs/source/conf.py +extensions = [ + "sphinx.ext.napoleon", + "sphinx.ext.intersphinx", + "sphinx_copybutton", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "myst_parser", + "sphinxarg.ext", + "sphinx_design", + "sphinx_togglebutton", +] +myst_enable_extensions = [ + "colon_fence", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [ + '_build', + 'Thumbs.db', + '.DS_Store', + '.venv', + 'README.md', + # TODO(yikun): Remove this after zh supported + 'developer_guide/contributing.zh.md' +] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_title = project +html_theme = 'sphinx_book_theme' +html_logo = 'logos/vllm-ascend-logo-text-light.png' +html_theme_options = { + 'path_to_docs': 'docs/source', + 'repository_url': 'https://github.com/vllm-project/vllm-ascend', + 'use_repository_button': True, + 'use_edit_page_button': True, +} +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ['_static'] + + +def setup(app): + pass diff --git a/CONTRIBUTING.md b/docs/source/developer_guide/contributing.md similarity index 95% rename from CONTRIBUTING.md rename to docs/source/developer_guide/contributing.md index c7d45f68..fda7dabb 100644 --- a/CONTRIBUTING.md +++ b/docs/source/developer_guide/contributing.md @@ -1,4 +1,4 @@ -# Contributing to vLLM Ascend plugin +# Contributing ## Building and testing It's recommended to set up a local development environment to build and test @@ -45,7 +45,7 @@ git commit -sm "your commit info" ### Testing -Although vllm-ascend CI provide integration test on [Ascend](.github/workflows/vllm_ascend_test.yaml), you can run it +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 diff --git a/CONTRIBUTING.zh.md b/docs/source/developer_guide/contributing.zh.md similarity index 92% rename from CONTRIBUTING.zh.md rename to docs/source/developer_guide/contributing.zh.md index 259bc56e..144ff35b 100644 --- a/CONTRIBUTING.zh.md +++ b/docs/source/developer_guide/contributing.zh.md @@ -1,4 +1,4 @@ -# 为 vLLM 昇腾插件贡献 +# 贡献指南 ## 构建与测试 我们推荐您在提交PR之前在本地开发环境进行构建和测试。 @@ -41,7 +41,7 @@ git commit -sm "your commit info" ``` ### 测试 -虽然 vllm-ascend CI 提供了对 [Ascend](.github/workflows/vllm_ascend_test.yaml) 的集成测试，但您也可以在本地运行它。在本地运行这些集成测试的最简单方法是通过容器： +虽然 vllm-ascend CI 提供了对 [Ascend](https://github.com/vllm-project/vllm-ascend/blob/main/.github/workflows/vllm_ascend_test.yaml) 的集成测试，但您也可以在本地运行它。在本地运行这些集成测试的最简单方法是通过容器： ```bash # 基于昇腾NPU环境 diff --git a/docs/usage/supported_models.md b/docs/source/features/supported_models.md similarity index 100% rename from docs/usage/supported_models.md rename to docs/source/features/supported_models.md diff --git a/docs/usage/feature_support.md b/docs/source/features/suppoted_features.md similarity index 100% rename from docs/usage/feature_support.md rename to docs/source/features/suppoted_features.md diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 00000000..eca5ca35 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,53 @@ +# Welcome to vLLM Ascend Plugin + +:::{figure} ./logos/vllm-ascend-logo-text-light.png +:align: center +:alt: vLLM +:class: no-scaled-link +:width: 70% +::: + +:::{raw} html +

+vLLM Ascend Plugin + +

+ +

+ +Star +Watch +Fork +

+::: + +vLLM Ascend plugin (vllm-ascend) is a community maintained hardware plugin for running vLLM on the Ascend NPU. + +This plugin is the recommended approach for supporting the Ascend backend within the vLLM community. It adheres to the principles outlined in the [[RFC]: Hardware pluggable](https://github.com/vllm-project/vllm/issues/11162), providing a hardware-pluggable interface that decouples the integration of the Ascend NPU with vLLM. + +By using vLLM Ascend plugin, popular open-source models, including Transformer-like, Mixture-of-Expert, Embedding, Multi-modal LLMs can run seamlessly on the Ascend NPU. + +## Documentation + +% How to start using vLLM on Ascend NPU? +:::{toctree} +:caption: Getting Started +:maxdepth: 1 +quick_start +installation +::: + +% What does vLLM Ascend Plugin support? +:::{toctree} +:caption: Features +:maxdepth: 1 +features/suppoted_features +features/supported_models +::: + +% How to contribute to the vLLM project +:::{toctree} +:caption: Developer Guide +:maxdepth: 1 +developer_guide/contributing +::: \ No newline at end of file diff --git a/docs/installation.md b/docs/source/installation.md similarity index 90% rename from docs/installation.md rename to docs/source/installation.md index d2646d52..d5feb24c 100644 --- a/docs/installation.md +++ b/docs/source/installation.md @@ -1,6 +1,6 @@ # Installation -### 1. Dependencies +## Dependencies | Requirement | Supported version | Recommended version | Note | | ------------ | ------- | ----------- | ----------- | | Python | >= 3.9 | [3.10](https://www.python.org/downloads/) | Required for vllm | @@ -8,11 +8,11 @@ | torch-npu | >= 2.4.0 | [2.5.1rc1](https://gitee.com/ascend/pytorch/releases/tag/v6.0.0.alpha001-pytorch2.5.1) | Required for vllm-ascend | | torch | >= 2.4.0 | [2.5.1](https://github.com/pytorch/pytorch/releases/tag/v2.5.1) | Required for torch-npu and vllm required | -### 2. Prepare Ascend NPU environment +## Prepare Ascend NPU environment Below is a quick note to install recommended version software: -#### Containerized installation +### Containerized installation You can use the [container image](https://hub.docker.com/r/ascendai/cann) directly with one line command: @@ -33,13 +33,13 @@ docker run \ You do not need to install `torch` and `torch_npu` manually, they will be automatically installed as `vllm-ascend` dependencies. -#### Manual installation +### Manual installation Or follow the instructions provided in the [Ascend Installation Guide](https://ascend.github.io/docs/sources/ascend/quick_install.html) to set up the environment. -### 3. Building +## Building -#### Build Python package from source +### Build Python package from source ```bash git clone https://github.com/vllm-project/vllm-ascend.git @@ -47,7 +47,7 @@ cd vllm-ascend pip install -e . ``` -#### Build container image from source +### Build container image from source ```bash git clone https://github.com/vllm-project/vllm-ascend.git cd vllm-ascend diff --git a/docs/logos/vllm-ascend-logo-text-dark.png b/docs/source/logos/vllm-ascend-logo-text-dark.png similarity index 100% rename from docs/logos/vllm-ascend-logo-text-dark.png rename to docs/source/logos/vllm-ascend-logo-text-dark.png diff --git a/docs/logos/vllm-ascend-logo-text-light.png b/docs/source/logos/vllm-ascend-logo-text-light.png similarity index 100% rename from docs/logos/vllm-ascend-logo-text-light.png rename to docs/source/logos/vllm-ascend-logo-text-light.png diff --git a/docs/quick_start.md b/docs/source/quick_start.md similarity index 99% rename from docs/quick_start.md rename to docs/source/quick_start.md index a6ef72a3..1c3d907b 100644 --- a/docs/quick_start.md +++ b/docs/source/quick_start.md @@ -1,6 +1,6 @@ # Quickstart -## 1. Prerequisites +## Prerequisites ### Supported Devices - Atlas A2 Training series (Atlas 800T A2, Atlas 900 A2 PoD, Atlas 200T A2 Box16, Atlas 300T A2) @@ -48,7 +48,7 @@ You will see following message: ``` -## 2. Installation +## Installation Prepare: @@ -84,7 +84,7 @@ cd .. ``` -## 3. Usage +## Usage After vLLM and vLLM Ascend plugin installation, you can start to try [vLLM QuickStart](https://docs.vllm.ai/en/latest/getting_started/quickstart.html). diff --git a/docs/usage/running_vllm_with_ascend.md b/docs/usage/running_vllm_with_ascend.md deleted file mode 100644 index 03de8dd5..00000000 --- a/docs/usage/running_vllm_with_ascend.md +++ /dev/null @@ -1 +0,0 @@ -# Running vLLM with Ascend \ No newline at end of file diff --git a/pytest.ini b/pytest.ini index 368ec106..fae8ae6f 100644 --- a/pytest.ini +++ b/pytest.ini @@ -15,6 +15,7 @@ norecursedirs = vllm-empty/tests/compile vllm-empty/tests/lora vllm-empty/tests/models + vllm-empty/tests/mistral_tool_use vllm-empty/tests/multimodal vllm-empty/tests/standalone_tests vllm-empty/tests/async_engine diff --git a/requirements-dev.txt b/requirements-dev.txt index 5eed0341..834cd0a7 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,3 +1,5 @@ -r requirements-lint.txt modelscope pytest >= 6.0 +pytest-asyncio +