常见问题

常见问题#

特定版本常见问题#

[v0.13.0] FAQ & Feedback

通用常见问题#

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

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

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

Find more details here.

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

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

提交 GitHub issue。
参加我们的周会并分享您的想法。
加入我们的微信群并进行提问。
加入 vLLM 论坛中的 Ascend 频道并发布话题。

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

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

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

根本原因是 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-ascend 的版本与 vLLM 版本保持一致。例如，如果您使用 vLLM 0.9.1，则也应使用 vllm-ascend 0.9.1。对于主分支，我们会确保 vllm-ascend 和 vllm 的每次提交都是兼容的。

8.vllm-ascend 支持预填充解耦 (Prefill Disaggregation) 功能吗？#

Yes, vllm-ascend supports Prefill Disaggregation feature with Mooncake backend. Take official tutorial for example.

9. How is vllm-ascend tested?#

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

功能测试：我们添加了 CI，包括部分 vLLM 原生单元测试和 vllm-ascend 自有的单元测试。在 vllm-ascend 的测试中，我们通过端到端 (E2E) 测试来验证基本功能、主流模型可用性以及支持的功能。
性能测试：我们提供了基准测试工具用于端到端性能基准测试，可以方便地在本地重现。我们将发布一个性能展示网站，显示每个 PR 的性能测试结果。
精度测试：我们正在努力将精度测试也添加到 CI 中。
每日构建测试 (Nightly)：我们每晚会运行全量测试以确保代码正常工作。

最后，在未来的每个正式版本发布时，我们都会公开性能测试和精度测试报告。

10. How to fix the error "InvalidVersion" when using vllm-ascend?#

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

11. How to handle the out-of-memory issue?#

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

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

限制 --max-model-len：这可以节省 KV 缓存初始化阶段的 HBM 占用。
调整 --gpu-memory-utilization：若未指定，默认值为 0.9。您可以降低此值以预留更多内存，从而降低碎片风险。详见：vLLM 推理与服务参数。
配置 PYTORCH_NPU_ALLOC_CONF：设置此环境变量以优化 NPU 内存管理。例如，您可以使用 export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True 启用虚拟内存功能，以缓解运行时频繁动态调整内存大小导致的内存碎片。详见：PYTORCH_NPU_ALLOC_CONF 文档。

12. Failed to enable NPU graph mode when running DeepSeek.#

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

如果您使用的是 DeepSeek-V3 或 DeepSeek-R1，请确保在张量并行 (TP) 切分后，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]

13. Failed to reinstall vllm-ascend from source after uninstalling vllm-ascend.#

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

14. How to generate deterministic results when using vllm-ascend?#

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

采样方法：在 SamplingParams 中设置 temperature=0 来使用贪婪采样 (Greedy Sample)，例如：

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

设置以下环境变量参数：

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

15. How to fix the error "ImportError: Please install vllm[audio] for audio support" for the Qwen2.5-Omni model？#

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

16. How to troubleshoot and resolve size capture failures resulting from stream resource exhaustion, and what are the underlying causes?#

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.

建议的缓解策略：

手动配置 compilation_config 参数以减少尺寸集：'{"cudagraph_capture_sizes":[size1, size2, size3, ...]}'。
采用 ACLgraph 的全图模式（Full Graph Mode）作为分段方式的替代方案。

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

17. How to install custom version of torch_npu?#

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

18. On certain systems (e.g., Kylin OS), `docker pull` may fail with an `invalid tar header` error#

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

19. Why am I getting an error when executing the script to start a Docker container? The error message is: "operation not permitted".#

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

20. How to achieve low latency in a small batch scenario?#

torch_npu.npu_fused_infer_attention_score 在小 Batch 场景下的性能不够理想，主要是由于缺乏 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，否则会导致使用另一种 Attention 算子。重要提示：请确保您使用的是 vllm-ascend 的官方镜像，否则您必须将脚本中的 /vllm-workspace 目录更改为您自己的目录。如果您不是 root 用户，运行此脚本需要 sudo 权限。