测试¶

本文档介绍如何编写单元测试、E2E 测试和 nightly 测试，以验证你的功能实现。

设置测试环境¶

设置测试环境的最快方式是使用 main 分支的容器镜像：

本地（CPU）单卡多卡

你可以按以下步骤在 CPU 上运行单元测试：

cd ~/vllm-project/
# ls
# vllm  vllm-ascend

# Use mirror to speed up download
# docker pull m.daocloud.io/quay.io/ascend/cann:9.1.0-910b-ubuntu22.04-py3.12
export IMAGE=quay.io/ascend/cann:9.1.0-910b-ubuntu22.04-py3.12
docker run --rm --name vllm-ascend-ut \
    -v $(pwd):/vllm-project \
    -v ~/.cache:/root/.cache \
    -ti $IMAGE bash

在容器内运行以下剩余命令：

# (Optional) Configure mirror to speed up download
sed -i 's|ports.ubuntu.com|mirrors.huaweicloud.com|g' /etc/apt/sources.list
pip config set global.index-url https://mirrors.huaweicloud.com/repository/pypi/simple/

# For TorchNPU dev version or x86 machine
export PIP_EXTRA_INDEX_URL="https://download.pytorch.org/whl/cpu/ https://mirrors.huaweicloud.com/ascend/repos/pypi"

# src path
export SRC_WORKSPACE=/vllm-workspace
mkdir -p $SRC_WORKSPACE
cd $SRC_WORKSPACE

apt-get update -y
apt-get install -y python3-pip git vim wget net-tools gcc g++ cmake libnuma-dev curl gnupg2

git clone -b v0.23.0 --depth 1 https://github.com/vllm-project/vllm-ascend.git
git clone -b v0.23.0 --depth 1 https://github.com/vllm-project/vllm.git

# vllm
cd $SRC_WORKSPACE/vllm
VLLM_TARGET_DEVICE=empty python3 -m pip install .
python3 -m pip uninstall -y triton

# vllm-ascend
cd $SRC_WORKSPACE/vllm-ascend
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/Ascend/ascend-toolkit/latest/$(uname -m)-linux/devlib
# For cpu environment, set SOC_VERSION for different chips.
# See https://github.com/vllm-project/vllm-ascend/blob/3cb0af0bcf3299089ca7e72159fa36e825a470f8/setup.py#L132 for detail.
export SOC_VERSION="ascend910b1"
python3 -m pip install .
python3 -m pip install -r requirements-dev.txt

# Update DEVICE according to your device (/dev/davinci[0-7])
export DEVICE=/dev/davinci0
# A2 Ubuntu image; use nightly-main-a3 for A3 and add -openeuler for openEuler.
export IMAGE=quay.io/ascend/vllm-ascend:nightly-main
docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --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/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /root/.cache:/root/.cache \
    -p 8000:8000 \
    -it $IMAGE bash

启动容器后，你应该安装所需的软件包：

# Prepare
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

# Switch to the /vllm-workspace/vllm-ascend directory
cd /vllm-workspace/vllm-ascend/

# Install required packages
pip install -r requirements-dev.txt

# A2 Ubuntu image; use nightly-main-a3 for A3 and add -openeuler for openEuler.
export IMAGE=quay.io/ascend/vllm-ascend:nightly-main
docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --device /dev/davinci0 \
    --device /dev/davinci1 \
    --device /dev/davinci2 \
    --device /dev/davinci3 \
    --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/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v /root/.cache:/root/.cache \
    -p 8000:8000 \
    -it $IMAGE bash

启动容器后，你应该安装所需的软件包：

cd /vllm-workspace/vllm-ascend/

# Prepare
pip config set global.index-url https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

# Install required packages
pip install -r requirements-dev.txt

运行测试¶

单元测试¶

编写单元测试时，需要遵循以下几项原则：

