企业官网建设流程全解析

如何安装 KTransformers kt-kernel 并验证 CPU 变体与 CUDA 支持

【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers

kt-kernel 是 KTransformers 中负责 CPU 优化的 MoE 算子层（支持 AMX、AVX512、AVX2、llamafile 后端），也是 kt-cli 和 SGLang 集成所依赖的底层模块。完成首次安装后，你需要确认两件事：当前 CPU 上实际加载了哪个内核变体（AMX / AVX512 / AVX2 系列），以及 CUDA 支持是否可用（有 NVIDIA GPU 时）。本文给出从 PyPI 安装的主路径、从源码构建的备选路径，以及文档提供的验证方式与两类常见构建报错的处理方法。

以下内容依据 kt-kernel/README.md 与 doc/en/kt-kernel/kt-kernel_intro.md（两者当前正文一致）。

环境要求

安装前对照文档列出的要求检查环境：

关于 CUDA 的支持范围，文档给出了 GPU 兼容矩阵：

驱动侧：CUDA 11.8、11.9、12.0–12.6+ 为完整支持；CUDA 11.0–11.7 不支持（需升级驱动，或仅用 CPU）。CPU-only 系统可以直接安装，CUDA 功能会在无 GPU 时自动禁用。

主路径：从 PyPI 安装

pip install kt-kernel

预构建 wheel 已包含全部 6 个 CPU 变体，运行时自动检测 CPU 并选择最合适的变体：

GPU 加速不需要单独安装：wheel 内置静态 CUDA 运行时，无需 CUDA toolkit，兼容 PyTorch 的 cu118、cu121、cu124 等任意 CUDA 变体。

验证 CPU 变体与 CUDA 支持

安装后运行文档给出的验证代码：

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 variant应打印为与你的 CPU 匹配的变体名称（源码kt-kernel/python/__init__.py中说明取值如amx、avx512、avx2）。
• CUDA support打印True表示构建中带有 CUDA 能力；在 CPU-only 机器上该特性会不可用，属文档说明的预期行为。

如果导入或加载结果不符合预期，可以借助文档提供的两个环境变量排查：

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

另有一条等价的模块导入检查（来自文档 Verification 一节）：

python -c "from kt_kernel import KTMoEWrapper; print('✓ kt-kernel installed successfully')"

用 kt version 查看完整环境信息

安装完成后，kt-cli 的kt version命令可以一次性查看 Python 版本、平台、CUDA 版本、kt-kernel 版本（含变体）与 sglang 版本。文档示例输出如下（版本号为占位示例，实际值以你的安装为准）：

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

其中kt-kernel: 0.x.x (amx)括号内的名称即当前加载的 CPU 变体，可与前面 Python 检查互相对照。此外kt doctor用于诊断环境问题与系统兼容性（见 doc/en/kt-kernel/kt-cli.md，注意该 CLI 功能文档标注为持续开发中）。更多子命令用kt --help查看。

备选路径：从源码构建

仅当 PyPI wheel 不满足需求时才走这条路径：文档明确其适用场景为本地使用或需要 AMD（BLIS）、ARM（KML）或自定义 CUDA 版本的定制构建。

准备步骤：

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

随后执行安装脚本：

./install.sh

执行前需要知道：该脚本会自动安装系统依赖（cmake、libhwloc-dev、pkg-config），会修改系统环境；并且默认用-march=native构建，产物只针对你当前的 CPU 优化，可能在其他或更旧的 CPU 上无法运行（文档明确标注了这一点）。脚本行为：自动检测 CPU 能力（AMX、AVX512_VNNI、AVX512_BF16）、为缺少 VNNI/BF16 的 CPU 自动启用软件回退。

也可以分两步执行：

./install.sh deps # 仅安装依赖 ./install.sh build # 构建并安装 kt-kernel

如果需要可移植到其他机器的构建产物，文档给出手动配置方式（CPUINFER_CPU_INSTRUCT取值NATIVE（默认，仅本机）、AVX512、AVX2、FANCY）：

# 通用发行版（适用于 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 要求（文档表格）：

AMD BLIS 后端用户在文档中被单独提示需按 AMD 专用安装指南操作（对应 doc/en/kt-kernel/amd_blis.md）；脚本的高级选项见 kt-kernel/scripts/README.md。

构建报错：CUDA Not Found 与 hwloc Not Found

源码构建（开启 CUDA 时）与依赖缺失时，文档给出两类报错的处理：

1. 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 中。若已安装但 CMake 找不到，按文档尝试：

export CMAKE_ARGS="-D CMAKE_CUDA_COMPILER=$(which nvcc)"

然后重新安装。注意这条仅适用于源码构建路径；PyPI 路径使用静态 CUDA 运行时，不依赖本机 CUDA toolkit，不会遇到该报错。

2. hwloc Not Found

Debian 系系统上按文档执行（需要 root/sudo 权限）：

sudo apt install libhwloc-dev

非 Debian 系系统按文档从源码构建 hwloc 安装。

验证结果与限制小结

• 完成标准：Python 验证片段能正常打印变体名、版本与CUDA support状态；kt version能列出 Python / CUDA / kt-kernel（含变体）信息。
• 变体不是"越强越好"的简单关系：6 个变体按 CPU 能力自动选择，AVX2是兜底变体，出现它说明 CPU 未满足更高指令集条件。
• CUDA 功能受 GPU 架构（CC 8.0+）与驱动（CUDA 11.8+/12.x）双重限制，Turing/Volta 旧卡不支持；CPU-only 机器上 CUDA 不可用是预期行为。
• 源码默认构建是-march=native的本机优化产物，跨机器部署需按前文的--manual方式指定目标指令集。

【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers