昇腾NPU部署vLLM：大模型推理在国产算力上的实践与优化

1. 项目概述：当大模型推理遇上国产算力

最近在折腾大语言模型（LLM）的推理部署，发现了一个挺有意思的项目：vllm-project/vllm-ascend。简单来说，这是将业界知名的开源大模型推理服务框架vLLM，适配到华为昇腾（Ascend）AI处理器上的一个分支版本。

如果你也和我一样，手头有昇腾的硬件资源（比如Atlas系列服务器或板卡），同时又想高效、低成本地跑起像Llama、Qwen、ChatGLM这些动辄百亿、千亿参数的大模型，那这个项目绝对值得你花时间研究。它解决的痛点非常明确：让基于英伟达CUDA生态的先进推理优化技术，能在国产AI芯片上跑起来，并且跑得足够快、足够省内存。

为什么这件事很重要？在当前的AI浪潮下，大模型的训练和推理对算力的需求是“吞金兽”级别的。英伟达的GPU固然强大，但成本、供应和生态自主性都是现实问题。昇腾作为国产AI芯片的代表，其算力密度和能效比表现不俗，但软件生态，尤其是针对大模型这种新兴且复杂的负载，一直是需要补强的短板。vllm-ascend的出现，相当于把vLLM这套经过大规模实践验证的“发动机”装到了昇腾的“底盘”上。

vLLM本身的核心优势在于其创新的PagedAttention注意力算法和高效的内存管理，它能将KV Cache（键值缓存）像操作系统管理内存一样进行分页，从而极大地提高了GPU显存的利用率，降低了推理延迟，提升了吞吐量。vllm-ascend项目的工作，就是将这些核心算法和内存管理机制，通过昇腾计算架构（CANN）进行重写和优化，让它们能在昇腾NPU上高效执行。

所以，这个项目适合谁？首先是拥有昇腾硬件资源的开发者或企业，无论是用于内部服务、产品研发还是学术研究。其次是关注国产AI软硬件生态的技术爱好者，想了解如何将主流AI框架迁移到新平台。最后，对于任何想深入理解大模型推理底层优化技术的人来说，研究这个项目的代码和实现思路，也是一个绝佳的学习机会。

接下来，我会结合自己的实践，带你从设计思路到实操部署，完整地走一遍流程，并分享其中遇到的坑和解决技巧。

2. 核心架构与设计思路拆解

要理解vllm-ascend，必须先吃透原版vLLM的核心思想，然后再看它是如何做“移植手术”的。

2.1 原版vLLM的精髓：PagedAttention与内存革命

大模型推理，尤其是生成式任务（如对话、续写），有一个显著特点：它是一个自回归的过程。模型根据已有的输入（prompt）和已经生成的部分输出（tokens），逐个预测下一个token。在这个过程中，为了计算效率，模型会将计算注意力（Attention）时产生的Key和Value张量缓存下来，这就是KV Cache。

对于长序列或大批量请求，KV Cache所占用的显存会非常巨大，成为制约吞吐量和并发能力的主要瓶颈。传统方法要么需要预留巨大的连续显存空间（造成浪费），要么在序列变长时不得不重新计算（增加延迟）。

vLLM的PagedAttention灵感来源于操作系统的虚拟内存和分页机制。它将KV Cache在逻辑上视为一个连续的“内存”空间，但在物理存储上，将其切分成固定大小的“块”（Block），这些块可以不连续地存放在显存中。每个请求的序列，对应一个由这些块组成的“块表”（Block Table）。

这样做带来了几个革命性的好处：

1. 近乎零浪费的内存利用：不同请求的序列可以共享物理块（例如相同的系统提示词），空闲的块可以立即分配给新的请求，消除了传统方法中因内存碎片和预分配导致的浪费。
2. 高效的共享与并行：对于同一个提示词生成多个回答（如采样不同参数），其共享的提示词部分对应的KV Cache可以物理上只存一份，多个生成流通过块表引用它，极大节省内存。
3. 灵活的内存管理：当序列长度动态增长时，只需按需分配新的块，并将其地址加入块表即可，无需移动大量数据。

vllm-ascend项目的首要任务，就是在昇腾NPU上实现这套精妙的内存管理和注意力计算机制。

2.2 昇腾适配的核心挑战与技术选型