测试文件路径应与源文件保持一致，并以 test_ 前缀开头，例如：vllm_ascend/worker/worker.py --> tests/ut/worker/test_worker.py
vLLM Ascend 测试使用 unittest 框架。请参阅 Python unittest 文档了解如何编写单元测试。
所有单元测试都可以在 CPU 上运行，因此必须在主机上模拟设备相关函数。
示例：tests/ut/test_ascend_config.py。
你可以使用 pytest 运行单元测试：

本地（CPU）单卡多卡

# Run unit tests
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/Ascend/ascend-toolkit/latest/$(uname -m)-linux/devlib
TORCH_DEVICE_BACKEND_AUTOLOAD=0 pytest -sv tests/ut

cd /vllm-workspace/vllm-ascend/
# Run all single-card tests
pytest -sv tests/ut

# Run single test
pytest -sv tests/ut/test_ascend_config.py

cd /vllm-workspace/vllm-ascend/
# Run all multi-card tests
pytest -sv tests/ut

# Run single test
pytest -sv tests/ut/test_ascend_config.py

E2E 测试¶

尽管 vllm-ascend CI 在 Ascend CI 上提供了 E2E 测试（例如， schedule_nightly_test_a2.yaml, schedule_nightly_test_a3.yaml, pr_test.yaml)，你也可以在本地运行它们。

PR 触发的 E2E 测试¶

你也可以使用 pytest 运行测试。典型示例：

本地（CPU）单卡多卡

你无法在 CPU 上运行 E2E 测试。

cd /vllm-workspace/vllm-ascend/
# Run all single-card tests
VLLM_USE_MODELSCOPE=true pytest -sv tests/e2e/pull_request/one_card/

# Run a certain test script
VLLM_USE_MODELSCOPE=true pytest -sv tests/e2e/pull_request/one_card/test_qwen3_0_6b.py

# Run a certain case in test script
VLLM_USE_MODELSCOPE=true pytest -sv tests/e2e/pull_request/one_card/test_qwen3_0_6b.py::test_dense_default_full_and_piecewise_graph

cd /vllm-workspace/vllm-ascend/
# Run all multi-card tests
VLLM_USE_MODELSCOPE=true pytest -sv tests/e2e/pull_request/two_card/

# Run a certain test script
VLLM_USE_MODELSCOPE=true pytest -sv tests/e2e/pull_request/two_card/test_qwen3_moe_eplb.py

# Run a certain case in test script
VLLM_USE_MODELSCOPE=true pytest -sv tests/e2e/pull_request/two_card/test_qwen3_moe_eplb.py::test_qwen3_moe_w8a8_distributed_tp2_ep_dynamic_eplb

这将复现 E2E 测试行为。

夜间触发的 E2E 测试¶

你也可以使用 pytest 运行测试。典型示例：

本地（CPU）单卡多卡

你无法在 CPU 上运行 E2E 测试。

cd /vllm-workspace/vllm-ascend/
# run all single-card op tests
VLLM_USE_MODELSCOPE=true pytest -sv tests/e2e/nightly/single_node/ops/singlecard_ops/

cd /vllm-workspace/vllm-ascend/
# run all multi-card op tests on A3
VLLM_USE_MODELSCOPE=true pytest -sv tests/e2e/nightly/single_node/ops/multicard_ops_a3/

要在本地运行夜间单节点模型测试用例，请参考以下示例。

export CONFIG_YAML_PATH=Qwen3-32B.yaml
VLLM_USE_MODELSCOPE=true pytest -sv tests/e2e/nightly/single_node/models/scripts/test_single_node.py

要在本地运行夜间多节点模型测试用例，请参考多节点测试中的 Running Locally 部分。

E2E 测试示例¶

离线测试示例：tests/e2e/pull_request/one_card/test_qwen3_0_6b.py

PR 选择性测试（CI）¶

