wehub-resource-sync
ec436095dd
16 KiB
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 集成，并参考本文档进行操作。也欢迎提出任何问题和建议！