将vLLM移植到昇腾，不是简单的“换几个API调用”。这涉及到计算硬件、编程模型、内存体系等多层面的差异。

核心挑战一：计算算子与内核（Kernel）重写vLLM的核心计算，尤其是注意力计算部分，包含了大量高度优化的CUDA内核。这些内核直接操作GPU的显存和计算单元，以达到极致性能。昇腾NPU使用不同的指令集（如达芬奇架构）和内存层次结构。因此，vllm-ascend必须使用昇腾的异构计算架构CANN提供的算子开发接口（如Ascend C语言），将这些关键内核重新实现。

这不仅仅是功能实现，更是性能调优的攻坚战。需要深入理解昇腾NPU的矩阵计算单元（Cube）、向量计算单元以及片上缓存（L1/L2）的特性，来设计数据搬运和计算流水，以匹配甚至超越原版CUDA内核的效率。

核心挑战二：内存管理系统对接vLLM有一套独立于PyTorch的内存管理器，用于管理上述的PagedAttention块。在GPU上，它直接调用cudaMalloc和cudaFree。在昇腾上，需要将其对接至昇腾运行时（Ascend Runtime）的内存管理接口，例如aclrtMalloc。这要求对vLLM的内存分配、释放、流转逻辑有深刻理解，确保在NPU设备内存上也能实现同样的分页、共享和回收语义。

核心挑战三：生态工具链整合vLLM的生态建立在PyTorch之上。昇腾通过PyTorch Adapter（PTA）或Torch-NPU插件来支持PyTorch。vllm-ascend需要确保其所有的张量操作、模型加载都能通过昇腾适配后的PyTorch正确执行在NPU上。这涉及到模型格式转换（如将Hugging Face格式的模型转换为昇腾支持的OM格式，或直接使用PTA进行JIT执行）、依赖库版本对齐等一系列工程化问题。

技术选型考量： 从项目代码和文档看，vllm-ascend目前主要基于较新的Torch-NPU架构进行开发，直接利用torch_npu模块将PyTorch算子下发到NPU。这种方式的好处是与PyTorch生态结合更紧密，开发模式更接近原生PyTorch，便于利用现有的模型代码和社区工具。另一种潜在路径是通过CANN的ACL接口进行更底层的开发，虽然控制力更强，但开发复杂度和生态兼容性挑战更大。当前选择Torch-NPU是务实且高效的。

3. 环境准备与依赖部署实战

理论说得再多，不如动手跑起来。部署vllm-ascend是对你昇腾环境掌握程度的一次综合考试。以下步骤基于我实际在Atlas 800训练服务器（型号9010，搭载Ascend 910B NPU）上的实践总结。

3.1 基础系统与驱动栈检查

这是所有工作的基石，务必确保稳固。

注意：昇腾软件栈版本迭代较快，强烈建议根据vllm-ascend项目仓库README.md或requirements.txt中明确指定的版本进行安装，避免兼容性问题。

1. 操作系统：主流Linux发行版均可，如CentOS 7.6+、Ubuntu 18.04/20.04。我使用的是Ubuntu 20.04.6 LTS。确保系统内核版本符合CANN要求。
2. 昇腾驱动与固件：首先安装NPU驱动和对应的固件包。你可以从华为昇腾社区下载。安装后，使用npu-smi info命令检查NPU设备是否被正确识别。你应该能看到类似如下输出，显示NPU的型号、算力版本、温度、功耗、内存使用情况等信息。这是你的“硬件体检报告”，必须全部正常。

   # 示例输出 +-------------------------------------------------------------------------------------------+ | npu-smi 23.0.0 Version: 23.0.0 | +----------------------+---------------+----------------------------------------------------+ | NPU Name | Health | Power(W) Temp(C) Hugepages-Usage(page) | | Chip | | Bus-Id Used-Mem(MB) Free-Mem(MB) | +======================+===============+====================================================+ | 0 910B1 | OK | 78.8 45 0 / 0 | | 0 | | 0000:89:00.0 1000 28704 | +======================+===============+====================================================+

