常见问题解答¶

版本特定常见问题¶

通用常见问题¶

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.22.1rc1
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.22.1rc1
docker load -i vllm-ascend-$TAG.tar.gz

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

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

请在此处查看更多详细信息。

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

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

提交 GitHub 问题。
加入我们的周会并分享您的想法。
加入我们的微信群组并提出您的问题。
加入 vLLM 论坛中的 ascend 频道并发布您的话题。

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

请在此处查看更多详细信息。

6. 如何解决“Failed to infer device type”或“libatb.so: cannot open shared object file”的问题？¶

根本原因是 NPU 环境配置不正确。您可以：

尝试执行 source /usr/local/Ascend/nnal/atb/set_env.sh 以启用 NNAL 包。
尝试执行 source /usr/local/Ascend/ascend-toolkit/set_env.sh 以启用 CANN 包。
尝试执行 npu-smi info 检查 NPU 是否正常工作。

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

import torch
import torch_npu
import vllm

如果上述步骤仍无法解决问题，请随时提交 GitHub issue。

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

vllm-ascend 是 vLLM 的硬件插件。稳定版本通常与相同的 vLLM 版本对齐，而 RC 版本可能使用对应的 vLLM 最终发布版本。例如，vllm-ascend v0.18.0rc1 对应 vLLM v0.18.0。对于主分支，我们确保 vllm-ascend 和 vllm 在每次提交时都是兼容的。

8. vllm-ascend 是否支持预填充-解码（PD）分离功能？¶

是的，vllm-ascend 通过 Mooncake 后端支持预填充-解码解耦功能。详情请参考官方教程。

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。

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