PR CI 工作流（pr_test.yaml）不会在每个 PR 上运行完整测试套件。它使用基于覆盖率/AST 的精确测试流水线选择测试，并将其路由到 NPU 运行器。当 PR 带有 ready-precise 标签（推荐子集）、ready-all 标签（完整套件）或 main2main 标签（针对已验证的 vLLM main 提交和匹配的 vLLM 发布标签执行完整套件）时，会运行测试。

测试是如何选择的：

test_selector.py 根据历史 CI 覆盖率数据，构建测试用例与其覆盖的源代码行之间的映射，然后推荐受 PR 更改行影响的测试（行 → 函数 → 文件粒度回退）。
select_tests.py 根据目录约定将每个推荐的测试路径路由到运行器（tests/ut/<module>/ → CPU，tests/ut/<module>/a2/ → A2，tests/e2e/pull_request/{one,two,four,eight}_card/ → A3，_310p → 310P），通过预估时间平衡负载，并生成 CI 矩阵。

添加新测试无需更改配置：将 UT 文件放置在匹配的 tests/ut/<module>[/<npu>] 目录下，或将 E2E 文件放置在匹配的 tests/e2e/pull_request/<card> 目录下，CI 会自动从测试树中拾取它。路由元数据（运行器映射、分区）位于 .github/workflows/scripts/test_config.yaml。用于负载均衡的预估时间位于 .github/workflows/scripts/estimated_times.yaml。

你可以在本地预览一组测试会被路由到哪些运行器：

python3 .github/workflows/scripts/select_tests.py \
  --explicit-e2e-tests tests/e2e/pull_request/one_card/test_qwen3_0_6b.py

# Full suite routing (mirrors the ready-all mode)
python3 .github/workflows/scripts/select_tests.py --all-tests

在请求标签之前，要在 CI 硬件上调试特定测试，请参阅 E2E CI 测试。

E2E 测试模型资源缩减¶

CI 资源有限，你可能需要减少模型的层数。以下是生成减少层数模型的示例：

在 modelscope 上 Fork 原始模型仓库。仓库中除权重之外的所有文件都是必需的。
将 num_hidden_layers 设置为预期的层数，例如 {"num_hidden_layers": 2,}

将以下 python 脚本复制为 generate_random_weight.py。根据需要设置相关参数 MODEL_LOCAL_PATH、DIST_DTYPE 和 DIST_MODEL_PATH：

import torch
from transformers import AutoTokenizer, AutoConfig
from modeling_deepseek import DeepseekV3ForCausalLM
from modelscope import snapshot_download

MODEL_LOCAL_PATH = "~/.cache/modelscope/models/vllm-ascend/DeepSeek-V3-Pruning"
DIST_DTYPE = torch.bfloat16
DIST_MODEL_PATH = "./random_deepseek_v3_with_2_hidden_layer"

config = AutoConfig.from_pretrained(MODEL_LOCAL_PATH, trust_remote_code=True)
model = DeepseekV3ForCausalLM(config)
model = model.to(DIST_DTYPE)
model.save_pretrained(DIST_MODEL_PATH)

CI 工作流触发器与 `schedule_` 前缀¶

位于 .github/workflows/ 下且文件名以 schedule_ 开头的工作流文件属于周期性 CI 系列（每日、每周、文档、覆盖率以及类似的定期任务）。schedule_ 前缀不保证工作流声明了 GitHub Actions 的 schedule:（cron）触发器。

一些 schedule_*.yaml 文件有意省略 schedule:，而是由项目的外部自动化通过 workflow_dispatch 触发。这是设计如此，并非缺少 cron 条目，因为外部调度器对资源密集型 NPU 任务的运行时间具有更强的控制能力。

具有原生 GitHub cron 触发器的工作流：

