KT-Kernel

KTransformers 的高性能内核操作库，支持 AMX、AVX、KML 和 BLIS (AMD 库) 的 CPU 优化 MoE 推理。

• 说明
• 特性
• 安装
• 验证
• KT CLI 概览
• 与 SGLang 集成
• Python API 直接使用
• 构建配置
• 错误排查
• 权重量化

说明

当前支持状态：

• ✅ AVX512/AMX 原生精度：支持 AVX512 CPU，格式为 FP8、BF16 和 RAWINT4
• ✅ Intel AMX CPU：完全支持（使用转换为 INT4/INT8 格式的权重）
• ✅ 通用 CPU（llamafile 后端）：支持（使用 GGUF 格式权重）
• ✅ AMD CPU BLIS：支持（用于 int8 prefill 和 decode）

KT-CLI

我们正在开发更简单的 KTransformers 使用方式。详见下方 KT-CLI 部分。

特性

• CPU 优化 MoE 内核：针对指令集优化的高吞吐 MoE 专家内核。
• AVX512 原生精度后端：适用于 AVX512 服务器的 FP8 / BF16 / INT4 原生 MoE 后端。
• AMX INT4/INT8 后端：适用于 AMX 服务器的 INT4 / INT8 量化专家推理后端。
• Llamafile CPU 后端：基于 Llamafile 的 AVX2/AVX512 MoE 后端，用于通用 CPU 部署。
• NUMA 感知执行：为多插槽/多 NUMA 机器设计的线程池和内存布局。

安装

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

一条命令安装最新版本：

pip install kt-kernel

提示：查看 PyPI 上的最新版本

功能特性：

• ✅ 自动 CPU 检测：检测你的 CPU 并加载最优内核变体
• ✅ CPU 多变体支持：包含 AMX、AVX512 (Base/VNNI/VBMI/BF16) 和 AVX2 变体
• ✅ 包含 CUDA 支持：NVIDIA GPU 加速（SM 80, 86, 89, 90）
• ✅ 无需编译：预编译 wheel，支持 Python 3.10、3.11、3.12
• ✅ 静态 CUDA 运行时：无需安装 CUDA 工具包
• ✅ 支持纯 CPU 系统：无 GPU 时 CUDA 功能自动禁用

环境要求：

• Python 3.10、3.11 或 3.12
• Linux x86-64（兼容 manylinux_2_17）
• 支持 AVX2 的 CPU（Intel Haswell 2013+，AMD Zen+）
• 可选：NVIDIA GPU，计算能力 8.0+，用于 CUDA 功能

CUDA 安装（GPU 加速）

如需 NVIDIA GPU 加速推理：

pip install kt-kernel-cuda

功能特性：

• ✅ 多架构支持：单个 wheel 支持 SM 80/86/89/90（Ampere、Ada、Hopper）
• ✅ 静态 CUDA 运行时：无需安装 CUDA 工具包
• ✅ 广泛兼容：适用于 CUDA 11.8+ 和 12.x 驱动
• ✅ 兼容 PyTorch：适用于任何 PyTorch CUDA 变体（cu118、cu121、cu124）

环境要求：

• Python 3.10、3.11 或 3.12
• Linux x86-64（兼容 manylinux_2_17）
• NVIDIA GPU，计算能力 8.0+（Ampere 或更新）
  • ✅ 支持：A100、RTX 3000/4000 系列、H100
  • ❌ 不支持：V100、P100、GTX 1000/2000 系列（太旧）
• NVIDIA 驱动，支持 CUDA 11.8+ 或 12.x（无需 CUDA 工具包）

GPU 兼容性矩阵：

CUDA 驱动兼容性（GPU 功能）：

• CUDA 11.8、11.9、12.0-12.6+：完全支持
• CUDA 11.0-11.7：不支持（请升级驱动或使用纯 CPU 模式）

包含的 CPU 变体：

wheel 包含 6 个优化变体，运行时根据你的 CPU 自动选择：

验证安装：

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 安装成功！")

环境变量：

