常见问题解答

常见问题解答#

版本特定常见问题解答#

通用常见问题解答#

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.12.0rc1
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.12.0rc1
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 支持 Prefill Disaggregation 功能，并使用 Mooncake 后端。以 官方教程 为例。

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

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

10. 如何运行 W8A8 DeepSeek 模型？#

遵循 推理教程，并将模型替换为 DeepSeek。

11. vllm-ascend 是如何进行测试的？#

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

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

  • 性能测试：我们提供了 基准测试 工具用于 E2E 性能基准测试，可以轻松地在本地重新配置。我们将发布一个性能网站来展示每次 PR 的性能测试结果。

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

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

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

12. 如何修复使用 vllm-ascend 时出现的“InvalidVersion”错误？#

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

13. 如何处理内存不足（out-of-memory）的问题？#

OOM 错误通常发生在模型超出单个 NPU 内存容量时。有关一般指导，您可以参考 vLLM OOM 故障排除文档。

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

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

  • 调整 --gpu-memory-utilization：如果未指定，则默认值为 0.9。您可以降低此值以保留更多内存，从而降低碎片化的风险。详情请参阅：vLLM - 推理和部署 - Engine Arguments。

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

14. 运行 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]

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

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

16. 如何在 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}")

  1. 设置以下环境变量。

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

17. 对于 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' 问题，并确保音频处理功能正常工作。

18. 如何对因流资源耗尽导致的尺寸捕获失败进行故障排除和解决，其根本原因是什么？#

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）。然而，许多不可量化的因素，如算子特性和特定硬件功能，会在此计算框架之外消耗额外的流资源，从而导致尺寸捕获操作期间流资源耗尽。

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

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

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

在某些操作系统（例如，麒麟 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> 是您使用的镜像标签）复制到您的目标机器。

21. 执行脚本启动 Docker 容器时收到错误消息“operation not permitted”的原因是什么？#

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

目录