一、XTuner 简介XTuner 是书生・浦语开源轻量化微调框架主打QLoRA 4bit 低成本微调支持 InternLM、Qwen、Llama3 等主流基座内置对话模板、训练监控、一键合并权重兼容单卡 / 多卡 DeepSpeed 分布式适合个人 24G 显卡微调 7B/13B 模型。核心优势QLoRA 4bit 量化单 24G 显卡可跑 13B统一对话数据集标准适配单 / 多轮指令数据一键训练、一键合并 LoRA、配套 LMDeploy 推理原生集成 DeepSpeed多卡显存分片优化。二、环境搭建Python3.10 CUDA11.8/12.x1. 创建虚拟环境# 创建环境 conda create -n xtuner python3.10 -y conda activate xtuner # 安装匹配CUDA的TorchCUDA12.6示例 pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu1262. 安装 XTuner源码完整版含 DeepSpeed# 国内Gitee镜像GitHub访问失败推荐 git clone https://gitee.com/Internlm/xtuner.git cd xtuner # 全量依赖包含deepspeed、lmdeploy pip install -e .[all] -i https://mirrors.aliyun.com/pypi/simple/ # 验证安装 xtuner --version三、数据集标准格式适配你之前小聚认知数据XTuner 标准单轮指令格式必须该结构对应你转换后的文件[ { conversation: [ { input: 你是谁, output: 我是小聚由Aron开发的AI助手。 } ] } ]Alpaca 原始 json → XTuner 标准转换代码import json def alpaca2xtuner(alpaca_path, save_path): with open(alpaca_path, r, encodingutf-8) as f: raw_data json.load(f) res [] for item in raw_data: ins item[instruction].strip() extra item[input].strip() ans item[output].strip() user_q f{ins}\n{extra}.strip() if extra else ins res.append({ conversation: [{input: user_q, output: ans}] }) with open(save_path, w, encodingutf-8) as f: json.dump(res, f, ensure_asciiFalse, indent2) if __name__ __main__: alpaca2xtuner(identity.json, xtuner_identity.json)四、基座模型准备以 Qwen2.5-7B-Instruct 为例本地存放基座路径./models/Qwen2.5-7B-Instruct快速下载modelscopefrom modelscope import snapshot_download model_dir snapshot_download(Qwen/Qwen2.5-7B-Instruct, cache_dir./models)五、复制并修改训练配置QLoRA 4bit 单卡模板1. 查看官方预置配置# 筛选Qwen相关配置 xtuner list-cfg -p qwen # 复制qlora配置到当前目录 xtuner copy-cfg qwen2_5_7b_qlora_alpaca_e3 ./train_cfg.py2. 核心配置文件train_cfg.py修改分段注释########################################################################### # PART 1 基础全局参数 ########################################################################### pretrained_model_name_or_path ./models/Qwen2.5-7B-Instruct # 基座路径 data_files ./xtuner_identity.json # XTuner数据集路径 max_length 1024 # 上下文长度 batch_size 4 # 单卡批次 accumulative_counts 2 # 梯度累积等效batch8 max_epochs 5 # 训练轮数认知数据3-5轮足够 lr 2e-4 # QLoRA标准学习率 # 训练过程实时测试样例 evaluation_inputs [ 你叫什么名字, 是谁开发了你, Are you ChatGPT? ] ########################################################################### # PART 2 QLoRA 配置显存核心 ########################################################################### lora dict( typeQLoRAConfig, r8, # LoRA秩小认知数据r8/16足够 lora_alpha16, # 一般r*2 lora_dropout0.1, biasnone, task_typeCAUSAL_LM, bits4, # 4bit量化单24G可跑7B/13B lora_target_modules[ q_proj, v_proj, k_proj, gate_proj, up_proj, down_proj ] # Qwen专属目标层 ) ########################################################################### # PART 3 数据集加载固定无需改动 ########################################################################### dataset dict( typeload_dataset, pathjson, data_filesdata_files, ) dataset_map_fn None # 已经是标准格式不用转换 ########################################################################### # PART 4 训练器、保存策略 ########################################################################### trainer dict( typeSupervisedFinetuneTrainer, optim_typeAdamW, warmup_ratio0.05, save_steps100, save_total_limit3, output_dir./work_dirs/qwen7b_xiaoju_lora )六、启动训练1. 单机单卡24G 显卡推荐xtuner train train_cfg.py2. 单机多卡4/8 卡自动启用 DeepSpeed# 使用0、1、2、3四张卡 CUDA_VISIBLE_DEVICES0,1,2,3 NPROC_PER_NODE4 xtuner train train_cfg.py3. 训练输出目录说明work_dirs/qwen7b_xiaoju_lora/ ├── last_checkpoint/ # 最终LoRA权重 │ └── hf/ # HuggingFace格式adapter │ ├── adapter_config.json │ └── adapter_model.bin ├── epoch_*.pth # 每轮权重快照 └── train_cfg.py # 备份配置七、训练后操作LoRA 权重合并完整模型LoRA 只是小适配器需要和基座合并才能给 vLLM/LMDeploy/Ollama 部署# 格式xtuner convert merge 基座路径 LoRA-hf目录 合并输出目录 xtuner convert merge \ ./models/Qwen2.5-7B-Instruct \ ./work_dirs/qwen7b_xiaoju_lora/last_checkpoint/hf \ ./models/qwen7b_xiaoju_full \ --max-shard-size 2GB八、两种测试方式方式 1直接加载 LoRA 对话无需合并快速验证xtuner chat ./models/Qwen2.5-7B-Instruct \ --adapter ./work_dirs/qwen7b_xiaoju_lora/last_checkpoint/hf \ --prompt-template qwen2.5方式 2合并后 LMDeploy 高性能推理pip install lmdeploy # 启动对话 python -m lmdeploy.pytorch.chat ./models/qwen7b_xiaoju_full # 启动API服务 lmdeploy serve api_server ./models/qwen7b_xiaoju_full --port 8000九、DeepSpeed 多卡配置扩展显存不足场景修改train_cfg.py末尾添加 deepspeed 配置ZeRO2 均衡显存速度deepspeed dict( zero_optimizationdict( stage2, offload_optimizerdict(devicecpu, pin_memoryTrue), overlap_commTrue ), fp16dict(enabledauto), bf16dict(enabledauto) )十、常见踩坑解决方案OOM 显存溢出降低batch_size、开启bits4QLoRA、多卡启用 ZeRO3模型不认识人设输出错乱检查数据集格式为input/output标准结构训练轮数增加至 5 轮对话模板错位训练推理不一致训练与推理prompt-template必须完全匹配qwen2.5/llama3 等GitHub 拉取 XTuner 超时切换 Gitee 镜像安装合并权重报错路径不存在hf 文件夹必须是last_checkpoint/hf不要直接传入 epoch 快照。十一、硬件选型参考表格显卡显存支持模型微调方案16G1.8B/3BQLoRA 4bitbatch1~224G7B/13BQLoRA 4bitbatch4~848G 双卡20BDeepSpeed ZeRO3 多卡微调