3. CANN工具包安装：CANN是昇腾计算的核心软件包，包含了运行时库、编译器、算子库等。下载与你的驱动和操作系统匹配的CANN版本（例如CANN 7.0.RC1）。按照官方指南安装，通常包括设置环境变量source /usr/local/Ascend/ascend-toolkit/set_env.sh。安装后，可以测试一个简单的aclruntime样例，确保基础功能正常。

3.2 Python环境与PyTorch-NPU构建

这是软件生态层，最容易出问题。

1. 创建独立的Python虚拟环境：这是避免依赖冲突的黄金法则。

   conda create -n vllm-ascend python=3.8 # 建议使用3.8或3.9，兼容性最好 conda activate vllm-ascend

2. 安装PyTorch和Torch-NPU：这是最关键的一步。不要直接从PyPI安装torch。你需要安装华为官方提供的、与CANN版本匹配的torch_npu包及其对应的PyTorch版本。
   • 访问昇腾社区，找到与你CANN版本匹配的torch_npu安装包（通常是.whl文件）。例如：torch_npu-2.1.0rc1-cp38-cp38m-linux_aarch64.whl(对于ARM CPU) 或...linux_x86_64.whl(对于x86 CPU)。
   • 同时，你需要指定对应版本的PyTorch。安装命令通常如下：

   # 首先安装对应版本的PyTorch (以2.1.0为例) pip install torch==2.1.0 # 然后安装torch_npu的wheel包 pip install torch_npu-2.1.0rc1-cp38-cp38m-linux_x86_64.whl

   安装完成后，在Python中验证：

   import torch import torch_npu print(torch.__version__) print(torch_npu.__version__) print(torch.npu.is_available()) # 应该返回True x = torch.randn(2,3).npu() print(x.device) # 应该显示 `npu:0`

   如果torch.npu.is_available()返回False，请检查驱动、CANN环境变量以及torch_npu版本匹配性。

3.3 编译安装vllm-ascend

现在可以开始安装主角了。

1. 克隆仓库与依赖安装：

   git clone https://github.com/vllm-project/vllm-ascend.git cd vllm-ascend # 仔细阅读requirements.txt，可能需要根据你的环境调整某些包的版本 pip install -r requirements.txt

   requirements.txt里会列出vllm包本身，以及一些必要的依赖如transformers,accelerate,ninja等。安装过程应该比较顺利。

2. 处理可能的编译依赖：vllm-ascend的部分核心组件（如自定义的Attention算子）可能需要从源码编译。确保你的系统安装了必要的编译工具：

   sudo apt-get update sudo apt-get install -y build-essential cmake g++

   如果项目中有setup.py或pyproject.toml，通常直接执行pip install -e .（可编辑模式安装）即可触发编译过程。密切关注编译输出，看是否有关于CUDA的警告或错误。在昇腾平台上，这些应该被替换为NPU相关的编译选项。如果编译失败，最常见的原因是找不到NPU的头文件或库，请确认CANN的环境变量（如ASCEND_HOME）已正确设置，并且LD_LIBRARY_PATH包含了CANN的库路径。

3. 安装验证：安装完成后，尝试一个最简单的导入，不报错即初步成功。

   import vllm print(vllm.__version__)

   但此时还不能运行模型，因为还没有处理模型本身。

3.4 模型准备与转换

vLLM支持直接从Hugging Face Hub加载模型。对于昇腾，由于计算图最终需要在NPU上执行，模型可能需要一个“编译”或“图优化”的过程。

1. 直接加载（PTA/JIT模式）：如果你的环境是较新的Torch-NPU，并且模型算子支持良好，理论上可以直接像在GPU上一样加载。vLLM会通过PyTorch将计算图下发到NPU。这是最理想的情况。

   from vllm import LLM llm = LLM(model="meta-llama/Llama-2-7b-chat-hf") # 指定模型ID

   首次加载时，Torch-NPU可能会对模型计算图进行JIT编译和优化，这需要一些时间，并会生成缓存。请确保磁盘有足够空间。

2. 离线模型转换（OM格式）：对于性能要求极致或遇到算子兼容性问题的场景，可能需要将模型转换为昇腾的离线模型（OM）格式。这个过程通常使用昇腾模型转换工具（ATC）。

   • 你需要先将Hugging Face模型导出为ONNX或PyTorch的TorchScript格式。
   • 然后使用ATC工具，指定输入输出、数据类型、精度（FP16/INT8）等，将中间格式转换为OM模型。
   • 最后，需要一个能够加载OM模型并进行推理的运行时封装，将其接入vLLM的模型执行引擎。这部分工作vllm-ascend项目可能尚未完全封装成自动化流程，可能是当前开发的重点或难点之一。你需要查阅项目进展或社区讨论，看是否有成熟的范例。

