ktransformers/doc/zh/KTransformers-Fine-Tuning_User-Guide_zh.md

• KTransformers 微调 × LLaMA-Factory 集成 – 用户指南

• Introduction

• Quick to Start

  • 快速上手
  • 环境安装
  • 核心功能1：使用KTransformers作为backend，微调超大规模MoE模型
  • 核心功能2：与微调后模型（即原模型+LoRA Adapter）聊天，用于交互
  • 核心功能3：生成微调后模型（即原模型+LoRA Adapter）的API，用于批量生成并评测指标

• KT微调速度性能测试：用户侧

  • 端到端性能
  • 显存/内存性能

• 结论

KTransformers 微调 × LLaMA-Factory 集成 – 用户指南

MadSys实验室, KVCache-AI团队, 趋境科技, LLaMA-Factory团队

Introduction

从 DeepSeek-V3/R1 到 Qwen3-MoE、Kimi-K2，每一次超大模型的开源都带来性能与规模上的巨大跃升。然而，多数研究者与开发者受限于昂贵的显卡与动辄数千亿参数的模型，难以在资源受限条件下微调超大模型。面对这种差距，我们提出了一种更具可行性的方案：通过 KTransformers 与 LLaMA-Factory 的结合，仅需2~4张RTX 4090与较高内存CPU，便可微调DeepSeek-671B等超大规模的MoE模型。

该架构的核心目标是为资源受限下的研究者提供 在本地探索超大规模模型微调的可能性。同时，也在较小规模（如 14B/30B）提供快速定制特定场景的路径。我们以风格化对话、西式腔调翻译、医学问答作为代表任务，验证架构的可行性，并展示在数小时内达成个性化适配的可操作性。

如下图所示，LLaMA-Factory 是整个微调流程的统一调度与配置框架，负责数据处理、训练调度、LoRA 插入与推理接口管理； KTransformers 则作为其可插拔的高性能后端，在相同的训练配置下接管 Attention / MoE 等核心算子，实现异构设备（GPU+CPU）的高效协同。

我们在 LLaMA-Factory 框架下，对比评测了 HuggingFace、Unsloth、KTransformers 三种后端的 LoRA 微调方案。结果显示，KTransformers为超大规模的MoE模型（671B等）提供了4090 级别的唯一可行方案，并在较小规模的MoE模型（DeepSeek-14B）上面也展现了更高的吞吐和更低的显存占用。

Under LoRA (BF16)+NekoQA-10K-风格化对话数据集	HuggingFace Backend	Unsloth Backend	KTransformers Backend
[14B-DeepSeekV2-Lite] LoRA Fine-tuning throughput	303.58 token/s	455.37 token/s	530.38 token/s
[14B-DeepSeekV2-Lite] GPU Memory	32.12 GB	9.64 GB	6.08 GB
[671B-DeepSeekV3] LoRA Fine-tuning throughput	Too Huge to run	NOT SUPPORT	40.35 token/s
[671B-DeepSeekV3] GPU Memory（多卡总和）	理论值1400 GB †	NOT SUPPORT	70 GB †

† 1400 GB 为理论显存（FP16 全参数常驻，非可运行配置）；70 GB 为 KT 策略（Attention 驻 GPU + MoE分层 offload）下的实测峰值。

微调效果示例

风格化对话测试（CatGirl风格语气）

数据集：NekoQA-10K: 面向猫娘语言建模的对话数据集，目标是提升风格一致性与可辨识度。

下图对比了原始模型和微调模型的回答，可以看到微调后模型在语气和称谓上更加稳定地保持了猫娘风格（红框部分），验证了风格迁移微调的有效性。

Benchmark测试

数据集选取：

（1）采用了西式翻译腔数据集，该数据集要求模型按西式表达习惯进行夸张的翻译，有明确的定制化风格需求。

（2）采用了AfriMed-QA数据集（ACL-2025），作为非洲地区医疗领域的专用数据集，具有很强的场景定制特征，包含选择题和简答题两种形式，非常适合作为垂直领域微调的评估。针对单选和简答形式，我们分别进行测试，结果如下。

下表显示了微调前后模型在这些数据集上的指标变化。可以看到经过 LoRA 微调后，各项指标大幅提升，验证了微调的有效性：

西式翻译腔数据集	BLEU-1	BLEU-2	BLEU-3	BLEU-4	ROUGE-1	ROUGE-2	ROUGE-L
V2-Lite原模型（不LoRA微调）	20.66	8.33	4.54	2.89	22.71	4.52	19.19
KT-LoRA微调DeepSeek-V2-Lite	35.41	22.44	15.42	11.18	42.03	18.38	33.10
V3原模型（不LoRA微调）	8.49	3.34	1.62	0.96	15.91	2.55	10.07
KT-LoRA微调DeepSeek-V3	37.02	23.70	16.21	11.49	43.43	18.96	34.54

