• 大模型
• 人工智能

Qwen3-4B-FP8 部署排错清单：在昇腾 NPU 上用 vLLM-Ascend 拉起 Qwen3-4B-FP8 推理服务时，最常见的 8 类报错（FP8 量化不支持、HCCL 绑定失败、OOM、图捕获失败等）都在这里，每个坑都附原因与一键可抄的解决方案。

Qwen3-4B-FP8 是 Qwen3-4B 的 FP8 量化版本（float8_e4m3fn，权重按 [128, 128] 分块量化），4B 参数、36 层、GQA 注意力（Q:32 / KV:8 头），原生支持 32K 上下文与思考/非思考模式切换。单张 Ascend 910B 即可运行，是昇腾上性价比很高的小模型。但 FP8 + NPU 的组合有几个"新手重灾区"，本文把踩坑清单一次讲完。🧭

部署前30秒自检：3条命令确认环境没坑

在排查任何报错之前，先跑完这 3 条命令，能提前避开一半的坑：

npu-smi info # 1. NPU 是否可见、内存是否被占 python -c "import torch_npu; print(torch.npu.is_available())" # 2. torch_npu 是否可用 python -c "import vllm, vllm_ascend; print(vllm.__version__)" # 3. vLLM-Ascend 是否装好

同时确认软件版本满足 README.md 中的要求：CANN ≥ 8.5.1、torch_npu 与 CANN 配套、vLLM ≥ 0.8.5、transformers ≥ 4.51.0。

坑1：torch_npu 与 CANN 版本不匹配，NPU 直接"隐身"

症状：import torch_npu报ImportError，或torch.npu.is_available()返回False；日志里出现SOC_VERSION not found。

原因：torch_npu 必须与 CANN 大版本严格配套，pip 源里装到的版本往往和机器上的 CANN 对不上。

解决方案：

1. 用ascend-cann-py -v查看 CANN 版本；
2. 按 CANN 官方版本表安装配套 torch_npu（不要随意 pip 升最新版）；
3. 若npu-smi不在 PATH 导致识别失败，手动指定：export SOC_VERSION=Ascend910B3（按实际机型）。

💡 判断口诀：npu-smi info能看到卡但 Python 里is_available()是 False，99% 是 torch_npu 版本问题，不是驱动问题。

坑2：报 "fp8 quantization is currently not supported in npu"，量化格式与引擎不匹配

这是本仓库最容易踩、也最致命的坑。Qwen3-4B-FP8 的 config.json 中声明了quant_method: fp8，而昇腾 NPU 上原生 FP8 执行 kernel 的支持受版本限制，旧版 vLLM-Ascend 会直接抛出：

RuntimeError: fp8 quantization is currently not supported in npu

两种解法：

FP8 → BF16 的反量化本质是x_bf16 = x_fp8 × scale，其动态量化公式可参考下图（反量化即逆过程）：

⚠️ 特别注意：--quantization ascend只能用于 W4A8/W8A8 等昇腾量化格式的模型。对 BF16/FP8 模型误加该参数不会报错，但会输出乱码甚至 NaN——这就是坑7。更多细节见 quantify-agent/vllm-run.md 与 reference/quantization-guide.md。

坑3：HCCL binding failed，僵尸进程占着端口和 NPU

症状：

RuntimeError: HCCL error in: ... HCCL binding failed

原因：上一次服务没退干净，8000 端口或 NPU 被残留进程占用。

解决方案（按顺序执行）：

pkill -f "vllm serve" pkill -f "vllm.entrypoints" netstat -tulpn | grep 8000 # 确认端口已释放 npu-smi info # 确认 NPU 内存已清零

💡 建议养成习惯：每次重启前都看一眼npu-smi info的 Memory 列，只要不是 0，就说明有进程还没释放。

坑4：ACL Graph capture error (507903)，图捕获失败

症状：启动后期报EZ9999: 507903 ... ACL Graph capture error，服务崩溃或卡在启动阶段。

原因：ACLGraph 流捕获序列被不兼容算子打断。

解决方案（三步走，先定位后优化）：

1. 加--enforce-eager隔离问题——eager 模式能跑通，就确认是图捕获问题而非算子缺失；
2. 设置 AIV 通信扩展模式：export HCCL_OP_EXPANSION_MODE="AIV"；
3. 必要时调小--max-model-len 16384降低图捕获规模。

稳定跑通后再去掉--enforce-eager恢复图模式以获得完整性能。

坑5：启动阶段 OOM，显存不够装模型 + KV Cache

