Ktransformers

ktransformers是清华开源的一款专为大模型设计的高效推理服务框架。通过整合多项创新技术，包括优化的 CPU/GPU 异构硬件调度、MoE 模型的稀疏矩阵卸载策略、高效算子优化以及 CUDA Graph 加速等，这一框架显著降低了对硬件的依赖需求，同时显著提升了推理效率。官方给的测试中在 24GB 显存的硬件条件下，ktransformers 已成功实现 DeepSeek R1 671B 4bit 量化模型的部署，且单个实例推理速度可达 14 tokens/秒（截至 2025 年 3 月，仅支持 MoE架构的模型）。

前提信息

• Linux平台下 RTX4090 x 4 +512DRAM，部署4bit量化版
• Ktransformers版本 0.2.1，docker镜像 approachingai/ktransformers:0.2.1(截止20250224 Docker hub中仅有非官方版的0.3.x版本镜像)
• CPU支持avx512指令集（可通过命令 lscpu查看是否支持，信息里面有个Flags参数）

Docker部署

• 官方docker镜像下载（若下载失败，百度下docker镜像源）
  docker pull approachingai/ktransformers:0.2.1
• 启动Ktranformers容器
  docker run -d --runtime nvidia --network=host --gpus all -v /models:/workspace/models --env "TRANSFORMERS_OFFLINE=0" --env "HF_HUB_OFFLINE=0" --name ktransformers -itd approachingai/ktransformers:0.2.1
• 进入容器
  docker exec -it ktransformers /bin/bash
• 启动Ktransformers本地聊天
  • GIT_LFS_SKIP_SMUDGE=1 git clone https://www.modelscope.cn/deepseek-ai/DeepSeek-R1.git
  • 注意下面命令中model_path参数要指向上述命令中的DeepSeek-R1目录，max_new_tokens要重新指定，默认只有300，cpu_infer默认只有10
  • python -m ktransformers.local_chat --gguf_path /workspace/models/DeepSeek-R1-GGUF/Deepseek-R1-Q4_K_M/ --model_path DeepSeek-R1 --optimize_rule_path /workspace/ktransformers/ktransformers/optimize/optimize_rules/DeepSeek-V3-Chat-multi-gpu-4.yaml --max_new_tokens 2048 --cpu_infer 64 --port 10012
• 启动Ktransformers的服务版
  • ktransformers --gguf_path /workspace/models/DeepSeek-R1-GGUF/Deepseek-R1-Q4_K_M/ --model_path DeepSeek-V3 --model_name deepseek-r1-671b --optimize_config_path /workspace/ktransformers/ktransformers/optimize/optimize_rules/DeepSeek-V3-Chat-multi-gpu-4.yaml --max_new_tokens 2048 --cpu_infer 64--port 10012--batch_size 5 --web True
  • 如果上述命令中指定了参数：–web True，则可开启web聊天页面：http://localhost:10012/web/index.html#/chat

性能测试

• 官方：单机RTX 4090下，Ktransformers 生成速度为13.69 tokens/s, 同比llama.cpp为4.51tokens/s, 速度提升303%

问题记录

• 1、【启动遇到：** Illegal instruction (core dumped) ** 】
  问题及解决方法：官方镜像提供的ktransformers版本是0.2.1+cu121torch23fancy版本，而我的cpu支持avx512指令集，通过更新ktransformers版本为0.2.1.post1+cu121torch23avx512解决。官方发布的release版本地址：Github.

• 2、【启动遇到： ValueError: vector::_M_default_append 】
  问题及解决方法：

  • 合并GGUF文件时使用Linux命令 *cat .gguf -> deepseek-r1.gguf，可能导致了文件的损坏，可通过llama.cpp的命令 ./llama-gguf-split --merge [gguf in] [gguf out] 解决。其它解决方法可参考官方的issue.
  • 启动ktransformer时指定–cpu_infer具体数值，比如***–cpu_infer 64***.

• 3、【启动提示：flashinfer not found, use triton for linux】
  问题及解决方法：参考 【FlashInfer-Github】或者【FlashInfer安装与配置完全指南】进行flashinfer安装

• 4、【OpenAI SDK调用问题：RuntimeError: shape mismatch: value tensor of shape [5, 1, 1, 512] cannot be broadcast to indexing result of shape [1, 1, 512]】
  问题及解决方法：

  • 服务形式的版本启动时 batch size 参数设置了大于1
  • 测试影响的版本：0.2.1、0.2.2、0.2.3（其他版本未知）

参考资源

• KTransformers：告别天价显卡！国产框架让单卡24G显存跑DeepSeek-R1 671B大模型：推理速度飙升28倍
• KTransformers: How to Run DeepSeek-R1
• DeepSeek-R1大模型学习笔记（架构、训练、Infra、复现代码）
• FlashInfer安装与配置完全指南