实操心得：在初期探索阶段，强烈建议从一个小模型开始（如Qwen-1.8B-Chat），先走通直接加载的流程。这能帮你快速验证整个软件栈是否通畅，避免在复杂的大模型转换上耗费过多时间却卡在基础环境问题。

4. 核心配置与推理服务启动

环境就绪，模型备好，接下来就是配置和启动推理服务了。vLLM提供了两种主要使用方式：离线批量推理和在线API服务。这里我们重点看在线服务，因为它更贴近生产部署场景。

4.1 启动vLLM API服务器

vLLM内置了一个高性能的API服务器，兼容OpenAI的API协议。这意味着任何兼容OpenAI API的客户端（包括LangChain、ChatGPT Next Web等）都可以直接连接使用。

启动命令的基本骨架如下：

python -m vllm.entrypoints.openai.api_server \ --model /path/to/your/model \ # 或 Hugging Face model ID --tensor-parallel-size 1 \ # 张量并行大小，对应使用的NPU数量 --served-model-name llama-2-7b \ # API中使用的模型名 --host 0.0.0.0 \ # 监听地址 --port 8000 # 监听端口 --dtype half # 模型权重数据类型，half (FP16) 节省内存 --max-model-len 4096 # 模型支持的最大序列长度

关键参数解析与昇腾适配要点：

1. --tensor-parallel-size：这是分布式推理参数。如果你有多张NPU卡，可以将其设置为NPU数量，vLLM会自动将模型进行张量切分，并行推理。在昇腾环境下，需要确保torch.distributed后端支持NPU（通常是hccl，华为集合通信库）。vLLM-ascend应该已经做了相应适配。单卡测试时务必设为1。
2. --dtype：对于大多数7B、13B模型，使用half(FP16/BF16) 是内存和精度之间的良好平衡。昇腾910B支持FP16和BF16。如果模型本身是BF16格式，可以尝试--dtype bfloat16。重要：你需要确认你的CANN版本和torch_npu是否完全支持bfloat16，有时可能需要特定版本或配置。
3. --max-model-len：这个参数直接影响KV Cache的内存分配。不要盲目设置得过大，应根据你的应用场景和可用NPU内存来设定。对于7B模型，在32GB NPU内存上，设置为4096或8192是常见的。你可以通过npu-smi info监控内存使用情况来调整。
4. --gpu-memory-utilization：这是vLLM控制显存/NPU内存利用率的参数。默认0.9，即预留90%的设备内存给vLLM的KV Cache和工作空间。在昇腾上同样有效。如果你的系统还有其他进程需要使用NPU内存，可以适当调低，例如0.8。
5. --enforce-eager：这是一个调试参数。如果遇到图编译错误或算子不支持，可以尝试加上此参数，强制PyTorch使用“eager mode”（即时执行）而非图模式，有助于定位问题，但可能会损失性能。

启动成功后，你应该看到类似下面的日志，注意观察是否有NPU相关的初始化信息：

INFO 07-15 14:30:00 llm_engine.py:137] Initializing an LLM engine (vllm-project/vllm-ascend)... INFO 07-15 14:30:00 llm_engine.py:138] Devices: NPU (type: cuda) # 这里可能仍显示cuda，是vLLM的抽象，实际后端是NPU INFO 07-15 14:30:00 llm_engine.py:139] Tensor parallelism: 1 INFO 07-15 14:30:00 model_runner.py:285] Loading model weights took 15.3 GB INFO 07-15 14:30:10 llm_engine.py:404] Model loaded successfully. Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

4.2 性能调优关键配置

要让服务跑得又快又稳，以下几个配置点需要特别关注：

