Files Expand file tree File metadata and controls 高性能 KTransformers 内核库，提供面向 CPU 的高效 MoE 推理内核，支持 AMX 和 AVX 等后端。 KT-Kernel 说明 特性 安装 先决条件 快速安装（推荐） 手动配置（进阶） 验证安装 与 SGLang 集成 安装步骤 1. 安装 SGLang 2. 准备权重 3. 启动 SGLang Server 完整示例：Qwen3-30B-A3B 方案 A：AMX 后端（AMXINT8） 方案 B：LLAMAFILE 后端（GGUF） KT-Kernel 参数 直接使用 Python API 高级选项 构建配置 手动安装 1. 安装系统依赖 2. 配置构建参数 3. 构建并安装 错误排查 找不到 CUDA 找不到 hwloc 权重量化 提交前必读 安装 先决条件 快速安装（推荐） 手动配置（进阶） 与 SGLang 集成 安装步骤 1. 安装 SGLang 2. 准备权重 3. 启动 SGLang Server 完整示例：Qwen3-30B-A3B 方案 A：AMX 后端（AMXINT8） 方案 B：LLAMAFILE 后端（GGUF） KT-Kernel 参数 安装步骤 1. 安装 SGLang 2. 准备权重 3. 启动 SGLang Server 3. 启动 SGLang Server 完整示例：Qwen3-30B-A3B 方案 A：AMX 后端（AMXINT8） 方案 B：LLAMAFILE 后端（GGUF） 方案 A：AMX 后端（AMXINT8） 方案 B：LLAMAFILE 后端（GGUF） 直接使用 Python API 高级选项 构建配置 手动安装 1. 安装系统依赖 2. 配置构建参数 3. 构建并安装 手动安装 1. 安装系统依赖 2. 配置构建参数 3. 构建并安装 错误排查 找不到 CUDA 找不到 hwloc ✅ 带 AMX 的 Intel CPU ：已支持（基于转换为 INT4/INT8 格式的权重） ✅ 通用 CPU（llamafile 后端） ：已支持（基于 GGUF 格式的权重） ✅ 带 BLIS 的 AMD CPU ：已支持（int8 的 prefill 和 decode） ✅ Kimi-K2 原生 INT4（RAWINT4） ：支持 AVX512 CPU（CPU-GPU 共享 INT4 权重）- 使用指南 CPU 友好的 MoE 内核 ：针对指令集优化的高吞吐 MoE 专家内核。 AMX INT4/INT8 后端 ：面向支持 AMX 的服务器提供 INT4 / INT8 量化专家推理后端。 Llamafile CPU 后端 ：基于 Llamafile 的 AVX2/AVX512 MoE 后端，适用于通用 CPU 部署。 NUMA 感知执行 ：为多路 / 多 NUMA 机器设计的线程池和内存布局。 从源码安装（本机使用或自定义构建） 适用于本地安装，或需要 AMD (BLIS)、ARM (KML) 或自定义 CUDA 版本的场景。 首先初始化子模块并创建 conda 环境： 只需运行安装脚本，它会自动检测 CPU 并优化性能： 自动检测 CPU 能力（AMX、AVX512_VNNI、AVX512_BF16） 安装系统依赖（ cmake 、 libhwloc-dev 、 pkg-config ） 为 你的 CPU 构建优化二进制（使用 -march=native ） 软件回退机制 ：为不支持 VNNI/BF16 的 CPU 自动启用 软件回退支持（AVX512 后端）： ✅ VNNI 回退：使用 AVX512BW 指令 ✅ BF16 回退：使用 AVX512F 指令 ✅ 老的 AVX512 CPU（Skylake-X、Cascade Lake）可以运行 RAWINT4（使用回退） ⚠️ 可移植性说明： 默认构建针对你的特定 CPU 优化，可能无法在不同/更老的 CPU 上运行。如需打包分发或跨机器部署，请参见下方的 手动配置 。 ⚠️ AMD BLIS 后端用户： 请参见 安装指南 了解 AMD 专用配置。 KT-Kernel 可以单独通过 Python API 使用，也可以集成到 SGLang 中用于生产部署。 本节描述如何与 SGLang 集成，实现 CPU-GPU 混合（异构）推理：将“热” experts 放在 GPU 上，“冷” experts 放在 CPU 上，以达到资源利用和性价比的平衡。 安装 kvcache-ai 分支的 SGLang（kt-kernel 需要此分支）： 重要: 请使用 sglang-kt （kvcache-ai 分支），而非官方 sglang 包。如已安装官方版本，请先卸载： pip uninstall sglang -y 要进行异构推理，需要同时准备 GPU 权重和 CPU 侧 experts 对应的权重，具体格式取决于后端类型： GPU 权重： 使用 SGLang 所需的模型权重（例如 Hugging Face 上的原始模型目录或已量化好的 GPU 权重）。 CPU 权重（AMX 后端： AMXINT4 / AMXINT8 ）： 通过提供的脚本将权重量化为适配 AMX 的 INT4/INT8 格式： --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 Server 在通常的 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 上的 experts 数量 --kt-max-deferred-experts-per-token ：每个 token 延迟到 CPU 的 experts 数量，用于流水线执行 更多调优建议见 KT-Kernel 参数 一节。 完整示例：Qwen3-30B-A3B 该示例展示从下载权重到启动服务的完整流程，分别演示 AMX 后端 和 LLAMAFILE 后端 两种方案。 GPU ：NVIDIA RTX 4090 24GB CPU ：2x Intel Xeon Gold 6454S（共 64 个物理核，128 线程，2 个 NUMA 节点） 模型 ： Qwen3-30B-A3B --kt-cpuinfer 64 ：设为物理核数（64），而不是 128 线程

