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)

Searching Database…

Что это такое?KTransformers — исследовательский фреймворк для эффективного инференса и дообучения больших языковых моделей с помощью гетерогенных вычислений на CPU и GPU. Он позволяет запускать огромные MoE-модели на оборудовании, где видеопамяти (VRAM) недостаточно, чтобы разместить их целиком на GPU.
Это готовое чат-приложение или то, что я встраиваю в собственную инфраструктуру для инференса?Это фреймворк и библиотека ядра, а не приложение: вы интегрируете его Python API kt-kernel в серверы инференса, например SGLang, для обслуживания запросов, либо в LlamaFactory для дообучения.
Как запустить инференс или дообучение с его помощью?В репозитории есть отдельные руководства Quick Start: для инференса (через Python API kt-kernel, часто вместе с SGLang) и для SFT (через интеграцию с LlamaFactory и MoE Fine-Tuning Cookbook).
Какое железо нужно, чтобы этим реально пользоваться?Нужны процессоры с инструкциями AMX или AVX512/AVX2 для квантованных ядер, а также GPU (NVIDIA, AMD через ROCm, Intel Arc или Ascend NPU). Запуск самых крупных моделей, например DeepSeek-R1, может требовать до 382 ГБ памяти DRAM или нескольких GPU.
Есть ли аппаратные ограничения, которые стоит знать, прежде чем пробовать?Некоторые функции изначально были доступны только на процессорах Intel с AMX. LoRA-дообучение лишь недавно получило поддержку обычных x86-процессоров с AVX512 (включая серверы AMD) без AMX, поэтому старые конфигурации могут не получать новых оптимизаций.
Работает ли это на Windows или только на Linux-серверах?Оно работает нативно как на Windows, так и на Linux и поддерживает несколько бэкендов GPU: NVIDIA, AMD (ROCm), Intel Arc и Ascend NPU.
Какую скорость инференса можно ожидать для DeepSeek-R1?На системе с 8×L20 GPU и процессором Xeon Gold 6454S KTransformers достигает примерно 227.85 токенов/с общей пропускной способности и 87.58 токенов/с выходной пропускной способности при параллельной обработке 8 запросов для DeepSeek-R1-0528 (FP8).
Можно ли дообучить огромную MoE-модель на одной потребительской видеокарте?Да — Qwen3-30B-A3B можно дообучить примерно на 24 ГБ видеопамяти на одной RTX 4090, а DeepSeek-V3/R1 — примерно на 80 ГБ суммарно на 4x RTX 4090.
Какие модели получают поддержку в день релиза?Среди недавних релизов с поддержкой day-0 — GLM-5.3-flash, MiniMax-M3, GLM-5.2, Kimi-K2.5 и GLM-5, а также продолжающаяся поддержка DeepSeek-V3/R1, Qwen3 и экспериментальной 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