ktransformers README

The project's README from github.com/kvcache-ai/ktransformers. As one markdown file: README.md.

KTransformers

A Flexible Framework for Experiencing Cutting-edge LLM Inference/Fine-tune Optimizations

🎯 Overview | 🚀 Inference | 🎓 SFT | 🔥 Citation | 🚀 Roadmap(2026Q2)

🎯 Overview

KTransformers is a research project focused on efficient inference and fine-tuning of large language models through CPU-GPU heterogeneous computing. The project now exposes two user-facing capabilities from the kt-kernel source tree: Inference and SFT.

🔥 Updates


📦 Capabilities

🚀 Inference - High-Performance kt-kernel Serving

CPU-optimized kernel operations for heterogeneous LLM inference.

image

Key Features:

Quick Start:

cd kt-kernel
pip install .

Use Cases:

Performance Examples:

Model Hardware Configuration Total Throughput Output Throughput
DeepSeek-R1-0528 (FP8) 8×L20 GPU + Xeon Gold 6454S 227.85 tokens/s 87.58 tokens/s (8-way concurrency)

👉 Full Documentation →


🎓 SFT - Fine-Tuning with LlamaFactory

KTransformers × LlamaFactory integration for ultra-large MoE model fine-tuning. The new Cookbook provides an easy-to-use path from hardware checks and installation to BF16/FP8/INT8 configuration, LoRA/full training, resource planning, and troubleshooting.

LlamaFactory and KTransformers MoE fine-tuning architecture

Key Features:

Model GPU Memory Training Speed Hardware
DeepSeek-V3 ~80GB total 3.7 it/s 4x RTX 4090
DeepSeek-R1 ~80GB total 3.7 it/s 4x RTX 4090
Qwen3-30B-A3B ~24GB total 8+ it/s 1x RTX 4090

Quick Start:

cd /path/to/LLaMA-Factory
python -m pip install -e .
python -m pip install "ktransformers[sft]==0.7.0"
python -m pip install "sglang-kt==0.7.0"
CUDA_VISIBLE_DEVICES=0,1,2,3 accelerate launch \
  --config_file examples/ktransformers/accelerate/fsdp2_kt_int8.yaml \
  src/train.py \
  examples/ktransformers/train_lora/qwen3_5moe_lora_sft_kt.yaml

👉 Easy-to-Use Fine-Tuning Cookbook → 👉 Quick Start → 👉 Full Documentation →


🔥 Citation

If you use KTransformers in your research, please cite our paper:

@inproceedings{10.1145/3731569.3764843,
  title = {KTransformers: Unleashing the Full Potential of CPU/GPU Hybrid Inference for MoE Models},
  author = {Chen, Hongtao and Xie, Weiyu and Zhang, Boxin and Tang, Jingqi and Wang, Jiahao and Dong, Jianwei and Chen, Shaoyuan and Yuan, Ziwei and Lin, Chen and Qiu, Chengyu and Zhu, Yuening and Ou, Qingliang and Liao, Jiaqi and Chen, Xianglin and Ai, Zhiyuan and Wu, Yongwei and Zhang, Mingxing},
  booktitle = {Proceedings of the ACM SIGOPS 31st Symposium on Operating Systems Principles},
  year = {2025}
}

👥 Contributors & Team

Developed and maintained by:

We welcome contributions! Please feel free to submit issues and pull requests.

💬 Community & Support

📦 KT original Code

The original integrated KTransformers framework has been archived to the archive/ directory for reference. The project now organizes the two capabilities above from the kt-kernel source tree for clearer documentation and maintenance.

For the original documentation with full quick-start guides and examples, see:

ktransformers (kvcache-ai/ktransformers)

rocm
Searching Database…

What is this?KTransformers is a research framework for efficient inference and fine-tuning of large language models through CPU-GPU heterogeneous computing, letting huge MoE models run on hardware that doesn't have enough VRAM to hold them entirely on GPU.
Is this a standalone chat app or something I plug into my own serving stack?It's a framework/kernel library, not an app: you integrate its 'kt-kernel' Python API into inference servers like SGLang for serving, or into LlamaFactory for fine-tuning.
How do I get inference or fine-tuning running with it?The repo provides separate Quick Start entry points for Inference (via the kt-kernel Python API, often paired with SGLang) and SFT (via the LlamaFactory integration and the MoE Fine-Tuning Cookbook).
What hardware do I need to actually use it?It needs CPUs with AMX or AVX512/AVX2 instructions for the quantized kernels, plus a GPU (NVIDIA, AMD via ROCm, Intel Arc, or Ascend NPU); running the largest models like DeepSeek-R1 can require up to 382GB of DRAM or multiple GPUs.
Are there hardware limits I should know about before trying it?Some features were originally restricted to Intel CPUs with AMX; LoRA fine-tuning only recently gained support for plain AVX512 x86 CPUs (including AMD servers) without needing AMX, so older setups may miss newer optimizations.
Does it run on Windows, or only Linux servers?It runs natively on Windows as well as Linux, and supports multiple GPU backends including NVIDIA, AMD (ROCm), Intel Arc, and Ascend NPU.
What inference speed can I expect for DeepSeek-R1?With 8×L20 GPUs plus a Xeon Gold 6454S CPU, KTransformers reaches about 227.85 tokens/s total throughput and 87.58 tokens/s output throughput at 8-way concurrency for DeepSeek-R1-0528 (FP8).
Can I fine-tune a huge MoE model on just one consumer GPU?Yes — Qwen3-30B-A3B can be fine-tuned using roughly 24GB of GPU memory on a single RTX 4090, while DeepSeek-V3/R1 fine-tune using about 80GB total across 4x RTX 4090s.
Which models get day-0 support?Recent day-0 releases include GLM-5.3-flash, MiniMax-M3, GLM-5.2, Kimi-K2.5 and GLM-5, alongside ongoing support for DeepSeek-V3/R1, Qwen3 and experimental LLaMA 4.
What are similar projects?vllm, verl, sglang, MoE4All, decider, airllm, ms-swift, unsloth
Creator
kvcache-ai
Size
73 MB
Stars
19.6K
Age
2y
Commits · 90 Days