常见问题解答

目录

常见问题解答#

版本特定常见问题#

通用常见问题#

1.目前支持哪些设备？#

目前，仅支持 Atlas A2 系列（Ascend-cann-kernels-910b）、Atlas A3 系列（Atlas-A3-cann-kernels）和 Atlas 300I（Ascend-cann-kernels-310p）系列：

  • Atlas A2 训练系列（Atlas 800T A2、Atlas 900 A2 PoD、Atlas 200T A2 Box16、Atlas 300T A2）

  • Atlas 800I A2 推理系列（Atlas 800I A2）

  • Atlas A3 训练系列（Atlas 800T A3、Atlas 900 A3 SuperPoD、Atlas 9000 A3 SuperPoD）

  • Atlas 800I A3 推理系列（Atlas 800I A3）

  • [实验性] Atlas 300I 推理系列（Atlas 300I Duo）。

  • [实验性] 目前对于 310I Duo，稳定版本是 vllm-ascend v0.10.0rc1。

以下系列目前尚不支持：

  • Atlas 200I A2（Ascend-cann-kernels-310b）尚未计划支持

  • Ascend 910、Ascend 910 Pro B（Ascend-cann-kernels-910）尚未计划支持

从技术角度看，如果 torch-npu 支持某设备，则 vllm-ascend 也支持该设备。否则，我们需要通过自定义算子来实现。我们也欢迎您加入我们，共同改进。

2.如何获取我们的 Docker 容器？#

您可以在 Quay.io 获取我们的容器，例如：vllm-ascend 和 cann。

如果您在中国，可以使用 daocloud 或其他镜像站点来加速下载：

# Replace with tag you want to pull
TAG=v0.9.1
docker pull m.daocloud.io/quay.io/ascend/vllm-ascend:$TAG
# or
docker pull quay.nju.edu.cn/ascend/vllm-ascend:$TAG

为离线环境加载 Docker 镜像#

如果您想在离线环境（无互联网连接）中使用容器镜像，您需要在有互联网访问权限的环境中下载容器镜像：

导出 Docker 镜像：

# Pull the image on a machine with internet access
TAG=v0.18.0
docker pull quay.io/ascend/vllm-ascend:$TAG

# Export the image to a tar file and compress to tar.gz
docker save quay.io/ascend/vllm-ascend:$TAG | gzip > vllm-ascend-$TAG.tar.gz

在无互联网访问权限的环境中导入 Docker 镜像：

# Transfer the tar/tar.gz file to the offline environment and load it
TAG=v0.18.0
docker load -i vllm-ascend-$TAG.tar.gz

# Verify the image is loaded
docker images | grep vllm-ascend

3.vllm-ascend 支持哪些模型？#

更多详细信息请参见此处。

4.如何与我们的社区取得联系？#

您可以通过多种渠道与我们的社区开发者/用户进行交流：

  • 提交一个 GitHub issue。

  • 参加我们的每周例会并分享您的想法。

  • 加入我们的微信群并提出您的问题。

  • 加入我们在 vLLM 论坛 的 ascend 频道并发布您的主题。

5.vllm-ascend V1 支持哪些功能？#

更多详细信息请参见此处。

6.如何解决“无法推断设备类型”或“libatb.so：无法打开共享对象文件”的问题？#

基本上，原因是 NPU 环境未正确配置。您可以：

  1. 尝试运行 source /usr/local/Ascend/nnal/atb/set_env.sh 以启用 NNAL 包。

  2. 尝试运行 source /usr/local/Ascend/ascend-toolkit/set_env.sh 以启用 CANN 包。

  3. 尝试运行 npu-smi info 来检查 NPU 是否正常工作。

如果上述步骤无效，您可以在 Python 中尝试以下代码来检查是否有任何错误：

import torch
import torch_npu
import vllm

如果以上所有步骤都无法解决问题，请随时提交一个 GitHub issue。

7.vllm-ascend 如何与 vLLM 协同工作？#

vllm-ascend 是 vLLM 的一个硬件插件。vllm-ascend 的版本与 vllm 的版本相同。例如，如果您使用 vllm 0.9.1，您也应该使用 vllm-ascend 0.9.1。对于主分支，我们确保 vllm-ascend 和 vllm 在每次提交时都是兼容的。

8.vllm-ascend 是否支持 Prefill Disaggregation 功能？#

