KTransformers 完整部署指南如何在单机上跑通大模型异构推理【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers读完本文你可以在一台 Linux 服务器上按 6 步完成 KTransformers 的部署并用「CPU 承载 MoE 专家 GPU 承载注意力」的 CPU-GPU 异构推理方式跑通大模型服务。每一步都给出关键命令和验证方法不需要你理解内核细节照着走即可。全文覆盖安装步骤、启动参数、性能调优与排障速查。一、开始之前环境自检表动手前先按下表核对自己的机器。KTransformers 的 CPU 端算子会根据指令集自动选择内核AMX / AVX512 / AVX2所以 CPU 型号直接决定你能用哪个后端。检查项推荐配置说明CPUx86_64至少支持 AVX2AVX512/AMX 更佳如 Xeon Gold 6454S决定可用后端AMXINT8 / BF16 / LLAMAFILE 等GPUNVIDIA计算能力 8.0 及以上RTX 4090、A100、H100 等V100、T4 等老架构不在支持列表内存671B 级模型建议 382GB 起专家权重常驻内存以官方文档中各模型条目为准操作系统Ubuntu 22.04 x86_6420.04 自带的 cmake 版本偏旧容易在编译期报错Python3.10 / 3.11 / 3.12kt-kernel 预编译 wheel 只覆盖这三个版本选择 22.04 的原因很简单它自带的 gcc/cmake 版本满足 C 与 CUDA 编译要求且社区资料最多。确认无误后看一下下图对整体架构有个概念——热点专家放 GPU冷专家放 CPU 内存两端并行调度。二、三步装完软件栈第 1 步克隆仓库并准备 Python 环境先克隆源码。即使你走 pip 安装仓库里的权重转换脚本和示例也值得留着。git clone https://gitcode.com/gh_mirrors/ktr/ktransformers cd ktransformers conda create -n kt python3.11 conda activate kt验证方法运行python --version确认是 3.11.xgit submodule status应能看到 third_party 下的子模块已拉取源码编译 SGLang 时需要。第 2 步安装 kt-kernel 与 SGLang 适配版大多数用户直接用预编译包即可无需本地编译pip install kt-kernel sglang-kt注意sglang-kt是 KTransformers 适配过的 fork与官方sglang包不兼容。若之前装过官方版先执行pip uninstall sglang -y再安装。偏好源码编译的话直接运行仓库根目录的./install.sh它会自动检测 CPU 指令集、安装 cmake 等系统依赖并构建详见 kt-kernel 文档。验证方法运行kt version输出应列出 Python 版本、CUDA 版本、kt-kernel 版本号及括号内的指令集变体如amx。变体名与你的 CPU 不匹配时参考后文排障表。第 3 步准备 GPU 与 CPU 两份权重异构推理需要两份权重GPU 端用模型原始权重CPU 端专家权重按后端二选一——AMXINT4/AMXINT8 后端用项目自带脚本从 BF16/FP8 转换LLAMAFILE 后端则直接下 GGUF 量化文件跳过转换。以 AMXINT8 为例python scripts/convert_cpu_weights.py \ --input-path /path/to/model \ --input-type bf16 \ --output /path/to/cpu-weights \ --quant-method int8验证方法ls /path/to/cpu-weights能看到非空的权重分片。更多转换选项低内存模式等见 脚本目录说明。三、首次启动与验证最小化启动命令如下只保留关键参数完整示例可到 kt-kernel 文档 中的 Qwen3-30B-A3B 一节参考python -m sglang.launch_server \ --host 0.0.0.0 --port 8000 \ --model /path/to/model \ --trust-remote-code \ --kt-method AMXINT8 \ --kt-weight-path /path/to/cpu-weights \ --kt-cpuinfer 64 \ --kt-threadpool-count 2关键参数说明参数含义建议值--kt-methodCPU 专家推理后端按 CPU 指令集选AMXINT8、BF16、LLAMAFILE 等--kt-weight-pathCPU 专家权重目录第 3 步转换的输出路径--kt-cpuinferCPU 推理线程数物理核数lscpu中 CPU(s) ÷ 每核线程数不要设成超线程数--kt-threadpool-count线程池数量NUMA 节点数单路机器填 1双路填 2--kt-num-gpu-experts放在 GPU 上的专家数按显存余量调整24GB 卡示例约 32如何确认启动成功日志出现The server is fired up and ready to roll!字样后另开终端运行下面两条命令。前者返回模型列表说明服务就绪后者能收到流式回复即全链路打通。curl http://localhost:8000/v1/models kt chat四、性能数据与调优以下是项目 README 中给出的实测吞吐硬件为 8×L20 GPU Xeon Gold 6454S模型硬件配置总吞吐输出吞吐DeepSeek-R1-0528FP88×L20 Xeon Gold 6454S227.85 tokens/s87.58 tokens/s8 路并发精度方面按 精度基准文档 的 MMLU 1k 抽样结果量化后端与云端基线基本持平CPU 权重格式MMLU1k 抽样云端基线BF1681.981.6Q4_K_M81.481.6调优时优先动下面这几个参数效果最明显参数 / 变量作用建议值--kt-cpuinferCPU 线程数设成超线程数反而降速物理核数--kt-threadpool-count跨 NUMA 域打散内存访问NUMA 节点数--kt-num-gpu-experts越大延迟越低但显存占用越高按显存余量留 10%~20% 富余--kt-max-deferred-experts-per-token专家流水线化执行降低延迟1~4设 5~7 可能有精度损失KT_KERNEL_CPU_VARIANT强制指定指令集变体排查用amx/avx512/avx2KT_KERNEL_DEBUG打开变体自动选择日志排查时设 1五、排障速查现象可能原因解决方式编译期报CUDA compiler not foundnvcc 不在 PATHexport CMAKE_ARGS-D CMAKE_CUDA_COMPILER$(which nvcc)后重装构建提示找不到 hwloc系统依赖缺失sudo apt install libhwloc-dev pkg-config后重装启动报未识别的--kt-*参数装了官方 sglang 而非适配版pip uninstall sglang -y后重装sglang-ktCPU 速度明显低于预期自动检测选错内核变体用KT_KERNEL_CPU_VARIANT指定变体配合KT_KERNEL_DEBUG1看选择日志GPU OOM放 GPU 的专家过多调小--kt-num-gpu-experts或降低--mem-fraction-static六、收尾到这里KTransformers 的部署闭环已经完成软件栈三步装完异构推理服务可以对外提供 OpenAI 兼容接口冷热专家在 CPU 与 GPU 之间自动分配。接下来你可以沿着 kt-kernel 示例目录 换后端、换模型或者接入 LlamaFactory 体验同一套权重下的 MoE 微调。异构推理的天花板还远没到值得持续跟进。【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考