1. 批处理大小（--max-num-batched-tokens）：这是vLLM吞吐量的关键调节器。它限制了单个批处理步骤中能处理的最大token数。增大此值可以提高吞吐量（每秒处理的token数），但会增加延迟和内存压力。需要根据你的NPU内存大小和典型请求长度进行压测找到平衡点。可以从默认值（如256或512）开始，逐步增加。
2. 调度策略（--scheduler）：vLLM默认使用vllm.core.scheduler.Scheduler，它结合了PagedAttention，非常高效。通常无需更改。
3. KV Cache内存分配：除了--gpu-memory-utilization，还可以通过--block-size来微调。块大小默认是16。对于非常长的序列，适当增大块大小（如32）可以减少块表的管理开销；对于短序列居多的场景，保持较小值可以提高内存利用率。这需要结合具体负载进行测试。
4. 日志级别：如果遇到问题，启动时添加--log-level debug可以输出更详细的信息，帮助排查。

4.3 客户端请求测试

服务器启动后，我们可以用curl或Python脚本来测试服务是否正常。

使用curl测试聊天补全接口：

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "llama-2-7b", # 与 --served-model-name 一致 "messages": [ {"role": "user", "content": "请用中文介绍一下华为昇腾处理器。"} ], "max_tokens": 100, "temperature": 0.7 }'

使用Python客户端（OpenAI SDK格式）测试：

from openai import OpenAI # 需要安装 openai>=1.0.0 client = OpenAI( api_key="token-abc123", # vLLM服务器不需要验证，可任意填写 base_url="http://localhost:8000/v1" ) response = client.chat.completions.create( model="llama-2-7b", messages=[{"role": "user", "content": "请用中文介绍一下你自己。"}], max_tokens=50, temperature=0.8 ) print(response.choices[0].message.content)

如果一切正常，你将收到模型生成的流畅回复。第一次请求可能会稍慢，因为涉及模型图编译或预热。

5. 深度性能分析与优化实践

服务跑起来只是第一步，让它跑得高效、稳定才是目标。在昇腾平台上进行性能分析和优化，有其独特的工具和方法。

5.1 性能监控指标解读

你需要关注以下几类核心指标：

1. 吞吐量（Throughput）：通常以Tokens per Second (TPS)或Requests per Second (RPS)衡量。这是衡量服务处理能力的核心。使用压力测试工具（如locust,wrk）模拟并发请求进行测量。
2. 延迟（Latency）：
   • Time to First Token (TTFT)：从发送请求到收到第一个输出token的时间。这反映了模型处理提示词（Prefill）阶段的速度，受输入长度和NPU计算能力影响。
   • Inter-token Latency：输出token之间的平均间隔时间。这反映了自回归生成（Decode）阶段的速度，受内存带宽和生成策略影响。
   • End-to-End Latency：整个请求完成的总时间。
3. NPU资源利用率：
   • 算力利用率：使用昇腾的msprof或Ascend PyTorch Profiler工具进行 profiling，查看NPU计算核心（Cube/Vector）的活跃周期占比。理想情况下，Prefill阶段算力利用率应很高，Decode阶段可能因内存访问频繁而利用率降低。
   • 内存使用率：通过npu-smi info持续监控。关注Used-Mem。vLLM的高效之处在于，即使模型很大，其Used-Mem也会稳定在一个值（模型权重+KV Cache+工作空间），不会随序列长度线性暴增，直到达到--gpu-memory-utilization设定的上限。
   • 内存带宽：Decode阶段是典型的“内存墙”场景，频繁读取KV Cache。高内存带宽对降低Inter-token Latency至关重要。可以通过 profiling 工具查看相关指标。

5.2 使用Ascend PyTorch Profiler进行性能剖析

这是定位性能瓶颈的利器。它类似于NVIDIA的Nsight Systems/Profiler。

1. 安装与配置：确保你的CANN版本包含了Profiler工具。通常位于/usr/local/Ascend/ascend-toolkit/latest/tools/profiler/bin。
2. 在代码中集成Profiling：

   import torch_npu from torch_npu.profiler import profile, ProfilerActivity activities=[ProfilerActivity.CPU, ProfilerActivity.NPU] with profile(activities=activities, record_shapes=True, profile_memory=True) as prof: # 在这里运行你的推理代码，例如调用一次 llm.generate() output = llm.generate(prompts=["Your prompt here"]) # 打印控制台摘要 print(prof.key_averages().table(sort_by="npu_time_total", row_limit=20)) # 导出为chrome tracing格式，用于在浏览器中可视化 prof.export_chrome_trace("trace.json")

3. 分析trace.json：用Chrome浏览器打开chrome://tracing，加载该文件。你可以清晰地看到：
   • 在时间线上，NPU的活动（计算、内存拷贝）和CPU的活动（调度、预处理）。
   • 哪些算子耗时最长？是Attention计算，还是LayerNorm，或是其他的？
   • 是否存在大量的“空隙”（NPU空闲）？这可能是由于CPU端调度跟不上，或者数据准备（如tokenization）太慢。
   • 内存拷贝（H2D， D2H）是否占用了大量时间？

5.3 针对昇腾平台的优化思路

根据Profiling结果，可以从以下几个方向进行优化：

1. 算子优化：如果发现某个算子在NPU上执行时间异常长，可能是该算子的昇腾实现不够优化。可以尝试：
   • 检查是否有更新的torch_npu或CANN版本，可能包含了性能修复。
   • 对于自定义算子（如vLLM自己的PagedAttention内核），需要深入vllm-ascend的源码，看是否有针对昇腾架构的特定优化（如循环展开、内存排布优化、使用特定指令等）。这需要较强的底层开发能力。
2. 计算图优化：
   • 图模式（Graph Mode） vs 动态图（Eager Mode）：NPU在图模式下通常能获得更好的性能，因为可以进行算子融合、常量折叠等优化。确保你的运行模式是图模式（除非用--enforce-eager调试）。首次运行时的编译开销是正常的。
   • 算子融合：通过Profiler查看是否有大量小算子连续执行。在昇腾上，可以通过CANN的图优化能力或修改模型代码，尝试将一些连续的小算子（如Add+LayerNorm）融合成一个更大的算子，减少内核启动开销。
3. 内存访问优化：
   • KV Cache布局：PagedAttention本身就是为了优化内存访问。在昇腾上，需要确保这些“内存页”（Blocks）在NPU设备内存中的访问是高效的。这可能涉及到块大小的选择（--block-size）是否与NPU的缓存行大小等因素匹配。这是一个比较深的调优点，通常需要框架开发者介入。
   • 连续内存分配：尽管是分页的，但尽量让同一个请求的KV Cache块在物理地址上相对连续，可以提高缓存命中率。这取决于vLLM-ascend内存分配器的实现。
4. 流水线与批处理：
   • 增大批处理：在内存允许的前提下，适当增加--max-num-batched-tokens，让NPU的计算单元更“饱”，是提高吞吐量最直接有效的方法。但要注意延迟也会随之增加。
   • 持续批处理（Continuous Batching）：vLLM原生支持，这是其高吞吐的关键。确保该功能在昇腾后端上正常工作。它允许不同请求的生成过程在批处理中交织进行，动态调度，最大化NPU利用率。

6. 常见问题排查与实战经验录

在实际部署和运行vllm-ascend的过程中，我遇到了不少问题。这里把一些典型问题和解决思路记录下来，希望能帮你少走弯路。

6.1 环境与依赖类问题

问题1：torch.npu.is_available()返回False

• 排查思路：
  1. 驱动与固件：首先用npu-smi info确认NPU设备被系统识别且状态健康。
  2. 环境变量：确保已正确source了CANN的set_env.sh脚本。检查LD_LIBRARY_PATH是否包含了CANN的库路径（如/usr/local/Ascend/ascend-toolkit/latest/lib64）。
  3. 版本匹配：这是最常见的原因。严格核对驱动版本、CANN版本、PyTorch版本、torch_npu wheel包版本四者之间的匹配关系。务必使用华为官方发布的版本匹配表格。
  4. 权限问题：运行Python程序的用户是否有访问NPU设备（/dev/davinciX）的权限？通常需要将用户加入hdc组，或直接使用root/sudo。

问题2：在编译或导入vllm时，出现CUDA相关的错误或警告

• 原因与解决：vLLM原版代码中充满了CUDA的硬编码。vllm-ascend项目的一个核心工作就是将这些替换为NPU的对应实现。如果遇到此类错误，说明你拉取的代码可能替换不彻底，或者编译时某些宏定义未正确开启。
  • 确保你克隆的是vllm-project/vllm-ascend仓库，而不是原版vllm-project/vllm。
  • 检查项目的setup.py或CMakeLists.txt，看是否有针对昇腾的编译开关（如-DWITH_ASCEND=ON），并确保其被启用。
  • 查看项目Issue和Pull Request，看是否有其他人遇到类似问题及解决方案。

