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/ktransformers

KT-Kernel 是 KTransformers 的高性能 CPU 内核包，为 MoE（Mixture-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 格式的权重）
• ✅通用 CPU（llamafile 后端）：使用 GGUF 格式权重
• ✅AMD CPU（BLIS 后端）：支持 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路由到AMXMoEWrapper，RAWINT4/FP8/BF16/FP8_PERCHANNEL/GPTQ_INT4/MXFP4/MXFP8等路由到NativeMoEWrapper，LLAMAFILE路由到LlamafileMoEWrapper，MOE_INT4/MOE_INT8路由到通用内核GeneralMoEWrapper（分发逻辑）。

安装

方式一：从 PyPI 安装（推荐大多数用户）

一条命令安装最新版本：

pip install kt-kernel

该方式的特点：

• ✅自动 CPU 检测：检测你的 CPU 并加载最优内核变体
• ✅CPU 多变体支持：包含 AMX、AVX512（Base/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.12；Linux x86-64（manylinux_2_17 兼容）；支持 AVX2 的 CPU（Intel Haswell 2013+ / AMD Zen+）；可选：计算能力 8.0+ 的 NVIDIA GPU。

CUDA（GPU 加速）说明

GPU 加速无需额外步骤，同一个 wheel 即支持。特性包括：

• ✅多架构支持：单个 wheel 支持 SM 80/86/89/90（Ampere、Ada、Hopper）
• ✅静态 CUDA 运行时：无需 CUDA toolkit
• ✅兼容性广：兼容 CUDA 11.8+ 与 12.x 驱动
• ✅PyTorch 兼容：适配任意 PyTorch CUDA 变体（cu118、cu121、cu124）

GPU 兼容性矩阵：

CUDA 驱动兼容性（GPU 特性）：CUDA 11.8、11.9、12.0–12.6+ 完整支持；CUDA 11.0–11.7 不支持（需升级驱动或改用纯 CPU 模式）。

CPU 变体说明：wheel 内置 6 种优化变体，运行时根据你的 CPU 自动选择：