症状：加载权重阶段就OutOfMemoryError。Qwen3-4B-FP8 权重约 4.1GB（model.safetensors.index.json 可见两个分片），但 KV Cache 和图缓存会额外吃显存，--max-model-len 32768时内存吃紧。

解决方案（按优先级）：

export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True # 减少显存碎片 # 启动参数： --max-model-len 16384 # 先降上下文 --max-num-seqs 8 # 降并发 --swap-space 16 # KV Cache 溢出到 CPU

反直觉提醒：调高--gpu-memory-utilization不能解决"模型装不下"，只会让 KV Cache 更激进地抢内存。显存真不够时优先降max-model-len和并发。

坑6：推理阶段 OOM，KV Cache 耗尽

症状：服务能启动、短请求正常，但长输入或高并发时请求报错/变慢，日志提示 KV cache 不足。

解决方案：

• 推理时缩短--max-model-len（4B 模型日常使用 8192~16384 足够）；
• 降低--max-num-seqs；
• 开启--swap-space将溢出 KV 换出到 CPU 内存（要求主机内存 ≥ 16GB，见硬件要求）。

坑7：输出乱码 / 全是 NaN，--quantization 参数用反了

症状：服务正常返回 200，但生成内容是乱码、重复或nan。

原因：这是新手最容易忽略的"静默错误"——BF16/FP8 模型误加了--quantization ascend。该参数仅对 W4A8/W8A8 等 ModelSlim 量化格式生效，加错不会启动报错，只会算出错误结果。

解决方案：

• Qwen3-4B-FP8 用加载期 FP8→BF16 反量化方案（坑2-方案①）时，不要加--quantization ascend；
• 只有权重目录里有quant_model_description.json（ModelSlim 量化产物）时才加；
• 验证方法：curl http://localhost:8000/v1/chat/completions发一个"法国首都是哪里？"，正常应回答 Paris。

坑8：多卡张量并行时 Shape mismatch，KV 头数切分不对

症状：--tensor-parallel-size 2/4时报RuntimeError: Shape mismatch: 128 vs 64 under tensor parallel。

原因：Qwen3-4B 的 KV 头数是 8，TP 切分后每卡的 KV 头必须是整数；当 TP 数与 KV 头数不整除、或 KV 头复制逻辑未正确走 local norm-shard 路径时，就会出现张量形状对不上。

解决方案：

1. 先打印配置确认：num_kv_heads（8）与 TP 数的整除关系；
2. 4B 模型单卡完全够用（FP8 反量化后约 8GB），优先单卡部署，从源头避开 TP；
3. 确需多卡时升级 vllm-ascend 到支持 replicated KV heads 的版本，或用--enforce-eager先定位到具体算子。

排错收尾：三步验证服务真的好了

排错结束后，用以下三步确认"真修好了"而不是"假就绪"（服务显示 ready 但首个请求才崩溃的情况很常见）：

curl -sf http://localhost:8000/v1/models # 1. 服务就绪 curl -s http://localhost:8000/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model":"qwen3-4b-fp8","messages":[{"role":"user","content":"What is the capital of France?"}],"max_tokens":32,"temperature":0}'

3. 跑仓库自带的完整精度测试（7 个用例：知识问答、数学思考模式、编程、翻译等）：

python vllm_inference_test.py --model-path . --port 8000

测试脚本会先检查 NPU、自动拉起 vLLM 服务、逐例判定输出是否包含期望关键词，并把结果写入vllm_inference_results.json，详见 vllm_inference_test.py。对精度敏感的部署，还可以用 precision_alignment.py 做 NPU vs CPU 数值误差对齐（预期综合误差 < 0.01%）。

8个坑速查表：症状 → 解法一览

通用排查阶梯（适用于本文所有坑）：复现确认确定性失败 → 加--enforce-eager隔离图捕获问题 → 定向修改 → 重新走三步验证。完整方法论见 reference/troubleshooting.md。

参考资料

• README.md —— 模型卡片、部署命令与硬件要求
• config.json —— FP8 量化配置（weight_block_size: [128, 128]）
• vllm_inference_test.py —— 一键推理精度测试
• precision_alignment.py —— NPU/CPU 精度对齐验证
• adapt-agent/vllm-ascend-model-adapter/reference/troubleshooting.md —— vLLM-Ascend 完整故障库
• doc-agent/models/vllm-ascend/qwen3-dense/Qwen3-Dense-A2-Vllm-Ascend.md —— Qwen3-Dense 系列 Docker 部署实例

按这份清单从上到下过一遍，Qwen3-4B-FP8 在昇腾 NPU 上的部署基本可以"一次跑通"。剩下的性能调优（FlashComm1、算子融合等），等它先稳定跑起来再说。🚀

• 大模型
• 人工智能