KTransformers 昇腾 NPU 部署排障笔记：在 300I A2 上跑满 DeepSeek-R1

KTransformers 昇腾 NPU 部署排障笔记在 300I A2 上跑满 DeepSeek-R1【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers这是一份 KTransformers 昇腾 NPU 部署的踩坑笔记。记录的是 2026 年某次真实部署时间线Atlas 2UPKunpeng 920 1TB DDR5 Atlas 300I A2 NPU上把满血 DeepSeek-R1 从拉代码到服务出词的全过程报错和排障按发生顺序嵌在步骤里。KTransformers 的异构思路是MLA 注意力、共享专家和稠密层等算力密集的模块放 NPU 上以 W8A8 精度跑256 个路由专家走 DDR5 里的 Q4 量化权重——专家层是访存瓶颈带宽换容量正是 CPU 内存的强项。17:20 先看机器硬件与内存自检跑满血版 R1/V3光路由专家权重就要约400GB物理内存这是第一道门槛。目前适配的 NPU 型号为300I A2参考机型 Atlas 2UP。系统用Ubuntu 22.04 for aarch64内核 5.15.0-25-generic装完记得关自动更新否则一次内核升级就能把驱动组合搞挂。18:05 软件栈torch_npu 编译与版本哈希排障按顺序装三样固件驱动Ascend HDK 25.3.RC1、CANN 8.3.RC1.alpha003ToolKit Kernel NNAL 三个组件都要然后 Python 3.11 环境pip3 install torch2.5.1 torchvision0.20.1 torchaudio2.5.1 pip3 install transformers4.57.1 # 必须这个版本其他版本未验证torch_npu 有个绕不开的坑这次适配动了算子公网 PyPI 上的包用不了得拉源码编译v2.5.1分支。编译前先把 CANN 和 NNAL 的环境变量加载进来source /usr/local/Ascend/ascend-toolkit/set_env.sh source /usr/local/Ascend/nnal/atb/set_env.sh别急着跑先确认这一步源码编译出来的包版本号会带上 git 哈希后缀形如2.5.1.post4git69550dfcpip 的严格版本校验会直接报错。用文本编辑器打开site-packages/torch_npu/version.py把__version__里的git...部分删掉即可。启动服务后如果抛ImportError: libhccl.so: cannot open shared object file说明当前 shell 没加载 CANN 环境补一次source /usr/local/Ascend/ascend-toolkit/set_env.sh报的是libascend_hal.so则属于驱动层把驱动库目录前置到LD_LIBRARY_PATHexport LD_LIBRARY_PATH/usr/local/Ascend/driver/lib64/driver:$LD_LIBRARY_PATH两条报错看着像其实一个在 CANN、一个在 Driver别混着治。19:10 权重合并两份权重合出一份NPU 路线需要两套量化各管一段Q4_K_M 的 GGUF 权重给 CPU 侧专家用W8A8 权重给 NPU 侧稠密模块用。两份都下齐后用仓库自带的合并脚本archive/merge_tensors/merge_safetensor_gguf.py输出一个统一目录python merge_safetensor_gguf.py \ --safetensor_path /mnt/weights/DeepSeek-R1-W8A8 \ --gguf_path /mnt/weights/DeepSeek-R1-Q4_K_M \ --output_path /mnt/weights/DeepSeek-R1-q4km-w8a8跑完后只用这个合并目录后面启动脚本的--model_path和--gguf_path两个参数都指向它这是最容易填错的地方。20:30 安装编译ARM 宏冲突与 attn 配置拉取代码并初始化子模块这一步网络不好会反复失败建议在一台网络好的机器上初始化后打包拷贝git clone https://gitcode.com/gh_mirrors/ktr/ktransformers cd ktransformers git submodule update --init --recursiveKunpeng 是 aarch64llamafile 的 ARM 路径会在这里撞车third_party/llamafile/iqk_mul_mat_arm82.cpp里那两行#define iqk_mul_mat ...arm82是纯 CPU 推理路径的宏和 NPU 算子路径冲突编译前注释掉。然后加载 CANN 环境、装编译依赖并修改ktransformers/configs/config.yaml中 attn 部分为page_size: 128、chunk_size: 16384——NPU 侧融合注意力算子只认这几个 page 粒度不改会在初始化时抛异常source /usr/local/Ascend/ascend-toolkit/set_env.sh apt install cmake libhwloc-dev pkg-config确认配置无误后再开始编译带上负载均衡与 NUMA 感知两个开关USE_BALANCE_SERVE1 USE_NUMA1 bash ./install.sh21:00 启动参数速查balance_serve 与优化规则启动脚本用相对路径引用优化配置必须放在仓库根目录执行。骨架如下完整注释版参考[doc/zh/DeepseekR1_V3_tutorial_zh_for_Ascend_NPU.md](https://link.gitcode.com/i/6367752efd0d8eb81b40b5353f79f793)#!/bin/bash export USE_MERGE0 # 权重已离线合并跳过运行时合并 export INF_NAN_MODE_FORCE_DISABLE1 export TASK_QUEUE_ENABLE0 # 关闭任务队列保证算子下发顺序有序 export RANK0 export LOCAL_WORLD_SIZE1 source /usr/local/Ascend/ascend-toolkit/set_env.sh source /usr/local/Ascend/nnal/atb/set_env.sh python ktransformers/server/main.py \ --port 10002 \ --model_path /mnt/weights/DeepSeek-R1-q4km-w8a8 \ --gguf_path /mnt/weights/DeepSeek-R1-q4km-w8a8 \ --model_name DeepSeekV3ForCausalLM \ --cpu_infer 100 \ --optimize_config_path ./ktransformers/optimize/optimize_rules/npu/DeepSeek-V3-Chat-300IA2-npu-serve.yaml \ --max_new_tokens 1024 \ --cache_lens 20480 \ --max_batch_size 4 \ --use_cuda_graph \ --tp 1 \ --backend_type balance_serve--optimize_config_path是必选参数指向 NPU 专用规则。这份 YAML 决定哪些模块换成 NPU 上的 W8A8 量化算子可以打开[archive/ktransformers/optimize/optimize_rules/npu/](https://link.gitcode.com/i/76a669dc9bb3173eabf07ce8235693f2)对照阅读--cache_lens 20480是所有请求共享的 KV cache 预算单位 token--use_cuda_graph即 NPU 图下沉能摊薄逐算子下发开销配合上面的TASK_QUEUE_ENABLE0使用。速度不达标时在脚本里打开PROF_DECODE/PROF_PREFILL两个开关就能定位是 prefill 还是 decode 卡住。21:40 验收服务就绪与基准数据看到 10002 端口开始监听、npu-smi info里目标卡利用率随请求波动就说明链路通了。此时用任一 OpenAI 兼容客户端打两条请求回复质量正常即算部署完成。Atlas 300I A2 实测batch4、输出 1024 tokenPrompt 长度1K2K4KPrefill token/s174.68169.52167.15Decode token/s16.0716.1216.48下一步可以把 OpenAI 兼容客户端直接指到这个端口接入业务想换 Qwen3-MoE参考[doc/zh/Qwen3-MoE_tutorial_zh_for_Ascend_NPU.md](https://link.gitcode.com/i/15e0549066aea8eaa29703f3abb803a2)主要差在 CPU 线程数和--cache_lens的取值。【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考