AfriMed-QA数据集（简答任务）	BLEU-1	BLEU-2	BLEU-3	BLEU-4	ROUGE-1	ROUGE-2	ROUGE-L
V2-Lite原模型（不LoRA微调）	13.58	11.12	9.10	7.23	22.48	7.81	11.73
KT-LoRA微调DeepSeek-V2-Lite	35.90	27.63	22.99	19.15	35.25	17.50	28.44
V3原模型（不LoRA微调）	12.75	10.27	8.05	5.99	20.33	5.65	10.11
KT-LoRA微调DeepSeek-V3	42.42	34.12	28.95	24.54	41.97	22.37	33.28

AfriMed-QA数据集（单选任务）	Accuracy
V2-Lite原模型（不LoRA微调）	0.0645
KT-LoRA微调DeepSeek-V2-Lite	0.4812
V3原模型（不LoRA微调）	0.5833
KT-LoRA微调DeepSeek-V3	0.7930

从以上测试可以看出，即使是参数量巨大的 MoE 模型，通过 KTransformers 后端的高效微调，也能在特定任务上快速达到理想效果。

Quick to Start

快速上手

本节将指导您如何安装环境并使用 LLaMA-Factory + KTransformers 完成微调和推理。我们将涵盖以下内容：

• 环境依赖的安装配置
• 使用 KTransformers 作为后端微调超大规模 MoE 模型
• 加载微调后的模型（原模型 + LoRA 适配器）进行对话/推理
• 批量推理微调模型并评测指标

环境安装

根据下面示例，同时安装KTransformers和LLaMA-Factory环境，这次为了简化KTransformers的安装流程，我们特意封装了wheel包避免本地编译，具体安装步骤如下：（注意对应好本地的python版本、torch版本、cuda版本和不同文件名的KTransformers包）

# 1. 安装conda环境
conda create -n Kllama python=3.12 # choose from : [3.11, 3.12, 3.13]
conda install -y -c conda-forge libstdcxx-ng gcc_impl_linux-64
conda install -y -c nvidia/label/cuda-11.8.0 cuda-runtime

# 2. 安装llamafactory环境
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e ".[torch,metrics]" --no-build-isolation

# 3. 安装对应torch和python版本的KTransformers（CUDA版本可以跟whl命名的不一致），从https://github.com/kvcache-ai/ktransformers/releases/tag/v0.4.1
pip install ktransformers-0.4.1+cu128torch27fancy-cp312-cp312-linux_x86_64.whl

# 4. 安装flash-attention，参照python版本和torch版本，从https://github.com/Dao-AILab/flash-attention/releases下载
pip install flash_attn-2.8.3+cu12torch2.7cxx11abiTRUE-cp312-cp312-linux_x86_64.whl
# abi=True/False可以用下面代码查看
# import torch
# print(torch._C._GLIBCXX_USE_CXX11_ABI)

# 5. （可选）如果你想使用flash_infer的话（不然默认triton）
git clone https://github.com/kvcache-ai/custom_flashinfer.git
pip install custom_flashinfer/

使用要点：在 LLaMA-Factory 的配置 YAML 文件中启用 KTransformers 后端，只需设置 use_kt: true，并指定相应的 kt_optimize_rule YAML 文件，即可切换到底层由 KTransformers 接管计算。下面我们将通过具体功能来说明如何设置这些配置。

核心功能1：使用KTransformers作为backend，微调超大规模MoE模型

运行命令：USE_KT=1 llamafactory-cli train examples/train_lora/deepseek3_lora_sft_kt.yaml。

需要注意的是，必须提供BF16格式模型文件，DeepSeek-V3-671B默认下载是FP8格式，需要通过 DeepSeek-V3/inference/fp8_cast_bf16.py 转换。

### model
model_name_or_path: opensourcerelease/DeepSeek-V3-bf16
trust_remote_code: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 8
lora_target: all

### dataset
dataset: identity
template: deepseek
cutoff_len: 2048
max_samples: 100000
overwrite_cache: true
preprocessing_num_workers: 16
dataloader_num_workers: 4

### output
output_dir: saves/Kllama_deepseekV3
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true
save_only_model: false
report_to: none  # choices: [none, wandb, tensorboard, swanlab, mlflow]

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 1.0e-4
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true
ddp_timeout: 180000000
resume_from_checkpoint: null

### ktransformers
use_kt: true # use KTransformers as LoRA sft backend
kt_optimize_rule: examples/kt_optimize_rules/DeepSeek-V3-Chat-sft-amx-multi-gpu.yaml
cpu_infer: 32
chunk_size: 8192

其中，kt_optimize_rule提供了大量默认的YAML文件来控制KTransformers的放置策略，下面针对YAML文件名和功能对照特别说明，也可以参考ktransformers/optimize_rules：（*指通配符）

文件名字段	功能特征
DeepSeek-V2-Lite-Chat-*或DeepSeek-V3-Chat-*	对应的不同模型
*-sft-*	微调所用的放置策略，其他为推理所用
*-amx-*	使用AMX指令集进行CPU运算，其他为llamafile
*-multi-gpu-X*	使用X张GPU进行模型并行（显存共担），X为空默认是2张