工作流	附加触发器
`schedule_doc_linkcheck.yaml`	PR 路径过滤、`workflow_dispatch`
`schedule_doc_translate.yaml`	`workflow_dispatch`
`schedule_e2e_upstream_test.yaml`	-
`schedule_lint_image_build.yaml`	`workflow_dispatch`、`push`
`schedule_main2main.yaml`	`workflow_dispatch`
`schedule_stale_manage.yaml`	`issue_comment`

没有 cron 触发器、通过 workflow_dispatch 由外部触发的工作流：

工作流	附加触发器
`schedule_doc_getting_started_test.yaml`	PR 路径过滤
`schedule_e2e_test.yaml`	-
`schedule_image_build_and_push.yaml`	PR 标签、标签 `push`
`schedule_nightly_test_310p.yaml`	-
`schedule_nightly_test_a2.yaml`	-
`schedule_nightly_test_a3.yaml`	-
`schedule_nightly_test_a3_560t.yaml`	-
`schedule_nightly_test_a5.yaml`	-
`schedule_release_code_and_wheel.yml`	标签 `push`
`schedule_test_coverage.yaml`	-
`schedule_weekly_test_310p.yaml`	-
`schedule_weekly_test_a2.yaml`	-
`schedule_weekly_test_a3.yaml`	-
`schedule_weekly_test_a3_560t.yaml`	-

运行 doctest¶

Doctest 会验证固定的、已标记的快速开始和安装代码块，而不是文档中的每个代码块。快速开始覆盖 A2 和 310P（Atlas 300I DUO），按顺序运行离线和在线示例。安装覆盖 A2 上的 pip、uv 和 source，随后进行离线推理验证。两者均支持 Ubuntu 和 openEuler。

在已准备好的 NPU 环境中，从仓库根目录运行以下命令之一：

./tests/e2e/doctests/scripts/run_doctests.sh quickstart a2
./tests/e2e/doctests/scripts/run_doctests.sh quickstart 310p

./tests/e2e/doctests/scripts/run_doctests.sh installation pip
./tests/e2e/doctests/scripts/run_doctests.sh installation uv
./tests/e2e/doctests/scripts/run_doctests.sh installation source

入口点不会创建容器。对于快速开始，请使用匹配的 vLLM Ascend 镜像；对于安装，请使用一次性 CANN 容器，该容器会更改系统和 Python 包。请提前准备示例的模型缓存；工作进程会启用 Hugging Face 离线模式。

在 CI 中，.github/workflows/schedule_doc_getting_started_test.yaml 显示为 Doc Test。针对 main 或 releases/v* 的相关 PR 更改会自动选择受影响的用例。外部自动化可以按计划触发它，或者你可以手动运行，并使用逗号分隔的 quickstart_devices 和/或 installation_methods；将某个输入留空即可跳过该测试类型。每个选中的用例都会在两种操作系统上运行。

有关代码块提取、计划预览和选择规则，请查看对应分支中 tests/e2e/doctests/scripts/doctest_helper.py 的使用说明和函数注释。

运行文档链接检查¶

你可以在本地使用以下命令验证 Sphinx 文档中的外部链接：

make -C docs linkcheck SPHINXOPTS="-W --keep-going"

若要检查特定 Markdown 文件中的链接，请将文件传递给 sphinx-build。例如，仅检查 docs/source/user_guide/release_notes.md：

cd docs
sphinx-build -b linkcheck -W --keep-going \
  source _build/linkcheck source/user_guide/release_notes.md

详细报告将写入：

docs/_build/linkcheck/output.txt
docs/_build/linkcheck/output.json

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 vl/vllm-ascend

测试¶

设置测试环境¶

运行测试¶

单元测试¶

E2E 测试¶

PR 触发的 E2E 测试¶

夜间触发的 E2E 测试¶

E2E 测试示例¶

PR 选择性测试（CI）¶

E2E 测试模型资源缩减¶

CI 工作流触发器与 schedule_ 前缀¶

运行 doctest¶

运行文档链接检查¶

CI 工作流触发器与 `schedule_` 前缀¶