KTransformers 混合推理实战：在 24GB 显存台式机上运行 671B 的 DeepSeek-R1/V3
【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers
本篇基于仓库中的 DeepSeek-R1/V3 中文教程，完整还原 KTransformers 如何在单张 24GB 显存（4090D）+ 382GB~1TB 内存的台式机上，通过 CPU/GPU 异构卸载运行 671B 参数的 DeepSeek-R1/V3 量化模型。读完你将掌握local_chat.py单并发与server/main.py多并发两类运行方式、balance_serve后端与注入规则（optimize_rules）的配置方法，以及 AMX 内核与"选择性专家激活"两大加速手段的落地细节。
一、方案前提：为什么 24GB 显存能跑 671B 模型
DeepSeek-V3/R1 有 671B 参数、256 个路由专家，单卡显然放不下。KTransformers 的核心思路是按 DeepSeek 的 MoE 架构做职责切分：把计算密集、但参数庞大的专家（experts）矩阵乘法卸载到 CPU 内存，把MLA 注意力与 KVCache 卸载到 GPU。文档在"一些解释"一节把这一点归纳为：
与传统的基于层或 KVCache 卸载（如 llama.cpp 中的）不同，我们将专家计算卸载到 CPU，将 MLA/KVCache 卸载到 GPU，与 DeepSeek 的架构完美对齐，实现最佳效率。
这套切分之所以成立，是因为 DeepSeek 的 MLA 算子本身是计算密集型——"虽然全部在 CPU 上运行是可行的，但将繁重的计算任务卸载到 GPU 上能带来巨大的性能提升"。而 CPU 侧选择 Intel 平台，文档给出的理由是"英特尔目前是唯一支持 AMX 类似指令的 CPU 供应商，与仅支持 AVX 的替代方案相比，性能显著更好"。
先决条件（硬件基准）
文档声明的"最佳性能测试"配置为：
- CPU：Intel(R) Xeon(R) Gold 6454S，1T 内存（2 个 NUMA 节点），每插槽 32 核心，共 2 插槽 / 2 NUMA 节点
- GPU：4090D 24GB 显存
- 内存：标准 DDR5-4800 服务器内存（1TB）
说明：不同量化与版本对内存/显存下限不同，见下文基准章节。单插槽 32 核心 + 382GB 内存是 V0.2 的最低门槛；V0.3-Preview（BF16 在线量化）则上升到 644GB 内存。
二、基准测试结果
以下数据与命令均来自原文档，用于横向对比 KTransformers 与 llama.cpp 在同一台双插槽 64 核心机器上的表现。
V0.2（Q4_K_M 量化，382GB 内存）
设置：
- Model：DeepseekV3-q4km（int4）
- CPU：Xeon Gold 6454S，每插槽 32 核心，2 插槽，2 NUMA 节点
- GPU：4090D 24GB 显存
- 测试在充分预热后进行
内存占用：
- 单插槽：382GB 内存，至少 14GB 显存
- 双插槽：1T 内存，至少 14GB 显存
基准测试结果（"6 个专家"情形属于 V0.3 预览版内容）：
| Prompt（500 tokens） | 双插槽 Ktrans（6 个专家） | 双插槽 Ktrans（8 个专家） | 单插槽 Ktrans（6 个专家） | 单插槽 Ktrans（8 个专家） | llama.cpp（8 个专家） |
|---|---|---|---|---|---|
| 预填充（Prefill）token/s | 97.32 | 82.94 | 65.14 | 54.21 | 10.31 |
| 解码（Decode）token/s | 13.69 | 12.208 | 10.303 | 8.73 | 4.51 |
最高加速比：解码 3.03 倍，预填充 9.44 倍。
V0.3-Preview（BF16 在线量化，AMX + 选择性专家）
设置：
- Model：DeepseekV3-BF16（在线量化为 CPU 的 int8 和 GPU 的 int4）
- CPU：Xeon Gold 6454S，每插槽 32 核心，2 插槽，2 NUMA 节点
- GPU：(1~4)× 4090D 24GB 显存（更长的 prompt 需要更多显存）
内存占用：644GB 内存，至少 14GB 显存。
基准测试结果：
| Prompt 长度 | 1K | 2K | 4K | 8K |
|---|---|---|---|---|
| KTrans（8 个专家）Prefill token/s | 185.96 | 255.26 | 252.58 | 195.62 |
| KTrans（6 个专家）Prefill token/s | 203.70 | 286.55 | 271.08 | 207.20 |
KTrans V0.3 的预填充比 V0.2 快 3.45 倍，比 llama.cpp 快 27.79 倍；解码速度与 V0.2（6 个专家版）相同，故省略。
文档将主要加速来源归结为两点：
- 英特尔 AMX 指令集+ 专门设计的缓存友好内存布局；
- 专家选择策略：根据离线配置文件结果选择更少的专家。
对减少激活专家数量而质量不变的判断，文档原文是：
从我们对 DeepSeekV2、DeepSeekV3 和 DeepSeekR1 的研究中，当我们略微减少推理中的激活专家数量时，输出质量没有变化。但解码和预填充的速度加快了，这令人鼓舞。
三、运行方式
仓库现状说明：本文教程对应的是 v0.2 / v0.3 时期的仓库布局。当前仓库已重构——旧版
ktransformersPython 包整体移入archive/ktransformers/，高性能 CPU 内核独立为kt-kernel/，顶层 install.sh 也改写为 "sglang + kt-kernel" 一键安装脚本。因此下文命令中的路径以当前仓库实际位置为准：local_chat.py、server/main.py、注入规则与旧版安装脚本都位于archive/下，AMX 专家内核位于 kt-kernel/operators/amx/。
1. 多并发展示（balance_serve 后端）
多并发需要额外编译调度器 C++ 代码。依赖与启动流程如下（依赖安装与git submodule update --init --recursive为文档原始步骤）：
sudo apt install libtbb-dev libssl-dev libcurl4-openssl-dev libaio1 libaio-dev libfmt-dev sudo apt-get install libgflags-dev zlib1g-dev patchelf git submodule update --init --recursive # 如果使用双 numa 版本 USE_BALANCE_SERVE=1 USE_NUMA=1 bash ./install.sh # 如果使用单 numa 版本 USE_BALANCE_SERVE=1 bash ./install.sh # 启动命令 python ktransformers/server/main.py \ --model_path <your model path> \ --gguf_path <your gguf path> \ --cpu_infer 62 \ --optimize_config_path <inject rule path> \ --port 10002 \ --chunk_size 256 \ --max_new_tokens 1024 \ --max_batch_size 4 \ --cache_lens 32768 \ --backend_type balance_serve（对应实现入口为 server/main.py。）
路径参数说明：
<your model path>：本地路径或在线模型名（如deepseek-ai/DeepSeek-V3）。在线连接有问题时可尝试镜像。<your gguf path>：也支持在线路径，但体量大，建议下载并量化后使用目录路径。<inject rule path>：注入规则 yaml 文件地址。仓库在 optimize_rules 目录 提供了 DeepSeek-V3-Chat-serve.yaml 与 DeepSeek-V3-Chat-fp8-linear-ggml-experts-serve.yaml，分别对应 Q4_K_M 与 hybrid 两类权重。
关键命令行参数（对应 local_chat.py 的入参签名，可交叉印证）：
| 参数 | 含义 |
|---|---|
--max_new_tokens 1024 | 最大输出 token 长度。若答案被截断可增大，但会增加显存压力并降低生成速度 |
--chunk_size 256 | 引擎单次运行最大 token 数 |
--cache_lens 32768 | 调度器申请的 KVCache 总长度；所有请求共享 32768 token 对应的 KVCache，请求完成后释放占用空间 |
--backend_type balance_serve | v0.2.4 新增的多并发后端引擎；原单并发引擎为ktransformers |
--max_batch_size 4 | 引擎单次运行最多处理的请求数（prefill + decode），仅用于balance_serve |
--cpu_infer 62 | 使用的 CPU 核心数（详见下文"一些解释"） |
多并发场景额外有numactl -N 1 -m 1的目的：避免 NUMA 节点之间的数据传输。测试 R1 时若跳过思考，可加--force_think，见文末 FAQ。
2. V0.2 展示
单插槽版本（32 核心）
git submodule init git submodule update numactl -N 1 -m 1 python ./ktransformers/local_chat.py \ --model_path <your model path> \ --gguf_path <your gguf path> \ --prompt_file <your prompt txt file> \ --cpu_infer 33 \ --max_new_tokens 1000 # 看到聊天提示后，按回车键加载文本提示文件双插槽版本（64 核心）
双插槽需在安装前设置环境变量USE_NUMA=1（export USE_NUMA=1；若已安装，需重新安装并带上该环境变量）：
git submodule init git submodule update export USE_NUMA=1 make dev_install # 或 sh ./install.sh python ./ktransformers/local_chat.py \ --model_path <your model path> \ --gguf_path <your gguf path> \ --prompt_file <your prompt txt file> \ --cpu_infer 65 \ --max_new_tokens 1000 # 看到聊天提示后，按回车键加载文本提示文件参数含义与单插槽相同，仅因双插槽把cpu_infer提到 65。
3. V0.3 展示（双插槽 64 核心，wheel 包）
V0.3 预览版当时提供二进制 wheel 分发，从本仓库对应 Release 页面下载ktransformers-0.3.0rc0+cu126torch26fancy-cp311-cp311-linux_x86_64.whl后安装即可：
# 从 Release 下载对应 wheel 后 pip install ./ktransformers-0.3.0rc0+cu126torch26fancy-cp311-cp311-linux_x86_64.whl python -m ktransformers.local_chat \ --model_path <your model path> \ --gguf_path <your gguf path> \ --prompt_file <your prompt txt file> \ --cpu_infer 65 \ --max_new_tokens 1000 # 看到聊天提示后，按回车键加载文本提示文件参数含义与 V0.2 相同，双插槽故cpu_infer设为 65。
四、参数与实现的源码印证
local_chat.py的入参签名能直接印证上述命令参数真实存在。在 archive/ktransformers/local_chat.py 中可看到：
max_new_tokens: int = 1000, cpu_infer: int = Config().cpu_infer, prompt_file: str | None = None, force_think: bool = False, ... Config().cpu_infer = cpu_infercpu_infer通过Config().cpu_infer注入全局配置；文档强调"超过物理核心数量是可以的，但并不是越多越好，应根据实际核心数量适当降低"。prompt_file在交互中被读取后作为输入（content = open(prompt_file, "r").read()），并拼入max_new_tokens一并下发到model.generate。force_think默认False，用于控制 R1 是否强制进入思考模式。
五、混合推理架构：从注入规则看"专家到 CPU、MLA 到 GPU"
文档描述的卸载策略，在注入规则 yaml 中有逐算子的落地。以 DeepSeek-V3-Chat-serve.yaml 为例，其中把每层self_attn的mlp.experts替换为自定义 MoE 内核，并显式声明设备路由：
- match: name: "^model\\.layers\\..*\\.mlp\\.experts$" replace: class: ktransformers.operators.experts.KTransformersExpertsV2 # custom MoE Kernel with expert paralleism kwargs: prefill_device: "cuda" prefill_op: "KExpertsTorch" generate_device: "cpu" generate_op: "KExpertsCPU" out_device: "cuda" recursive: False这段规则正是"专家解码走 CPU（KExpertsCPU）、预填充走 GPU（KExpertsTorch）、输出回到 CUDA"的声明式表达；同时self_attn被替换为优化过的 MLA 实现（balance_serve_attention.flashinfer_attn），lm_head与linear使用 Marlin/Torch 量化算子。换言之，注入规则文件就是文档所述"架构对齐"的可执行配置，<inject rule path>直接决定哪些算子落在哪块设备。
AMX 加速内核的当前源码位于 kt-kernel/operators/amx/（含moe.hpp、fp8-moe.hpp、fp8-perchannel-moe.hpp、k2-moe.hpp等专家算子），配套基准脚本如 bench_k2_moe_amx.py、bench_moe_amx.py 可用于在 Intel 平台上复现 AMX 专家内核的性能。文档同时说明 NUMA 复制的取舍：
为了避免节点之间的数据传输成本，我们在两个节点上 "copy" 了关键矩阵，这会增加内存占用，但会加速预填充和解码过程……加载权重时速度较慢，因此加载时请耐心等待并监控内存使用情况。
六、常见问题（FAQ）
R1 不返回思考过程
测试 R1 时可能跳过思考。解决方法是追加参数：
--force_think true该参数在 local_chat.py 中以force_think: bool = False定义。更多问题见 FAQ。
七、适用前提与限制小结
- 本文数据与命令基于 v0.2 / v0.3 时期的 DeepSeek-V3/R1 量化方案（Q4_K_M 或 BF16 在线量化）。V0.3 的 AMX 加速强依赖 Intel AMX 指令集，非 AMX 平台仅能获得 AVX 级别性能。
- 显存下限约 14GB（单卡 24GB 足够），内存占用随版本/量化在 382GB~1TB 之间波动。
- 当前仓库已把旧版推理包移入
archive/，并把内核收敛到kt-kernel/，最新的推理/微调入口以 kt-kernel 及其 README 为准；本文保留 v0.2/v0.3 的复现命令以便历史对照。 - 文档"问题"一节列出的当时遗留项（服务器集成、
local_chat多行输入支持）属于历史状态，是否修复请以当前仓库代码为准。
【免费下载链接】ktransformersA Flexible Framework for Experiencing Heterogeneous LLM Inference/Fine-tune Optimizations项目地址: https://gitcode.com/GitHub_Trending/ktr/ktransformers
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