是的，vllm-ascend 支持通过 Mooncake 后端实现 Prefill Disaggregation 功能。示例请参见官方教程。

9.vllm-ascend 是否支持量化方法？#

目前，vllm-ascend 已支持 w8a8、w4a8 和 w4a4 量化方法。

10.vllm-ascend 是如何测试的？#

vllm-ascend 在三个方面进行测试：功能、性能和精度。

  • 功能测试：我们添加了 CI，包括部分 vllm 的原生单元测试和 vllm-ascend 自身的单元测试。在 vllm-ascend 的测试中，我们通过端到端测试来验证基本功能、主流模型的可用性以及支持的功能。

  • 性能测试：我们提供了用于端到端性能基准测试的基准测试工具，可以方便地在本地重新运行。我们将发布一个性能网站，展示每个拉取请求的性能测试结果。

  • 准确性测试：我们正在努力将准确性测试也添加到 CI 中。

  • 夜间测试：我们将每晚运行完整测试，以确保代码正常工作。

对于每个版本，我们未来都将发布性能测试和准确性测试报告。

11.使用 vllm-ascend 时如何修复 "InvalidVersion" 错误？#

此问题通常是由于安装了开发版或可编辑版本的 vLLM 包引起的。为此，我们提供了环境变量 VLLM_VERSION，允许用户指定要使用的 vLLM 包版本。请将环境变量 VLLM_VERSION 设置为你已安装的 vLLM 包的版本。VLLM_VERSION 的格式应为 X.Y.Z。

12.如何处理内存不足问题？#

当模型超出单个 NPU 的内存容量时，通常会发生 OOM（内存不足）错误。一般性指导可参考 vLLM OOM 故障排除文档。

在 NPU 的高带宽内存（片上内存）容量有限的场景下，推理过程中的动态内存分配/释放会加剧内存碎片，导致 OOM。为解决此问题：

  • 限制 --max-model-len：它可以节省 KV 缓存初始化步骤的片上内存使用量。

  • 调整 --gpu-memory-utilization：如果未指定，默认值为 0.9。你可以降低此值以预留更多内存，从而减少碎片风险。详情参见：vLLM - 推理与服务 - 引擎参数。

  • 配置 PYTORCH_NPU_ALLOC_CONF：设置此环境变量以优化 NPU 内存管理。例如，你可以使用 export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True 来启用虚拟内存功能，以缓解运行时频繁动态调整内存大小导致的内存碎片问题。详情参见：PYTORCH_NPU_ALLOC_CONF。

13.运行 DeepSeek 时无法启用 NPU 图模式#

为 DeepSeek 启用 NPU 图模式可能会触发错误。这是因为当 MLA（多头潜在注意力）和 NPU 图模式同时激活时，每个 KV 头的查询数必须为 32、64 或 128。然而，DeepSeek-V2-Lite 只有 16 个注意力头，导致每个 KV 有 16 个查询，该值超出了支持范围。对 DeepSeek-V2-Lite 的 NPU 图模式支持将在未来的更新中添加。

如果你正在使用 DeepSeek-V3 或 DeepSeek-R1，请确保在张量并行切分后，num_heads/num_kv_heads 的值为 {32, 64, 128} 中的一个。

[rank0]: RuntimeError: EZ9999: Inner Error!
[rank0]: EZ9999: [PID: 62938] 2025-05-27-06:52:12.455.807 numHeads / numKvHeads = 8, MLA only support {32, 64, 128}.[FUNC:CheckMlaAttrs][FILE:incre_flash_attention_tiling_check.cc][LINE:1218]

14.卸载 vllm-ascend 后无法从源码重新安装 vllm-ascend#

使用 pip 从源码重新安装 vllm-ascend 时，可能会遇到 C/C++ 编译失败的问题。如果安装失败，请使用 python setup.py install（推荐）进行安装，或使用 python setup.py clean 清除缓存。

15.使用 vllm-ascend 时如何生成确定性结果？#

有几个因素会影响输出的确定性：

  1. 采样方法：通过在 SamplingParams 中设置 temperature=0 来使用 贪婪采样，例如：

    from vllm import LLM, SamplingParams

prompts = [
   "Hello, my name is",
   "The president of the United States is",
   "The capital of France is",
   "The future of AI is",
]