--kt-threadpool-count 2 ：检测到 2 个 NUMA 节点（双路系统） --kt-num-gpu-experts 32 ：在 24GB 显存下，对该模型可以大约放 32 个 experts 在 GPU 上（具体取决于模型结构和实际内存占用） --kt-max-deferred-experts-per-token 2 ：启用流水线执行；允许 CPU 处理下一批 token 的同时，GPU 完成当前批次 方案 A：AMX 后端（AMXINT8） 适用于支持 AMX 指令集的 Intel CPU。 步骤 2：转换为 CPU 权重（AMXINT8） 步骤 3：启动 SGLang 服务 方案 B：LLAMAFILE 后端（GGUF） 适用于通用 CPU（无需 AMX 支持），直接使用预量化的 GGUF 权重。 步骤 1：下载 GPU 权重（原始模型） 步骤 2：下载 CPU 权重（GGUF 格式） 步骤 3：启动 SGLang 服务 kt-method ：根据 CPU 能力和权重格式选择： AMXINT4 ：在 AMX CPU 上 INT4 量化时具有最佳性能（但可能对某些模型有较大精度影响，例如 Qwen3-30B-A3B） AMXINT8 ：在 AMX CPU 上提供更高精度的 INT8 量化方案 RAWINT4 ：CPU 和 GPU 共享原生 INT4 权重（仅限 AMX 后端，目前仅支持 Kimi-K2-Thinking 模型）。详见 Kimi-K2-Thinking 原生推理教程 。 LLAMAFILE ：基于 AVX2/AVX512 的通用 CPU 后端，性能较 AMX 略低，但适用范围更广 kt-method ：根据 CPU 能力和权重格式选择： AMXINT4 ：在 AMX CPU 上 INT4 量化时具有最佳性能（但可能对某些模型有较大精度影响，例如 Qwen3-30B-A3B） AMXINT8 ：在 AMX CPU 上提供更高精度的 INT8 量化方案 RAWINT4 ：CPU 和 GPU 共享原生 INT4 权重（仅限 AMX 后端，目前仅支持 Kimi-K2-Thinking 模型）。详见 Kimi-K2-Thinking 原生推理教程 。 LLAMAFILE ：基于 AVX2/AVX512 的通用 CPU 后端，性能较 AMX 略低，但适用范围更广 kt-cpuinfer ：设置为 物理核数 （不是线程数）。 查看物理核数： 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-cpuinfer ：设置为 物理核数 （不是线程数）。 查看物理核数： 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 节点数为准。 常见配置：单路 1–2，双路 2–4 正确设置有助于充分利用跨 NUMA 域的内存带宽。 kt-threadpool-count ：设置为 NUMA 节点数 。 查看 NUMA 数： lscpu | grep "NUMA node(s)" 或： numactl --hardware | grep "available" 注意 ：NUMA 节点数不等同于物理 CPU 数量： 它表示内存域，可能在单颗 CPU 内被拆分，也可能跨多颗 CPU。 请以 lscpu 输出的 NUMA 节点数为准。 它表示内存域，可能在单颗 CPU 内被拆分，也可能跨多颗 CPU。 请以 lscpu 输出的 NUMA 节点数为准。 常见配置：单路 1–2，双路 2–4 正确设置有助于充分利用跨 NUMA 域的内存带宽。 kt-num-gpu-experts ：根据 GPU 显存和实际性能测试决定： GPU 上的 experts 越多 → 延迟越低，但显存占用越高（可能 OOM） kt-num-gpu-experts ：根据 GPU 显存和实际性能测试决定： GPU 上的 experts 越多 → 延迟越低，但显存占用越高（可能 OOM） kt-max-deferred-experts-per-token ：用于开启 CPU-GPU 流水线： 0 ：完全同步执行（简单但延迟较高） 1–4 ：推荐范围，一部分 experts 延迟到 CPU，在延迟和质量之间取得较好平衡（需要按模型调参） 5–7 ：可以获得更低延迟，但存在明显精度下降风险，请谨慎使用 kt-max-deferred-experts-per-token ：用于开启 CPU-GPU 流水线： 0 ：完全同步执行（简单但延迟较高） 1–4 ：推荐范围，一部分 experts 延迟到 CPU，在延迟和质量之间取得较好平衡（需要按模型调参） 5–7 ：可以获得更低延迟，但存在明显精度下降风险，请谨慎使用 kt-gpu-prefill-token-threshold （仅 RAWINT4）：控制原生 INT4 推理的 prefill 策略： ≤ 阈值 ：使用 CPU+GPU 混合 prefill。无需额外显存，但随着 token 数量增加性能会缓慢下降。 > 阈值 ：使用分层 GPU prefill。长序列性能更好，但需要约 9GB+ 额外显存。 仅在使用 --kt-method RAWINT4 时生效。目前仅支持 Kimi-K2-Thinking 模型。 kt-gpu-prefill-token-threshold （仅 RAWINT4）：控制原生 INT4 推理的 prefill 策略： ≤ 阈值 ：使用 CPU+GPU 混合 prefill。无需额外显存，但随着 token 数量增加性能会缓慢下降。 > 阈值 ：使用分层 GPU prefill。长序列性能更好，但需要约 9GB+ 额外显存。 仅在使用 --kt-method RAWINT4 时生效。目前仅支持 Kimi-K2-Thinking 模型。 直接使用 Python API 如果不集成 SGLang，也可以直接通过 Python API 单独使用 KT-Kernel： 如需打包分发、跨机器部署或构建可移植二进制，需要手动指定目标指令集： 可选：覆盖 VNNI/BF16 检测 运行 ./install.sh --help 查看所有可用选项。 手动安装（不使用 install.sh） 如果你不想使用 install.sh 脚本： cmake （推荐： conda install -y cmake ） libhwloc-dev 和 pkg-config 请确认已安装 CUDA Toolkit 且 nvcc 在系统 PATH 中。 在 Debian 系发行版上可以直接： 或从源码构建： https://www.open-mpi.org/projects/hwloc/ 对于 AMX 后端（ AMXINT4 / AMXINT8 ），CPU 侧 experts 需要通过提供的脚本转换为适配 AMX 的 INT4/INT8 格式： 支持的格式： FP8、FP16、BF16 → INT4/INT8 对于 LLAMAFILE 后端（ LLAMAFILE ），CPU 侧 experts 直接从 GGUF 权重中加载。 你 不需要 运行 AMX 转换脚本；只需从互联网上下载 GGUF 模型（例如 Hugging Face 上的 GGUF 仓库），并在 weight_path 或 SGLang 的 --kt-weight-path / --model 中指向该 GGUF 目录即可。KT-Kernel 支持多种 GGUF 量化格式，如 Q4_KM 、 Q4_K 、 Q5_K 等。 更多详细文档、高级参数和低显存模式，请参见 scripts/README.md 。 提交信息应符合 Conventional Commits 规范： https://www.conventionalcommits.org/ 在提交前请先格式化代码： 你可能需要一个较新的 clang-format（至少 18），在 conda 环境中可以： 并且建议安装 black 用于 Python 代码格式化：