手把手教你用Xtuner微调Qwen模型：从KeyError到成功训练的3种配置文件修改技巧

手把手教你用Xtuner微调Qwen模型：从KeyError到成功训练的3种配置文件修改技巧

1. 环境准备与常见错误排查

在开始Qwen模型的微调之前，确保你的环境配置正确至关重要。许多初学者常犯的错误就是直接使用最新版本的PyTorch和Transformers，这往往会导致兼容性问题。

典型环境配置问题：

• PyTorch版本冲突：最新版PyTorch（如2.6+）可能与bitsandbytes不兼容
• Transformers版本不匹配：Qwen特定版本可能需要特定Transformers版本
• CUDA驱动问题：CUDA版本与PyTorch版本不匹配

提示：建议使用conda创建独立环境，避免依赖冲突

# 创建conda环境 conda create -n qwen_finetune python=3.10 conda activate qwen_finetune # 安装推荐版本的PyTorch pip install torch==2.5.1 torchvision==0.15.2 torchaudio==2.5.1 --index-url https://download.pytorch.org/whl/cu118

常见错误排查表：

2. 配置文件修改的三种核心技巧

2.1 模型类型适配修改

当遇到KeyError: 'qwen'错误时，这通常是因为Transformers库无法识别配置文件中的model_type。Qwen系列模型随着版本迭代，其model_type可能发生变化。

解决方案：

1. 检查模型官方文档确认支持的Transformers版本
2. 如果无法升级Transformers，可以修改配置文件中的model_type字段

# 修改前 model_type = 'qwen' # 修改后（根据实际情况选择） model_type = 'qwen2' # 或'qwen1.5'等兼容类型

版本兼容性对照表：

2.2 量化参数调整

QLoRA微调时经常遇到量化相关错误，如RuntimeError: Failed to import transformers.integrations.bitsandbytes。这时需要检查量化配置：

# 在配置文件中确保量化设置正确 quantization_config = dict( type='BitsAndBytesConfig', load_in_4bit=True, bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True, bnb_4bit_quant_type='nf4' )

关键参数说明：

• load_in_4bit: 启用4bit量化
• bnb_4bit_compute_dtype: 计算时使用的数据类型
• bnb_4bit_use_double_quant: 是否使用双重量化
• bnb_4bit_quant_type: 量化类型，'nf4'通常效果最好

2.3 数据结构适配

当使用自定义数据集时，需要确保数据格式与Xtuner要求一致。常见错误是数据格式不匹配导致训练无法开始。

标准数据格式示例：

[ { "conversation": [ { "system": "你是一个专业的AI助手", "input": "什么是酮咯酸滴眼液？", "output": "酮咯酸滴眼液是一种用于治疗过敏性眼痒的药物..." } ] }, { "conversation": [ { "system": "你是一个专业的AI助手", "input": "什么药物会升高血糖？", "output": "某些非糖尿病药物可能会升高血糖水平..." } ] } ]

数据转换Python脚本：

import pandas as pd import json def convert_excel_to_jsonl(input_file, output_file): df = pd.read_excel(input_file) output_data = [] for _, row in df.iterrows(): conversation = { "system": "你是一个专业的AI助手", "input": row["问题"], "output": row["答案"] } output_data.append({"conversation": [conversation]}) with open(output_file, 'w', encoding='utf-8') as f: for item in output_data: f.write(json.dumps(item, ensure_ascii=False) + '\n') # 使用示例 convert_excel_to_jsonl('MedQA2019.xlsx', 'MedQA2019.jsonl')

3. 实战：Qwen模型微调全流程

3.1 准备配置文件

Xtuner提供了多种预设配置模板，我们可以基于这些模板进行修改：

# 列出所有可用配置 xtuner list-cfg | grep qwen # 复制配置文件到当前目录 xtuner copy-cfg qwen_7b_qlora_oasst1_e3 . mv qwen_7b_qlora_oasst1_e3_copy.py qwen_7b_qlora_medqa_e3.py

关键配置修改点：

1. 模型路径修改
2. 数据路径设置
3. 训练参数调整
4. 量化配置

# 修改示例 - pretrained_model_name_or_path = 'qwen/qwen-7b' + pretrained_model_name_or_path = './qwen-7b' - data_path = 'timdettmers/openassistant-guanaco' + data_path = './MedQA2019.jsonl' # 调整训练参数 max_length = 2048 # 根据显存情况调整 batch_size = 8 # 根据显存情况调整 accumulative_counts = 4 # 梯度累积

3.2 启动训练

配置完成后，可以使用以下命令启动训练：

# 普通训练 xtuner train qwen_7b_qlora_medqa_e3.py # 使用Deepspeed加速 xtuner train qwen_7b_qlora_medqa_e3.py --deepspeed deepspeed_zero2

训练过程监控：

• 使用nvidia-smi监控GPU使用情况
• 检查训练日志中的loss变化
• 注意显存使用情况，避免OOM

3.3 模型测试与部署

训练完成后，可以使用Xtuner内置的chat功能测试模型：

# 测试原始模型 xtuner chat ./qwen-7b --prompt-template qwen_chat # 测试微调后的模型 xtuner chat ./qwen-7b --adapter ./work_dir --prompt-template qwen_chat

Web Demo部署：

1. 安装streamlit
2. 准备web_demo.py脚本
3. 修改模型路径和端口配置

# 简化版web_demo.py示例 import streamlit as st from transformers import AutoModelForCausalLM, AutoTokenizer model_path = './qwen-7b' adapter_path = './work_dir' tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True) model = AutoModelForCausalLM.from_pretrained( model_path, trust_remote_code=True, device_map='auto' ) model.load_adapter(adapter_path) st.title('Qwen医学问答助手') user_input = st.text_input("请输入您的问题:") if user_input: response, _ = model.chat(tokenizer, user_input, history=[]) st.write(response)

4. 高级技巧与问题解决

4.1 处理序列长度问题

当遇到Qwen2RotaryEmbedding.forward() got an unexpected keyword argument 'seq_len'错误时，这通常与旋转位置编码的实现有关。

解决方案：

1. 更新Xtuner到最新版本
2. 在配置文件中显式设置rope_scaling参数

# 在模型配置中添加 rope_scaling = dict( type='linear', factor=2.0 # 根据需求调整 )

4.2 混合精度训练优化

为了提升训练效率并减少显存占用，可以配置混合精度训练：

# 在配置文件中添加 fp16 = dict( enabled=True, loss_scale=512, initial_scale_power=16, min_loss_scale=1 ) # 或者使用bf16 bf16 = dict(enabled=True)

精度选择建议：

4.3 自定义提示模板

不同的模型需要不同的提示模板才能发挥最佳性能。Xtuner支持自定义提示模板：

# 在配置文件中定义 prompt_template = dict( system='你是一个专业的医学AI助手，请用准确、专业的语言回答问题。', user='{input}', assistant='{output}', system_prefix='', system_suffix='\n', user_prefix='问：', user_suffix='\n', assistant_prefix='答：', assistant_suffix='\n', stop_words=['\n', '</s>'] )

模板设计原则：

1. 明确区分系统提示、用户输入和助手回复
2. 保持风格一致性
3. 包含适当的停止词
4. 考虑多轮对话场景