企业官网建设流程全解析

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：日志与模型保存目录
• --deepspeed：DeepSpeed 的 .json 配置文件路径
• --resume：指定断点续训的 checkpoint 路径
• --seed：训练随机种子
• --cfg-options：以xxx=yyy形式覆盖配置文件中的任意键值
• --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 配置：

以最简单的 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-7B
• qlora：微调方式为 QLoRA（4-bit 量化 + LoRA 适配器）
• oasst1：使用的数据集
• e3：训练 3 个 epoch（e5即 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_4bit=True、bnb_4bit_quant_type='nf4'、bnb_4bit_use_double_quant=True、bnb_4bit_compute_dtype=torch.float16），LoraConfig负责注入 LoRA 适配器（r=64、lora_alpha=16、lora_dropout=0.1、task_type='CAUSAL_LM'）：

model = dict( type=SupervisedFinetune, use_varlen_attn=use_varlen_attn, llm=dict( type=AutoModelForCausalLM.from_pretrained, pretrained_model_name_or_path=pretrained_model_name_or_path, trust_remote_code=True, torch_dtype=torch.float16, quantization_config=dict( type=BitsAndBytesConfig, load_in_4bit=True, load_in_8bit=False, llm_int8_threshold=6.0, llm_int8_has_fp16_weight=False, bnb_4bit_compute_dtype=torch.float16, bnb_4bit_use_double_quant=True, bnb_4bit_quant_type='nf4')), lora=dict( type=LoraConfig, r=64, lora_alpha=16, lora_dropout=0.1, bias='none', task_type='CAUSAL_LM'))

PART 3 Dataset & Dataloader（数据管线）

数据集经过dataset_map_fn（将原始数据格式化为input_ids与labels）和template_map_fn（套用对话模板）两阶段映射，再经pack_to_max_length=True打包到max_length=2048，显著减少短样本带来的显存浪费：

train_dataset = dict( type=process_hf_dataset, dataset=dict(type=load_dataset, path=data_path), tokenizer=tokenizer, max_length=max_length, dataset_map_fn=oasst1_map_fn, template_map_fn=dict( type=template_map_fn_factory, template=prompt_template), remove_unused_columns=True, shuffle_before_pack=True, pack_to_max_length=pack_to_max_length, use_varlen_attn=use_varlen_attn)

PART 4 Scheduler & Optimizer（优化器与学习率调度）

优化器使用AmpOptimWrapper（自动混合精度，dtype='float16'，loss_scale='dynamic'），学习率采用「线性预热 + 余弦退火」两段式调度：前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/ 目录下提供了文档对应的三个场景：

3.1 多卡训练的环境变量语义

NPROC_PER_NODE=8表示每个节点使用 8 个 GPU 进程。从 xtuner/entry_point.py 的调度逻辑可以看到，xtuner命令会根据环境变量自动选择启动方式：

• NPROC_PER_NODE/NNODES均默认为 1 时，直接以python进程运行（单卡）；
• 任一变量大于 1 时，自动改用torchrun分布式启动，并支持以下环境变量：
  • NNODES：节点总数
  • NODE_RANK：当前节点编号（多机训练必填）
  • ADDR：master 节点地址（默认127.0.0.1）
  • PORT：通信端口（未指定时会在 20000~29999 随机选取）

因此多机场景可以写成：

NPROC_PER_NODE=8 NNODES=2 NODE_RANK=0 ADDR=MASTER_IP PORT=PORT xtuner train llama2_7b_qlora_moss_sft_all_e2_gpu8

3.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/：

Qwen 场景与 Llama2 场景的用法完全一致：MOSS 插件任务推荐 8 卡（NPROC_PER_NODE=8），其余任务单卡即可。这体现了 XTuner 配置体系的复用性——不同基座模型只需更换pretrained_model_name_or_path与数据路径，其余 QLoRA 量化参数、LoRA 结构、优化器与调度器设计保持同构。

需要注意的是，Qwen 与 Baichuan 这类模型依赖trust_remote_code=True从远程仓库加载自定义代码，相关字段已在配置的model与tokenizer定义中预设好，无需手动处理。

五、Baichuan-7B QLoRA 微调（3 个场景）

文档第四组演示 Baichuan-7B，对应配置位于 xtuner/configs/baichuan/baichuan_7b/：

该目录下还额外提供了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」进行对话评测，无需完整合并。

七、常见问题与调参建议

1. 训练报「找不到配置」：确认配置名拼写，或先用xtuner list-cfg -p $KEYWORD检索；也可以直接传配置文件的绝对/相对路径。
2. 显存不足：文档中 7B 模型的 oasst1 配置默认batch_size=1、accumulative_counts=16、max_length=2048，单卡 16GB 左右即可起步。若仍超限，可优先降低max_length，再考虑调小batch_size并同步增大accumulative_counts以维持等效 batch。
3. Llama2 下载失败：检查是否已执行huggingface-cli login并配置了有效访问令牌。
4. MOSS 数据路径：moss_sft_no_plugins_path与moss_sft_plugins_path指向本地 jsonl 文件，需按配置文件注释先从 HuggingFace（fnlp/moss-003-sft-data）下载到对应路径。
5. 自定义场景：将任一内置配置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_hf+merge的完整转换链路。借助 xtuner/configs/ 下的现成配置，你可以在一行命令内完成 InternLM、Llama2、Qwen、Baichuan 等主流模型的低成本微调，并在此基础上按需定制属于自己的训练场景。

【免费下载链接】xtunerA Next-Generation Training Engine Built for Ultra-Large MoE Models项目地址: https://gitcode.com/GitHub_Trending/xt/xtuner