常见问题¶

版本特定常见问题¶

通用常见问题¶

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）暂无计划

从技术角度看，如果 TorchNPU 支持某设备，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.23.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.23.0
docker load -i vllm-ascend-$TAG.tar.gz

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

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

更多详情见这里。

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

你可以通过许多渠道与我们的社区开发者/用户交流：

提交一个 GitHub 问题。
加入我们的每周会议并分享你的想法。
加入我们的 WeChat 群并提问。
加入 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 是否支持 Prefill-Decode（PD）分离功能？¶

是的，vllm-ascend 支持使用 Mooncake 后端的 Prefill-Decode 分离功能。示例见官方教程。

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

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

10. vllm-ascend 如何进行测试？¶

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

功能测试：我们添加了 CI，包括 vllm 原生单元测试的一部分以及 vllm-ascend 自身的单元测试。在 vllm-ascend 的测试中，我们通过 E2E 测试验证基本功能、热门模型可用性以及支持的功能。
性能测试：我们提供了用于端到端性能基准测试的基准测试工具，可以在本地轻松重新运行。我们将发布一个性能网站，用于展示每个拉取请求的性能测试结果。
精度测试：我们也在将精度测试添加到 CI 中。
夜间测试：我们每晚都会运行完整测试，以确保代码正常工作。

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

11. 使用 vllm-ascend 时如何修复 “InvalidVersion” 错误？¶

该问题通常由安装了 vLLM 包的开发版本或可编辑版本引起。在这种情况下，我们提供环境变量 VLLM_VERSION，让用户指定要使用的 vLLM 包版本。请将环境变量 VLLM_VERSION 设置为您已安装的 vLLM 包版本。VLLM_VERSION 的格式应为 X.Y.Z。

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

OOM 错误通常发生在模型超出单个 NPU 内存容量时。一般性指导可参考 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 时如何生成确定性结果？¶

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

采样器方法：通过在 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/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

某些多模态模型需要安装 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 会为选定的硬件配置应用捕获大小剪枝。如果捕获仍然失败，请升级匹配的 HDK/CANN 栈，或显式减少已配置的图大小。运行时指导有意保持狭窄：只有当捕获失败并出现上述已确认的流资源特征时，才会添加该指导。

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

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

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

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

在另一台主机（例如标准 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 时，你可能需要在 docker run 命令中添加 --privileged=true 标志，以授予容器必要的权限。请注意，使用 --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"

# 950PR&950DT Products
export SOC_VERSION="<value starting with ascend950>"

22. 为什么随着并发增长，TPOT 会急剧增加？¶

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

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 cache 容量。你可以根据此值调整整体请求流量。

由于 KV cache 使用量始终有限制，抢占无法完全避免。但有一些方法可以降低抢占发生的概率。正如 PREEMPTION 中建议的，核心策略是增加可用的 KV cache。例如，可以增加 --gpu-memory-utilization 或减少 --max-num-seqs && --max-num-batched-tokens。

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

当模型能够容纳在单个节点 NPU 的内存中时，建议使用单节点部署。对于 Qwen3-32B（BF16）等需要 4 × 64GB 卡片的模型，单个节点内的多 NPU（TP）就足够了。只有当 NPU 总数超过单个节点的容量时，才需要多节点部署。

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

BF16：精度最佳，内存占用最高。适用于对精度要求较高的应用，或内存充足的情况。
W8A8：在精度和内存缩减之间取得良好平衡。适用于内存受限硬件上的大模型（例如 32B）。
W4A8/W4A4：内存缩减最大。适用于在较小硬件配置上部署更大的模型，但会牺牲一定精度。

25. 用于注意力的 FIA 和 PA 算子有什么区别？¶

FIA（Flash Attention）是 vLLM-Ascend 中的默认注意力算子。在某些 batch-size 设置（尤其是中等并发）下，FIA 可能表现不佳。可以通过 --additional-config 中的 pa_shape_list 手动启用 PA（Page Attention）算子。当运行时 batch size 与 pa_shape_list 中的某个值匹配时，框架会切换到 PA。这是一个临时调优参数——未来的 FIA 优化将使该参数过时。

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