KTransformers KT-Kernel 深度指南从 CPU 内核选型、构建配置到 SGLang 异构推理实战【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformersKT-Kernel 是 KTransformers 的高性能 CPU 内核包为 MoEMixture-of-Experts模型提供面向 AMX、AVX512、AVX2、KML 与 AMD BLIS 指令集优化的专家计算后端。本文以仓库中kt-kernel模块的官方 README 为主线系统讲解安装PyPI 与源码构建、CPU 变体自动检测原理、与 SGLang 的 CPU-GPU 异构推理集成含 Qwen3-30B-A3B 完整示例、ktCLI 工具、Python API 用法、构建配置与环境排错并结合仓库源码印证关键调用链帮助你把大 MoE 模型的冷专家高效下放到 CPU同时让热专家留在 GPU 上。支持状态与核心特性当前 KT-Kernel 的支持情况见 kt-kernel/README.md✅AVX512 原生精度FP8、BF16、RAWINT4格式适用于 AVX512 CPU配套教程见 Native-Precision-Tutorial✅Intel AMX CPU完整支持使用转换为 INT4/INT8 格式的权重✅通用 CPUllamafile 后端使用 GGUF 格式权重✅AMD CPUBLIS 后端支持 int8 prefill 与 decode指南见 amd_blis核心特性包括CPU 优化的 MoE 内核面向不同指令集优化的高吞吐 MoE 专家算子AVX512 原生精度后端面向 AVX512 服务器的 FP8 / BF16 / INT4 原生 MoE 后端AMX INT4/INT8 后端面向 AMX 服务器的 INT4 / INT8 量化专家推理后端Llamafile CPU 后端基于 Llamafile 的 AVX2/AVX512 MoE 后端用于通用 CPU 部署NUMA 感知执行线程池与内存布局面向多插槽 / 多 NUMA 机器设计。从源码结构看上述后端由 python/experts.py 中的工厂函数统一分发AMXINT4/AMXINT8路由到AMXMoEWrapperRAWINT4/FP8/BF16/FP8_PERCHANNEL/GPTQ_INT4/MXFP4/MXFP8等路由到NativeMoEWrapperLLAMAFILE路由到LlamafileMoEWrapperMOE_INT4/MOE_INT8路由到通用内核GeneralMoEWrapper分发逻辑。安装方式一从 PyPI 安装推荐大多数用户一条命令安装最新版本pip install kt-kernel该方式的特点✅自动 CPU 检测检测你的 CPU 并加载最优内核变体✅CPU 多变体支持包含 AMX、AVX512Base/VNNI/VBMI/BF16、AVX2 变体✅内置 CUDA 支持NVIDIA GPU 加速SM 80、86、89、90✅无需编译提供 Python 3.10 / 3.11 / 3.12 的预构建 wheel✅静态 CUDA 运行时无需安装 CUDA toolkit✅纯 CPU 系统可用无 GPU 时 CUDA 特性自动禁用要求Python 3.10/3.11/3.12Linux x86-64manylinux_2_17 兼容支持 AVX2 的 CPUIntel Haswell 2013 / AMD Zen可选计算能力 8.0 的 NVIDIA GPU。CUDAGPU 加速说明GPU 加速无需额外步骤同一个 wheel 即支持。特性包括✅多架构支持单个 wheel 支持 SM 80/86/89/90Ampere、Ada、Hopper✅静态 CUDA 运行时无需 CUDA toolkit✅兼容性广兼容 CUDA 11.8 与 12.x 驱动✅PyTorch 兼容适配任意 PyTorch CUDA 变体cu118、cu121、cu124GPU 兼容性矩阵GPU 架构计算能力支持情况示例 GPUHopper9.0✅H100, H200Ada Lovelace8.9✅RTX 4090, 4080, 4070Ampere8.6✅RTX 3090, 3080, 3070, 3060Ampere8.0✅A100, A30Turing7.5❌RTX 2080, T4Volta7.0❌V100CUDA 驱动兼容性GPU 特性CUDA 11.8、11.9、12.0–12.6 完整支持CUDA 11.0–11.7 不支持需升级驱动或改用纯 CPU 模式。CPU 变体说明wheel 内置 6 种优化变体运行时根据你的 CPU 自动选择变体CPU 支持性能自动选择条件AMXIntel Sapphire Rapids2023最佳检测到 AMX 指令AVX512BF16Ice Lake server、Zen 42021优秀AVX512 BF16AVX512VBMIIce Lake client2019良好AVX512 VBMIAVX512VNNICascade Lake2019良好AVX512 VNNIAVX512 BaseSkylake-X2017较好AVX512 baseAVX2Haswell2013、AMD Zen可用最大兼容性回退这一渐进式匹配机制在 python/_cpu_detect.py 中实现detect_cpu_features()按 AMX → avx512_bf16 → avx512_vbmi → avx512_vnni → avx512_base → avx2 的优先级逐级匹配/proc/cpuinfo中的 CPU flags且加载前会校验加载的变体不能高于检测到的能力校验逻辑否则提示安装多变体 wheel 或本机重编。验证安装import kt_kernel # 查看加载的 CPU 变体 print(fCPU variant: {kt_kernel.__cpu_variant__}) print(fVersion: {kt_kernel.__version__}) # 检查 CUDA 支持 from kt_kernel import kt_kernel_ext cpu_infer kt_kernel_ext.CPUInfer(4) has_cuda hasattr(cpu_infer, submit_with_cuda_stream) print(fCUDA support: {has_cuda}) print(✓ kt-kernel installed successfully!)环境变量# 覆盖自动 CPU 检测用于测试或调试 export KT_KERNEL_CPU_VARIANTavx2 # 强制指定变体 # 打开调试输出查看检测过程 export KT_KERNEL_DEBUG1 python -c import kt_kernel其中KT_KERNEL_CPU_VARIANT可取值amx、avx512_bf16、avx512_vbmi、avx512_vnni、avx512_base、avx2见 _cpu_detect.py。方式二从源码安装本地使用或自定义构建当你需要 AMDBLIS、ARMKML或自定义 CUDA 版本时从源码构建。前置准备初始化 git 子模块并创建 conda 环境git submodule update --init --recursive conda create -n kt-kernel python3.11 -y conda activate kt-kernel快速安装推荐直接运行安装脚本它会自动检测 CPU 并优化./install.sh自动完成的工作自动检测 CPU 能力AMX、AVX512_VNNI、AVX512_BF16安装系统依赖cmake、libhwloc-dev、pkg-config只针对你的 CPU构建优化二进制使用-marchnative软件回退对没有 VNNI/BF16 的 CPU 自动启用回退路径从 install.sh 源码可以看到自动检测函数detect_cpu_features()会解析/proc/cpuinfo的 flags 行判断amx_tile/amx_int8/amx_bf16、avx512f、avx512_vnni、avx512_bf16、avx512_vbmi五类能力检测实现随后据此导出CPUINFER_CPU_INSTRUCTNATIVE、CPUINFER_ENABLE_AMX、CPUINFER_ENABLE_AVX512_VNNI/BF16/VBMI等变量进入 CMake 构建脚本还内置了 aarch64 路径检测 DOTPROD/FP16/SVE/BF16/I8MM以及 Ascend CANN 工具链的自动发现CPUINFER_USE_ASCEND_NPU。可选的两步安装./install.sh deps # 只安装依赖 ./install.sh build # 构建并安装 kt-kernel各后端的最低 CPU 要求后端最低 CPU 要求示例 CPU备注LLAMAFILEAVX2Intel Haswell2013、AMD Zen通用兼容RAWINT4AVX512F AVX512BWIntel Skylake-X2017、Ice Lake、Cascade LakeVNNI/BF16 有软件回退AMXINT4/INT8AMXIntel Sapphire Rapids2023性能最佳需要 AMX 硬件FP8AVX512F AVX512BW AVX512_BF16 AVX512_VBMIIntel Cooper Lake2020、Sapphire Rapids2023AMD Zen 4如 EPYC 9355原生精度如 DeepSeek V3.2、MiniMax M2.1BF16AVX512F AVX512BW AVX512_BF16同上原生精度如 Qwen3-235B-A22B、GLM-4.7AVX512 后端的软件回退VNNI 不可用时回退到 AVX512BW 指令BF16 不可用时回退到 AVX512F 指令。因此仅有 AVX512FBW 的旧 CPUSkylake-X、Cascade Lake也能运行 RAWINT4只是更慢。⚠️可移植性注意默认构建针对你的 CPU 优化可能无法在其他/更旧的 CPU 上运行。可移植构建或二进制分发请参考下文手动配置高级章节。⚠️AMD BLIS 后端用户AMD 专用设置请参考仓库文档 amd_blis。安装验证安装完成后验证 CLI 是否可用kt version期望输出KTransformers CLI v0.x.x Python: 3.11.x Platform: Linux 5.15.0-xxx-generic CUDA: 12.x kt-kernel: 0.x.x (amx) sglang: 0.x.x也可以直接验证 Python 模块python -c from kt_kernel import KTMoEWrapper; print(✓ kt-kernel installed successfully)kt命令的入口在 pyproject.toml 中定义为kt kt_kernel.cli.main:main对应实现为基于 Typer 的 cli/main.py首次运行时还会引导完成语言偏好等初始化设置。KT CLI 概览kt命令行工具为运行和管理 KTransformers 模型提供统一入口命令说明kt run model启动模型推理服务器自动优化参数kt chat与运行中的模型服务器交互聊天kt model管理模型与存储路径kt doctor诊断环境问题并检查系统兼容性kt config管理 CLI 配置kt version显示版本信息快速上手# 启动模型服务器自动检测硬件并应用最优配置 kt run m2 # 在另一个终端与模型聊天 kt chat # 检查系统兼容性 kt doctor更多选项执行kt --help或kt command --help查看命令级帮助。与 SGLang 集成KT-Kernel 既可以通过下文 Python API 独立使用也可以与 SGLang 集成做生产部署。集成后可以实现 CPU-GPU 异构推理热专家跑在 GPU 上冷专家跑在 CPU 上实现资源的最优利用。安装步骤1. 安装 SGLang安装 kvcache-ai 的 SGLang forkkt-kernel 支持所必需# 选项 A一键安装在 ktransformers 根目录安装 sglang kt-kernel ./install.sh # 选项 Bpip 安装 pip install kt-kernel sglang-kt # 选项 C源码可编辑模式 git clone --recursive https://github.com/kvcache-ai/ktransformers.git cd ktransformers pip install -e third_party/sglang/python[all]重要请使用sglang-ktkvcache-ai fork而非官方sglang包。若已安装官方版本先卸载pip uninstall sglang -y2. 准备权重异构推理同时需要 GPU 权重与 CPU 端专家权重具体格式取决于后端GPU 权重所有后端通用使用 SGLang GPU 推理所需的模型权重例如 Hugging Face 上的原始或已量化模型目录。CPU 权重AMX 后端AMXINT4/AMXINT8使用仓库提供的脚本量化为 AMX 优化的 INT4/INT8 格式python scripts/convert_cpu_weights.py \ --input-path /path/to/model \ --input-type bf16 \ --output /path/to/cpu-weights \ --quant-method int8 # 或 int4 或 moe_int8amd 后端--input-pathGPU 端原始权重路径--input-type取决于 GPU 权重类型fp8、fp16或bf16在 SGLang 集成中--kt-weight-path应指向该转换后的 CPU 权重目录。支持的输入格式FP8、FP16、BF16 → INT4/INT8。CPU 权重LLAMAFILE 后端LLAMAFILE直接加载预量化的GGUF权重无需运行convert_cpu_weights.py从网上直接下载 GGUF 模型如 Hugging Face / ModelScope 上的 GGUF 仓库SGLang 集成中将该 GGUF 目录作为--kt-weight-path。KT-Kernel 支持Q4_KM、Q4_K、Q5_K等多种 GGUF 量化格式可根据延迟与精度需求选择。3. 启动 SGLang 服务器在常规 SGLang 参数之外追加以下 KT-Kernel 参数即可启用 CPU-GPU 异构推理--kt-methodCPU 推理后端AMXINT4、AMXINT8 或 LLAMAFILE 等--kt-weight-path转换后的 CPU 权重路径--kt-cpuinferCPU 推理线程数设为物理核心数--kt-threadpool-count线程池数量设为 NUMA 节点数--kt-num-gpu-experts保留在 GPU 上的专家数--kt-max-deferred-experts-per-token用于流水线执行的延迟专家数示例python -m sglang.launch_server \ [your normal SGLang parameters...] \ --kt-method AMXINT8 \ --kt-weight-path /path/to/cpu-weights \ --kt-cpuinfer 64 \ --kt-threadpool-count 2 \ --kt-num-gpu-experts 32 \ --kt-max-deferred-experts-per-token 2详细调参指南见下文 KT-Kernel 参数 小节。完整示例Qwen3-30B-A3B本示例演示从下载权重到启动服务器的完整流程展示Native 后端、AMX 后端与LLAMAFILE 后端三种方案。硬件配置GPUNVIDIA RTX 4090 24GBCPU2× Intel Xeon Gold 6454S共 64 物理核、128 线程、2 个 NUMA 节点模型Qwen/Qwen3-30B-A3B如何确认你的系统配置# 查看 CPU 配置 lscpu | grep -E ^CPU\(s\)|Thread\(s\) per core|Socket\(s\)|NUMA node\(s\) # 输出示例 CPU(s): 128 Thread(s) per core: 2 Socket(s): 2 NUMA node(s): 2 # → 物理核 CPU(s) / Thread(s) per core 128 / 2 64参数依据--kt-cpuinfer 64设为物理核数64而非超线程数128--kt-threadpool-count 2检测到 2 个 NUMA 节点双路系统--kt-num-gpu-experts 3224GB 显存下该模型约可容纳 32 个专家随模型架构与实际显存占用而异--kt-max-deferred-experts-per-token 2启用流水线执行允许 GPU 完成当前批次时 CPU 处理下一批--kt-gpu-prefill-token-threshold 2048token 数超过 2048 时使用 layerwise prefill 策略仅原生后端选项 ANative 后端BF16适用于支持 BF16 的 AVX512 CPU。第 1 步下载模型权重# 未安装 huggingface-cli 时先安装 pip install huggingface-hub # 从 Hugging Face 下载模型 huggingface-cli download Qwen/Qwen3-30B-A3B --local-dir /mnt/data/models/Qwen3-30B-A3B第 2 步启动 SGLang 服务器python -m sglang.launch_server \ --host 0.0.0.0 \ --port 30000 \ --model /mnt/data/models/Qwen3-30B-A3B \ --kt-weight-path /mnt/data/models/Qwen3-30B-A3B \ --kt-cpuinfer 64 \ --kt-threadpool-count 2 \ --kt-num-gpu-experts 32 \ --kt-method BF16 \ --attention-backend flashinfer \ --trust-remote-code \ --mem-fraction-static 0.80 \ --chunked-prefill-size 16384 \ --max-running-requests 4 \ --served-model-name Qwen3 \ --enable-mixed-chunk \ --tensor-parallel-size 1 \ --enable-p2p-check \ --disable-shared-experts-fusion \ --kt-gpu-prefill-token-threshold 4096 \ --kt-enable-dynamic-expert-update选项 BAMX 后端AMXINT8适用于支持 AMX 指令集的 Intel CPU。第 1 步下载模型权重pip install huggingface-hub huggingface-cli download Qwen/Qwen3-30B-A3B --local-dir /mnt/data/models/Qwen3-30B-A3B第 2 步转换为 CPU 权重AMXINT8python scripts/convert_cpu_weights.py \ --input-path /mnt/data/models/Qwen3-30B-A3B \ --input-type bf16 \ --output /mnt/data/models/Qwen3-30B-A3B-INT8 \ --quant-method int8第 3 步启动 SGLang 服务器python -m sglang.launch_server \ --host 0.0.0.0 \ --port 8000 \ --model /mnt/data/models/Qwen3-30B-A3B \ --trust-remote-code \ --mem-fraction-static 0.92 \ --chunked-prefill-size 4096 \ --served-model-name Qwen3-30B-A3B \ --enable-mixed-chunk \ --kt-method AMXINT8 \ --kt-weight-path /mnt/data/models/Qwen3-30B-A3B-INT8 \ --kt-cpuinfer 64 \ --kt-threadpool-count 2 \ --kt-num-gpu-experts 32 \ --kt-max-deferred-experts-per-token 2选项 CLLAMAFILE 后端GGUF适用于无 AMX 的通用 CPU直接使用预量化 GGUF 权重。第 1 步下载 GPU 权重原始模型pip install huggingface-hub huggingface-cli download Qwen/Qwen3-30B-A3B --local-dir /mnt/data/models/Qwen3-30B-A3B第 2 步下载 CPU 权重GGUF 格式huggingface-cli download Qwen/Qwen3-30B-A3B-GGUF Qwen3-30B-A3B-Q4_K_M.gguf \ --local-dir /mnt/data/models/Qwen3-30B-A3B-Q4_K_M第 3 步启动 SGLang 服务器python -m sglang.launch_server \ --host 0.0.0.0 \ --port 8000 \ --model /mnt/data/models/Qwen3-30B-A3B \ --trust-remote-code \ --mem-fraction-static 0.92 \ --chunked-prefill-size 4096 \ --served-model-name Qwen3-30B-A3B \ --enable-mixed-chunk \ --kt-method LLAMAFILE \ --kt-weight-path /mnt/data/models/Qwen3-30B-A3B-Q4_K_M \ --kt-cpuinfer 64 \ --kt-threadpool-count 2 \ --kt-num-gpu-experts 32 \ --kt-max-deferred-experts-per-token 2KT-Kernel 参数参数说明示例值--kt-methodCPU 推理后端方法AMXINT4、AMXINT8、RAWINT4、FP8、FP8_PERCHANNEL、BF16或LLAMAFILE--kt-weight-path量化 CPU 权重路径/path/to/cpu-weights--kt-cpuinferCPU 推理线程数64根据 CPU 核心数调整--kt-threadpool-count并行执行的线程池数2通常 1–4--kt-num-gpu-experts保留在 GPU 上的专家数32其余专家放到 CPU--kt-max-deferred-experts-per-token每 token 延迟执行的专家数流水线20 禁用推荐 1–4--kt-gpu-prefill-token-thresholdprefill 策略的 token 数阈值仅原生后端约1024-4096--kt-enable-dynamic-expert-update根据实际路由统计在 prefill 期间动态更新专家放置flag无需值--kt-expert-placement-strategy初始 GPU 专家放置策略uniform、frequency、front-loading或random参数调优指南kt-method根据 CPU 与权重格式选择AMXINT4AMX CPU 上 INT4 量化权重性能最佳注意部分模型可能大幅掉精度例如 Qwen3-30B-A3BAMXINT8AMX CPU 上 INT8 量化权重精度更高RAWINT4CPU 与 GPU 共享的原生 INT4 权重当前支持 Kimi-K2-Thinking 模型详见 Kimi-K2-Thinking Native 教程FP8、FP8_PERCHANNELCPU 与 GPU 共享的 FP8 权重BF16CPU 与 GPU 共享的 BF16 权重LLAMAFILEGGUF 后端kt-cpuinfer设为物理 CPU 核心数不是超线程数。查看物理核lscpu | grep -E ^CPU\(s\)|Thread\(s\) per core物理核 CPU(s) / Thread(s) per core。例如 CPU(s)128 且 Thread(s) per core2 时物理核为 64。切勿设为超线程数否则会劣化性能。kt-threadpool-count设为NUMA 节点数。查看方法lscpu | grep NUMA node(s)或numactl --hardware | grep available。注意 NUMA 节点数不一定等于物理 CPU 数——它表示内存域可能出现在单个 CPU 内部或多个 CPU 之间请以lscpu的 NUMA 节点数为准。典型值单路 1–2双路 2–4。可提升跨 NUMA 域的内存带宽利用率。kt-num-gpu-experts根据显存与 profiling 结果确定。GPU 专家越多延迟越低但显存占用越高可能 OOM。kt-max-deferred-experts-per-token启用流水线执行0同步执行简单、延迟较高1-4延迟执行推荐区间延迟/质量平衡好需要调参5-7延迟降低最明显但可能引入明显精度损失谨慎使用kt-gpu-prefill-token-thresholdFP8 与 RAWINT4 可用控制原生 FP8/INT4 推理的 prefill 策略≤ 阈值使用 CPUGPU 混合 prefill无需额外显存但性能随 token 数增长缓慢下降 阈值使用 layerwise GPU prefill长序列下扩展性更好但需要约一层 MoE 的额外显存例如 Kimi-K2-Thinking 约 9GBMiniMax-M2.1 约 3.6GB。仅在--kt-method RAWINT4或--kt-method FP8时生效。kt-enable-dynamic-expert-update推理期间动态更新专家放置。layerwise prefill 期间系统收集实际路由统计并据此重新分配 GPU 专家。需要设置--kt-gpu-prefill-token-threshold且 prefill 长度 ≥ 阈值。在 GPU 专家占比较低10%–70%时特别有效可显著优于静态策略。详见 Expert Scheduling 教程。kt-expert-placement-strategy决定服务器启动时哪些专家放到 GPUuniform在所有 MoE 层间均匀分布 GPU 专家。默认选项无需先验统计frequency将激活最频繁的专家放到 GPU。有激活统计时性能最佳需要--init-expert-location指向.pt统计文件front-loading从第一个 MoE 层开始填充 GPU 专家random固定种子42随机选择专家。策略对比详见 Expert Scheduling 教程。从源码结构看frequency 策略背后的放置逻辑对应 experts_base.py 中的generate_gpu_experts_masks()它接收形状为(num_layers, num_experts)的激活频率表选出激活频率最高的num_gpu_experts个专家生成布尔 mask实现。直接 Python API 使用不依赖 SGLang 时可通过 Python API 直接使用 KT-Kernelfrom kt_kernel import KTMoEWrapper # 初始化 MoE wrapper wrapper KTMoEWrapper( layer_idx0, num_experts8, num_experts_per_tok2, hidden_size4096, moe_intermediate_size14336, num_gpu_experts2, cpuinfer_threads32, threadpool_count2, weight_path/path/to/weights, chunked_prefill_size512, methodAMXINT4 # 可选: AMXINT4, AMXINT8, LLAMAFILE 等 ) # 从磁盘加载权重预量化 wrapper.load_weights(physical_to_logical_map) # 或从张量加载权重在线量化 wrapper.load_weights_from_tensors(gate_proj, up_proj, down_proj, physical_to_logical_map) # 同步推理 output wrapper.forward(hidden_states, topk_ids, topk_weights, cuda_stream) # 或使用异步 API 获得更好性能 wrapper.submit_forward(hidden_states, topk_ids, topk_weights, cuda_stream) # ... 期间可做其他工作 ... output wrapper.sync_forward(hidden_states, cuda_stream)高级选项# 附加选项初始化 wrapper KTMoEWrapper( layer_idx0, num_experts8, num_experts_per_tok2, hidden_size4096, moe_intermediate_size14336, num_gpu_experts2, cpuinfer_threads32, threadpool_count2, weight_path/path/to/weights, chunked_prefill_size512, methodAMXINT4, cpu_saveFalse, # 加载后保留权重在 CPU 内存 max_deferred_experts_per_token0 # 延迟专家数流水线执行 ) # 为特定 batch size 预分配缓冲提升性能 KTMoEWrapper.set_capture_batch_sizes([1, 2, 4, 8, 16]) # 查询已捕获的 batch sizes batch_sizes KTMoEWrapper.get_capture_batch_sizes() # 清空缓冲缓存以释放内存 KTMoEWrapper.clear_buffer_cache()在 python/experts.py 中KTMoEWrapper实际上是工厂类__new__根据modeinference/sft与method参数校验后构造具体后端实例工厂入口。推理模式下合法方法集合为AMXINT4、AMXINT8、RAWINT4、FP8、BF16、FP8_PERCHANNEL、GPTQ_INT4、SYCL_GPTQ_INT4、MXFP4、NVFP4、MXFP8、LLAMAFILE、MOE_INT4、MOE_INT8此外还支持gpu_experts_mask布尔掩码mask[i]True表示专家 i 在 GPU 上来显式控制专家放置。set_capture_batch_sizes等静态方法则转发到底层BaseMoEWrapper的缓冲缓存管理静态方法。构建配置手动配置高级可移植构建、二进制分发或跨机器部署时需要手动指定目标指令集# 通用分发任何 2017 的 AVX512 CPU 均可运行 export CPUINFER_CPU_INSTRUCTAVX512 export CPUINFER_ENABLE_AMXOFF ./install.sh build --manual # 最大兼容任何 2013 的 CPU export CPUINFER_CPU_INSTRUCTAVX2 export CPUINFER_ENABLE_AMXOFF ./install.sh build --manual # 仅现代 CPUIce Lake、Zen 4 export CPUINFER_CPU_INSTRUCTFANCY export CPUINFER_ENABLE_AMXOFF ./install.sh build --manual可选覆盖 VNNI/BF16 检测# 强制启用/禁用 VNNI 和 BF16用于测试回退路径 export CPUINFER_ENABLE_AVX512_VNNIOFF export CPUINFER_ENABLE_AVX512_BF16OFF ./install.sh可选非 AMX AVX512 CPU 上的 oneDNN INT8 BRGEMM# 需要已安装的 oneDNN 3.9 包 export CPUINFER_ENABLE_ONEDNN_VNNION # 或针对 oneDNN 源码树构建 export CPUINFER_ONEDNN_SOURCE_DIR/path/to/oneDNN ./install.sh # 编译出的 wheel 默认使用 oneDNNnative 路径保留用于 A/B 对比 export KT_INT8_VNNI_BACKENDauto # auto | onednn | native完整选项见./install.sh --help。不依赖 install.sh 的手动安装1. 安装系统依赖cmake推荐conda install -y cmakelibhwloc-dev与pkg-config2. 设置构建配置核心变量变量可选值说明CPUINFER_CPU_INSTRUCTNATIVE、AVX512、AVX2、FANCY使用的 CPU 指令集CPUINFER_ENABLE_AMXON、OFF启用 Intel AMX 支持CPUINFER_ENABLE_ONEDNN_VNNION、OFF非 AMX AVX512 CPU 上启用 oneDNN INT8 BRGEMMCPUINFER_ONEDNN_SOURCE_DIR路径可选的 oneDNN 3.9 源码树CPUINFER_BUILD_TYPERelease、Debug、RelWithDebInfo构建类型默认ReleaseCPUINFER_PARALLEL数字并行构建任务数默认自动检测CPUINFER_VERBOSE0、1详细构建输出默认0指令集选项详情选项目标 CPU使用场景NATIVE仅你自己的 CPU本地构建性能最佳默认AVX512Skylake-X、Ice Lake、Cascade Lake、Zen 4通用分发AVX2Haswell2013及更新最大兼容性FANCYIce Lake、Zen 4带完整 AVX512 扩展的现代 CPU配置示例# 本地使用 - 最大性能默认行为 export CPUINFER_CPU_INSTRUCTNATIVE export CPUINFER_ENABLE_AMXON # 或 OFF # 分发布 - 任何 AVX512 CPU 可用 export CPUINFER_CPU_INSTRUCTAVX512 export CPUINFER_ENABLE_AMXOFF # 最大兼容 - 2013 年起的 CPU 可用 export CPUINFER_CPU_INSTRUCTAVX2 export CPUINFER_ENABLE_AMXOFF # 调试构建 export CPUINFER_BUILD_TYPEDebug export CPUINFER_VERBOSE13. 构建与安装# 可编辑安装开发用 pip install -e . # 标准安装 pip install .错误排查CUDA Not Found-- Looking for a CUDA compiler - NOTFOUND CMake Error at CMakeLists.txt:389 (message): KTRANSFORMERS_USE_CUDAON but CUDA compiler not found确认已安装 CUDA toolkit 且nvcc在系统 PATH 中。可尝试export CMAKE_ARGS-D CMAKE_CUDA_COMPILER$(which nvcc)后重新安装。hwloc Not FoundDebian 系系统执行sudo apt install libhwloc-dev或从源码构建 hwlocwget https://download.open-mpi.org/release/hwloc/v2.12/hwloc-2.12.2.tar.gz tar -xzf hwloc-2.12.2.tar.gz cd hwloc-2.12.2 ./configure make sudo make install权重量化AMX 后端AMXINT4/AMXINT8要求 CPU 端专家先转换为 AMX 友好的 INT4/INT8 格式python scripts/convert_cpu_weights.py \ --input-path /path/to/model \ --input-type bf16 \ --output /path/to/output \ --quant-method int4支持格式FP8、FP16、BF16 → INT4/INT8。LLAMAFILE 后端则直接从GGUF权重加载 CPU 端专家无需运行 AMX 转换脚本下载 GGUF 模型如 Hugging Face 上的 GGUF 仓库并将weight_path/ SGLang--kt-weight-path或相应场景下的--model指向该 GGUF 目录。支持的 GGUF 量化类型包括Q4_KM、Q4_K、Q5_K等。更多高级选项与低内存模式详见 scripts/README.md。提交前须知Before Commit!Commit message 应遵循 Conventional Commits 规范。提交前请格式化代码cmake -B build cd build make format可能需要较新的 clang-format至少 18 版本。conda 环境中conda install -c conda-forge clang-format18 rm -rf build建议同时安装 black 用于 Python 代码格式化conda install black小结KT-Kernel 的核心价值在于以--kt-method一个参数切换 AMX / AVX512 原生精度 / GGUF 三条 CPU 推理路径并以--kt-cpuinfer物理核、--kt-threadpool-countNUMA 节点、--kt-num-gpu-experts显存预算、--kt-max-deferred-experts-per-token流水线深度四个旋钮完成资源编排。PyPI 多指令集 wheel 运行时变体检测让大多数用户装完即用而源码构建路径install.sh自动检测 /--manual指定指令集则为可移植分发与 AMD、ARM 等特殊平台保留了完整的定制空间。【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
KTransformers KT-Kernel 深度指南：从 CPU 内核选型、构建配置到 SGLang 异构推理实战
KTransformers KT-Kernel 深度指南从 CPU 内核选型、构建配置到 SGLang 异构推理实战【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformersKT-Kernel 是 KTransformers 的高性能 CPU 内核包为 MoEMixture-of-Experts模型提供面向 AMX、AVX512、AVX2、KML 与 AMD BLIS 指令集优化的专家计算后端。本文以仓库中kt-kernel模块的官方 README 为主线系统讲解安装PyPI 与源码构建、CPU 变体自动检测原理、与 SGLang 的 CPU-GPU 异构推理集成含 Qwen3-30B-A3B 完整示例、ktCLI 工具、Python API 用法、构建配置与环境排错并结合仓库源码印证关键调用链帮助你把大 MoE 模型的冷专家高效下放到 CPU同时让热专家留在 GPU 上。支持状态与核心特性当前 KT-Kernel 的支持情况见 kt-kernel/README.md✅AVX512 原生精度FP8、BF16、RAWINT4格式适用于 AVX512 CPU配套教程见 Native-Precision-Tutorial✅Intel AMX CPU完整支持使用转换为 INT4/INT8 格式的权重✅通用 CPUllamafile 后端使用 GGUF 格式权重✅AMD CPUBLIS 后端支持 int8 prefill 与 decode指南见 amd_blis核心特性包括CPU 优化的 MoE 内核面向不同指令集优化的高吞吐 MoE 专家算子AVX512 原生精度后端面向 AVX512 服务器的 FP8 / BF16 / INT4 原生 MoE 后端AMX INT4/INT8 后端面向 AMX 服务器的 INT4 / INT8 量化专家推理后端Llamafile CPU 后端基于 Llamafile 的 AVX2/AVX512 MoE 后端用于通用 CPU 部署NUMA 感知执行线程池与内存布局面向多插槽 / 多 NUMA 机器设计。从源码结构看上述后端由 python/experts.py 中的工厂函数统一分发AMXINT4/AMXINT8路由到AMXMoEWrapperRAWINT4/FP8/BF16/FP8_PERCHANNEL/GPTQ_INT4/MXFP4/MXFP8等路由到NativeMoEWrapperLLAMAFILE路由到LlamafileMoEWrapperMOE_INT4/MOE_INT8路由到通用内核GeneralMoEWrapper分发逻辑。安装方式一从 PyPI 安装推荐大多数用户一条命令安装最新版本pip install kt-kernel该方式的特点✅自动 CPU 检测检测你的 CPU 并加载最优内核变体✅CPU 多变体支持包含 AMX、AVX512Base/VNNI/VBMI/BF16、AVX2 变体✅内置 CUDA 支持NVIDIA GPU 加速SM 80、86、89、90✅无需编译提供 Python 3.10 / 3.11 / 3.12 的预构建 wheel✅静态 CUDA 运行时无需安装 CUDA toolkit✅纯 CPU 系统可用无 GPU 时 CUDA 特性自动禁用要求Python 3.10/3.11/3.12Linux x86-64manylinux_2_17 兼容支持 AVX2 的 CPUIntel Haswell 2013 / AMD Zen可选计算能力 8.0 的 NVIDIA GPU。CUDAGPU 加速说明GPU 加速无需额外步骤同一个 wheel 即支持。特性包括✅多架构支持单个 wheel 支持 SM 80/86/89/90Ampere、Ada、Hopper✅静态 CUDA 运行时无需 CUDA toolkit✅兼容性广兼容 CUDA 11.8 与 12.x 驱动✅PyTorch 兼容适配任意 PyTorch CUDA 变体cu118、cu121、cu124GPU 兼容性矩阵GPU 架构计算能力支持情况示例 GPUHopper9.0✅H100, H200Ada Lovelace8.9✅RTX 4090, 4080, 4070Ampere8.6✅RTX 3090, 3080, 3070, 3060Ampere8.0✅A100, A30Turing7.5❌RTX 2080, T4Volta7.0❌V100CUDA 驱动兼容性GPU 特性CUDA 11.8、11.9、12.0–12.6 完整支持CUDA 11.0–11.7 不支持需升级驱动或改用纯 CPU 模式。CPU 变体说明wheel 内置 6 种优化变体运行时根据你的 CPU 自动选择变体CPU 支持性能自动选择条件AMXIntel Sapphire Rapids2023最佳检测到 AMX 指令AVX512BF16Ice Lake server、Zen 42021优秀AVX512 BF16AVX512VBMIIce Lake client2019良好AVX512 VBMIAVX512VNNICascade Lake2019良好AVX512 VNNIAVX512 BaseSkylake-X2017较好AVX512 baseAVX2Haswell2013、AMD Zen可用最大兼容性回退这一渐进式匹配机制在 python/_cpu_detect.py 中实现detect_cpu_features()按 AMX → avx512_bf16 → avx512_vbmi → avx512_vnni → avx512_base → avx2 的优先级逐级匹配/proc/cpuinfo中的 CPU flags且加载前会校验加载的变体不能高于检测到的能力校验逻辑否则提示安装多变体 wheel 或本机重编。验证安装import kt_kernel # 查看加载的 CPU 变体 print(fCPU variant: {kt_kernel.__cpu_variant__}) print(fVersion: {kt_kernel.__version__}) # 检查 CUDA 支持 from kt_kernel import kt_kernel_ext cpu_infer kt_kernel_ext.CPUInfer(4) has_cuda hasattr(cpu_infer, submit_with_cuda_stream) print(fCUDA support: {has_cuda}) print(✓ kt-kernel installed successfully!)环境变量# 覆盖自动 CPU 检测用于测试或调试 export KT_KERNEL_CPU_VARIANTavx2 # 强制指定变体 # 打开调试输出查看检测过程 export KT_KERNEL_DEBUG1 python -c import kt_kernel其中KT_KERNEL_CPU_VARIANT可取值amx、avx512_bf16、avx512_vbmi、avx512_vnni、avx512_base、avx2见 _cpu_detect.py。方式二从源码安装本地使用或自定义构建当你需要 AMDBLIS、ARMKML或自定义 CUDA 版本时从源码构建。前置准备初始化 git 子模块并创建 conda 环境git submodule update --init --recursive conda create -n kt-kernel python3.11 -y conda activate kt-kernel快速安装推荐直接运行安装脚本它会自动检测 CPU 并优化./install.sh自动完成的工作自动检测 CPU 能力AMX、AVX512_VNNI、AVX512_BF16安装系统依赖cmake、libhwloc-dev、pkg-config只针对你的 CPU构建优化二进制使用-marchnative软件回退对没有 VNNI/BF16 的 CPU 自动启用回退路径从 install.sh 源码可以看到自动检测函数detect_cpu_features()会解析/proc/cpuinfo的 flags 行判断amx_tile/amx_int8/amx_bf16、avx512f、avx512_vnni、avx512_bf16、avx512_vbmi五类能力检测实现随后据此导出CPUINFER_CPU_INSTRUCTNATIVE、CPUINFER_ENABLE_AMX、CPUINFER_ENABLE_AVX512_VNNI/BF16/VBMI等变量进入 CMake 构建脚本还内置了 aarch64 路径检测 DOTPROD/FP16/SVE/BF16/I8MM以及 Ascend CANN 工具链的自动发现CPUINFER_USE_ASCEND_NPU。可选的两步安装./install.sh deps # 只安装依赖 ./install.sh build # 构建并安装 kt-kernel各后端的最低 CPU 要求后端最低 CPU 要求示例 CPU备注LLAMAFILEAVX2Intel Haswell2013、AMD Zen通用兼容RAWINT4AVX512F AVX512BWIntel Skylake-X2017、Ice Lake、Cascade LakeVNNI/BF16 有软件回退AMXINT4/INT8AMXIntel Sapphire Rapids2023性能最佳需要 AMX 硬件FP8AVX512F AVX512BW AVX512_BF16 AVX512_VBMIIntel Cooper Lake2020、Sapphire Rapids2023AMD Zen 4如 EPYC 9355原生精度如 DeepSeek V3.2、MiniMax M2.1BF16AVX512F AVX512BW AVX512_BF16同上原生精度如 Qwen3-235B-A22B、GLM-4.7AVX512 后端的软件回退VNNI 不可用时回退到 AVX512BW 指令BF16 不可用时回退到 AVX512F 指令。因此仅有 AVX512FBW 的旧 CPUSkylake-X、Cascade Lake也能运行 RAWINT4只是更慢。⚠️可移植性注意默认构建针对你的 CPU 优化可能无法在其他/更旧的 CPU 上运行。可移植构建或二进制分发请参考下文手动配置高级章节。⚠️AMD BLIS 后端用户AMD 专用设置请参考仓库文档 amd_blis。安装验证安装完成后验证 CLI 是否可用kt version期望输出KTransformers CLI v0.x.x Python: 3.11.x Platform: Linux 5.15.0-xxx-generic CUDA: 12.x kt-kernel: 0.x.x (amx) sglang: 0.x.x也可以直接验证 Python 模块python -c from kt_kernel import KTMoEWrapper; print(✓ kt-kernel installed successfully)kt命令的入口在 pyproject.toml 中定义为kt kt_kernel.cli.main:main对应实现为基于 Typer 的 cli/main.py首次运行时还会引导完成语言偏好等初始化设置。KT CLI 概览kt命令行工具为运行和管理 KTransformers 模型提供统一入口命令说明kt run model启动模型推理服务器自动优化参数kt chat与运行中的模型服务器交互聊天kt model管理模型与存储路径kt doctor诊断环境问题并检查系统兼容性kt config管理 CLI 配置kt version显示版本信息快速上手# 启动模型服务器自动检测硬件并应用最优配置 kt run m2 # 在另一个终端与模型聊天 kt chat # 检查系统兼容性 kt doctor更多选项执行kt --help或kt command --help查看命令级帮助。与 SGLang 集成KT-Kernel 既可以通过下文 Python API 独立使用也可以与 SGLang 集成做生产部署。集成后可以实现 CPU-GPU 异构推理热专家跑在 GPU 上冷专家跑在 CPU 上实现资源的最优利用。安装步骤1. 安装 SGLang安装 kvcache-ai 的 SGLang forkkt-kernel 支持所必需# 选项 A一键安装在 ktransformers 根目录安装 sglang kt-kernel ./install.sh # 选项 Bpip 安装 pip install kt-kernel sglang-kt # 选项 C源码可编辑模式 git clone --recursive https://github.com/kvcache-ai/ktransformers.git cd ktransformers pip install -e third_party/sglang/python[all]重要请使用sglang-ktkvcache-ai fork而非官方sglang包。若已安装官方版本先卸载pip uninstall sglang -y2. 准备权重异构推理同时需要 GPU 权重与 CPU 端专家权重具体格式取决于后端GPU 权重所有后端通用使用 SGLang GPU 推理所需的模型权重例如 Hugging Face 上的原始或已量化模型目录。CPU 权重AMX 后端AMXINT4/AMXINT8使用仓库提供的脚本量化为 AMX 优化的 INT4/INT8 格式python scripts/convert_cpu_weights.py \ --input-path /path/to/model \ --input-type bf16 \ --output /path/to/cpu-weights \ --quant-method int8 # 或 int4 或 moe_int8amd 后端--input-pathGPU 端原始权重路径--input-type取决于 GPU 权重类型fp8、fp16或bf16在 SGLang 集成中--kt-weight-path应指向该转换后的 CPU 权重目录。支持的输入格式FP8、FP16、BF16 → INT4/INT8。CPU 权重LLAMAFILE 后端LLAMAFILE直接加载预量化的GGUF权重无需运行convert_cpu_weights.py从网上直接下载 GGUF 模型如 Hugging Face / ModelScope 上的 GGUF 仓库SGLang 集成中将该 GGUF 目录作为--kt-weight-path。KT-Kernel 支持Q4_KM、Q4_K、Q5_K等多种 GGUF 量化格式可根据延迟与精度需求选择。3. 启动 SGLang 服务器在常规 SGLang 参数之外追加以下 KT-Kernel 参数即可启用 CPU-GPU 异构推理--kt-methodCPU 推理后端AMXINT4、AMXINT8 或 LLAMAFILE 等--kt-weight-path转换后的 CPU 权重路径--kt-cpuinferCPU 推理线程数设为物理核心数--kt-threadpool-count线程池数量设为 NUMA 节点数--kt-num-gpu-experts保留在 GPU 上的专家数--kt-max-deferred-experts-per-token用于流水线执行的延迟专家数示例python -m sglang.launch_server \ [your normal SGLang parameters...] \ --kt-method AMXINT8 \ --kt-weight-path /path/to/cpu-weights \ --kt-cpuinfer 64 \ --kt-threadpool-count 2 \ --kt-num-gpu-experts 32 \ --kt-max-deferred-experts-per-token 2详细调参指南见下文 KT-Kernel 参数 小节。完整示例Qwen3-30B-A3B本示例演示从下载权重到启动服务器的完整流程展示Native 后端、AMX 后端与LLAMAFILE 后端三种方案。硬件配置GPUNVIDIA RTX 4090 24GBCPU2× Intel Xeon Gold 6454S共 64 物理核、128 线程、2 个 NUMA 节点模型Qwen/Qwen3-30B-A3B如何确认你的系统配置# 查看 CPU 配置 lscpu | grep -E ^CPU\(s\)|Thread\(s\) per core|Socket\(s\)|NUMA node\(s\) # 输出示例 CPU(s): 128 Thread(s) per core: 2 Socket(s): 2 NUMA node(s): 2 # → 物理核 CPU(s) / Thread(s) per core 128 / 2 64参数依据--kt-cpuinfer 64设为物理核数64而非超线程数128--kt-threadpool-count 2检测到 2 个 NUMA 节点双路系统--kt-num-gpu-experts 3224GB 显存下该模型约可容纳 32 个专家随模型架构与实际显存占用而异--kt-max-deferred-experts-per-token 2启用流水线执行允许 GPU 完成当前批次时 CPU 处理下一批--kt-gpu-prefill-token-threshold 2048token 数超过 2048 时使用 layerwise prefill 策略仅原生后端选项 ANative 后端BF16适用于支持 BF16 的 AVX512 CPU。第 1 步下载模型权重# 未安装 huggingface-cli 时先安装 pip install huggingface-hub # 从 Hugging Face 下载模型 huggingface-cli download Qwen/Qwen3-30B-A3B --local-dir /mnt/data/models/Qwen3-30B-A3B第 2 步启动 SGLang 服务器python -m sglang.launch_server \ --host 0.0.0.0 \ --port 30000 \ --model /mnt/data/models/Qwen3-30B-A3B \ --kt-weight-path /mnt/data/models/Qwen3-30B-A3B \ --kt-cpuinfer 64 \ --kt-threadpool-count 2 \ --kt-num-gpu-experts 32 \ --kt-method BF16 \ --attention-backend flashinfer \ --trust-remote-code \ --mem-fraction-static 0.80 \ --chunked-prefill-size 16384 \ --max-running-requests 4 \ --served-model-name Qwen3 \ --enable-mixed-chunk \ --tensor-parallel-size 1 \ --enable-p2p-check \ --disable-shared-experts-fusion \ --kt-gpu-prefill-token-threshold 4096 \ --kt-enable-dynamic-expert-update选项 BAMX 后端AMXINT8适用于支持 AMX 指令集的 Intel CPU。第 1 步下载模型权重pip install huggingface-hub huggingface-cli download Qwen/Qwen3-30B-A3B --local-dir /mnt/data/models/Qwen3-30B-A3B第 2 步转换为 CPU 权重AMXINT8python scripts/convert_cpu_weights.py \ --input-path /mnt/data/models/Qwen3-30B-A3B \ --input-type bf16 \ --output /mnt/data/models/Qwen3-30B-A3B-INT8 \ --quant-method int8第 3 步启动 SGLang 服务器python -m sglang.launch_server \ --host 0.0.0.0 \ --port 8000 \ --model /mnt/data/models/Qwen3-30B-A3B \ --trust-remote-code \ --mem-fraction-static 0.92 \ --chunked-prefill-size 4096 \ --served-model-name Qwen3-30B-A3B \ --enable-mixed-chunk \ --kt-method AMXINT8 \ --kt-weight-path /mnt/data/models/Qwen3-30B-A3B-INT8 \ --kt-cpuinfer 64 \ --kt-threadpool-count 2 \ --kt-num-gpu-experts 32 \ --kt-max-deferred-experts-per-token 2选项 CLLAMAFILE 后端GGUF适用于无 AMX 的通用 CPU直接使用预量化 GGUF 权重。第 1 步下载 GPU 权重原始模型pip install huggingface-hub huggingface-cli download Qwen/Qwen3-30B-A3B --local-dir /mnt/data/models/Qwen3-30B-A3B第 2 步下载 CPU 权重GGUF 格式huggingface-cli download Qwen/Qwen3-30B-A3B-GGUF Qwen3-30B-A3B-Q4_K_M.gguf \ --local-dir /mnt/data/models/Qwen3-30B-A3B-Q4_K_M第 3 步启动 SGLang 服务器python -m sglang.launch_server \ --host 0.0.0.0 \ --port 8000 \ --model /mnt/data/models/Qwen3-30B-A3B \ --trust-remote-code \ --mem-fraction-static 0.92 \ --chunked-prefill-size 4096 \ --served-model-name Qwen3-30B-A3B \ --enable-mixed-chunk \ --kt-method LLAMAFILE \ --kt-weight-path /mnt/data/models/Qwen3-30B-A3B-Q4_K_M \ --kt-cpuinfer 64 \ --kt-threadpool-count 2 \ --kt-num-gpu-experts 32 \ --kt-max-deferred-experts-per-token 2KT-Kernel 参数参数说明示例值--kt-methodCPU 推理后端方法AMXINT4、AMXINT8、RAWINT4、FP8、FP8_PERCHANNEL、BF16或LLAMAFILE--kt-weight-path量化 CPU 权重路径/path/to/cpu-weights--kt-cpuinferCPU 推理线程数64根据 CPU 核心数调整--kt-threadpool-count并行执行的线程池数2通常 1–4--kt-num-gpu-experts保留在 GPU 上的专家数32其余专家放到 CPU--kt-max-deferred-experts-per-token每 token 延迟执行的专家数流水线20 禁用推荐 1–4--kt-gpu-prefill-token-thresholdprefill 策略的 token 数阈值仅原生后端约1024-4096--kt-enable-dynamic-expert-update根据实际路由统计在 prefill 期间动态更新专家放置flag无需值--kt-expert-placement-strategy初始 GPU 专家放置策略uniform、frequency、front-loading或random参数调优指南kt-method根据 CPU 与权重格式选择AMXINT4AMX CPU 上 INT4 量化权重性能最佳注意部分模型可能大幅掉精度例如 Qwen3-30B-A3BAMXINT8AMX CPU 上 INT8 量化权重精度更高RAWINT4CPU 与 GPU 共享的原生 INT4 权重当前支持 Kimi-K2-Thinking 模型详见 Kimi-K2-Thinking Native 教程FP8、FP8_PERCHANNELCPU 与 GPU 共享的 FP8 权重BF16CPU 与 GPU 共享的 BF16 权重LLAMAFILEGGUF 后端kt-cpuinfer设为物理 CPU 核心数不是超线程数。查看物理核lscpu | grep -E ^CPU\(s\)|Thread\(s\) per core物理核 CPU(s) / Thread(s) per core。例如 CPU(s)128 且 Thread(s) per core2 时物理核为 64。切勿设为超线程数否则会劣化性能。kt-threadpool-count设为NUMA 节点数。查看方法lscpu | grep NUMA node(s)或numactl --hardware | grep available。注意 NUMA 节点数不一定等于物理 CPU 数——它表示内存域可能出现在单个 CPU 内部或多个 CPU 之间请以lscpu的 NUMA 节点数为准。典型值单路 1–2双路 2–4。可提升跨 NUMA 域的内存带宽利用率。kt-num-gpu-experts根据显存与 profiling 结果确定。GPU 专家越多延迟越低但显存占用越高可能 OOM。kt-max-deferred-experts-per-token启用流水线执行0同步执行简单、延迟较高1-4延迟执行推荐区间延迟/质量平衡好需要调参5-7延迟降低最明显但可能引入明显精度损失谨慎使用kt-gpu-prefill-token-thresholdFP8 与 RAWINT4 可用控制原生 FP8/INT4 推理的 prefill 策略≤ 阈值使用 CPUGPU 混合 prefill无需额外显存但性能随 token 数增长缓慢下降 阈值使用 layerwise GPU prefill长序列下扩展性更好但需要约一层 MoE 的额外显存例如 Kimi-K2-Thinking 约 9GBMiniMax-M2.1 约 3.6GB。仅在--kt-method RAWINT4或--kt-method FP8时生效。kt-enable-dynamic-expert-update推理期间动态更新专家放置。layerwise prefill 期间系统收集实际路由统计并据此重新分配 GPU 专家。需要设置--kt-gpu-prefill-token-threshold且 prefill 长度 ≥ 阈值。在 GPU 专家占比较低10%–70%时特别有效可显著优于静态策略。详见 Expert Scheduling 教程。kt-expert-placement-strategy决定服务器启动时哪些专家放到 GPUuniform在所有 MoE 层间均匀分布 GPU 专家。默认选项无需先验统计frequency将激活最频繁的专家放到 GPU。有激活统计时性能最佳需要--init-expert-location指向.pt统计文件front-loading从第一个 MoE 层开始填充 GPU 专家random固定种子42随机选择专家。策略对比详见 Expert Scheduling 教程。从源码结构看frequency 策略背后的放置逻辑对应 experts_base.py 中的generate_gpu_experts_masks()它接收形状为(num_layers, num_experts)的激活频率表选出激活频率最高的num_gpu_experts个专家生成布尔 mask实现。直接 Python API 使用不依赖 SGLang 时可通过 Python API 直接使用 KT-Kernelfrom kt_kernel import KTMoEWrapper # 初始化 MoE wrapper wrapper KTMoEWrapper( layer_idx0, num_experts8, num_experts_per_tok2, hidden_size4096, moe_intermediate_size14336, num_gpu_experts2, cpuinfer_threads32, threadpool_count2, weight_path/path/to/weights, chunked_prefill_size512, methodAMXINT4 # 可选: AMXINT4, AMXINT8, LLAMAFILE 等 ) # 从磁盘加载权重预量化 wrapper.load_weights(physical_to_logical_map) # 或从张量加载权重在线量化 wrapper.load_weights_from_tensors(gate_proj, up_proj, down_proj, physical_to_logical_map) # 同步推理 output wrapper.forward(hidden_states, topk_ids, topk_weights, cuda_stream) # 或使用异步 API 获得更好性能 wrapper.submit_forward(hidden_states, topk_ids, topk_weights, cuda_stream) # ... 期间可做其他工作 ... output wrapper.sync_forward(hidden_states, cuda_stream)高级选项# 附加选项初始化 wrapper KTMoEWrapper( layer_idx0, num_experts8, num_experts_per_tok2, hidden_size4096, moe_intermediate_size14336, num_gpu_experts2, cpuinfer_threads32, threadpool_count2, weight_path/path/to/weights, chunked_prefill_size512, methodAMXINT4, cpu_saveFalse, # 加载后保留权重在 CPU 内存 max_deferred_experts_per_token0 # 延迟专家数流水线执行 ) # 为特定 batch size 预分配缓冲提升性能 KTMoEWrapper.set_capture_batch_sizes([1, 2, 4, 8, 16]) # 查询已捕获的 batch sizes batch_sizes KTMoEWrapper.get_capture_batch_sizes() # 清空缓冲缓存以释放内存 KTMoEWrapper.clear_buffer_cache()在 python/experts.py 中KTMoEWrapper实际上是工厂类__new__根据modeinference/sft与method参数校验后构造具体后端实例工厂入口。推理模式下合法方法集合为AMXINT4、AMXINT8、RAWINT4、FP8、BF16、FP8_PERCHANNEL、GPTQ_INT4、SYCL_GPTQ_INT4、MXFP4、NVFP4、MXFP8、LLAMAFILE、MOE_INT4、MOE_INT8此外还支持gpu_experts_mask布尔掩码mask[i]True表示专家 i 在 GPU 上来显式控制专家放置。set_capture_batch_sizes等静态方法则转发到底层BaseMoEWrapper的缓冲缓存管理静态方法。构建配置手动配置高级可移植构建、二进制分发或跨机器部署时需要手动指定目标指令集# 通用分发任何 2017 的 AVX512 CPU 均可运行 export CPUINFER_CPU_INSTRUCTAVX512 export CPUINFER_ENABLE_AMXOFF ./install.sh build --manual # 最大兼容任何 2013 的 CPU export CPUINFER_CPU_INSTRUCTAVX2 export CPUINFER_ENABLE_AMXOFF ./install.sh build --manual # 仅现代 CPUIce Lake、Zen 4 export CPUINFER_CPU_INSTRUCTFANCY export CPUINFER_ENABLE_AMXOFF ./install.sh build --manual可选覆盖 VNNI/BF16 检测# 强制启用/禁用 VNNI 和 BF16用于测试回退路径 export CPUINFER_ENABLE_AVX512_VNNIOFF export CPUINFER_ENABLE_AVX512_BF16OFF ./install.sh可选非 AMX AVX512 CPU 上的 oneDNN INT8 BRGEMM# 需要已安装的 oneDNN 3.9 包 export CPUINFER_ENABLE_ONEDNN_VNNION # 或针对 oneDNN 源码树构建 export CPUINFER_ONEDNN_SOURCE_DIR/path/to/oneDNN ./install.sh # 编译出的 wheel 默认使用 oneDNNnative 路径保留用于 A/B 对比 export KT_INT8_VNNI_BACKENDauto # auto | onednn | native完整选项见./install.sh --help。不依赖 install.sh 的手动安装1. 安装系统依赖cmake推荐conda install -y cmakelibhwloc-dev与pkg-config2. 设置构建配置核心变量变量可选值说明CPUINFER_CPU_INSTRUCTNATIVE、AVX512、AVX2、FANCY使用的 CPU 指令集CPUINFER_ENABLE_AMXON、OFF启用 Intel AMX 支持CPUINFER_ENABLE_ONEDNN_VNNION、OFF非 AMX AVX512 CPU 上启用 oneDNN INT8 BRGEMMCPUINFER_ONEDNN_SOURCE_DIR路径可选的 oneDNN 3.9 源码树CPUINFER_BUILD_TYPERelease、Debug、RelWithDebInfo构建类型默认ReleaseCPUINFER_PARALLEL数字并行构建任务数默认自动检测CPUINFER_VERBOSE0、1详细构建输出默认0指令集选项详情选项目标 CPU使用场景NATIVE仅你自己的 CPU本地构建性能最佳默认AVX512Skylake-X、Ice Lake、Cascade Lake、Zen 4通用分发AVX2Haswell2013及更新最大兼容性FANCYIce Lake、Zen 4带完整 AVX512 扩展的现代 CPU配置示例# 本地使用 - 最大性能默认行为 export CPUINFER_CPU_INSTRUCTNATIVE export CPUINFER_ENABLE_AMXON # 或 OFF # 分发布 - 任何 AVX512 CPU 可用 export CPUINFER_CPU_INSTRUCTAVX512 export CPUINFER_ENABLE_AMXOFF # 最大兼容 - 2013 年起的 CPU 可用 export CPUINFER_CPU_INSTRUCTAVX2 export CPUINFER_ENABLE_AMXOFF # 调试构建 export CPUINFER_BUILD_TYPEDebug export CPUINFER_VERBOSE13. 构建与安装# 可编辑安装开发用 pip install -e . # 标准安装 pip install .错误排查CUDA Not Found-- Looking for a CUDA compiler - NOTFOUND CMake Error at CMakeLists.txt:389 (message): KTRANSFORMERS_USE_CUDAON but CUDA compiler not found确认已安装 CUDA toolkit 且nvcc在系统 PATH 中。可尝试export CMAKE_ARGS-D CMAKE_CUDA_COMPILER$(which nvcc)后重新安装。hwloc Not FoundDebian 系系统执行sudo apt install libhwloc-dev或从源码构建 hwlocwget https://download.open-mpi.org/release/hwloc/v2.12/hwloc-2.12.2.tar.gz tar -xzf hwloc-2.12.2.tar.gz cd hwloc-2.12.2 ./configure make sudo make install权重量化AMX 后端AMXINT4/AMXINT8要求 CPU 端专家先转换为 AMX 友好的 INT4/INT8 格式python scripts/convert_cpu_weights.py \ --input-path /path/to/model \ --input-type bf16 \ --output /path/to/output \ --quant-method int4支持格式FP8、FP16、BF16 → INT4/INT8。LLAMAFILE 后端则直接从GGUF权重加载 CPU 端专家无需运行 AMX 转换脚本下载 GGUF 模型如 Hugging Face 上的 GGUF 仓库并将weight_path/ SGLang--kt-weight-path或相应场景下的--model指向该 GGUF 目录。支持的 GGUF 量化类型包括Q4_KM、Q4_K、Q5_K等。更多高级选项与低内存模式详见 scripts/README.md。提交前须知Before Commit!Commit message 应遵循 Conventional Commits 规范。提交前请格式化代码cmake -B build cd build make format可能需要较新的 clang-format至少 18 版本。conda 环境中conda install -c conda-forge clang-format18 rm -rf build建议同时安装 black 用于 Python 代码格式化conda install black小结KT-Kernel 的核心价值在于以--kt-method一个参数切换 AMX / AVX512 原生精度 / GGUF 三条 CPU 推理路径并以--kt-cpuinfer物理核、--kt-threadpool-countNUMA 节点、--kt-num-gpu-experts显存预算、--kt-max-deferred-experts-per-token流水线深度四个旋钮完成资源编排。PyPI 多指令集 wheel 运行时变体检测让大多数用户装完即用而源码构建路径install.sh自动检测 /--manual指定指令集则为可移植分发与 AMD、ARM 等特殊平台保留了完整的定制空间。【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
