## 项目概述

KTransformers 是一个研究项目，专注于通过 CPU-GPU 异构计算实现大语言模型的高效推理和微调。项目提供两类用户功能：高性能推理（kt-kernel 服务）和基于 LLaMA-Factory 的微调（SFT）。它旨在让消费级 GPU 也能运行超大规模 MoE 模型，并已在多种主流模型（如 DeepSeek、GLM、Kimi、MiniMax 等）上提供 Day0 支持。

## 核心功能

- **异构推理（kt-kernel）**：利用 CPU 和 GPU 协同工作，支持 INT4/INT8 量化推理，集成 Intel AMX/AVX512/AVX2 优化内核，实现 MoE 模型的 CPU-GPU 混合部署。
- **MoE 优化**：高效的专家并行（Expert Scheduling）和 NUMA 感知内存管理，支持将热门专家放在 GPU、冷门专家放在 CPU。
- **量化支持**：CPU 侧支持 INT4/INT8 量化权重，GPU 侧支持 GPTQ；支持 FP8、BF16、以及多种混合精度方案。
- **超长上下文**：支持 1M token 上下文（如 GLM-5.3-flash），并具有三层（GPU-CPU-Disk）前缀缓存复用功能。
- **多后端支持**：支持 NVIDIA GPU、AMD GPU（ROCm）、Intel Arc GPU、Ascend NPU，以及 AVX2 仅 CPU 后端。
- **框架集成**：与 SGLang 集成，支持生产环境部署；与 LLaMA-Factory 集成，支持 MoE 模型的高效微调。
- **微调（SFT）**：提供端到端的 BF16 全参数微调、LoRA 微调，支持 FP8/INT8 量化训练，以及在有限 GPU 内存下微调超大规模 MoE 模型。

## 适用与不适用场景

**适用场景**：

- 在消费级或受限 GPU 显存（如 24GB）下运行和微调超大 MoE 模型（如 DeepSeek-V3/R1、Qwen3-30B-A3B）。
- 需要长上下文支持的推理任务（如 139K、1M token）。
- 希望利用 CPU-GPU 混合架构以降低部署成本的应用。
- 需要将 MoE 模型集成到 SGLang 生产环境。

**不适用场景**：

- 对纯 GPU 性能要求极高且 CPU 资源有限的场景，可能无法完全发挥 KT 的混合优势。
- 不支持的非 MoE 架构模型（具体支持列表需参考官方文档）。
- 使用未列出的硬件平台或操作系统时，可能需要进行额外适配。

## 技术架构与依赖

- **编程语言**：Python（主要），可能涉及 CUDA/C++ 内核。
- **主要依赖**：PyTorch、LLaMA-Factory、SGLang、accelerate、transformers 等（具体以官方要求为准）。
- **硬件支持**：Intel AMX/AVX512/AVX2 CPU、NVIDIA GPU（CUDA）、AMD GPU（ROCm）、Intel Arc GPU、Ascend NPU。
- **关键特性**：CPU-GPU 异构计算、MoE 专家调度、多层前缀缓存、量化内核（INT4/INT8/FP8/BF16）。

## 安装与快速开始

### 推理

```bash
cd kt-kernel
pip install .
```

### 微调（SFT）

```bash
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
```

详细安装和配置请参考官方文档（见“官方链接”）。

## 典型使用方法

- **推理示例**：使用 Python API 集成 SGLang，实现 CPU-GPU 混合推理，例如运行 DeepSeek-R1/V3 模型，通过异构专家部署提升吞吐量。
- **微调示例**：使用 LLaMA-Factory 和 KTransformers 进行 MoE 模型的 LoRA 或全参数微调，可选 BF16/FP8/INT8 等精度。
- **多并发支持**：支持多用户并发推理（multi-concurrency），适合服务化部署。
- **Day0 模型支持**：针对新发布模型（如 GLM-5、Kimi-K2.5）提供开箱即用的教程。

## 配置与部署要点

- **硬件配置**：需要搭配 Intel AMX/AVX512 CPU 或兼容 AVX512 的 AMD 服务器以支持 LoRA 微调；推理可仅用 AVX2。
- **显存与内存**：根据模型大小规划 GPU 显存和 CPU DRAM 容量，例如 DeepSeek-V3 在 4x RTX 4090 (约 80GB) 下可进行微调。
- **量化选择**：根据需求选择 FP8/INT8/INT4 或混合精度，平衡速度与精度。
- **框架集成**：确保安装匹配的 SGLang 和 LLaMA-Factory 版本。
- **环境变量**：使用 `CUDA_VISIBLE_DEVICES` 指定 GPU。

## 限制、风险与许可证

- **许可证**：Apache-2.0。
- **限制**：仓库文档未提供完整的运行失败排查指南，也未明确说明所有支持的硬件组合（仓库资料未提供）。
- **风险**：作为研究项目，可能存在版本更新较快、API 变化频繁的风险；依赖的第三方框架（如 SGLang、LLaMA-Factory）版本兼容性需自行测试。
- **其他**：仓库描述提到“灵活框架”，但具体扩展性细节需查阅源码。

## 官方链接

- **GitHub 仓库**：[https://github.com/kvcache-ai/ktransformers](https://github.com/kvcache-ai/ktransformers)
- **最新发布**：[v0.7.0](https://github.com/kvcache-ai/ktransformers/releases/tag/v0.7.0)
- **文档**：在仓库内 `doc/en` 和 `doc/zh` 目录下有丰富教程。
- **在线书**：[https://kvcache-ai.github.io/ktransformers/](https://kvcache-ai.github.io/ktransformers/)

## 信息来源和分析时间

- **信息来源**：来自 GitHub 仓库的 README 文件（未包含其他文档）。
- **分析时间**：2026年8月（基于最新更新日期）。