# Create a sampling params object.
sampling_params = SamplingParams(temperature=0)
# Create an LLM.
llm = LLM(model="Qwen/Qwen2.5-0.5B-Instruct")

# Generate texts from the prompts.
outputs = llm.generate(prompts, sampling_params)
for output in outputs:
   prompt = output.prompt
   generated_text = output.outputs[0].text
   print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

  2. 设置以下环境参数：

    export LCCL_DETERMINISTIC=1
export HCCL_DETERMINISTIC=true
export ATB_MATMUL_SHUFFLE_K_ENABLE=0
export ATB_LLM_LCOC_ENABLE=0

16.对于 Qwen2.5-Omni 模型，如何修复 "ImportError: Please install vllm[audio] for audio support" 错误？#

Qwen2.5-Omni 模型需要安装 librosa 包，你需要安装 qwen-omni-utils 包以确保满足所有依赖，运行 pip install qwen-omni-utils。此包将安装 librosa 及其相关依赖，解决 ImportError: No module named 'librosa' 问题，并确保音频处理功能正常工作。

17.如何排查和解决因流资源耗尽导致的尺寸捕获失败，其根本原因是什么？#

error example in detail: 
ERROR 09-26 10:48:07 [model_runner_v1.py:3029] ACLgraph sizes capture fail: RuntimeError:
ERROR 09-26 10:48:07 [model_runner_v1.py:3029] ACLgraph has insufficient available streams to capture the configured number of sizes.Please verify both the availability of adequate streams and the appropriateness of the configured size count.

推荐的缓解策略：

  1. 手动配置 compilation_config 参数，使用缩减后的尺寸集合：'{"cudagraph_capture_sizes":[size1, size2, size3, ...]}'。

  2. 采用 ACLgraph 的全图模式作为分段方法的替代方案。

根本原因分析：当前尺寸捕获的流需求计算仅考虑了可测量的因素，包括：数据并行大小、张量并行大小、专家并行配置、分段图数量、多流重叠共享专家设置以及 HCCL 通信模式（AIV/AICPU）。然而，许多不可量化的元素，例如算子特性和特定硬件特性，在此计算框架之外消耗了额外的流，导致尺寸捕获操作期间流资源耗尽。

18.如何安装自定义版本的 torch_npu？#

安装 vllm-ascend 时会覆盖 torch-npu。如果你需要安装特定版本的 torch-npu，可以在 vllm-ascend 安装后手动安装指定版本的 torch-npu。

19.在某些系统上（例如 Kylin OS），docker pull 可能因 invalid tar header 错误而失败#

在某些操作系统上，例如 Kylin OS，你可能会在 docker pull 过程中遇到 invalid tar header 错误：

failed to register layer: ApplyLayer exit status 1 stdout: stderr: archive/tar: invalid tar header

这通常是由于系统兼容性问题。你可以使用第二台机器通过离线加载方法来解决此问题。

  1. 在一台独立的主机上（例如，标准的 Ubuntu 服务器），拉取目标 ARM64 架构的镜像并将其打包成 .tar 文件。

    export IMAGE_TAG=v0.10.0rc1-310p
export IMAGE_NAME="quay.io/ascend/vllm-ascend:${IMAGE_TAG}"
# If in China region, uncomment to use a mirror:
# export IMAGE_NAME="m.daocloud.io/quay.io/ascend/vllm-ascend:${IMAGE_TAG}"

# Pull the image for the ARM64 platform and save it
docker pull --platform linux/arm64 "${IMAGE_NAME}"
docker save -o "vllm_ascend_${IMAGE_TAG}.tar" "${IMAGE_NAME}"

  2. 传输镜像归档文件

将 vllm_ascend_<tag>.tar 文件（其中 <tag> 是你使用的镜像标签）复制到你的目标机器

20.为什么执行启动 Docker 容器的脚本时会出错？错误信息是："operation not permitted"#

使用 --shm-size 时，你可能需要在 docker run 命令中添加 --privileged=true 标志，以授予容器必要的权限。请注意，使用 --privileged=true 会授予容器在主机系统上的广泛权限，这可能带来安全风险。只有在理解其影响并信任容器来源的情况下才使用此选项。

21.如何在小批量场景下实现低延迟？#