# 覆盖自动 CPU 检测（用于测试或调试）
export KT_KERNEL_CPU_VARIANT=avx2  # 强制使用指定变体

# 启用调试输出以查看检测过程
export KT_KERNEL_DEBUG=1
python -c "import kt_kernel"

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

从源码构建，适用于本地安装或需要 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 deps   # 仅安装依赖
./install.sh build  # 构建并安装 kt-kernel

各后端的 CPU 要求：

软件回退支持（AVX512 后端）：

• ✅ VNNI 回退：使用 AVX512BW 指令
• ✅ BF16 回退：使用 AVX512F 指令
• ✅ 较旧的 AVX512 CPU（Skylake-X、Cascade Lake）可通过回退运行 RAWINT4

可移植性说明： 默认构建针对你的特定 CPU 优化，可能无法在不同/更旧的 CPU 上运行。如需可移植构建或二进制分发，请参阅下方手动配置。

AMD BLIS 后端用户： 请参阅 AMD 专用安装指南。

验证

安装后，验证 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 安装成功')"

KT CLI 概览

kt 命令行工具提供了运行和管理 KTransformers 模型的统一接口：

快速开始示例：

# 启动模型服务（自动检测硬件并应用最优设置）
kt run m2

# 在另一个终端中与模型对话
kt chat

# 检查系统兼容性
kt doctor

运行 kt --help 查看更多选项，或 kt <command> --help 查看特定命令帮助。

与 SGLang 集成

KT-Kernel 可通过 Python API 直接使用独立运行，也可与 SGLang 集成用于生产部署。本节介绍 SGLang 集成，实现 CPU-GPU 异构推理——"热门"专家在 GPU 上运行，"冷门"专家在 CPU 上运行，优化资源利用。

安装步骤

1. 安装 SGLang

git clone https://github.com/sgl-project/sglang.git
cd sglang
pip install -e "python[all]"

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）： LLAMAFILE 在 CPU 侧直接使用预量化的 GGUF 权重，无需运行 convert_cpu_weights.py。你需要：

• 直接从网上下载 GGUF 模型（例如 Hugging Face / Modelscope 上的 GGUF 仓库）；
• 在 SGLang 集成中，将该 GGUF 目录用作 --kt-weight-path。 KT-Kernel 支持多种 GGUF 量化格式如 Q4_KM、Q4_K、Q5_K 等。根据延迟和精度需求选择。

3. 启动 SGLang 服务

使用你正常的 SGLang 参数启动服务，并添加以下 KT-Kernel 特定参数以启用 CPU-GPU 异构推理：

需要添加的 KT-Kernel 参数：

• --kt-method：后端方法（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 \
  [你的正常 SGLang 参数...] \
  --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：2x Intel Xeon Gold 6454S（共 64 物理核心，128 线程，2 个 NUMA 节点）
• 模型：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 GPU 显存可容纳约 32 个专家（因模型架构和实际显存使用而异）
• --kt-max-deferred-experts-per-token 2：启用流水线执行；允许 CPU 在 GPU 完成当前批次时处理下一批
• --kt-gpu-prefill-token-threshold 2048：token 数超过 2048 时使用逐层预填充策略（仅限 native 后端）

方案 A：Native 后端（BF16）

适用于支持 BF16 的 AVX512 CPU。

第一步：下载模型权重

# 如未安装 huggingface-cli，先安装
pip install huggingface-hub
# 从 Hugging Face 下载模型
huggingface-cli download Qwen/Qwen3-30B-A3B --local-dir /mnt/data/models/Qwen3-30B-A3B

第二步：启动 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。

第一步：下载模型权重

# 如未安装 huggingface-cli，先安装
pip install huggingface-hub

# 从 Hugging Face 下载模型
huggingface-cli download Qwen/Qwen3-30B-A3B --local-dir /mnt/data/models/Qwen3-30B-A3B

第二步：转换 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

第三步：启动 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）

适用于通用 CPU（无需 AMX），直接使用预量化的 GGUF 权重。

第一步：下载 GPU 权重（原始模型）