6.2 模型加载与推理类问题

问题3：加载模型时卡住或报错“算子不支持”

• 排查思路：
  1. 模型格式：确认你尝试加载的模型格式是vLLM和PyTorch-NPU支持的。对于Hugging Face模型，最好是原生的PyTorch.bin格式。safetensors格式通常也支持，但需确保safetensors库已安装。
  2. 具体算子：错误信息通常会指出哪个算子不支持（例如，某个特殊的激活函数silu的某个实现）。这可能是因为：
     • torch_npu对该算子的支持尚不完善。尝试搜索昇腾社区或torch_npu的Issue。
     • 模型使用了非常新的或自定义的算子。可以尝试使用更主流、更老的模型版本。
  3. 使用--enforce-eager模式：如果图模式编译失败，用此参数切换到动态图模式，如果能成功，则说明是图编译/优化阶段的问题，至少可以先用起来。
  4. 精度问题：尝试更换--dtype。例如，将bfloat16改为float16，或者尝试--dtype auto让vLLM自动选择。

问题4：推理结果出现乱码、重复或逻辑错误

• 原因：这通常是计算精度问题或内核实现有Bug的迹象。
  1. 精度对比：在CPU或GPU上，用相同的模型、相同的输入和随机种子运行一次，对比输出结果。如果昇腾NPU上的输出完全不同，则基本可以确定是计算错误。
  2. 简化测试：用一个极短的文本（如“Hello”），关闭采样（temperature=0），进行确定性生成，看输出是否合理。
  3. 检查内核：如果精度对比确实不一致，问题可能出在重写的NPU内核上，例如Attention计算中的softmax数值稳定性、LayerNorm的实现等。这需要向vllm-ascend项目组反馈，并提供详细的复现步骤。

6.3 性能与稳定性类问题

问题5：吞吐量远低于预期，或NPU利用率很低

• 排查步骤：
  1. Profiling：立即使用Ascend PyTorch Profiler抓取trace。看时间线里NPU是忙碌还是空闲居多。
  2. 检查瓶颈：
     • CPU瓶颈：如果Profiler显示NPU经常在等待CPU任务（如tokenization、数据准备、调度），那么需要优化预处理流水线，或者检查是否使用了过于复杂的Prompt模板。
     • 内存带宽瓶颈：Decode阶段NPU算力利用率低，但Inter-token Latency很高。这可能是受限于从NPU内存中读取KV Cache的速度。此时优化内存访问（如调整--block-size）可能收效甚微，更多依赖于硬件和底层驱动优化。
     • 批处理大小：检查实际运行的批处理大小是否过小。可以通过vLLM的日志或监控请求队列来判断。
  3. 对比测试：在相同硬件规格的GPU服务器上，用原版vLLM运行同一个模型，作为性能基准进行对比。差距可以帮助定位是硬件差异还是软件适配问题。

问题6：服务运行一段时间后崩溃，报内存不足（OOM）

• 分析：
  1. 内存泄漏：这是最可能的原因。可能是vLLM-ascend的内存管理器中存在Bug，导致分配的内存块在请求结束后没有被正确回收。
  2. 监控：在服务运行时，定期执行npu-smi info，观察Used-Mem是否在持续缓慢增长，即使在没有请求的时候。
  3. 测试：编写一个脚本，循环发送大量请求然后停止，观察内存是否回落。如果不回落，则基本确认是内存泄漏。
  4. 解决：尝试升级到vllm-ascend的最新版本。如果问题依旧，需要向开发者提交详细的复现报告，包括模型、请求模式、环境信息等。

踩坑心得：在昇腾生态下做早期适配，心态要摆正。遇到问题，首先系统性地检查环境版本匹配（这解决了80%的问题），然后善用Profiler工具进行量化分析，而不是盲目猜测。积极参与项目社区（GitHub Issues, 昇腾论坛）的讨论，你遇到的问题很可能别人已经遇到并解决了。最后，对于深度性能问题和内核Bug，可能需要一定的耐心等待官方或社区的更新。