例如：examples/kt_optimize_rules/DeepSeek-V3-Chat-sft-amx-multi-gpu.yaml为DeepSeek-V3-Chat模型用AMX指令集进行微调，并调用两卡模型并行。

对于微调任务，我们推荐使用AMX指令集加速，可以使用lscpu | grep amx查看CPU是否支持AMX指令集，AMX精度支持BF16/Int8，修改方式如下：

- match:
    name: "^model\\.layers\\..*\\.mlp\\.experts$"
  replace:
    class: ktransformers.operators.experts.KTransformersExperts     # custom MoE Kernel with expert parallelism
    kwargs:
      prefill_device: "cpu"
      prefill_op: "KExpertsTorch"
      generate_device: "cpu"
      generate_op: "KSFTExpertsCPU"
      out_device: "cuda"
      backend: "AMXInt8" # or "AMXBF16" or "llamafile" (default)

输出会保存在output_dir里面，默认为safetensor格式，并且保留adapter.json等配套内容以便后续加载。

核心功能2：与微调后模型（即原模型+LoRA Adapter）聊天，用于交互

运行命令：llamafactory-cli chat examples/inference/deepseek3_lora_sft_kt.yaml。

调用KT微调的adapter (safetensor格式) 推理对话。

model_name_or_path: opensourcerelease/DeepSeek-V3-bf16
adapter_name_or_path: saves/Kllama_deepseekV3
template: deepseek
infer_backend: ktransformers  # choices: [huggingface, vllm, sglang, ktransformers]
trust_remote_code: true

use_kt: true # 调用KTransformers backend
kt_optimize_rule: examples/kt_optimize_rules/DeepSeek-V3-Chat-sft-amx-multi-gpu.yaml # 请选择和LoRA微调的时候保持一致的YAML文件
cpu_infer: 32
chunk_size: 8192

同时，我们也支持GGUF格式的adapter进行推理（如果您已经使用了上述LLaMA-Factory+KTransformers的微调方案，就不用管啦~）。

safetensors 场景填文件所在目录，GGUF 场景填文件路径，也就是说您需要把adapter_name_or_path选为具体的GGUF格式文件。

加载过程中适配了KT每层的命名，和torch.save保存下来的常规命名的不同，正常映射日志Loaded adapter weight: XXX -> XXX，展示如下。

核心功能3：生成微调后模型（即原模型+LoRA Adapter）的API，用于批量生成并评测指标

运行命令：API_PORT=8000 llamafactory-cli api examples/inference/deepseek3_lora_sft_kt.yaml。

调用KT微调的adapter给出API，其他API使用逻辑和llamafactory原生方式一致。

model_name_or_path: opensourcerelease/DeepSeek-V3-bf16
adapter_name_or_path: saves/Kllama_deepseekV3
template: deepseek
infer_backend: ktransformers  # choices: [huggingface, vllm, sglang, ktransformers]
trust_remote_code: true

use_kt: true # use KTransformers as LoRA sft backend to inference
kt_optimize_rule: examples/kt_optimize_rules/DeepSeek-V3-Chat-sft-amx-multi-gpu.yaml
cpu_infer: 32
chunk_size: 8192

KT微调速度性能测试：用户侧

端到端性能

测试定义：

step_time：一次优化步（包含 gradient_accumulation_steps (GAS) 次累积）的总时间，涵盖 PyTorch 张量搬运 + Attention + MoE + 其他计算等。

tokens_per_step = GAS × qlen；token/s = tokens_per_step / step_time。

测试设置：GAS=16，qlen=512（即每步 8192 tokens）；LoRA（r=8, alpha=32, dropout=0.1）；使用AMX指令集优化；GPU选取RTX 4090，CPU选取Intel Xeon Platinum 8488C。

实测结果：

**DeepSeek-V3-671B：**step_time = 203 s→token/s ≈ 8192 / 203 ≈ 40.35 token/s

**DeepSeek-V2-Lite-14B：**step_time = 36 s→token/s ≈ 8192 / 36 ≈ 227.6 token/s

显存/内存性能

DeepSeek-V3（671B，61层，其中58层有MoE）占用显存（多卡总量）大约70GB、内存占用约1.2-1.3TB。

DeepSeek-V2-lite（14B，27层，其中26层有MoE）占用显存大约5.5GB、内存占用约150GB。

结论

通过开发 KTransformers LoRA微调并将其集成到 LLaMA‑Factory，我们为希望高效训练与部署 MoE 大模型的用户提供了可行指南。KT 带来最尖端的优化（支持 DeepSeek、Qwen、Kimi 等，配合 AMX 加速 kernel），同时通过 LoRA 微调在极低 GPU 显存下实现定制化。LLaMA‑Factory 则提供友好的统一界面，更广的用户支持。

该集成（类似 Unsloth 补丁所带来的提速）意味着即便是数百亿乃至万亿总参数量的 MoE 模型，也可在普通硬件上完成微调并低延迟部署。显存节省、速度提升、易用性 三者兼得。我们鼓励用户在下一次 MoE 项目中尝试 LLaMA‑Factory 的 KT 集成，并参考本文档进行操作。也欢迎提出任何问题和建议！