在 Atlas 上跑通 DeepSeek-R1KTransformers 昇腾 NPU 部署实战【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers导语为什么要把 LLM 搬到昇腾 NPU 上跑最直接的答案是内存和成本。DeepSeek-R1 这类满血 MoE 模型的路由专家权重体量巨大GPU 集群要么买不起、要么排队。Atlas 服务器配 1TB DDR5用 CPU NPU 异构分工承接推理KTransformers 的 CPU 推理内核正好吃下这条路径——专家权重放在内存里注意力与算子下沉到 NPU 执行。本文是一次真实部署的复盘从 Atlas 硬件、CANN 软件栈、双权重合并到 balance_serve 服务启动与性能核对每一步的坑都标在原地。部署前避坑清单先知道会踩什么坑后面装环境时心里有数transformers 版本被钉死在4.57.1其他版本未验证装错了直接报结构解析异常。torch_npu 不能直接用 pypi 预编译包。因为涉及新增算子必须从源码编译 v2.5.1 分支且编译后版本号里的哈希后缀要手动去掉见下文。两份权重缺一不可。Q4 的 GGUF 与 W8A8 的 safetensor 必须先用合并脚本合成一份只放一份进模型目录服务起不来。400GB 物理内存是下限。满血版 DeepSeek-R1/V3 的路由专家权重需要约 400GB 物理内存内存不足的机器别硬试。CANN 环境变量没 source一切白搭。libhccl.so、libascend_hal.so缺失都是同一个原因速查表里给了解法这里不重复展开。搭建 Atlas 硬件与操作系统本节目标是把一台 Atlas 2UP 变成可用的 300I A2 推理节点。硬件与系统版本按下表核对项规格服务器Atlas 2UPNPU300I A2当前 KTransformers 适配的 NPU 型号CPUHUAWEI Kunpeng 920 7270Z内存DDR5 服务器内存1TB操作系统Ubuntu 22.04 for aarch64内核5.15.0-25-generic装完系统后做两件事关闭自动更新并记录好 CANN、NPU 驱动的实际安装路径——后面 source 环境变量要用。硬件插拔与固件确认建议拉原厂支持一起完成NPU 的固件版本直接影响后面 Kernel 能否加载。配置 CANN 软件栈软件栈分四层HDK 固件驱动 → CANN → Python 环境 → torch_npu。顺序不能乱版本必须严格对齐下表任何一层漂移都会在算子加载阶段报错组件版本Ascend HDK25.3.RC1CANN8.3.RC1.alpha003需装 ToolKit、Kernel、NNAL 三件Python3.11conda 环境一行conda create -n py311 python3.11即可PyTorchtorch2.5.1/torchvision0.20.1/torchaudio2.5.1transformers4.57.1必须无替代torch_npuv2.5.1 分支源码编译torch_npu 编译前先把 CANN 与 NNAL 的环境加载进当前 shellsource /usr/local/Ascend/ascend-toolkit/set_env.sh source /usr/local/Ascend/nnal/atb/set_env.sh⚠️ 编译过程对 github、gitcode 等平台的网络访问敏感网络不畅通时子模块拉取会静默失败。从源码仓库Gitcode 上的 Ascend/pytorch获取代码后编译 v2.5.1 分支。编译装好后还有一个反直觉的步骤打开 site-packages 下torch_npu/version.py路径用pip show torch_npu确认把形如__version__ 2.5.1.post4git69550dfc的版本号改为__version__ 2.5.1.post4去掉哈希后缀。环境对版本号有严格匹配带后缀会直接被拒。合并 Q4 与 W8A8 双权重KTransformers 对 NPU 路径的精度要求决定了权重要走双份合并Q4_K_M 的 GGUF 权重负责路由专家的 CPU 侧存储W8A8 的 safetensor 权重负责 NPU 侧算子。两份原始权重都下载就位后跑仓库里的合并脚本python merge_safetensor_gguf.py \ --safetensor_path /path/to/DeepSeek-R1-W8A8 \ --gguf_path /path/to/DeepSeek-R1-Q4_K_M \ --output_path /output/merged脚本位于 merge_tensors/。合并完成后后续启动参数只指向合并后的目录两份原始权重不再参与推理。初始化项目与编译扩展克隆仓库并拉取子模块git clone https://gitcode.com/gh_mirrors/ktr/ktransformers cd ktransformers git submodule update --init --recursive进入编译前先安装构建依赖并加载 CANN 环境source /usr/local/Ascend/ascend-toolkit/set_env.sh apt install cmake libhwloc-dev pkg-config bash ./install.shinstall.sh 会编译 CPU 侧的 kt-kernel 扩展与 llamafile 算子库。⚠️ 在 aarch64ARM82上如果链接阶段报iqk_mul_mat相关错误把 third_party/llamafile/iqk_mul_mat_arm82.cpp 文件内的两行宏定义注释掉即可通过编译// #define iqk_mul_mat iqk_mul_mat_arm82 // #define iqk_mul_mat_moe iqk_mul_mat_moe_arm82这是 aarch64 工具链的已知适配点x86 机器不用动这个文件。启动 balance_serve 推理服务服务入口是ktransformers/server/main.py关键参数与 NPU 优化规则文件一起给出export USE_MERGE0 export INF_NAN_MODE_FORCE_DISABLE1 export TASK_QUEUE_ENABLE0 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 merged_weights \ --gguf_path merged_weights \ --model_name DeepSeekV3ForCausalLM \ --optimize_config_path ./ktransformers/optimize/optimize_rules/npu/DeepSeek-V3-Chat-300IA2-npu-serve.yaml \ --max_new_tokens 1024 \ --cache_lens 20480 \ --backend_type balance_serve环境变量逐个说明故障排查时只需对照这一段速查表不重复TASK_QUEUE_ENABLE0关闭任务队列保证算子下发顺序严格有序这是开启图下沉的前置条件USE_BALANCE_SERVE1与USE_NUMA1启用 balance_serve 后端与 NUMA 绑定启动脚本中按需导出USE_MERGE0权重已离线合并运行时不再做在线合并INF_NAN_MODE_FORCE_DISABLE1禁用推理期的 NaN 强制检查省去每步的开销--backend_type balance_serve指定服务后端--cache_lens 20480决定 KV cache 预分配长度按上下文预算调整。优化规则文件位于 ktransformers/optimize/optimize_rules/npu/300I A2 上 DeepSeek-V3 的服务化配置即上面启动参数引用的DeepSeek-V3-Chat-300IA2-npu-serve.yaml同目录还有非 serve 版与 Qwen3 的对应配置可选。用基准数据验证 NPU 推理性能服务起来后用固定长度 prompt 压一遍 prefill 与 decode。以下为 Batchsize4、输出长度 1024 条件下的参考值tokens/sPrompt 长度1K2K4KPrefill174.68169.52167.15Decode16.0716.1216.48实测与参考值偏差超过 20% 时先查 NPU 侧算子是否真的走下去了npu-smi看利用率再查cache_lens是否被默认值截断。需要定位慢算子时用PROF_PREFILL与PROF_DECODE两个环境变量分别开启两阶段的 profiling 输出。故障速查现象处理报libhccl.so缺失见上文「配置 CANN 软件栈」当前 shell 先source /usr/local/Ascend/ascend-toolkit/set_env.sh报libascend_hal.so缺失补驱动库路径export LD_LIBRARY_PATH/usr/local/Ascend/driver/lib64/driver:$LD_LIBRARY_PATHaarch64 编译期iqk_mul_mat链接错误注释 third_party/llamafile/iqk_mul_mat_arm82.cpp 中两行宏定义见「初始化项目与编译扩展」节torch_npu 导入即报错检查version.py是否仍带git...哈希后缀服务启动 OOM物理内存不足 400GB满血版无法容纳路由专家权重下一步建议把--cache_lens按业务真实上下文长度调到位再用PROF_PREFILL抓一次 prefill 分布——prefill 吞吐从 170 tokens/s 量级再往上走瓶颈基本都在长序列的注意力段。【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Atlas 上跑通 DeepSeek-R1：KTransformers 昇腾 NPU 部署实战
在 Atlas 上跑通 DeepSeek-R1KTransformers 昇腾 NPU 部署实战【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers导语为什么要把 LLM 搬到昇腾 NPU 上跑最直接的答案是内存和成本。DeepSeek-R1 这类满血 MoE 模型的路由专家权重体量巨大GPU 集群要么买不起、要么排队。Atlas 服务器配 1TB DDR5用 CPU NPU 异构分工承接推理KTransformers 的 CPU 推理内核正好吃下这条路径——专家权重放在内存里注意力与算子下沉到 NPU 执行。本文是一次真实部署的复盘从 Atlas 硬件、CANN 软件栈、双权重合并到 balance_serve 服务启动与性能核对每一步的坑都标在原地。部署前避坑清单先知道会踩什么坑后面装环境时心里有数transformers 版本被钉死在4.57.1其他版本未验证装错了直接报结构解析异常。torch_npu 不能直接用 pypi 预编译包。因为涉及新增算子必须从源码编译 v2.5.1 分支且编译后版本号里的哈希后缀要手动去掉见下文。两份权重缺一不可。Q4 的 GGUF 与 W8A8 的 safetensor 必须先用合并脚本合成一份只放一份进模型目录服务起不来。400GB 物理内存是下限。满血版 DeepSeek-R1/V3 的路由专家权重需要约 400GB 物理内存内存不足的机器别硬试。CANN 环境变量没 source一切白搭。libhccl.so、libascend_hal.so缺失都是同一个原因速查表里给了解法这里不重复展开。搭建 Atlas 硬件与操作系统本节目标是把一台 Atlas 2UP 变成可用的 300I A2 推理节点。硬件与系统版本按下表核对项规格服务器Atlas 2UPNPU300I A2当前 KTransformers 适配的 NPU 型号CPUHUAWEI Kunpeng 920 7270Z内存DDR5 服务器内存1TB操作系统Ubuntu 22.04 for aarch64内核5.15.0-25-generic装完系统后做两件事关闭自动更新并记录好 CANN、NPU 驱动的实际安装路径——后面 source 环境变量要用。硬件插拔与固件确认建议拉原厂支持一起完成NPU 的固件版本直接影响后面 Kernel 能否加载。配置 CANN 软件栈软件栈分四层HDK 固件驱动 → CANN → Python 环境 → torch_npu。顺序不能乱版本必须严格对齐下表任何一层漂移都会在算子加载阶段报错组件版本Ascend HDK25.3.RC1CANN8.3.RC1.alpha003需装 ToolKit、Kernel、NNAL 三件Python3.11conda 环境一行conda create -n py311 python3.11即可PyTorchtorch2.5.1/torchvision0.20.1/torchaudio2.5.1transformers4.57.1必须无替代torch_npuv2.5.1 分支源码编译torch_npu 编译前先把 CANN 与 NNAL 的环境加载进当前 shellsource /usr/local/Ascend/ascend-toolkit/set_env.sh source /usr/local/Ascend/nnal/atb/set_env.sh⚠️ 编译过程对 github、gitcode 等平台的网络访问敏感网络不畅通时子模块拉取会静默失败。从源码仓库Gitcode 上的 Ascend/pytorch获取代码后编译 v2.5.1 分支。编译装好后还有一个反直觉的步骤打开 site-packages 下torch_npu/version.py路径用pip show torch_npu确认把形如__version__ 2.5.1.post4git69550dfc的版本号改为__version__ 2.5.1.post4去掉哈希后缀。环境对版本号有严格匹配带后缀会直接被拒。合并 Q4 与 W8A8 双权重KTransformers 对 NPU 路径的精度要求决定了权重要走双份合并Q4_K_M 的 GGUF 权重负责路由专家的 CPU 侧存储W8A8 的 safetensor 权重负责 NPU 侧算子。两份原始权重都下载就位后跑仓库里的合并脚本python merge_safetensor_gguf.py \ --safetensor_path /path/to/DeepSeek-R1-W8A8 \ --gguf_path /path/to/DeepSeek-R1-Q4_K_M \ --output_path /output/merged脚本位于 merge_tensors/。合并完成后后续启动参数只指向合并后的目录两份原始权重不再参与推理。初始化项目与编译扩展克隆仓库并拉取子模块git clone https://gitcode.com/gh_mirrors/ktr/ktransformers cd ktransformers git submodule update --init --recursive进入编译前先安装构建依赖并加载 CANN 环境source /usr/local/Ascend/ascend-toolkit/set_env.sh apt install cmake libhwloc-dev pkg-config bash ./install.shinstall.sh 会编译 CPU 侧的 kt-kernel 扩展与 llamafile 算子库。⚠️ 在 aarch64ARM82上如果链接阶段报iqk_mul_mat相关错误把 third_party/llamafile/iqk_mul_mat_arm82.cpp 文件内的两行宏定义注释掉即可通过编译// #define iqk_mul_mat iqk_mul_mat_arm82 // #define iqk_mul_mat_moe iqk_mul_mat_moe_arm82这是 aarch64 工具链的已知适配点x86 机器不用动这个文件。启动 balance_serve 推理服务服务入口是ktransformers/server/main.py关键参数与 NPU 优化规则文件一起给出export USE_MERGE0 export INF_NAN_MODE_FORCE_DISABLE1 export TASK_QUEUE_ENABLE0 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 merged_weights \ --gguf_path merged_weights \ --model_name DeepSeekV3ForCausalLM \ --optimize_config_path ./ktransformers/optimize/optimize_rules/npu/DeepSeek-V3-Chat-300IA2-npu-serve.yaml \ --max_new_tokens 1024 \ --cache_lens 20480 \ --backend_type balance_serve环境变量逐个说明故障排查时只需对照这一段速查表不重复TASK_QUEUE_ENABLE0关闭任务队列保证算子下发顺序严格有序这是开启图下沉的前置条件USE_BALANCE_SERVE1与USE_NUMA1启用 balance_serve 后端与 NUMA 绑定启动脚本中按需导出USE_MERGE0权重已离线合并运行时不再做在线合并INF_NAN_MODE_FORCE_DISABLE1禁用推理期的 NaN 强制检查省去每步的开销--backend_type balance_serve指定服务后端--cache_lens 20480决定 KV cache 预分配长度按上下文预算调整。优化规则文件位于 ktransformers/optimize/optimize_rules/npu/300I A2 上 DeepSeek-V3 的服务化配置即上面启动参数引用的DeepSeek-V3-Chat-300IA2-npu-serve.yaml同目录还有非 serve 版与 Qwen3 的对应配置可选。用基准数据验证 NPU 推理性能服务起来后用固定长度 prompt 压一遍 prefill 与 decode。以下为 Batchsize4、输出长度 1024 条件下的参考值tokens/sPrompt 长度1K2K4KPrefill174.68169.52167.15Decode16.0716.1216.48实测与参考值偏差超过 20% 时先查 NPU 侧算子是否真的走下去了npu-smi看利用率再查cache_lens是否被默认值截断。需要定位慢算子时用PROF_PREFILL与PROF_DECODE两个环境变量分别开启两阶段的 profiling 输出。故障速查现象处理报libhccl.so缺失见上文「配置 CANN 软件栈」当前 shell 先source /usr/local/Ascend/ascend-toolkit/set_env.sh报libascend_hal.so缺失补驱动库路径export LD_LIBRARY_PATH/usr/local/Ascend/driver/lib64/driver:$LD_LIBRARY_PATHaarch64 编译期iqk_mul_mat链接错误注释 third_party/llamafile/iqk_mul_mat_arm82.cpp 中两行宏定义见「初始化项目与编译扩展」节torch_npu 导入即报错检查version.py是否仍带git...哈希后缀服务启动 OOM物理内存不足 400GB满血版无法容纳路由专家权重下一步建议把--cache_lens按业务真实上下文长度调到位再用PROF_PREFILL抓一次 prefill 分布——prefill 吞吐从 170 tokens/s 量级再往上走瓶颈基本都在长序列的注意力段。【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 RELATED READING
延伸阅读
更多一线实战笔记与深度复盘，助您持续精进