这一"渐进式匹配"机制在 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(f"CPU variant: {kt_kernel.__cpu_variant__}") print(f"Version: {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(f"CUDA support: {has_cuda}") print("✓ kt-kernel installed successfully!")

环境变量：

# 覆盖自动 CPU 检测（用于测试或调试） export KT_KERNEL_CPU_VARIANT=avx2 # 强制指定变体 # 打开调试输出，查看检测过程 export KT_KERNEL_DEBUG=1 python -c "import kt_kernel"

其中KT_KERNEL_CPU_VARIANT可取值amx、avx512_bf16、avx512_vbmi、avx512_vnni、avx512_base、avx2（见 _cpu_detect.py）。

方式二：从源码安装（本地使用或自定义构建）

当你需要 AMD（BLIS）、ARM（KML）或自定义 CUDA 版本时，从源码构建。

前置准备

初始化 git 子模块并创建 conda 环境：

git submodule update --init --recursive conda create -n kt-kernel python=3.11 -y conda activate kt-kernel

快速安装（推荐）

直接运行安装脚本，它会自动检测 CPU 并优化：

./install.sh

自动完成的工作：

• 自动检测 CPU 能力（AMX、AVX512_VNNI、AVX512_BF16）
• 安装系统依赖（cmake、libhwloc-dev、pkg-config）
• 只针对你的 CPU构建优化二进制（使用-march=native）
• 软件回退：对没有 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_INSTRUCT=NATIVE、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 要求：

AVX512 后端的软件回退：VNNI 不可用时回退到 AVX512BW 指令；BF16 不可用时回退到 AVX512F 指令。因此仅有 AVX512F+BW 的旧 CPU（Skylake-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 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 fork（kt-kernel 支持所必需）：

# 选项 A：一键安装（在 ktransformers 根目录，安装 sglang + kt-kernel） ./install.sh # 选项 B：pip 安装 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-kt（kvcache-ai fork），而非官方sglang包。若已安装官方版本，先卸载：pip uninstall sglang -y

2. 准备权重

异构推理同时需要 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_int8（amd 后端）

• --input-path：GPU 端原始权重路径
• --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-method：CPU 推理后端（AMXINT4、AMXINT8 或 LLAMAFILE 等）
• --kt-weight-path：转换后的 CPU 权重路径
• --kt-cpuinfer：CPU 推理线程数（设为物理核心数）
• --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 后端三种方案。

硬件配置：

• GPU：NVIDIA RTX 4090 24GB
• CPU：2× 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 32：24GB 显存下该模型约可容纳 32 个专家（随模型架构与实际显存占用而异）
• --kt-max-deferred-experts-per-token 2：启用流水线执行，允许 GPU 完成当前批次时 CPU 处理下一批
• --kt-gpu-prefill-token-threshold 2048：token 数超过 2048 时使用 layerwise prefill 策略（仅原生后端）

选项 A：Native 后端（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

选项 B：AMX 后端（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 权重（AMXINT8）

python 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

选项 C：LLAMAFILE 后端（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 2

KT-Kernel 参数

参数调优指南：

• kt-method：根据 CPU 与权重格式选择：
  • AMXINT4：AMX CPU 上 INT4 量化权重性能最佳（注意：部分模型可能大幅掉精度，例如 Qwen3-30B-A3B）
  • AMXINT8：AMX CPU 上 INT8 量化权重，精度更高
  • RAWINT4：CPU 与 GPU 共享的原生 INT4 权重（当前支持 Kimi-K2-Thinking 模型），详见 Kimi-K2-Thinking Native 教程
  • FP8、FP8_PERCHANNEL：CPU 与 GPU 共享的 FP8 权重
  • BF16：CPU 与 GPU 共享的 BF16 权重
  • LLAMAFILE：GGUF 后端
• kt-cpuinfer：设为物理 CPU 核心数（不是超线程数）。查看物理核：lscpu | grep -E "^CPU\(s\)|Thread\(s\) per core"；物理核 = CPU(s) / Thread(s) per core。例如 CPU(s)=128 且 Thread(s) per core=2 时物理核为 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-threshold（FP8 与 RAWINT4 可用）：控制原生 FP8/INT4 推理的 prefill 策略：
  • ≤ 阈值：使用 CPU+GPU 混合 prefill，无需额外显存，但性能随 token 数增长缓慢下降；
  • > 阈值：使用 layerwise GPU prefill，长序列下扩展性更好，但需要约一层 MoE 的额外显存（例如 Kimi-K2-Thinking 约 9GB+，MiniMax-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：决定服务器启动时哪些专家放到 GPU：
  • uniform：在所有 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-Kernel：

from kt_kernel import KTMoEWrapper # 初始化 MoE wrapper wrapper = KTMoEWrapper( layer_idx=0, num_experts=8, num_experts_per_tok=2, hidden_size=4096, moe_intermediate_size=14336, num_gpu_experts=2, cpuinfer_threads=32, threadpool_count=2, weight_path="/path/to/weights", chunked_prefill_size=512, method="AMXINT4" # 可选: "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_idx=0, num_experts=8, num_experts_per_tok=2, hidden_size=4096, moe_intermediate_size=14336, num_gpu_experts=2, cpuinfer_threads=32, threadpool_count=2, weight_path="/path/to/weights", chunked_prefill_size=512, method="AMXINT4", cpu_save=False, # 加载后保留权重在 CPU 内存 max_deferred_experts_per_token=0 # 延迟专家数（流水线执行） ) # 为特定 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__根据mode（"inference"/"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_INSTRUCT=AVX512 export CPUINFER_ENABLE_AMX=OFF ./install.sh build --manual # 最大兼容（任何 2013+ 的 CPU） export CPUINFER_CPU_INSTRUCT=AVX2 export CPUINFER_ENABLE_AMX=OFF ./install.sh build --manual # 仅现代 CPU（Ice Lake+、Zen 4+） export CPUINFER_CPU_INSTRUCT=FANCY export CPUINFER_ENABLE_AMX=OFF ./install.sh build --manual

可选：覆盖 VNNI/BF16 检测

# 强制启用/禁用 VNNI 和 BF16（用于测试回退路径） export CPUINFER_ENABLE_AVX512_VNNI=OFF export CPUINFER_ENABLE_AVX512_BF16=OFF ./install.sh

可选：非 AMX AVX512 CPU 上的 oneDNN INT8 BRGEMM

# 需要已安装的 oneDNN >= 3.9 包： export CPUINFER_ENABLE_ONEDNN_VNNI=ON # 或针对 oneDNN 源码树构建： export CPUINFER_ONEDNN_SOURCE_DIR=/path/to/oneDNN ./install.sh # 编译出的 wheel 默认使用 oneDNN；native 路径保留用于 A/B 对比 export KT_INT8_VNNI_BACKEND=auto # auto | onednn | native

完整选项见./install.sh --help。

不依赖 install.sh 的手动安装

1. 安装系统依赖

• cmake（推荐：conda install -y cmake）
• libhwloc-dev与pkg-config

2. 设置构建配置

核心变量：

指令集选项详情：

配置示例：

# 本地使用 - 最大性能（默认行为） export CPUINFER_CPU_INSTRUCT=NATIVE export CPUINFER_ENABLE_AMX=ON # 或 OFF # 分发布 - 任何 AVX512 CPU 可用 export CPUINFER_CPU_INSTRUCT=AVX512 export CPUINFER_ENABLE_AMX=OFF # 最大兼容 - 2013 年起的 CPU 可用 export CPUINFER_CPU_INSTRUCT=AVX2 export CPUINFER_ENABLE_AMX=OFF # 调试构建 export CPUINFER_BUILD_TYPE=Debug export CPUINFER_VERBOSE=1

3. 构建与安装

# 可编辑安装（开发用） pip install -e . # 标准安装 pip install .

错误排查

CUDA Not Found

-- Looking for a CUDA compiler - NOTFOUND CMake Error at CMakeLists.txt:389 (message): KTRANSFORMERS_USE_CUDA=ON but CUDA compiler not found

确认已安装 CUDA toolkit 且nvcc在系统 PATH 中。可尝试export CMAKE_ARGS="-D CMAKE_CUDA_COMPILER=$(which nvcc)"后重新安装。

hwloc Not Found

Debian 系系统执行sudo apt install libhwloc-dev，或从源码构建 hwloc：

wget 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-format=18 rm -rf build

建议同时安装 black 用于 Python 代码格式化：

conda install black

小结

KT-Kernel 的核心价值在于：以--kt-method一个参数切换 AMX / AVX512 原生精度 / GGUF 三条 CPU 推理路径，并以--kt-cpuinfer（物理核）、--kt-threadpool-count（NUMA 节点）、--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