pip install huggingface-hub

huggingface-cli download Qwen/Qwen3-30B-A3B --local-dir /mnt/data/models/Qwen3-30B-A3B

第二步：下载 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

第三步：启动 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 模型）
  • 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 节点数。

  • 查看 NUMA 数量：lscpu | grep "NUMA node(s)"
  • 或使用：numactl --hardware | grep "available"
  • 注意：NUMA 节点数不一定等于物理 CPU 数量。它代表内存域，可能在单个 CPU 内划分或跨多个 CPU。使用 lscpu 显示的 NUMA 节点数，不论物理 CPU 数量。
  • 典型值：单路 1-2，双路 2-4
  • 这能更好地利用跨 NUMA 域的内存带宽

• kt-num-gpu-experts：根据 GPU 显存和性能分析确定：

  • 更多 GPU 专家 = 更低延迟但更高显存占用（可能导致 OOM）

• kt-max-deferred-experts-per-token：启用流水线执行：

  • 0：同步执行（更简单，延迟较高）
  • 1-4：延迟执行（推荐范围；延迟/质量平衡好，需要调优）
  • 5-7：延迟降低最多但可能引入明显的精度损失；谨慎使用

• kt-gpu-prefill-token-threshold（仅 FP8 和 RAWINT4）：控制原生 FP8 和 INT4 推理的预填充策略：

  • ≤ 阈值：使用 CPU+GPU 混合预填充。无需额外显存，但随 token 数增加性能缓慢下降。
  • > 阈值：使用逐层 GPU 预填充。长序列性能更好，但需要一个 MoE 层的额外显存（如 Kimi-K2-Thinking 约 9GB+，MiniMax-M2.1 约 3.6GB）。
  • 仅在使用 --kt-method RAWINT4 或 --kt-method FP8 时适用。

• kt-enable-dynamic-expert-update：推理期间启用动态专家放置更新。

  • 在逐层预填充期间，系统收集实际路由统计并相应地重新分配 GPU 专家。
  • 需要设置 --kt-gpu-prefill-token-threshold，且预填充长度必须 ≥ 阈值。
  • 在较低的 GPU 专家比例（10%-70%）下特别有效，可显著优于静态策略。

• kt-expert-placement-strategy：决定服务启动时哪些专家放置在 GPU 上。

  • uniform：在所有 MoE 层间均匀分配 GPU 专家。默认选项，无需先验统计。
  • frequency：将最常被激活的专家放在 GPU 上。有激活统计时性能最佳；需要 --init-expert-location 指向 .pt 统计文件。
  • front-loading：从第一个 MoE 层开始填充 GPU 专家。
  • random：使用固定种子（42）随机选择专家。

Python API 直接使用

无需 SGLang 独立使用时，可直接通过 Python API 调用 KT-Kernel：

from kt_kernel import KTMoEWrapper

# 初始化 MoE 包装器
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 size
batch_sizes = KTMoEWrapper.get_capture_batch_sizes()

# 清除缓冲区缓存以释放内存
KTMoEWrapper.clear_buffer_cache()

手动配置（高级）

用于可移植构建、二进制分发或跨机器部署时，需要手动指定目标指令集：

# 通用分发（适用于 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

运行 ./install.sh --help 查看所有可用选项。

构建配置

手动安装（不使用 install.sh）

如果你更倾向于不使用 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

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

确保已安装 CUDA 工具包且 nvcc 在系统 PATH 中。

尝试 export CMAKE_ARGS="-D CMAKE_CUDA_COMPILER=$(which nvcc)" 后重新安装。

找不到 hwloc

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

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 后端（LLAMAFILE）的 CPU 侧专家直接从 GGUF 权重加载。你不需要运行 AMX 转换脚本；而是从网上下载 GGUF 模型（例如 Hugging Face 上的 GGUF 仓库），然后将 weight_path / SGLang --kt-weight-path（或适当时的 --model）指向该 GGUF 目录。KT-Kernel 支持多种 GGUF 量化类型如 Q4_KM、Q4_K、Q5_K 等。