torch_npu.npu_fused_infer_attention_score 在小批量场景下的性能不理想，主要是由于缺乏 Flash Decoding 功能。我们在 tools/install_flash_infer_attention_score_ops_a2.sh 和 tools/install_flash_infer_attention_score_ops_a3.sh 中提供了一个替代算子，你可以使用以下指令安装它：

bash tools/install_flash_infer_attention_score_ops_a2.sh
# change to run the following instruction if you're using A3 machine
# bash tools/install_flash_infer_attention_score_ops_a3.sh

注意：使用此方法时不要设置 additional_config.pa_shape_list；否则会导致使用另一个注意力算子。重要：请确保你使用的是 vllm-ascend 的官方镜像；否则，你必须将 tools/install_flash_infer_attention_score_ops_a2.sh 或 tools/install_flash_infer_attention_score_ops_a3.sh 中的目录 /vllm-workspace 更改为你自己的目录，或者创建一个。如果你不是 root 用户，则需要 sudo 权限来运行此脚本。

22.在仅含 CPU 的机器上从源码构建时，如何设置 SOC_VERSION？#

从源码构建时（例如 pip install -e .），构建过程可能会尝试通过 npu-smi 推断目标芯片。如果 npu-smi 不可用（在仅含 CPU 的构建环境中很常见），则必须在安装前手动设置 SOC_VERSION。

你可以参考 Dockerfile* 中的默认值。例如：

# Atlas A2
export SOC_VERSION="ascend910b1"

# Atlas A3
export SOC_VERSION="ascend910_9391"

# Atlas 300I
export SOC_VERSION="ascend310p1"

# Atlas A5 (Ascend 950 series)
export SOC_VERSION="<value starting with ascend950>"

23.triton-ascend 偶尔遇到编译错误#

如 #7782 所示，triton-ascend 偶尔会遇到编译错误，这是 triton-ascend 3.2.0 中的一个已知问题。为避免此问题，请使用官方 docker 镜像或按以下方式安装特定的 triton-ascend 版本：

PYTHON_TAG=$(python3 -c "import sys; print(f'cp{sys.version_info.major}{sys.version_info.minor}')") && \
ARCH=$(python3 -c "import platform; machine = platform.machine().lower(); arch_map = {'x86_64': 'x86_64', 'amd64': 'x86_64', 'aarch64': 'aarch64', 'arm64': 'aarch64'}; print(arch_map.get(machine, machine))") && \
TRITON_ASCEND_WHEEL="triton_ascend-3.2.0.dev20260322-${PYTHON_TAG}-${PYTHON_TAG}-manylinux_2_27_${ARCH}.manylinux_2_28_${ARCH}.whl" && \
python3 -m pip install "https://vllm-ascend.obs.cn-north-4.myhuaweicloud.com/vllm-ascend/${TRITON_ASCEND_WHEEL}"

24.为什么 TPOT 随着并发增长而急剧增加？#

在测试 vLLM 服务器时，可能会发现 TPOT 随着并发度的增加而增加（例如，并发度增加 4 时，TPOT 增加 0.5 ~ 1ms）。在大多数情况下，这种现象是正常的。然而，有时随着并发度的增长，TPOT 可能会急剧增加（例如增加 10 到 100ms）。这可能是由 vLLM 中的 抢占 引起的。通常，当服务器达到 KV 缓存限制时，vLLM 会尝试释放请求的 KV 缓存，以确保为其他请求提供足够的空间，这在 vLLM 中称为抢占。当一个请求被抢占时，默认行为是在未来重新计算该请求的 KV 缓存，这就是性能可能显著下降的原因。有几种方法可以验证这一点：

  • vLLM 通常会在服务器上记录统计信息。您可能会看到类似 GPU KV cache usage: 99.0%, 的指标。当达到 100% 时，会触发抢占。

  • 启动 vLLM 服务器时，您会看到类似 GPU KV cache size: 66340 tokens 和 Maximum concurrency for 16,384 tokens per request: 4.05 的日志。这些是针对单个 DP 组的估计 KV 缓存容量。您可以据此调整总体请求流量。

抢占无法完全避免，因为 KV 缓存的使用总是有限制的。但有方法可以减少抢占的发生几率。正如 抢占 中所建议的，核心策略是增加可用的 KV 缓存。例如，可以增加 --gpu-memory-utilization 或减少 --max-num-seqs 和 --max-num-batched-tokens。

目录