USAGE — DeepSeek-V4-Flash 单卡 Ascend NPU K920 CPU MoE【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer从一台干净 container开始到从开源仓库拉代码、设置 third_party、打补丁、编译、转权重、拉起服务、 连贯性验收的完整步骤。方案原理见 dsv4_flash_single_card_design.md。交付物边界patch 只含三仓的代码改动转权重 / 拉起 / 校验脚本是独立文件本目录scripts/ 不在 patch 内。0. 三仓 pristine 基线必须钉死这三个 SHA仓公开来源pristine SHApatch 目录ktransformers-AK父仓github.com/kvcache-ai/ktransformers0.6.2.post1d7b5b49main_repo/sglanggithub.com/iforgetmyname/sglangdsv4_releaseAscend DSv4 基线298193eb3sglang/llama.cppgithub.com/ggerganov/llama.cpptagb3173a94e6ffllama_cpp/⚠️ sglang 这部分目前不是正式版本以 patch 形式打在 DSv4 公开基线上待 sglang 主干正式支持该路径后会改为基于主干。third_party/pybind11、third_party/custom_flashinfer用父仓自带的上游子模块无额外 patch。1. 准备镜像、权重、容器、系统依赖路径约定除「本工程内」用相对路径$REPO外权重/缓存目录都用环境变量按你的环境配置即可。 下文用到三个$W8A8_DIRNPU 侧权重、$MXFP4_SRCCPU 转换源权重、$GGUF_CACHEMXFP4 GGUF 输出需 ≥150 GiB 可写空间。1.1 拉镜像docker pull lmsysorg/sglang:deepseek-v4-npu-910b # Atlas 910B docker pull lmsysorg/sglang:deepseek-v4-npu-a3 # A31.2 下载两份权重缺一不可NPU 侧 W8A8int8 : https://modelscope.cn/models/sgl-npu/DeepSeek-V4-Flash-W8A8 CPU 转换源 原生 MXFP4 : https://huggingface.co/deepseek-ai/DeepSeek-V4-Flash下到宿主机同一权重根目录下一步会整体挂进容器的/workspace/models。1.3 起容器参考脚本scripts/launch_dsv4_singleCard_cann8.5.0_910b.shWORKSPACE宿主机代码目录 MODEL_DIR宿主机权重根目录 \ bash scripts/launch_dsv4_singleCard_cann8.5.0_910b.sh # 自动挂 NPU 驱动/设备 代码(/workspace/code) 权重(/workspace/models) 映射服务端口。 # 可配置IMAGE / NAME / SERVICE_PORT(默认 8020) / SHM_SIZE / NPU_VISIBLE_DEVICES(auto 或 0,3)。1.4 容器内系统依赖apt-get update apt-get install -y git build-essential cmake libhwloc-dev libhwloc15 # libhwloc 是 kt-kernel 的硬依赖运行期 import cmake 编译都需容器重启后通常要重装。 # 下文命令直接用 python容器内通常即 python3.11本方案验证版本torch/torch_npu/CANN 由镜像提供。1.5 设置路径变量按你挂载后的实际位置export W8A8_DIR/workspace/models/DeepSeek-V4-Flash-W8A8 # 1.2 下载的 W8A8 目录容器内路径 export MXFP4_SRC/workspace/models/DeepSeek-V4-Flash # 1.2 下载的原生 MXFP4 目录 export GGUF_CACHE/workspace/models/cache # MXFP4 GGUF 输出目录任意可写、≥150 GiB2. 从开源仓库拉代码 设置 third_party 指针关键pristined7b5b49的.gitmodules把 sglang 指向kvcache-ai/sglangmain、llama.cpp 指向ggerganov/llama.cpp和本方案需要的 DSv4 基线不一致。所以 sglang / llama.cpp 这两个third_party子目录不能直接git submodule update要手动 clone 到指定 repoSHA即“改 third_party 指针”。下面统一用checkout -b 本地分支 SHA建一个本地分支再切过去而不是checkout SHA—— 后者会进入 detached HEAD无头状态apply patch 后想 commit/出新 patch 都不方便。分支名随意。# (1) 父仓clone 后建分支钉到 pristine 基线 git clone https://github.com/kvcache-ai/ktransformers.git ktransformers-AK cd ktransformers-AK git checkout -b dsv4-npu-release d7b5b49 # 建本地分支避免 detached HEAD REPO$(pwd) # 记下父仓根目录后文都用 $REPO # (2) 上游子模块按原样用无 patch git submodule update --init third_party/pybind11 third_party/custom_flashinfer # (3) sglang把 third_party/sglang 换成 DSv4 公开基线 298193eb3 rm -rf third_party/sglang git clone https://github.com/iforgetmyname/sglang.git third_party/sglang git -C third_party/sglang checkout -b dsv4-release-base 298193eb3 # (4) llama.cpp把 third_party/llama.cpp 换成 tag b3173 (a94e6ff)头文件在根目录 rm -rf third_party/llama.cpp git clone https://github.com/ggerganov/llama.cpp.git third_party/llama.cpp git -C third_party/llama.cpp checkout -b b3173-base a94e6ff这样third_party/sglang、third_party/llama.cpp是独立 git 仓库不再跟 pristine 的子模块指针走 各自在自己的本地分支上。父仓会把它们显示为 “modified submodule”不要紧——我们走 patch 本地构建 不提交父仓。建分支后apply 完 patch 可以直接git commit固化也方便后续再出 patch见 §10。 校验三仓 SHAgit -C $REPO rev-parse --short HEAD # d7b5b49 git -C $REPO/third_party/sglang rev-parse --short HEAD # 298193eb3 git -C $REPO/third_party/llama.cpp rev-parse --short HEAD # a94e6ff3. 打补丁仅代码补丁清单只动三仓源码main_repo/ (apply 到 ktransformers-AK d7b5b49) —— 只动 kt-kernel 引擎代码 0001-kt-kernel-ascend-npu-backend.patch NPU 后端 ACL callback worker 构建系统 0002-kt-kernel-cpu-moe-mxfp4-kernel.patch CPU MoE 原生 MXFP4 GEMV kernel GGUF loader sglang/ (apply 到 sglang 298193eb3) 0001-sglang-npu-kv-triton-fallback.patch triton×ascend KV/MoE 自动回退 torch 等价 0002-sglang-kt-ep-cpu-moe-offload.patch KT EP wrapperCPU MoE offload 热专家 mask 0003-sglang-packaging.patch Ascend/NPU 打包配置 llama_cpp/ (apply 到 llama.cpp a94e6ff) 0001-fix-gguf-NumPy-2-GGUFReader.patch gguf-py NumPy 2.0 兼容 0002-add-ggml-type-mxfp4.patch 注册 GGML_TYPE_MXFP439 NEON kernelCPU MXFP4 硬依赖一键release_dir 本交付目录的绝对路径bash release_dir/apply_all.sh $REPOapply_all.sh逐仓git apply --check后再apply任一--check失败即中止多半是 SHA 没钉对。手工等价cd $REPO for p in release_dir/main_repo/*.patch; do git apply $p; done cd $REPO/third_party/sglang for p in release_dir/sglang/*.patch; do git apply $p; done cd $REPO/third_party/llama.cpp for p in release_dir/llama_cpp/*.patch; do git apply -p1 $p; done把独立脚本放回父仓tools/这些不在 patch 内单独分发cp -r release_dir/scripts/tools/* $REPO/tools/4. 编译 kt-kernel带 Ascend NPU 后端下文命令里的python 目标 Python本方案验证于python3.11容器内python通常已是它 否则把命令里的python换成你的python3.11。cd $REPO/kt-kernel CPUINFER_USE_ASCEND_NPU1 python setup.py build_ext --inplace配置期日志应出现LLAMA_ARM_DOTPRODON且SVEOFF / BF16OFF / I8MMOFF红线 R1。Found Ascend CL library … libascendcl.so NPU 后端就绪。ggmlGGML_TYPE_MXFP4 not handled in switch警告良性非 MoE 路径 op 不需要 mxfp4 分支。体检find $REPO/kt-kernel -name kt_kernel_ext*.so python -c import ctypes,glob; ctypes.CDLL(glob.glob($REPO/kt-kernel/python/kt_kernel_ext*.so)[0]); print(dlopen OK)4b. 让import kt_kernel可用关键别漏build_ext --inplace只产出.so不注册包名。setup.py 把包名kt_kernel映射到python/目录 所以直接把kt-kernel加进 PYTHONPATH 只能import python不能import kt_kernel。两种方式二选一# 方式 A推荐无 site-packages 污染建符号链接 kt_kernel - pythonPYTHONPATH 指 kt-kernel 父目录 ln -sfn python $REPO/kt-kernel/kt_kernel export PYTHONPATH$REPO/third_party/sglang/python:$REPO/kt-kernel${PYTHONPATH::$PYTHONPATH} # 项目自带 helper 就是干这个的source tools/ensure_kt_kernel.sh ensure_kt_kernel $REPO # 方式 Beditable 安装写 site-packages之后任意 cwd 可 import cd $REPO/kt-kernel python -m pip install -e .验证python -c import kt_kernel; print(import kt_kernel OK)拉服务脚本launch_ds4flash_npu.sh内部已 source 上述 helper§7 不会遇到此错 但所有单独跑的脚本§6 离线对账、§5 转换若以import kt_kernel的方式调用等都要先做 4b。5. 原生 MXFP4 → 43 层 GGUF现行主路径mkdir -p $GGUF_CACHE nohup python tools/batch_convert_mxfp4_layers_mp.py \ --input $MXFP4_SRC --output-dir $GGUF_CACHE \ --layer-start 0 --layer-end 42 --jobs 16 --verify-sample 3 \ /tmp/kt_mxfp4_convert.log 21 # 产出 dsv4_layer{0..42}_mxfp4.gguf每层 ~3.42 GiB合计 ~138 GiB收尾全集校验尺寸 sha256 抽样逐元素 bit-exactpython tools/verify_mxfp4_gguf_set.py --dir $GGUF_CACHE --sha256-manifest tools/mxfp4_gguf_sha256.txt⚠️ 并发转换曾把某层写截断收尾务必跑全集校验。 单层快验convert_mxfp4_layer_to_gguf.py --input $MXFP4_SRC --layer-idx 16 --output /tmp/l16.gguf→verify_mxfp4_layer.py --gguf /tmp/l16.gguf --layer-idx 16bit-exact。转完并通过校验后原生 MXFP4 源$MXFP4_SRC可删回收磁盘拉服务§7只用$GGUF_CACHECPU 专家$W8A8_DIRNPU 侧不再碰 MXFP4 源。注意删前先过校验——单层 bit-exact、§5 全集校验的--deep/L3 深抽、§6 cosine 对账都要读源全集sha256 尺寸校验是自包含的只需 GGUF mxfp4_gguf_sha256.txt删源后仍可复验 GGUF 完整性别删$W8A8_DIRNPU 侧一直要用它和 MXFP4 源是两份不同权重。6.推荐拉服务前离线对账 kernelcosine ≥ 0.9999# 先确保 import kt_kernel 可用见 §4bhelper 会建符号链接并设好 PYTHONPATH source tools/ensure_kt_kernel.sh ensure_kt_kernel $REPO python tools/cpu_moe_reference_check_mxfp4.py --model-dir $MXFP4_SRC \ --gguf $GGUF_CACHE/dsv4_layer16_mxfp4.gguf --layer-idx 16 # 脚本内置 KT_FORCE_SYNC_SUBMIT1孤立单层调用须同步提交否则 cand 全零 # 若没用 helper先 ln -sfn python $REPO/kt-kernel/kt_kernel再带 # PYTHONPATH$REPO/third_party/sglang/python:$REPO/kt-kernel 运行7. 拉起服务MXFP4graph-on可选拉起前预检 GGUF 层文件与kt_kernel是否就位GGUF_DIR$GGUF_CACHE GGUF_SUFFIX_mxfp4 bash tools/e2e_preflight.sh # 退出码 0通过先npu-smi info选空闲卡避开别容器/别 session。长跑服务在自己终端前台拉远程/后台拉的父进程上下文会被回收 →main process disappeared。cd $REPO NPU_DEVICE_ID空闲卡 PORT8020 \ KT_GGUF_TEMPLATE$GGUF_CACHE/dsv4_layer{layer_idx}_mxfp4.gguf \ KT_CPUINFER128 MODEL_PATH$W8A8_DIR KT_DECODE_TIMING1 \ bash tools/launch_ds4flash_npu.sh 21 | tee /tmp/kt_serve.logKT_GGUF_TEMPLATE必填脚本无内置默认不设会报错退出指向你的 GGUF 目录 _mxfp4模板 如上{layer_idx}是脚本的层号占位符不是 shell 变量保持字面量$GGUF_CACHE会正常展开。MODEL_PATH指W8A8NPU 侧与 GGUFCPU 侧缺一不可。graph-on 是默认勿传--disable-cuda-graphKT_CPUINFER默认 128甜点勿设 192。环境变量仅计时类env作用KT_DECODE_TIMING1每 token 打印 CPU MoE submit→sync wallcpu_moe_wallKT_MOE_PHASE_TIMING1kernel 相位细分gateup / down / merge / quant µsKT_FORCE_SYNC_SUBMIT1eager 兜底配EXTRA_FLAGS--disable-cuda-graph 离线对账依赖CPU MoE 行内预取 优化 GEMV 恒生效triton×ascend 错配自动回退 torch 等价——均无需任何开关。8. 验收加载约 2–3.5 min 热 cacheuntil curl -sf http://127.0.0.1:8020/health /dev/null; do sleep 5; done # 就绪 PORT8020 bash tools/curl_f2_prompts.sh # 四-prompt 连贯性验收核心验收 curl -sS -X POST http://127.0.0.1:8020/generate -H Content-Type: application/json \ -d {text:中国的首都是,sampling_params:{max_new_tokens:64,temperature:0}} # 期望北京…性能观测grep KT_DECODE_TIMING /tmp/kt_serve.log # cpu_moe_wallMXFP4 生产 min ~17ms / median ~22–27ms grep gen throughput /tmp/kt_serve.log # decode tok/s预期吞吐单发、短上下文、graph-on、kt-cpuinfer 128清净独占NPU 空卡 CPU 无邻居争抢~16 tok/s中等争抢共享机有邻居吃 DRAM 带宽~13–14 tok/s低于此区间多半是邻居抢带宽 / NPU 卡被占 /KT_CPUINFER设错 / 并发多发 / 上下文太长。 原理带宽 vs 算力 roofline、与理想的 ~2.5–3.5× gap、各下降因素见 dsv4_flash_single_card_design.md「当前状态」一节。⚠️--max-running-requests 1别并发多发并发撞争抢窗口会触发 NPU runtime 失稳崩。 收服务跑服务的终端Ctrl-CSIGTERM 优雅释放 HBM绝不pkill -f sglang.launch_server。9. 常见坑速查现象根因修复git submodule update后 sglang/llama.cpp 不是预期版本pristine.gitmodules指向别的 repo/branch按 §2 手动 clone 到 repoSHACMake 找不到 hwloc系统未装apt-get install -y libhwloc-dev libhwloc15每容器No module named kt_kernel单独跑脚本时只build_ext没注册包名见 §4b建kt_kernel-python符号链接 或pip install -e .import kt_kernel失败 /not installed已建链接后libhwloc.so.15缺失 或.so没编出来装 libhwloc§1确认kt-kernel/python/kt_kernel_ext*.so存在启动崩 quant 类型不匹配sglang 没钉对298193eb3重新 checkout 基线 SHA输出乱码 MXFP4 对账偏nibble 序未重排用本仓转换器逐 32-group 重排verify_mxfp4_layer.py把关--chunked-prefill-size -1→ malloc 越界max_len-1按 1 分配llamafile.py已对 ≤0 回落 2048跑一会儿main process disappeared远程/后台拉服务被回收在自己终端前台拉eager 出 token 但乱码CPU MoE async submit 未 flusheager 下加KT_FORCE_SYNC_SUBMIT110. 在此基础上再出 patch你改完代码后如何重新生成本交付里的gen_main_repo_patches.sh/gen_sglang_patches.sh就是 patch 的生成器它们对 pristine 基线 做git diff——所以你 apply 完 patch、再继续改代码后重跑同一个生成器就能产出更新后的全量 patch覆盖我们的版本包含「我们的改动 你的改动」相对 pristine 的完整 diff。前提是 §2 建分支的方式让 pristine 基线 SHA 仍在历史里可达。底层就是一行git diff按需直接用# 父仓 kt-kernel 全量相对 pristine d7b5b49——含工作区未提交改动 git -C $REPO diff d7b5b49 -- kt-kernel/operators/llamafile/moe.hpp \ kt-kernel/python/experts_base.py kt-kernel/python/utils/llamafile.py \ kt-kernel/python/utils/loader.py /tmp/my_kt_kernel.patch # sglang 全量相对 pristine 298193eb3 git -C $REPO/third_party/sglang diff 298193eb3 -- python/sglang/... /tmp/my_sglang.patch全量 vs pristine推荐交付用git diff pristine_SHA -- paths和我们出 patch 完全同法。只要你相对“已 apply 我们 patch 那一刻”的增量apply 完先git add -A git commit或打 tag固化成基线B 之后git diff B -- paths即只含你后续的改动。生成器脚本里的OUT/BASE/pathspec 可按你的目录与改动范围改它不是黑盒就是git diff的封装。【免费下载链接】cann-recipes-infer本项目针对LLM与多模态模型推理业务中的典型模型、加速算法提供基于CANN平台的优化样例项目地址: https://gitcode.com/cann/cann-recipes-infer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考