OOM 错误通常在模型超出单个 NPU 的内存容量时发生。一般性指导请参考 [vLLM OOM 故障排除文档X.Y.Z。

在 NPU 的高带宽内存（片上内存）容量有限的场景下，推理期间的动态内存分配/释放可能会加剧内存碎片，从而导致 OOM。解决方法如下：

限制 ](https://docs.vllm.ai/en/latest/usage/troubleshooting/#out-of-memory)：这可以节省 KV 缓存初始化步骤的片上内存使用量。
调整 --max-model-len：如果未指定，默认值为 --gpu-memory-utilization。您可以减小此值以预留更多内存，从而降低碎片化风险。详情请参阅：[vLLM - 推理与服务 - 引擎参数0.9。
配置 ](https://docs.vllm.ai/en/latest/cli/serve/#-gpu-memory-utilization)：设置此环境变量以优化 NPU 内存管理。例如，您可以使用 PYTORCH_NPU_ALLOC_CONF 启用虚拟内存功能，以缓解运行时频繁动态调整内存大小导致的内存碎片问题。详情请参阅 [PYTORCH_NPU_ALLOC_CONFexport PYTORCH_NPU_ALLOC_CONF=expandable_segments:True。

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，请确保在张量并行切分后，](https://www.hiascend.com/document/detail/zh/Pytorch/700/comref/Envvariables/Envir_012.html)/num_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 后从源码重新安装失败¶

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

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

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

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

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/Qwen3-0.6B")

# 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}")

设置以下环境参数：

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

16. 如何修复多模态模型的错误“ImportError: Please install vllm[audio] for audio support”？¶

某些多模态模型需要安装 librosa 包，您需要安装 qwen-omni-utils 包以确保满足所有依赖关系，对于 Qwen-omni，请运行 pip install qwen-omni-utils。该包将安装 librosa 及其相关依赖，解决 ImportError: No module named 'librosa' 问题，并确保音频处理功能正常工作。

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

capture_begin:../torch_npu/csrc/core/npu/NPUGraph.cpp:230 NPU function error: c10_npu::acl::AclmdlRICaptureBegin(capture_stream_, capture_mode), error code is 207008
[Error]: Stream resources are insufficient.
[PID: ...] Insufficient_Stream_Resources(EL0009): The stream resources are insufficient.

当 vLLM Ascend 在错误文本中识别出这种捕获时的流资源特征时，它会重新抛出错误，并提供针对 ACL 图尺寸和缓解措施的具体指导。

建议的缓解策略：

如果您的环境中有可用的新版 HDK/CANN 栈，请升级到该版本。最新版本改进了 ACL 图的容量，因此旧的解决方法可能不再需要。
手动减小配置的图大小，例如：'{"cudagraph_capture_sizes":[size1, size2, size3, ...]}'，或降低 max_cudagraph_capture_size。
如果您的负载主要是均匀的解码，请尝试使用 ACLGraph 的 FULL 或 FULL_DECODE_ONLY 模式，而不是 PIECEWISE。
如果您使用 PIECEWISE 或 FULL_AND_PIECEWISE，并且在升级后仍然遇到此失败，请根据您的实际工作负载手动设置 cudagraph_capture_sizes 并减少配置的覆盖范围。
如果您正在调试启动失败，请临时禁用图模式（cudagraph_mode="NONE" / enforce_eager=True）以确认问题是否与捕获相关。

根本原因分析：当所选图大小所需的运行时资源超出当前软件/硬件栈所能提供的范围时，ACL 图捕获仍然可能失败。这在 PIECEWISE 场景中最为明显，因为捕获的图数量随模型深度和捕获大小覆盖范围而扩展。vLLM Ascend 不再在本地自动缩小 PIECEWISE 捕获大小集，因此实际的缓解措施是升级 HDK/CANN 栈或显式减小配置的图大小。运行时指导是特意窄化的：仅在捕获失败并出现上述确认的流资源签名时才会添加。

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

安装 vllm-ascend 时会覆盖 torch-npu。如果您需要安装特定版本的 torch-npu，请在安装完 vllm-ascend 之后再手动安装指定版本的 torch-npu。

19. 在某些系统（例如麒麟操作系统）上，`docker pull` 可能会因 `invalid tar header` 错误而失败¶

在某些操作系统（如麒麟 OS）上，您可能会在 invalid tar header 过程中遇到 docker pull 错误：

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

这通常是由于系统兼容性问题导致的。您可以通过另一台机器使用离线加载的方法来解决。

在另一台主机（例如标准的 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}"

传输镜像归档文件

将 vllm_ascend_<tag>.tar 文件（其中 <tag> 是您使用的镜像标签）拷贝到目标机器。

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

当使用 --shm-size 时，您可能需要在 --privileged=true 命令中添加 docker run 标志以授予容器必要权限。请注意，使用 --privileged=true 会授予容器在宿主机系统上的极高权限，这可能存在安全风险。请仅在您了解后果并信任镜像来源的情况下使用此选项。

21. 在仅有 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"

# Ascend 950 Products
export SOC_VERSION="<value starting with ascend950>"

22. 为什么 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。

23. 如何在单节点和多节点部署之间进行选择？¶

当模型适配在单个节点的 NPU 内存中时，建议使用单节点部署。对于像 Qwen3-32B (BF16) 这样需要 4 × 64G 卡的模型，单个节点内的多 NPU (TP) 就足够了。只有当总 NPU 数量超过单个节点容量时，才需要多节点部署。

24. 我应该使用哪种量化方法？¶

BF16: 最佳精度，最高内存占用。用于精度关键型应用或内存充足时。
W8A8: 精度和内存减少的良好平衡。用于内存受限硬件上的大型模型（例如 32B）。
W4A8/W4A4: 最大程度减少内存。适用于在较小硬件配置上部署更大模型，但会牺牲一些精度。

25. 何时应该启用 FlashComm_v1？¶

在使用张量并行 (TP ≥ 2) 且高并发时启用 FlashComm_v1 (VLLM_ASCEND_ENABLE_FLASHCOMM1=1)。它具有阈值保护，在可能降低性能的低并发场景下不会激活。