XTuner QLoRA 微调实战指南InternLM / Llama2 / Qwen / Baichuan 开箱即用【免费下载链接】xtunerA Next-Generation Training Engine Built for Ultra-Large MoE Models项目地址: https://gitcode.com/GitHub_Trending/xt/xtuner导读本文以 docs/en/user_guides/finetune.md 为主线系统讲解如何使用 XTuner 对 InternLM-7B、Llama2-7B、Qwen-7B、Baichuan-7B 四类主流开源 LLM 执行 QLoRA 高效微调。你将掌握xtuner train一行命令启动训练的完整用法、配置文件五大分区的结构拆解、多卡分布式训练的启动方式以及微调后的模型转换与合并流程可直接对照仓库中的 19 个现成示例配置上手实操。一、准备工作安装 XTuner 与确认命令入口在运行任何微调命令之前需要先完成 XTuner 的安装。仓库根目录的 requirements.txt 声明了基础运行时依赖其中包含 transformers、peft、bitsandbytes、mmengine 等关键组件若需 DeepSpeed 支持可参照 requirements/deepspeed.txt 单独安装对应版本。XTuner 的所有能力统一暴露在xtuner命令之下其入口实现位于 xtuner/entry_point.py。该入口定义了一组模式MODES其中包括train训练、list-cfg列出预定义配置、copy-cfg复制配置、convert模型转换等xtuner MODE MODE_ARGS ARGS执行xtuner help或直接输入xtuner即可查看全部模式说明。训练与微调相关的能力集中在train模式其实际逻辑由 xtuner/tools/train.py 承载参数包括config配置文件名称或路径必填--work-dir日志与模型保存目录--deepspeedDeepSpeed 的 .json 配置文件路径--resume指定断点续训的 checkpoint 路径--seed训练随机种子--cfg-options以xxxyyy形式覆盖配置文件中的任意键值--launcher分布式启动方式none/pytorch/slurm/mpi在 xtuner/tools/train.py 中可以看到train命令支持两种定位配置的方式直接传配置文件路径或传配置名——配置名会通过 xtuner/configs/init.py 中构建的cfgs_name_path映射自动解析到实际文件。这就是文档中所有命令只写配置名如internlm_7b_qlora_oasst1_e3即可运行的原因。如需查看仓库内置的全部可用配置可运行xtuner list-cfg该命令实现在 xtuner/tools/list_cfg.py支持-p/--pattern参数做模糊匹配例如xtuner list-cfg -p qwen_7b可以只列出 Qwen-7B 相关的配置。若想把某个内置配置复制到自定义目录进行修改使用xtuner copy-cfg $CONFIG $SAVE_DIR对应实现见 xtuner/tools/copy_cfg.py复制后的文件会以_copy后缀命名方便在不动仓库原文件的前提下定制训练参数。二、InternLM-7B QLoRA 微调8 个场景开箱即用InternLM 是文档中第一个演示的模型族。仓库在 xtuner/configs/internlm/internlm_7b/ 目录下为 InternLM-7B 提供了 8 个与文档一一对应的 QLoRA 配置数据集 / 场景命令对应配置文件oasst1xtuner train internlm_7b_qlora_oasst1_e3internlm_7b_qlora_oasst1_e3.pyArxiv Gentitlextuner train internlm_7b_qlora_arxiv_gentitle_e3internlm_7b_qlora_arxiv_gentitle_e3.pyColoristxtuner train internlm_7b_qlora_colorist_e5internlm_7b_qlora_colorist_e5.pyCoderxtuner train internlm_7b_qlora_code_alpaca_e3internlm_7b_qlora_code_alpaca_e3.pySQLxtuner train internlm_7b_qlora_sql_e3internlm_7b_qlora_sql_e3.pyLawyerxtuner train internlm_7b_qlora_lawyer_e3internlm_7b_qlora_lawyer_e3.pyOpen-Platypusxtuner train internlm_7b_qlora_open_platypus_e3internlm_7b_qlora_open_platypus_e3.pyAlpaca-enzhxtuner train internlm_7b_qlora_alpaca_enzh_e3internlm_7b_qlora_alpaca_enzh_e3.py以最简单的 oasst1 场景为例直接执行xtuner train internlm_7b_qlora_oasst1_e3即可启动训练。需要说明的是这些配置文件中的模型权重默认从 HuggingFace 拉取internlm/internlm-7b数据集同样来自 HuggingFace如timdettmers/openassistant-guanaco首次运行需要保证网络可访问 HuggingFace Hub。2.1 配置命名规则解读配置名遵循{model}_{task}_{dataset}_{epoch}的命名规律internlm_7b基座模型为 InternLM-7Bqlora微调方式为 QLoRA4-bit 量化 LoRA 适配器oasst1使用的数据集e3训练 3 个 epoche5即 5 个 epoch如 Colorist 场景理解这一规则后即使不查阅文档也能推测任意配置的用途也方便按xtuner list-cfg -p快速定位所需配置。2.2 配置文件的五大分区以 internlm_7b_qlora_oasst1_e3.py 为例XTuner 的配置文件统一组织为五个 PART这份结构几乎适用于仓库中全部微调配置PART 1 Settings全局超参数pretrained_model_name_or_path internlm/internlm-7b use_varlen_attn False data_path timdettmers/openassistant-guanaco prompt_template PROMPT_TEMPLATE.default max_length 2048 pack_to_max_length True batch_size 1 # 单卡 batch size accumulative_counts 16 # 梯度累积步数 dataloader_num_workers 0 max_epochs 3 optim_type AdamW lr 2e-4 betas (0.9, 0.999) weight_decay 0 max_norm 1 # 梯度裁剪 warmup_ratio 0.03 save_steps 500 save_total_limit 2 # 最多保留的 checkpoint 数-1 表示不限 evaluation_freq 500 SYSTEM evaluation_inputs [请给我介绍五个上海的景点, Please tell me five scenic spots in Shanghai]PART 2 Model Tokenizer模型与分词器这里集中体现了 QLoRA 的核心配置BitsAndBytesConfig负责 4-bit 量化加载load_in_4bitTrue、bnb_4bit_quant_typenf4、bnb_4bit_use_double_quantTrue、bnb_4bit_compute_dtypetorch.float16LoraConfig负责注入 LoRA 适配器r64、lora_alpha16、lora_dropout0.1、task_typeCAUSAL_LMmodel dict( typeSupervisedFinetune, use_varlen_attnuse_varlen_attn, llmdict( typeAutoModelForCausalLM.from_pretrained, pretrained_model_name_or_pathpretrained_model_name_or_path, trust_remote_codeTrue, torch_dtypetorch.float16, quantization_configdict( typeBitsAndBytesConfig, load_in_4bitTrue, load_in_8bitFalse, llm_int8_threshold6.0, llm_int8_has_fp16_weightFalse, bnb_4bit_compute_dtypetorch.float16, bnb_4bit_use_double_quantTrue, bnb_4bit_quant_typenf4)), loradict( typeLoraConfig, r64, lora_alpha16, lora_dropout0.1, biasnone, task_typeCAUSAL_LM))PART 3 Dataset Dataloader数据管线数据集经过dataset_map_fn将原始数据格式化为input_ids与labels和template_map_fn套用对话模板两阶段映射再经pack_to_max_lengthTrue打包到max_length2048显著减少短样本带来的显存浪费train_dataset dict( typeprocess_hf_dataset, datasetdict(typeload_dataset, pathdata_path), tokenizertokenizer, max_lengthmax_length, dataset_map_fnoasst1_map_fn, template_map_fndict( typetemplate_map_fn_factory, templateprompt_template), remove_unused_columnsTrue, shuffle_before_packTrue, pack_to_max_lengthpack_to_max_length, use_varlen_attnuse_varlen_attn)PART 4 Scheduler Optimizer优化器与学习率调度优化器使用AmpOptimWrapper自动混合精度dtypefloat16loss_scaledynamic学习率采用「线性预热 余弦退火」两段式调度前warmup_ratio * max_epochs个 epoch 从1e-5线性升温至目标lr之后余弦衰减至 0。PART 5 Runtime运行时custom_hooks中的EvaluateChatHook会在训练过程中每隔evaluation_freq个 iteration 自动用evaluation_inputs里的问题做一次生成评测把对话结果打印到日志方便实时观察模型学习效果。2.3 底层训练流程从 xtuner/tools/train.py 可以看到完整的调用链解析配置 → 构建 tokenizer / model / dataset → 组装 dataloader 与优化器 → 交给 MMEngine 的Runner或 HuggingFaceTrainer执行。对于 QLoRA 配置训练框架默认为 MMEngine框架字段为huggingface的配置如 examples/huggingface_trainer/ 下的示例则走 HuggingFaceTrainer路径。LoRA 适配器的注入通过peft库的get_peft_model完成因此训练产物是一份轻量的 adapter而非完整模型权重。三、Llama2-7B QLoRA 微调含 MOSS 插件数据多卡场景文档第二组演示的是 Llama2-7B。由于 Llama2 的权重需要 HuggingFace 授权访问使用前必须先登录并配置访问令牌huggingface-cli login输入你的 HuggingFace User Access Token获取方式见 HuggingFace 官方文档的安全令牌说明。未完成此步骤会直接报访问错误。仓库在 xtuner/configs/llama/llama2_7b/ 目录下提供了文档对应的三个场景场景命令说明MOSS-003-SFT含插件NPROC_PER_NODE8 xtuner train llama2_7b_qlora_moss_sft_all_e2_gpu8推荐8 卡并行MOSS-003-SFT含插件xtuner train llama2_7b_qlora_moss_sft_all_e1单卡版Arxiv Gentitlextuner train llama2_7b_qlora_arxiv_gentitle_e3单卡Coloristxtuner train llama2_7b_qlora_colorist_e5单卡3.1 多卡训练的环境变量语义NPROC_PER_NODE8表示每个节点使用 8 个 GPU 进程。从 xtuner/entry_point.py 的调度逻辑可以看到xtuner命令会根据环境变量自动选择启动方式NPROC_PER_NODE/NNODES均默认为 1 时直接以python进程运行单卡任一变量大于 1 时自动改用torchrun分布式启动并支持以下环境变量NNODES节点总数NODE_RANK当前节点编号多机训练必填ADDRmaster 节点地址默认127.0.0.1PORT通信端口未指定时会在 20000~29999 随机选取因此多机场景可以写成NPROC_PER_NODE8 NNODES2 NODE_RANK0 ADDRMASTER_IP PORTPORT xtuner train llama2_7b_qlora_moss_sft_all_e2_gpu83.2 MOSS 插件数据的源码级解析MOSS-003-SFT 场景的特殊之处在于数据中包含工具插件调用。其数据加载实现在 xtuner/dataset/moss_sft.py 的MOSSSFTDataset类中关键行为包括读取data_file指定的 jsonl 数据配置文件中的moss_sft_no_plugins_path与moss_sft_plugins_path两个路径并将meta_instruction中的 MOSS 替换为配置指定的bot_name如 Llama2对「元指令」以及「插件返回结果」对应的 token 区间打上-100标签在 process_data 中置为-100从而在损失计算时屏蔽这些非模型生成内容保证模型只学习自己的回复首次加载后会把 tokenized 结果缓存为本地文件_data_{tokenizer}_{bot_name}与_no_loss_spans_{tokenizer}_{bot_name}二次运行直接读缓存避免重复解析。在 llama2_7b_qlora_moss_sft_all_e2_gpu8.py 中无插件数据与含插件数据通过ConcatDataset拼接为训练集该配置还额外设置了 MOSS 专用的SYSTEM_TEMPLATE.moss_sft与PROMPT_TEMPLATE.moss_sft并在EvaluateChatHook中通过stop_words[eoc]控制生成停止符。四、Qwen-7B QLoRA 微调5 个场景文档第三组演示 Qwen-7B对应配置位于 xtuner/configs/qwen/qwen1/qwen_7b/场景命令MOSS-003-SFT含插件NPROC_PER_NODE8 xtuner train qwen_7b_qlora_moss_sft_all_e2_gpu8推荐/xtuner train qwen_7b_qlora_moss_sft_all_e1oasst1xtuner train qwen_7b_qlora_oasst1_e3Arxiv Gentitlextuner train qwen_7b_qlora_arxiv_gentitle_e3Alpaca-enzhxtuner train qwen_7b_qlora_alpaca_enzh_e3Qwen 场景与 Llama2 场景的用法完全一致MOSS 插件任务推荐 8 卡NPROC_PER_NODE8其余任务单卡即可。这体现了 XTuner 配置体系的复用性——不同基座模型只需更换pretrained_model_name_or_path与数据路径其余 QLoRA 量化参数、LoRA 结构、优化器与调度器设计保持同构。需要注意的是Qwen 与 Baichuan 这类模型依赖trust_remote_codeTrue从远程仓库加载自定义代码相关字段已在配置的model与tokenizer定义中预设好无需手动处理。五、Baichuan-7B QLoRA 微调3 个场景文档第四组演示 Baichuan-7B对应配置位于 xtuner/configs/baichuan/baichuan_7b/场景命令oasst1xtuner train baichuan_7b_qlora_oasst1_e3Arxiv Gentitlextuner train baichuan_7b_qlora_arxiv_gentitle_e3Alpaca-enzhxtuner train baichuan_7b_qlora_alpaca_enzh_e3该目录下还额外提供了baichuan_7b_qlora_alpaca_zh_e3纯中文 Alpaca、baichuan_7b_qlora_code_alpaca_e3代码、baichuan_7b_qlora_lawyer_e3法律、baichuan_7b_qlora_moss_sft_plugins_e1仅插件数据等配置按同样方式即可启动此处不再赘述。六、训练之后模型转换与权重合并XTuner 训练产生的 checkpoint 与 HuggingFace 原生格式并不直接等价发布或部署前需要两步转换统一由xtuner convert子命令完成模式定义见 xtuner/entry_point.py。第一步将训练 checkpoint 转换为 HuggingFace 格式xtuner convert pth_to_hf $CONFIG $PATH_TO_PTH_MODEL $SAVE_PATH_TO_HF_MODEL$CONFIG使用训练时相同的配置名或路径$PATH_TO_PTH_MODEL指向训练日志中保存的 checkpoint默认输出在./work_dirs/{config_name}/下。第二步将 LoRA adapter 合并回基座模型xtuner convert merge $LLM $ADAPTER $SAVE_PATH其中$LLM是基座模型路径如meta-llama/Llama-2-7b-hf$ADAPTER是上一步转换出的 adapter 目录。该命令实现在 xtuner/tools/model_converters/merge.py通过peft的PeftModel.from_pretrained加载 adapter 并调用merge_and_unload()合并最终以分片形式保存完整模型默认每片不超过 2GB可用--max-shard-size调整同时保存 tokenizer。合并产物即为可直接用于推理或部署的标准 HuggingFace 模型。如果希望验证微调效果还可以使用xtuner chat $LLM --adapter $ADAPTER --prompt-template $PROMPT_TEMPLATE --system-template $SYSTEM_TEMPLATE在合并前直接加载「基座模型 adapter」进行对话评测无需完整合并。七、常见问题与调参建议训练报「找不到配置」确认配置名拼写或先用xtuner list-cfg -p $KEYWORD检索也可以直接传配置文件的绝对/相对路径。显存不足文档中 7B 模型的 oasst1 配置默认batch_size1、accumulative_counts16、max_length2048单卡 16GB 左右即可起步。若仍超限可优先降低max_length再考虑调小batch_size并同步增大accumulative_counts以维持等效 batch。Llama2 下载失败检查是否已执行huggingface-cli login并配置了有效访问令牌。MOSS 数据路径moss_sft_no_plugins_path与moss_sft_plugins_path指向本地 jsonl 文件需按配置文件注释先从 HuggingFacefnlp/moss-003-sft-data下载到对应路径。自定义场景将任一内置配置copy-cfg到工作目录后修改pretrained_model_name_or_path、data_path、max_epochs等字段即可复用到自己的数据与模型上更完整的自定义数据集教程可参考 docs/en/training/custom_sft_dataset.rst。结语本文覆盖了 XTuner 文档 finetune.md 中全部 19 条 QLoRA 微调命令及其对应的仓库配置并深入解释了xtuner train的命令解析、配置文件五大分区、多卡启动的环境变量机制、MOSS 插件数据的损失屏蔽原理以及训练后pth_to_hfmerge的完整转换链路。借助 xtuner/configs/ 下的现成配置你可以在一行命令内完成 InternLM、Llama2、Qwen、Baichuan 等主流模型的低成本微调并在此基础上按需定制属于自己的训练场景。【免费下载链接】xtunerA Next-Generation Training Engine Built for Ultra-Large MoE Models项目地址: https://gitcode.com/GitHub_Trending/xt/xtuner创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考